# Planting Service 架构文档 ## 目录 - [概述](#概述) - [架构模式](#架构模式) - [分层架构](#分层架构) - [领域模型](#领域模型) - [数据流](#数据流) - [技术栈](#技术栈) - [目录结构](#目录结构) --- ## 概述 Planting Service 是 RWA Durian Queen 平台的核心微服务之一，负责处理榴莲树认种业务的完整生命周期。该服务采用 **领域驱动设计 (DDD)** 结合 **六边形架构 (Hexagonal Architecture)** 进行设计和实现。 ### 核心职责 1. **认种订单管理** - 创建、支付、取消订单 2. **省市选择机制** - 5秒确认机制防止误操作 3. **资金分配** - 10种目标的精确分配（总计2199 USDT/棵） 4. **持仓管理** - 用户认种持仓的统计与追踪 5. **资金池注入** - 5天批次管理机制 --- ## 架构模式 ### 领域驱动设计 (DDD) ``` ┌─────────────────────────────────────────────────────────────────┐ │ Presentation Layer │ │ (Controllers, DTOs) │ ├─────────────────────────────────────────────────────────────────┤ │ Application Layer │ │ (Application Services, Use Cases) │ ├─────────────────────────────────────────────────────────────────┤ │ Domain Layer │ │ (Aggregates, Entities, Value Objects, Domain Services) │ ├─────────────────────────────────────────────────────────────────┤ │ Infrastructure Layer │ │ (Repositories, External Services, Persistence) │ └─────────────────────────────────────────────────────────────────┘ ``` ### 六边形架构 (Ports & Adapters) ``` ┌─────────────────────────┐ │ HTTP API │ │ (Primary Adapter) │ └───────────┬─────────────┘ │ ┌───────────▼─────────────┐ │ │ ┌───────────────┤ Application Core ├───────────────┐ │ │ │ │ │ │ ┌─────────────────┐ │ │ │ │ │ Domain Model │ │ │ │ │ │ │ │ │ │ │ │ - Aggregates │ │ │ │ │ │ - Services │ │ │ │ │ │ - Events │ │ │ │ │ └─────────────────┘ │ │ │ │ │ │ │ └─────────────────────────┘ │ │ │ │ ▼ ▼ ▼ ┌───────────┐ ┌───────────────┐ ┌───────────────┐ │ PostgreSQL│ │ Wallet Service│ │Referral Service│ │ (Prisma) │ │ (HTTP) │ │ (HTTP) │ └───────────┘ └───────────────┘ └───────────────┘ Secondary Secondary Secondary Adapter Adapter Adapter ``` --- ## 分层架构 ### 1. API 层 (`src/api/`) **职责**: 处理 HTTP 请求/响应，输入验证，认证授权 ``` src/api/ ├── controllers/ # 控制器 │ ├── health.controller.ts │ ├── planting-order.controller.ts │ └── planting-position.controller.ts ├── dto/ # 数据传输对象 │ ├── request/ # 请求 DTO │ └── response/ # 响应 DTO ├── guards/ # 守卫 │ └── jwt-auth.guard.ts └── api.module.ts ``` **设计原则**: - 控制器仅负责 HTTP 协议处理 - DTO 用于数据验证和转换 - 不包含业务逻辑 ### 2. Application 层 (`src/application/`) **职责**: 编排业务用例，协调领域对象，事务管理 ``` src/application/ ├── services/ │ ├── planting-application.service.ts # 主应用服务 │ └── pool-injection.service.ts # 资金池注入服务 └── application.module.ts ``` **核心职责**: - 用例编排 - 跨聚合协调 - 外部服务调用 - 事务边界控制 ### 3. Domain 层 (`src/domain/`) **职责**: 核心业务逻辑，业务规则验证 ``` src/domain/ ├── aggregates/ # 聚合根 │ ├── planting-order.aggregate.ts │ ├── planting-position.aggregate.ts │ └── pool-injection-batch.aggregate.ts ├── value-objects/ # 值对象 │ ├── tree-count.vo.ts │ ├── province-city-selection.vo.ts │ ├── fund-allocation.vo.ts │ └── money.vo.ts ├── events/ # 领域事件 │ ├── planting-order-created.event.ts │ ├── province-city-confirmed.event.ts │ └── funds-allocated.event.ts ├── services/ # 领域服务 │ └── fund-allocation.service.ts ├── repositories/ # 仓储接口 │ ├── planting-order.repository.interface.ts │ ├── planting-position.repository.interface.ts │ └── pool-injection-batch.repository.interface.ts └── domain.module.ts ``` **设计原则**: - 聚合是事务一致性边界 - 值对象不可变 - 领域事件用于跨聚合通信 - 仓储接口定义在领域层 ### 4. Infrastructure 层 (`src/infrastructure/`) **职责**: 技术实现，外部系统集成 ``` src/infrastructure/ ├── persistence/ │ ├── prisma/ │ │ └── prisma.service.ts │ ├── mappers/ # 领域对象<->持久化对象映射 │ │ ├── planting-order.mapper.ts │ │ ├── planting-position.mapper.ts │ │ └── pool-injection-batch.mapper.ts │ └── repositories/ # 仓储实现 │ ├── planting-order.repository.impl.ts │ ├── planting-position.repository.impl.ts │ └── pool-injection-batch.repository.impl.ts ├── external/ # 外部服务客户端 │ ├── wallet-service.client.ts │ └── referral-service.client.ts └── infrastructure.module.ts ``` --- ## 领域模型 ### 聚合关系图 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ PlantingOrder │ │ (聚合根 - 认种订单) │ │ │ │ ┌──────────────────┐ ┌────────────────────┐ │ │ │ TreeCount │ │ ProvinceCitySelection│ │ │ │ (认种数量) │ │ (省市选择) │ │ │ └──────────────────┘ └────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ FundAllocation[] │ │ │ │ (资金分配列表) │ │ │ │ │ │ │ │ POOL(90%) | OPERATION(5%) | PROVINCE(0.6%) | CITY(0.3%) ... │ │ │ └──────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ │ 1:N ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ PlantingPosition │ │ (聚合根 - 用户持仓) │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ PositionDistribution[] │ │ │ │ (持仓分布 - 按省市统计) │ │ │ └──────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────┐ │ PoolInjectionBatch │ │ (聚合根 - 资金池注入批次) │ │ │ │ - 5天为一个批次周期 │ │ - 批量处理订单的资金池注入 │ │ - 状态: OPEN -> SCHEDULED -> INJECTING -> COMPLETED │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 订单状态流转 ``` ┌──────────┐ │ CREATED │ ◄─── 创建订单 └────┬─────┘ │ selectProvinceCity() ▼ ┌──────────────────────┐ │ PROVINCE_CITY_SELECTED│ ◄─── 选择省市（5秒等待） └────┬─────────────────┘ │ confirmProvinceCity() (5秒后) ▼ ┌──────────────────────┐ │PROVINCE_CITY_CONFIRMED│ ◄─── 确认省市 └────┬─────────────────┘ │ pay() ▼ ┌──────────┐ │ PAID │ ◄─── 支付完成 └────┬─────┘ │ allocateFunds() ▼ ┌────────────────┐ │ FUND_ALLOCATED │ ◄─── 资金分配完成 └────┬───────────┘ │ scheduleToBatch() ▼ ┌────────────────┐ │ POOL_SCHEDULED │ ◄─── 加入注入批次 └────┬───────────┘ │ markPoolInjected() ▼ ┌────────────────┐ │ POOL_INJECTED │ ◄─── 资金池注入完成 └────┬───────────┘ │ enableMining() ▼ ┌────────────────┐ │ MINING_ENABLED │ ◄─── 开始挖矿 └────────────────┘ 任意状态（PAID之前）可转为: ┌───────────┐ │ CANCELLED │ ◄─── 取消订单 └───────────┘ ``` ### 资金分配模型 每棵树 **2199 USDT** 分配到 10 个目标： | 序号 | 目标类型 | 金额 (USDT) | 比例 | |-----|---------|------------|------| | 1 | POOL (资金池) | 1979.1 | 90% | | 2 | OPERATION (运营) | 109.95 | 5% | | 3 | PROVINCE_AUTH (省代) | 13.194 | 0.6% | | 4 | CITY_AUTH (市代) | 6.597 | 0.3% | | 5 | COMMUNITY (社区长) | 10.995 | 0.5% | | 6 | REFERRAL_L1 (一级推荐) | 32.985 | 1.5% | | 7 | REFERRAL_L2 (二级推荐) | 21.99 | 1.0% | | 8 | REFERRAL_L3 (三级推荐) | 10.995 | 0.5% | | 9 | PLATFORM (平台) | 6.597 | 0.3% | | 10 | RESERVE (储备) | 6.597 | 0.3% | | **总计** | | **2199** | **100%** | --- ## 数据流 ### 创建订单流程 ``` ┌──────┐ ┌────────────┐ ┌─────────────────┐ ┌──────────────┐ │Client│────▶│ Controller │────▶│ Application Svc │────▶│ Domain Layer │ └──────┘ └────────────┘ └─────────────────┘ └──────────────┘ │ │ │ │ │ POST /orders│ │ │ │ {treeCount} │ │ │ │ │ │ │ │ │ createOrder() │ │ │ │────────────────────▶│ │ │ │ │ │ │ │ │ 检查限购数量 │ │ │ │─────────────────────▶│ │ │ │ │ │ │ │ 检查余额 │ │ │ │─────────────────────▶│ │ │ │ (Wallet Service) │ │ │ │ │ │ │ │ 创建订单聚合 │ │ │ │─────────────────────▶│ │ │ │ │ │ │ │ 保存订单 │ │ │ │─────────────────────▶│ │ │ │ (Repository) │ │ │ │ │ │◀─────────────│◀────────────────────│◀─────────────────────│ │ OrderDTO │ │ │ ``` ### 支付订单流程 ``` ┌──────┐ ┌────────────┐ ┌─────────────────┐ ┌──────────────┐ │Client│────▶│ Controller │────▶│ Application Svc │────▶│ Domain Layer │ └──────┘ └────────────┘ └─────────────────┘ └──────────────┘ │ │ │ │ │ POST /pay │ │ │ │ │ payOrder() │ │ │ │────────────────────▶│ │ │ │ │ │ │ │ │ 1. 扣款 │ │ │ │─────────────────────▶│ │ │ │ (Wallet Service) │ │ │ │ │ │ │ │ 2. 获取推荐上下文 │ │ │ │─────────────────────▶│ │ │ │ (Referral Service) │ │ │ │ │ │ │ │ 3. 计算资金分配 │ │ │ │─────────────────────▶│ │ │ │ (FundAllocationSvc) │ │ │ │ │ │ │ │ 4. 执行资金分配 │ │ │ │─────────────────────▶│ │ │ │ (Wallet Service) │ │ │ │ │ │ │ │ 5. 更新用户持仓 │ │ │ │─────────────────────▶│ │ │ │ (Position Repo) │ │ │ │ │ │ │ │ 6. 加入注入批次 │ │ │ │─────────────────────▶│ │ │ │ (Batch Repo) │ │ │ │ │ │◀─────────────│◀────────────────────│◀─────────────────────│ │ PayResult │ │ │ ``` --- ## 技术栈 | 组件 | 技术选型 | 用途 | |-----|---------|------| | 框架 | NestJS 10.x | Web 框架 | | 语言 | TypeScript 5.x | 开发语言 | | 数据库 | PostgreSQL 16 | 主数据库 | | ORM | Prisma 5.x | 数据访问 | | 验证 | class-validator | 输入验证 | | 文档 | Swagger/OpenAPI | API 文档 | | 测试 | Jest + Supertest | 测试框架 | | 容器 | Docker | 容器化部署 | --- ## 目录结构 ``` planting-service/ ├── docs/ # 文档目录 │ ├── ARCHITECTURE.md # 架构文档 │ ├── API.md # API 文档 │ ├── DEVELOPMENT.md # 开发指南 │ ├── TESTING.md # 测试文档 │ └── DEPLOYMENT.md # 部署文档 ├── prisma/ │ ├── schema.prisma # 数据库模型 │ └── migrations/ # 数据库迁移 ├── src/ │ ├── api/ # API 层 │ ├── application/ # 应用层 │ ├── domain/ # 领域层 │ ├── infrastructure/ # 基础设施层 │ ├── config/ # 配置 │ ├── shared/ # 共享模块 │ ├── app.module.ts # 根模块 │ └── main.ts # 入口文件 ├── test/ # E2E 测试 ├── docker-compose.yml # Docker 编排 ├── docker-compose.test.yml # 测试环境编排 ├── Dockerfile # 生产镜像 ├── Dockerfile.test # 测试镜像 ├── Makefile # 构建脚本 └── package.json ``` --- ## 参考资料 - [领域驱动设计 (Eric Evans)](https://www.domainlanguage.com/ddd/) - [六边形架构 (Alistair Cockburn)](https://alistair.cockburn.us/hexagonal-architecture/) - [NestJS 官方文档](https://docs.nestjs.com/) - [Prisma 官方文档](https://www.prisma.io/docs/)