33 KiB

Raw Blame History

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 张表）

// ===== 以下全部是新增表，写在 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（新增配置表）

// 追加到 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（新增同步表）

// 追加到 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")
}

预种分配金额配置（在预种模块新文件中定义）

// 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

// 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 },
      );
  }
}

// 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：

// 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 购买前校验）：

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 流零影响：

{
  "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 开关管理
集成测试（购买 → 分配 → 合并 → 签约 → 挖矿）

验证方案

单元测试：PrePlantingOrder 聚合根状态机、PRE_PLANTING_RIGHT_AMOUNTS 总额校验（= 3171）
集成测试：购买 5 份 → 验证 5 次分配（各 3171）→ 验证自动合并 → 验证 PrePlantingMerge 创建
E2E 测试：合并后签约 → hasPlanted=true → 可申请授权 → 可卖出 eUSDT → 可提现
CDC 测试：预种订单 → contribution-service 同步 → 算力 = tree算力/5 → 1 年冻结验证
开关测试：关闭开关 → 新用户不可购买 → 已有 3 份的用户可继续购买 2 份 → 凑满合并

33 KiB Raw Blame History Unescape Escape