424 lines
22 KiB
Markdown
424 lines
22 KiB
Markdown
# 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/)
|