746 lines
33 KiB
Markdown
746 lines
33 KiB
Markdown
# 3171 预种计划（拼种/团购计划）— 实现方案
|
||
|
||
## Context
|
||
|
||
RWADurian 平台需要新增"3171 预种计划"功能。这本质是一个**拼种团购计划**：用户以 3171 USDT/份（1 棵树的 1/5 价格）参与认种，每购买一份立即享有分配、推荐奖励和算力收益；累计 5 份自动合成 1 棵树，触发合同签署和挖矿开启，同时解除交易和提现限制。此功能需无缝融入现有 1.0 认种分配和 2.0 算力挖矿体系，不破坏任何已有功能。
|
||
|
||
---
|
||
|
||
## 架构决策
|
||
|
||
### 核心原则：纯新增，零侵入
|
||
|
||
**现有代码文件一行不改。** 所有预种逻辑通过以下方式实现：
|
||
- 新增独立文件（新 controller、新 service、新 handler、新 Guard）
|
||
- 新增数据库表（不修改现有表结构）
|
||
- 新增 Kafka Topic（不修改现有 Topic 的生产/消费逻辑）
|
||
- 唯一的"接触"是在各服务的 `app.module.ts` 中 import 新模块（纯注册，不改现有逻辑）
|
||
|
||
### 决策 1：在 planting-service 中新增独立模块（非新服务）
|
||
|
||
预种作为 planting-service 内的一个**完全独立的 NestJS Module**：
|
||
- 有自己的 Controller、Service、Repository、Events
|
||
- 有自己的 Prisma 表（不触碰现有 planting_orders 等表）
|
||
- 通过自己的 Kafka Topic 通信（不复用 `planting.planting.created` 等现有 Topic）
|
||
- 与现有 PlantingOrder 聚合根**零耦合**
|
||
|
||
**不创建新微服务的原因**：共享同一 PostgreSQL (rwa_planting) + 同一 Redis + 同一 Kafka，避免新增基础设施和运维成本。
|
||
|
||
### 决策 2：预种有自己完整的独立事件流
|
||
|
||
预种使用全新的 Kafka Topic（`pre-planting.*`），现有消费者不会收到这些事件，所以：
|
||
- referral-service 的现有 `planting-created.handler.ts` **完全不受影响**
|
||
- reward-service 的现有 `reward-calculation.service.ts` **完全不受影响**
|
||
- contract-signing 的现有流程 **完全不受影响**
|
||
|
||
### 决策 3：合并产生的"树"不进入现有 PlantingOrder 表
|
||
|
||
5 份合并后，**不创建 PlantingOrder**（避免触发现有分配流程）。而是：
|
||
- 在预种模块自己的 `pre_planting_merges` 表中记录合并
|
||
- 预种模块自己处理合同签署（复用签署逻辑但在新文件中）
|
||
- 预种模块通过自己的事件通知 contribution-service（2.0）
|
||
- 预种模块直接调用 wallet-service 内部 API 设置 `hasPlanted=true`
|
||
|
||
**好处**：现有 PlantingOrder 的整个生命周期管道（事件 → referral → contract → reward → contribution）完全不被触碰。
|
||
|
||
### 决策 4：从第 1 份起即产生分配与算力，附带限制条件
|
||
|
||
**从第 1 份预种开始，以下功能立即生效：**
|
||
- 10 类权益分配（1/5 比例）立即触发并入账
|
||
- 推荐人立即获得 720 推荐奖励
|
||
- 算力（贡献值）立即产生并参与 2.0 挖矿分配
|
||
- 团队统计立即更新（预种份额计入团队业绩）
|
||
|
||
**附带的限制条件（未累积满 5 份前）：**
|
||
- 不可卖出 eUSDT（只能看，不能卖）
|
||
- 不可申请/授权社区、市公司、省公司
|
||
- 不可使用对公账户提现
|
||
- 若 1 年内未满 5 份 → 算力暂停分配（满 5 份后恢复，恢复起算 2 年后失效）
|
||
|
||
**合并后解锁全部限制 + 触发合同签署和挖矿开启。**
|
||
|
||
### 决策 5：推荐奖励取决于"被推荐人买了什么"，与推荐人自身无关
|
||
|
||
推荐奖励规则（与现有逻辑完全一致，只是新增预种产品类型）：
|
||
|
||
| 场景 | 推荐人 A | 被推荐人 B | A 获得奖励 |
|
||
|------|----------|------------|------------|
|
||
| B 认种 1 棵树 | 买了 1 份预种 | 认种 1 棵树 | **3600** 绿积分 |
|
||
| B 买 1 份预种 | 买了 1 份预种 | 买 1 份预种 | **720** 绿积分 |
|
||
| B 买 1 份预种 | 认种了 1 棵树 | 买 1 份预种 | **720** 绿积分 |
|
||
| B 认种 1 棵树 | 认种了 1 棵树 | 认种 1 棵树 | **3600** 绿积分（原有逻辑不变） |
|
||
|
||
规则本质：奖励金额 = 被推荐人购买产品对应的 SHARE_RIGHT（树=3600，预种份=720）
|
||
|
||
---
|
||
|
||
## 涉及服务清单（纯新增方式）
|
||
|
||
| 服务 | 现有代码改动 | 新增内容 |
|
||
|------|-------------|----------|
|
||
| **planting-service** | `app.module.ts` 加 1 行 import | **新增 PrePlantingModule**（独立聚合根、Controller、Service、Repository、Events、合并逻辑、开关） |
|
||
| **referral-service** | `app.module.ts` 加 1 行 import | **新增 PrePlantingStatsModule**（新 handler 消费预种事件更新团队统计） |
|
||
| **reward-service** | 无 | **不涉及**。预种的 1/5 分配由 planting-service 的预种模块直接调用 wallet-service 完成 |
|
||
| **authorization-service** | `app.module.ts` 加 1 行 import | **新增 PrePlantingGuardModule**（路由级 Middleware，仅对授权申请路由生效） |
|
||
| **trading-service** | `app.module.ts` 加 1 行 import | **新增 PrePlantingGuardModule**（路由级 Middleware，仅对卖单路由生效） |
|
||
| **wallet-service** | `app.module.ts` 加 1 行 import | **新增 PrePlantingGuardModule**（路由级 Middleware，仅对提现路由生效） |
|
||
| **admin-service** | `app.module.ts` 加 1 行 import | **新增 PrePlantingAdminModule**（开关管理 + 预种订单查询视图） |
|
||
| **contribution-service (2.0)** | `app.module.ts` 加 1 行 import | **新增 PrePlantingCdcModule**（CDC 消费预种表、1/5 算力、冻结逻辑） |
|
||
| **mobile-app (Flutter)** | 无 | **新增预种功能模块**（购买页、持仓页、合并流程、签约弹窗） |
|
||
|
||
**关键**：除 `app.module.ts` 的 import 注册外，**每个服务的现有 .ts 文件零修改**。
|
||
|
||
---
|
||
|
||
## 数据模型变更（全部是新增表，不修改任何现有表）
|
||
|
||
### planting-service（新增 4 张表）
|
||
|
||
```prisma
|
||
// ===== 以下全部是新增表，写在 schema.prisma 末尾 =====
|
||
|
||
// 预种订单
|
||
model PrePlantingOrder {
|
||
id BigInt @id @default(autoincrement())
|
||
orderNo String @unique // PPL{timestamp}{random}
|
||
userId BigInt
|
||
accountSequence String
|
||
portionCount Int @default(1)
|
||
pricePerPortion Decimal @default(3171)
|
||
totalAmount Decimal // portionCount × 3171
|
||
provinceCode String // 省代码（购买时选择）
|
||
cityCode String // 市代码（购买时选择）
|
||
status String @default("CREATED") // CREATED → PAID → MERGED
|
||
mergedToMergeId BigInt? // 合并后指向 PrePlantingMerge.id
|
||
mergedAt DateTime?
|
||
createdAt DateTime @default(now())
|
||
paidAt DateTime?
|
||
updatedAt DateTime @updatedAt
|
||
@@map("pre_planting_orders")
|
||
}
|
||
|
||
// 预种持仓（每用户一条）
|
||
model PrePlantingPosition {
|
||
id BigInt @id @default(autoincrement())
|
||
userId BigInt @unique
|
||
accountSequence String @unique
|
||
totalPortions Int @default(0) // 累计购买份数（含已合并）
|
||
availablePortions Int @default(0) // 待合并份数（0-4）
|
||
mergedPortions Int @default(0) // 已合并份数
|
||
totalTreesMerged Int @default(0) // 已合成的树数
|
||
provinceCode String? // 首次购买时选择的省代码（后续复用）
|
||
cityCode String? // 首次购买时选择的市代码（后续复用）
|
||
firstPurchaseAt DateTime? // 首次购买时间（1年冻结起点）
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
@@map("pre_planting_positions")
|
||
}
|
||
|
||
// 合并记录（预种的"树"，不进入现有 planting_orders 表）
|
||
model PrePlantingMerge {
|
||
id BigInt @id @default(autoincrement())
|
||
mergeNo String @unique // PMG{timestamp}{random}
|
||
userId BigInt
|
||
accountSequence String
|
||
sourceOrderNos Json // 5 笔预种订单号数组
|
||
treeCount Int @default(1) // 合并产生的树数（固定 1）
|
||
|
||
// 省市选择（合并后由用户选择）
|
||
selectedProvince String?
|
||
selectedCity String?
|
||
provinceCityConfirmedAt DateTime?
|
||
|
||
// 合同签署
|
||
contractStatus String @default("PENDING") // PENDING → SIGNED → EXPIRED
|
||
contractSignedAt DateTime?
|
||
|
||
// 挖矿
|
||
miningEnabledAt DateTime?
|
||
|
||
mergedAt DateTime @default(now())
|
||
@@map("pre_planting_merges")
|
||
}
|
||
|
||
// 预种分配记录（预种模块自己管理分配，不经过 reward-service）
|
||
model PrePlantingRewardEntry {
|
||
id BigInt @id @default(autoincrement())
|
||
sourceOrderNo String // 来源预种订单号
|
||
sourceAccountSequence String // 购买者 accountSequence
|
||
recipientAccountSequence String // 接收者 accountSequence（推荐人/社区/省市公司/系统账户）
|
||
rightType String // 权益类型（同 RightType 枚举）
|
||
usdtAmount Decimal
|
||
rewardStatus String @default("SETTLED") // SETTLED / PENDING / EXPIRED
|
||
memo String? // 分配原因说明
|
||
createdAt DateTime @default(now())
|
||
@@map("pre_planting_reward_entries")
|
||
}
|
||
```
|
||
|
||
**注意**：现有 `planting_orders`、`planting_positions` 等表**零修改**。
|
||
**注意**：现有 `PlantingOrder` 聚合根代码**零修改**。
|
||
|
||
### admin-service（新增配置表）
|
||
|
||
```prisma
|
||
// 追加到 schema.prisma 末尾
|
||
model PrePlantingConfig {
|
||
id String @id @default(uuid())
|
||
isActive Boolean @default(false)
|
||
activatedAt DateTime?
|
||
updatedAt DateTime @updatedAt
|
||
updatedBy String?
|
||
@@map("pre_planting_configs")
|
||
}
|
||
```
|
||
|
||
### contribution-service 2.0（新增同步表）
|
||
|
||
```prisma
|
||
// 追加到 schema.prisma 末尾
|
||
model SyncedPrePlantingAdoption {
|
||
id BigInt @id @default(autoincrement())
|
||
originalOrderId BigInt @unique
|
||
accountSequence String
|
||
portionCount Int
|
||
purchaseDate DateTime @db.Date
|
||
contributionPerPortion Decimal
|
||
contributionFrozen Boolean @default(false)
|
||
freezeExpiresAt DateTime?
|
||
contributionDistributed Boolean @default(false)
|
||
syncedAt DateTime @default(now())
|
||
@@map("synced_pre_planting_adoptions")
|
||
}
|
||
```
|
||
|
||
### 预种分配金额配置（在预种模块新文件中定义）
|
||
|
||
```typescript
|
||
// planting-service/src/pre-planting/domain/value-objects/pre-planting-right-amounts.ts（新文件）
|
||
// 基准：reward-service 的 RIGHT_AMOUNTS（实际生效的分配金额）
|
||
// 预种每份 = 整棵树金额 / 5，差额 4.8 归入总部社区
|
||
export const PRE_PLANTING_RIGHT_AMOUNTS = {
|
||
COST_FEE: 576, // 2880/5
|
||
OPERATION_FEE: 420, // 2100/5
|
||
HEADQUARTERS_BASE_FEE: 29.4, // 123/5 + 4.8 差额（3171 - 3166.2 = 4.8）
|
||
RWAD_POOL_INJECTION: 1152, // 5760/5
|
||
SHARE_RIGHT: 720, // 3600/5 = 720（推荐奖励金额）
|
||
PROVINCE_AREA_RIGHT: 21.6, // 108/5
|
||
PROVINCE_TEAM_RIGHT: 28.8, // 144/5
|
||
CITY_AREA_RIGHT: 50.4, // 252/5
|
||
CITY_TEAM_RIGHT: 57.6, // 288/5
|
||
COMMUNITY_RIGHT: 115.2, // 576/5
|
||
} as const;
|
||
// 合计 = 576 + 420 + 29.4 + 1152 + 720 + 21.6 + 28.8 + 50.4 + 57.6 + 115.2 = 3171.0 ✓
|
||
```
|
||
|
||
---
|
||
|
||
## 核心事件流
|
||
|
||
### 流程 A：预种购买（每份） — 全部在预种模块内完成
|
||
|
||
**重要**：购买时即选择省市（与现有认种流程一致），后续购买复用同一省市。
|
||
这样 10 类权益全部可在购买时立即分配。
|
||
|
||
```
|
||
用户购买 1 份预种（3171 USDT）
|
||
│
|
||
▼
|
||
[planting-service / PrePlantingModule]（全新代码，不触碰现有代码）
|
||
│
|
||
├─ Step 1：前置校验
|
||
│ ├─ 开关 ON（或续购规则通过）
|
||
│ ├─ 余额 ≥ 3171
|
||
│ └─ 省市信息（首次购买：用户选择；续购：自动复用 PrePlantingPosition 中的省市）
|
||
│
|
||
├─ Step 2：冻结余额
|
||
│ └─ wallet.freezeForPlanting(3171)（调用已有内部 API）
|
||
│
|
||
├─ Step 3：确定 10 类权益的分配对象（pre-planting-reward.service.ts）
|
||
│ │
|
||
│ ├─ 4 类系统费用（硬编码，无需查询）：
|
||
│ │ ├─ COST_FEE: 576 → S0000000002（成本账户）
|
||
│ │ ├─ OPERATION_FEE: 420 → S0000000003（运营账户）
|
||
│ │ ├─ HQ_BASE_FEE: 29.4 → S0000000001（总部社区）
|
||
│ │ └─ RWAD_POOL: 1152 → S0000000004（RWAD底池）
|
||
│ │
|
||
│ ├─ 推荐奖励（调用 referral-service 已有 API）：
|
||
│ │ └─ SHARE_RIGHT: 720 → GET /api/v1/referral/chain/{accountSeq}
|
||
│ │ ├─ 有推荐人且已认种 → 推荐人账户（立即到账）
|
||
│ │ ├─ 有推荐人未认种 → 推荐人账户（PENDING，24h 内认种可领取）
|
||
│ │ └─ 无推荐人 → S0000000005（分享权益池）
|
||
│ │
|
||
│ ├─ 社区权益（调用 authorization-service 已有 API）：
|
||
│ │ └─ COMMUNITY: 115.2 → GET /authorization/community-reward-distribution
|
||
│ │ ├─ 有前有效社区 → 社区领导账户
|
||
│ │ └─ 无社区 → S0000000001（总部）
|
||
│ │
|
||
│ └─ 省市 4 类权益（调用 authorization-service 已有 API，需要 provinceCode/cityCode）：
|
||
│ ├─ PROVINCE_AREA: 21.6 → GET /authorization/province-area-reward-distribution?provinceCode=XX
|
||
│ │ └─ 有正式省公司 → 省公司账户 | 无 → 9{provinceCode}（系统省账户）
|
||
│ ├─ PROVINCE_TEAM: 28.8 → GET /authorization/province-team-reward-distribution
|
||
│ │ └─ 有授权省团队 → 团队领导账户 | 无 → S0000000001（总部）
|
||
│ ├─ CITY_AREA: 50.4 → GET /authorization/city-area-reward-distribution?cityCode=XX
|
||
│ │ └─ 有正式市公司 → 市公司账户 | 无 → 8{cityCode}（系统市账户）
|
||
│ └─ CITY_TEAM: 57.6 → GET /authorization/city-team-reward-distribution
|
||
│ └─ 有授权市团队 → 团队领导账户 | 无 → S0000000001（总部）
|
||
│
|
||
├─ Step 4：事务内持久化
|
||
│ ├─ 创建 PrePlantingOrder(status=PAID, provinceCode, cityCode)
|
||
│ ├─ 更新 PrePlantingPosition(totalPortions++, availablePortions++)
|
||
│ ├─ 设置 firstPurchaseAt + provinceCode/cityCode（仅首次）
|
||
│ ├─ 创建 PrePlantingRewardEntry（10 条记录，含每条的接收人 accountSequence）
|
||
│ └─ Outbox: "pre-planting.portion.purchased"
|
||
│
|
||
├─ Step 5：执行资金转账
|
||
│ ├─ wallet.confirmDeduction(3171)（调用已有 API）
|
||
│ └─ wallet.allocateFunds(10 条分配)（调用已有 API，与 reward-service 调用格式完全一致）
|
||
│
|
||
└─ Step 6：检查是否触发合并
|
||
└─ availablePortions == 5 ? → 触发合并（流程 B）
|
||
│
|
||
▼
|
||
[referral-service / PrePlantingStatsModule]（新增 handler，不改现有文件）
|
||
├─ 消费 "pre-planting.portion.purchased"
|
||
└─ 更新 TeamStatistics（团队认种统计，预种份额按 1/5 棵树计入）
|
||
```
|
||
|
||
**与现有系统的隔离**：
|
||
- 预种模块**直接调用** referral-service 和 authorization-service 的**已有内部 API** 确定分配对象
|
||
- 确定对象后，调用 wallet-service 的 `allocateFunds` 执行转账（与 reward-service 调同一个 API）
|
||
- **reward-service 完全不感知预种的存在**——预种模块自己做了 reward-service 做的事情
|
||
- 推荐奖励 720 由预种模块计算后直接写入推荐人钱包
|
||
|
||
### 流程 B：自动合并（5 份 → 1 棵树） — 不创建 PlantingOrder
|
||
|
||
```
|
||
availablePortions == 5
|
||
│
|
||
▼
|
||
[planting-service / PrePlantingModule] 同一事务内：
|
||
├─ 创建 PrePlantingMerge 记录（mergeNo, 5个sourceOrderNos, contractStatus=PENDING）
|
||
│ └─ 注意：不创建 PlantingOrder！合并的树记录在自己的表中
|
||
├─ 标记 5 笔 PrePlantingOrder → MERGED
|
||
├─ 更新 PrePlantingPosition(available-=5, merged+=5, treesMerged++)
|
||
└─ Outbox: "pre-planting.merged"
|
||
│
|
||
▼
|
||
前端收到合并通知 → 弹出合同签署流程（省市已在首次购买时确定，无需再选）
|
||
│
|
||
▼
|
||
[planting-service / PrePlantingModule] 处理合同签署：
|
||
├─ 省市从 PrePlantingPosition 直接带入 PrePlantingMerge（无需用户重新选择）
|
||
├─ 生成合同 PDF（复用 MinIO 上传逻辑）
|
||
├─ 用户签约 → contractStatus = SIGNED
|
||
├─ wallet.setHasPlanted(accountSequence, true)（调用已有 API）
|
||
├─ Outbox: "pre-planting.contract.signed"
|
||
└─ 开启挖矿：miningEnabledAt = now()
|
||
│
|
||
▼
|
||
[contribution-service / PrePlantingCdcModule]（新增 handler）
|
||
├─ 消费 CDC 或 "pre-planting.contract.signed"
|
||
└─ 同步合并记录，标记为 MINING_ENABLED
|
||
```
|
||
|
||
**关键隔离点**：
|
||
- 不创建 PlantingOrder → referral-service 的现有 handler 不会被触发
|
||
- 不发布 `planting.planting.created` → reward-service 的现有 handler 不会被触发
|
||
- 不发布 `planting-events` → contract-signing 的现有 handler 不会被触发
|
||
- **所有预种事件走 `pre-planting.*` 独立 Topic**
|
||
|
||
### 流程 C：CDC 同步到 2.0（算力 — 从第 1 份即生效）
|
||
|
||
```
|
||
每份预种购买支付成功后，Debezium 立即捕获 pre_planting_orders 变更
|
||
│
|
||
▼
|
||
[contribution-service] CDC Consumer
|
||
├─ 同步到 SyncedPrePlantingAdoption
|
||
├─ 立即计算算力 = contributionPerTree / 5 × portionCount
|
||
├─ 算力立即参与挖矿分配（从第 1 份起就有收益）
|
||
├─ 解锁条件同正常认种（15 级 + 3 阶梯，按预种份额判断）
|
||
│
|
||
├─ 1 年冻结逻辑（定时任务检查）：
|
||
│ ├─ 正常状态：firstPurchaseAt + 1 年内 → 算力正常分配
|
||
│ ├─ 触发冻结：firstPurchaseAt + 1 年后仍未满 5 份 → 所有算力暂停分配
|
||
│ └─ 解冻恢复：此 ID 后续累计满 5 份 → 算力恢复分配
|
||
│ └─ 恢复后的失效期 = 恢复日起算 + 2 年
|
||
│
|
||
└─ 正常到期：首次产生挖矿收益日 + 2 年后失效（未被冻结过的情况）
|
||
```
|
||
|
||
**关键时间线示例：**
|
||
```
|
||
Day 0: 买第 1 份 → 算力 = tree算力/5，立即开始挖矿分配
|
||
Day 30: 买第 2 份 → 算力 += tree算力/5
|
||
Day 200: 买第 3 份 → 算力 += tree算力/5
|
||
Day 365: 仍只有 3 份 → 所有 3 份算力冻结（暂停分配）
|
||
Day 400: 买第 4 份 → 仍冻结（未满 5 份）
|
||
Day 420: 买第 5 份 → 自动合并成 1 棵树
|
||
→ 所有 5 份算力解冻，恢复分配
|
||
→ 解冻起算 + 2 年后失效
|
||
```
|
||
|
||
---
|
||
|
||
## 跨服务限制实现（全部通过新增 NestJS Middleware，不改现有代码）
|
||
|
||
### 实现模式：NestJS Middleware + forRoutes 精确路由匹配 + 内部 API
|
||
|
||
每个需要限制的服务新增一个 `PrePlantingGuardModule`（新文件），通过 `NestModule.configure()` + `forRoutes()` 注册路由级别 Middleware。
|
||
**只有特定路由才会执行检查逻辑**，其他路由完全无感知、零执行开销。Middleware 调用 planting-service 暴露的预种资格 API。
|
||
|
||
**planting-service 新增内部 API**（在 PrePlantingModule 内）：
|
||
```
|
||
GET /internal/pre-planting/eligibility/{accountSequence}
|
||
返回：{
|
||
hasPrePlanting: boolean, // 是否有预种记录
|
||
totalPortions: number, // 累计份数
|
||
totalTreesMerged: number, // 已合成树数
|
||
canApplyAuthorization: boolean, // 可申请授权
|
||
canTrade: boolean, // 可卖出 eUSDT
|
||
}
|
||
```
|
||
|
||
逻辑：
|
||
- `canApplyAuthorization = totalTreesMerged >= 1`（已有认种记录的老用户不受影响，因为 hasPrePlanting=false 时 Guard 直接放行）
|
||
- `canTrade = totalTreesMerged >= 1`（同上）
|
||
|
||
### 授权锁（authorization-service — 新增文件）
|
||
|
||
```
|
||
新增文件：authorization-service/src/pre-planting/pre-planting-guard.module.ts
|
||
新增文件：authorization-service/src/pre-planting/pre-planting-authorization.middleware.ts
|
||
新增文件：authorization-service/src/pre-planting/pre-planting.client.ts
|
||
```
|
||
|
||
```typescript
|
||
// pre-planting-guard.module.ts（新文件，不触碰现有代码）
|
||
@Module({ providers: [PrePlantingClient] })
|
||
export class PrePlantingGuardModule implements NestModule {
|
||
configure(consumer: MiddlewareConsumer) {
|
||
consumer
|
||
.apply(PrePlantingAuthorizationMiddleware)
|
||
.forRoutes(
|
||
{ path: 'authorization/apply*', method: RequestMethod.POST },
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// pre-planting-authorization.middleware.ts（新文件）
|
||
@Injectable()
|
||
export class PrePlantingAuthorizationMiddleware implements NestMiddleware {
|
||
constructor(private readonly prePlantingClient: PrePlantingClient) {}
|
||
|
||
async use(req: Request, res: Response, next: NextFunction) {
|
||
try {
|
||
const accountSequence = req['user']?.accountSequence;
|
||
if (!accountSequence) return next(); // 无用户信息，放行
|
||
|
||
const eligibility = await this.prePlantingClient.getEligibility(accountSequence);
|
||
|
||
// 没有预种记录（纯认种用户）→ 直接放行，现有逻辑零影响
|
||
if (!eligibility.hasPrePlanting) return next();
|
||
|
||
// 有预种记录但未满 5 份合并 → 拦截
|
||
if (!eligibility.canApplyAuthorization) {
|
||
return res.status(403).json({
|
||
message: '须累积购买5份预种计划合并成树后方可申请授权',
|
||
});
|
||
}
|
||
return next();
|
||
} catch (error) {
|
||
// planting-service 不可达时，默认放行（不影响现有功能）
|
||
return next();
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 交易锁（trading-service — 新增文件）
|
||
|
||
```
|
||
新增文件：trading-service/src/pre-planting/pre-planting-guard.module.ts
|
||
新增文件：trading-service/src/pre-planting/pre-planting-trading.middleware.ts
|
||
新增文件：trading-service/src/pre-planting/pre-planting.client.ts
|
||
```
|
||
|
||
同理：Middleware 通过 `forRoutes({ path: 'trading/orders', method: POST })` 精确匹配卖单路由。其他路由**完全不经过此 Middleware**。对无预种记录的用户直接放行。
|
||
|
||
### 提现锁（wallet-service — 新增文件）
|
||
|
||
```
|
||
新增文件：wallet-service/src/pre-planting/pre-planting-guard.module.ts
|
||
新增文件：wallet-service/src/pre-planting/pre-planting-withdrawal.middleware.ts
|
||
新增文件：wallet-service/src/pre-planting/pre-planting.client.ts
|
||
```
|
||
|
||
Middleware 通过 `forRoutes` 精确匹配提现路由，检查 `hasPlanted`（wallet-service 自己的字段，合并签约后由 PrePlantingModule 设置为 true）。
|
||
|
||
**Middleware 的关键设计**：
|
||
- **精确路由匹配**：通过 `forRoutes()` 只对特定路由生效，其他路由零执行开销
|
||
- **异常容错**：planting-service 不可达时默认放行（`catch → next()`），不影响现有功能
|
||
- `hasPrePlanting=false`（纯认种用户）→ **直接放行**，现有功能零影响
|
||
- `hasPrePlanting=true` 且 `canXxx=true` → 放行
|
||
- `hasPrePlanting=true` 且 `canXxx=false` → 拦截
|
||
|
||
### 1 年算力冻结（contribution-service — 新增文件）
|
||
|
||
```
|
||
新增文件：contribution-service/src/pre-planting/pre-planting-cdc.module.ts
|
||
新增文件：contribution-service/src/pre-planting/pre-planting-contribution.service.ts
|
||
新增文件：contribution-service/src/pre-planting/pre-planting-freeze-scheduler.ts
|
||
```
|
||
|
||
冻结逻辑在全新的 service 文件中实现，不触碰现有 `contribution-calculation.service.ts`：
|
||
|
||
```typescript
|
||
// pre-planting-freeze-scheduler.ts（新文件）
|
||
@Cron('0 0 * * *') // 每日检查
|
||
async checkContributionFreeze() {
|
||
// 查找所有 firstPurchaseAt + 1年 < NOW() 且 totalPortions < 5 的用户
|
||
// 冻结其预种算力记录
|
||
// 查找所有 totalPortions >= 5 且仍被冻结的用户
|
||
// 解冻，设 expireDate = 解冻日 + 2年
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 后台开关逻辑
|
||
|
||
修改文件：`admin-service` 新增 `PrePlantingConfigController` + `PrePlantingConfigEntity`
|
||
|
||
### 核心原则
|
||
|
||
- **随时可开**：打开后所有用户均可购买预种
|
||
- **随时可关**：关闭后限制新购买，但**已成交的一切保持不变**
|
||
- 已支付的预种订单：状态不变、分配不变、算力不变
|
||
- 已获得的推荐奖励：不回收
|
||
- 已产生的算力：继续参与挖矿分配（除非触发 1 年冻结规则）
|
||
- 待合并的份额：允许继续购买至下一个 5 的整数倍（凑满合并）
|
||
- **开关仅控制"能否发起新购买"，不影响任何已完成的业务流程**
|
||
|
||
### 开关规则（planting-service 购买前校验）：
|
||
|
||
```typescript
|
||
async validatePrePlantingPurchase(userId, portionCount) {
|
||
const config = await adminClient.getPrePlantingConfig();
|
||
const position = await prePositionRepo.findByUserId(userId);
|
||
|
||
if (config.isActive) {
|
||
// 开关打开：任何人都可以购买
|
||
return;
|
||
}
|
||
|
||
// 开关关闭：已成交的保持不变，仅限制新购买
|
||
if (!position || position.totalPortions === 0) {
|
||
// 从未购买过的用户：显示"待开启"
|
||
throw new BusinessError('预种功能待开启');
|
||
}
|
||
|
||
// 已有未凑满的份额：允许继续购买至下一个 5 的倍数
|
||
const remainder = position.availablePortions % 5;
|
||
if (remainder === 0) {
|
||
// 已凑满当前轮次（如 5/10/15...），不可开启新一轮
|
||
throw new BusinessError('预种功能已关闭，您当前份额已满，无法继续购买');
|
||
}
|
||
const maxAdditional = 5 - remainder;
|
||
if (portionCount > maxAdditional) {
|
||
throw new BusinessError(`当前只可再购买 ${maxAdditional} 份以凑满5份`);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 前端展示逻辑
|
||
|
||
| 开关状态 | 用户状态 | 前端表现 |
|
||
|----------|----------|----------|
|
||
| ON | 任何用户 | 正常显示购买入口 |
|
||
| OFF | 从未购买 | 显示"待开启"，购买按钮置灰 |
|
||
| OFF | 有 1-4 份未合并 | 显示"可继续购买 N 份凑满合并"，购买按钮可用 |
|
||
| OFF | 份额恰好为 5 的倍数 | 显示"预种功能已暂停"，购买按钮置灰 |
|
||
|
||
---
|
||
|
||
## 新增 Kafka Topics
|
||
|
||
| Topic | 生产者 | 消费者 | 触发时机 |
|
||
|-------|--------|--------|----------|
|
||
| `pre-planting.portion.purchased` | planting-service | referral-service | 每份购买支付成功 |
|
||
| `pre-planting.order.paid` | referral-service | reward-service | referral 处理完团队统计后 |
|
||
| `pre-planting.merged` | planting-service | contribution-service, referral-service | 5 份合并完成 |
|
||
|
||
**注意：不复用任何现有 Topic**。预种的所有事件（购买、合并、签约）全部走 `pre-planting.*` 独立 Topic，现有消费者完全不受影响。
|
||
|
||
---
|
||
|
||
## 新增 Debezium CDC Connector（独立连接器，不修改现有连接器）
|
||
|
||
**不修改现有 Debezium 连接器**。为预种表创建一个**全新的独立连接器**，确保现有 CDC 流零影响：
|
||
|
||
```json
|
||
{
|
||
"name": "pre-planting-connector",
|
||
"config": {
|
||
"connector.class": "io.debezium.connector.postgresql.PostgresConnector",
|
||
"database.hostname": "postgres-planting",
|
||
"database.port": "5432",
|
||
"database.dbname": "rwa_planting",
|
||
"database.server.name": "cdc.pre-planting",
|
||
"table.include.list": "public.pre_planting_orders,public.pre_planting_positions,public.pre_planting_merges",
|
||
"slot.name": "pre_planting_slot",
|
||
"publication.name": "pre_planting_publication",
|
||
"topic.prefix": "cdc.pre-planting"
|
||
}
|
||
}
|
||
```
|
||
|
||
Topic 命名（与现有 CDC Topic 完全隔离）：
|
||
- `cdc.pre-planting.public.pre_planting_orders`
|
||
- `cdc.pre-planting.public.pre_planting_positions`
|
||
- `cdc.pre-planting.public.pre_planting_merges`
|
||
|
||
contribution-service 新增对应 CDC Consumer（在 PrePlantingCdcModule 内）。
|
||
|
||
**隔离保证**：
|
||
- 独立 replication slot → 不影响现有 slot 的 WAL 消费
|
||
- 独立 publication → 不影响现有 publication
|
||
- 独立 topic prefix → 现有消费者不会收到预种 CDC 事件
|
||
|
||
---
|
||
|
||
## 关键文件索引
|
||
|
||
### 需要触碰的现有文件（仅 import 注册，不改业务逻辑）
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `planting-service/src/app.module.ts` | `imports: [..., PrePlantingModule]` |
|
||
| `planting-service/prisma/schema.prisma` | 文件末尾追加 4 张新表定义 |
|
||
| `referral-service/src/app.module.ts` | `imports: [..., PrePlantingStatsModule]` |
|
||
| `authorization-service/src/app.module.ts` | `imports: [..., PrePlantingGuardModule]` |
|
||
| `trading-service/src/app.module.ts` | `imports: [..., PrePlantingGuardModule]` |
|
||
| `wallet-service/src/app.module.ts` | `imports: [..., PrePlantingGuardModule]` |
|
||
| `admin-service/src/app.module.ts` | `imports: [..., PrePlantingAdminModule]` |
|
||
| `admin-service/prisma/schema.prisma` | 文件末尾追加 1 张新表定义 |
|
||
| `contribution-service/src/app.module.ts` | `imports: [..., PrePlantingCdcModule]` |
|
||
| `contribution-service/prisma/schema.prisma` | 文件末尾追加 1 张新表定义 |
|
||
|
||
**以上改动总量**：每个文件仅增加 1 行 import。现有业务逻辑文件**零修改**。
|
||
|
||
### 全部新增的文件
|
||
|
||
**planting-service/src/pre-planting/**（核心模块，约 15-20 个新文件）
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `pre-planting.module.ts` | 模块注册 |
|
||
| `domain/aggregates/pre-planting-order.aggregate.ts` | PrePlantingOrder 聚合根 |
|
||
| `domain/aggregates/pre-planting-position.aggregate.ts` | PrePlantingPosition 聚合根 |
|
||
| `domain/aggregates/pre-planting-merge.aggregate.ts` | PrePlantingMerge 聚合根（合并的树） |
|
||
| `domain/events/pre-planting-*.event.ts` | 领域事件（purchased/merged/contract-signed） |
|
||
| `domain/value-objects/pre-planting-order-status.enum.ts` | 预种状态枚举 |
|
||
| `domain/value-objects/pre-planting-right-amounts.ts` | 1/5 分配金额常量 |
|
||
| `application/services/pre-planting-application.service.ts` | 购买 + 合并应用服务 |
|
||
| `application/services/pre-planting-reward.service.ts` | 预种分配服务（调用 wallet-service） |
|
||
| `application/services/pre-planting-contract.service.ts` | 合并后合同签署服务 |
|
||
| `api/controllers/pre-planting.controller.ts` | 用户端 API |
|
||
| `api/controllers/internal-pre-planting.controller.ts` | 内部资格查询 API |
|
||
| `infrastructure/repositories/pre-planting-order.repository.ts` | 订单仓储 |
|
||
| `infrastructure/repositories/pre-planting-position.repository.ts` | 持仓仓储 |
|
||
| `infrastructure/repositories/pre-planting-merge.repository.ts` | 合并记录仓储 |
|
||
| `infrastructure/kafka/pre-planting-outbox-publisher.service.ts` | Outbox 事件发布 |
|
||
|
||
**referral-service/src/pre-planting/**（新 handler）
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `pre-planting-stats.module.ts` | 模块注册 |
|
||
| `pre-planting-purchased.handler.ts` | 消费预种购买事件，更新团队统计 |
|
||
|
||
**authorization-service/src/pre-planting/**（路由级 Middleware）
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `pre-planting-guard.module.ts` | Middleware 模块注册（forRoutes 精确匹配） |
|
||
| `pre-planting-authorization.middleware.ts` | 授权申请拦截 Middleware |
|
||
| `pre-planting.client.ts` | 调用 planting-service 资格 API 的 HTTP Client |
|
||
|
||
**trading-service/src/pre-planting/**（路由级 Middleware）
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `pre-planting-guard.module.ts` | Middleware 模块注册（forRoutes 精确匹配） |
|
||
| `pre-planting-trading.middleware.ts` | 卖单拦截 Middleware |
|
||
| `pre-planting.client.ts` | HTTP Client |
|
||
|
||
**wallet-service/src/pre-planting/**（路由级 Middleware）
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `pre-planting-guard.module.ts` | Middleware 模块注册（forRoutes 精确匹配） |
|
||
| `pre-planting-withdrawal.middleware.ts` | 提现拦截 Middleware |
|
||
| `pre-planting.client.ts` | HTTP Client |
|
||
|
||
**admin-service/src/pre-planting/**（开关管理）
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `pre-planting-admin.module.ts` | 模块注册 |
|
||
| `pre-planting-config.entity.ts` | 开关实体 |
|
||
| `pre-planting-config.controller.ts` | 开关 API |
|
||
| `pre-planting-config.repository.ts` | 开关仓储 |
|
||
|
||
**contribution-service/src/pre-planting/**（CDC + 算力）
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `pre-planting-cdc.module.ts` | 模块注册 |
|
||
| `pre-planting-cdc.consumer.ts` | 预种表 CDC 消费 |
|
||
| `pre-planting-contribution.service.ts` | 1/5 算力计算 |
|
||
| `pre-planting-freeze-scheduler.ts` | 1 年冻结定时任务 |
|
||
|
||
---
|
||
|
||
## 实施阶段
|
||
|
||
### Phase 1：预种购买基础（planting-service + admin-service）
|
||
- Schema 迁移（3 新表 + 1 字段）
|
||
- PrePlantingOrder 聚合根 + PrePlantingPosition
|
||
- 购买 API + 开关配置
|
||
- Outbox 事件发布
|
||
|
||
### Phase 2：分配与推荐（reward-service + referral-service）
|
||
- 1/5 分配逻辑 + 720 推荐奖励
|
||
- 预种事件消费 + 团队统计
|
||
- 合并订单跳过分配逻辑
|
||
|
||
### Phase 3：自动合并（planting-service 核心）
|
||
- 5 份合并 → PrePlantingMerge 创建（不创建 PlantingOrder）
|
||
- 合并后省市选择 + 合同签署流程
|
||
- 前端合并通知 + 签约弹窗
|
||
|
||
### Phase 4：跨服务限制（authorization + trading + wallet）
|
||
- 授权申请资格校验
|
||
- eUSDT 卖出限制
|
||
- 提现 hasPlanted 校验
|
||
- 内部 API 端点
|
||
|
||
### Phase 5：2.0 算力集成（contribution-service）
|
||
- CDC 新表消费
|
||
- 1/5 算力计算
|
||
- 1 年冻结 / 解冻逻辑
|
||
- Debezium 连接器配置
|
||
|
||
### Phase 6：前端 + 测试
|
||
- Flutter 预种购买/持仓页面
|
||
- 合并提示与合同签署
|
||
- admin-web 开关管理
|
||
- 集成测试（购买 → 分配 → 合并 → 签约 → 挖矿）
|
||
|
||
---
|
||
|
||
## 验证方案
|
||
|
||
1. **单元测试**：PrePlantingOrder 聚合根状态机、PRE_PLANTING_RIGHT_AMOUNTS 总额校验（= 3171）
|
||
2. **集成测试**：购买 5 份 → 验证 5 次分配（各 3171）→ 验证自动合并 → 验证 PrePlantingMerge 创建
|
||
3. **E2E 测试**：合并后签约 → hasPlanted=true → 可申请授权 → 可卖出 eUSDT → 可提现
|
||
4. **CDC 测试**：预种订单 → contribution-service 同步 → 算力 = tree算力/5 → 1 年冻结验证
|
||
5. **开关测试**：关闭开关 → 新用户不可购买 → 已有 3 份的用户可继续购买 2 份 → 凑满合并
|