22 KiB
22 KiB
Planting Service 架构文档
目录
概述
Planting Service 是 RWA Durian Queen 平台的核心微服务之一，负责处理榴莲树认种业务的完整生命周期。该服务采用 领域驱动设计 (DDD) 结合 六边形架构 (Hexagonal Architecture) 进行设计和实现。
核心职责
- 认种订单管理 - 创建、支付、取消订单
- 省市选择机制 - 5秒确认机制防止误操作
- 资金分配 - 10种目标的精确分配（总计2199 USDT/棵）
- 持仓管理 - 用户认种持仓的统计与追踪
- 资金池注入 - 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