From c3e43b81e9bc88db4ff901739beaf17413f461b6 Mon Sep 17 00:00:00 2001 From: hailin Date: Thu, 19 Feb 2026 03:49:01 -0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=B9=B3=E5=8F=B0=E5=85=A8=E6=99=AF?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=A4=A7=E7=BA=B2=20+=20=E9=A2=84=E7=A7=8D?= =?UTF-8?q?=E8=AE=A1=E5=88=92=E5=AE=9E=E6=96=BD=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增两份项目核心文档： 1. platform-overview.md — 平台全景架构大纲（551 行） - RWADurian 1.0 认种分配系统 + 2.0 算力挖矿系统完整梳理 - 13 个微服务架构、核心业务流程、CDC 数据桥梁 - 推荐层级体系、代币与链上体系、安全运维要点 - 可作为开发、运维、新成员 onboarding 的单一事实来源 2. pre-planting-implementation-plan.md — 3171 预种计划实施方案（745 行） - 核心原则：纯新增，零侵入（现有代码文件一行不改） - 架构决策：planting-service 内独立模块，非新服务 - 完整的事件流、数据模型、API 设计 - 六大服务的实现步骤与变更文件清单 Co-Authored-By: Claude Opus 4.6 --- docs/platform-overview.md | 551 +++++++++++++++++ docs/pre-planting-implementation-plan.md | 745 +++++++++++++++++++++++ 2 files changed, 1296 insertions(+) create mode 100644 docs/platform-overview.md create mode 100644 docs/pre-planting-implementation-plan.md diff --git a/docs/platform-overview.md b/docs/platform-overview.md new file mode 100644 index 00000000..372ef1ac --- /dev/null +++ b/docs/platform-overview.md @@ -0,0 +1,551 @@ +# RWADurian 榴莲认种平台 — 全景架构大纲 + +> 本文档是对 RWADurian 1.0（认种分配系统）与 2.0（算力挖矿系统）的完整业务与技术梳理。 +> 可作为开发、运维、新成员 onboarding 的单一事实来源。 + +--- + +## 目录 + +1. [平台定位与核心概念](#1-平台定位与核心概念) +2. [系统全局拓扑](#2-系统全局拓扑) +3. [1.0 认种分配系统](#3-10-认种分配系统) + - 3.1 基础设施层 + - 3.2 后端服务清单（13 个微服务） + - 3.3 前端应用 + - 3.4 核心业务流程 +4. [2.0 算力挖矿系统](#4-20-算力挖矿系统) + - 4.1 部署模式 + - 4.2 后端服务清单（7 个微服务 + 1 前端） + - 4.3 核心业务流程 +5. [跨系统数据桥梁 — CDC](#5-跨系统数据桥梁--cdc) +6. [推荐层级体系](#6-推荐层级体系) +7. [认种与分配流程（1.0 核心）](#7-认种与分配流程10-核心) +8. [算力与挖矿流程（2.0 核心）](#8-算力与挖矿流程20-核心) +9. [代币与链上体系](#9-代币与链上体系) +10. [安全加固与运维要点](#10-安全加固与运维要点) +11. [关键文件索引](#11-关键文件索引) + +--- + +## 1. 平台定位与核心概念 + +| 概念 | 说明 | +|------|------| +| **RWADurian** | 一个以真实榴莲果树为底层资产的 RWA（Real World Asset）认种参与平台 | +| **认种（Planting）** | 用户花费 USDT 认种一棵果树，每棵树价格 15,831 USDT | +| **推荐关系（Referral）** | 用户通过推荐码邀请新用户，形成无限层级的树形结构 | +| **分配（Reward）** | 每笔认种产生的资金按 10 种权益类型分配给系统账户和上级链路用户 | +| **授权层级（Authorization）** | 根据团队业绩（认种量、省市占比）授予社区/省公司/市公司等经营资格 | +| **算力（Contribution）** | 1.0 认种行为通过 CDC 同步到 2.0，转化为用户的算力值 | +| **挖矿（Mining）** | 2.0 系统按算力占比进行每秒级 Share Token 分配，模拟"挖矿"收益 | +| **eUSDT / fUSDT** | 链上 ERC-20 代币，分别代表"积分股"和"积分值"，可在 2.0 交易市场流通 | + +--- + +## 2. 系统全局拓扑 + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ 用户端 │ +│ mobile-app (Flutter) mining-app (Flutter) │ +│ admin-web (Next.js 14) mining-admin-web (Next.js 14) │ +└──────────────┬─────────────────────────────┬────────────────────────────┘ + │ HTTPS / Kong Gateway │ HTTPS + ▼ ▼ +┌──────────────────────────────┐ ┌──────────────────────────────────────┐ +│ 1.0 认种分配系统 │ │ 2.0 算力挖矿系统 │ +│ docker-compose.yml │ │ docker-compose.2.0.yml │ +│ │ │ │ +│ 13 NestJS 微服务 │ │ 7 NestJS 微服务 + 1 前端 │ +│ ┌─────────────────────────┐ │ │ ┌──────────────────────────────┐ │ +│ │ identity │ referral │ │ │ │ auth │ contribution │ │ +│ │ wallet │ reward │ │ │ │ mining │ trading │ │ +│ │ planting │ authorize │ │ │ │ mining-admin│ mining-wallet │ │ +│ │ blockchain │ admin │ │ │ │ mining-blockchain │ │ +│ │ mpc │ backup │ │ │ └──────────────────────────────┘ │ +│ │ leaderboard│ presence │ │ │ │ +│ │ reporting │ │ │ │ mining-admin-web (Next.js) │ +│ └─────────────────────────┘ │ └──────────────────────────────────────┘ +│ │ ▲ +│ ┌─────────────────────────┐ │ │ CDC (Debezium → Kafka) +│ │ PostgreSQL 16 (13 DB) │─┼────────┘ +│ │ Redis 7 (DB 0-11) │ │ +│ │ Kafka 7.5 (单 Broker) │ │ ┌──────────────────────────────────────┐ +│ │ Debezium 2.5.4 │ │ │ 独立模式额外基础设施 │ +│ │ Zookeeper 7.5 │ │ │ postgres-2 / redis-2 / debezium-2 │ +│ └─────────────────────────┘ │ └──────────────────────────────────────┘ +│ │ +│ MPC System (Go, 9 服务) │ KAVA 主网 / BSC +└──────────────────────────────┘ 智能合约 (DurianUSDT, eUSDT, fUSDT) +``` + +--- + +## 3. 1.0 认种分配系统 + +### 3.1 基础设施层 + +| 组件 | 版本 | 端口 | 说明 | +|------|------|------|------| +| PostgreSQL | 16-alpine | 127.0.0.1:5432 | 13 个独立数据库，WAL logical 模式 | +| Redis | 7-alpine | 6379 | AOF 持久化，20 个 DB（DB 0-11 分配给各服务） | +| Kafka | 7.5.0 | 9092/9093/29092 | 单 Broker，auto-create topics | +| Zookeeper | 7.5.0 | 2181 | Kafka 协调 | +| Debezium | 2.5.4.Final | 127.0.0.1:8084 | CDC 连接器，ExtractNewRecordState SMT | + +**关键配置：** +- `max_slot_wal_keep_size=10GB` — 防止 WAL 无限积压（历史事故：305GB） +- `max_replication_slots=20` / `max_wal_senders=20` +- Kafka 9093 端口为远程 MPC 访问预留（192.168.1.111） + +### 3.2 后端服务清单 + +| 服务 | 端口 | Redis DB | 核心职责 | +|------|------|----------|----------| +| **identity-service** | 3000 | 0 | 用户注册/登录、KYC、SMS、头像、钱包地址创建 | +| **wallet-service** | 3001 | 1 | 钱包余额、冻结/解冻、充值/提现、区域账户 | +| **backup-service** | 3002 | — | 钱包私钥加密备份与恢复（限速 3次/天） | +| **planting-service** | 3003 | 2 | 认种订单创建 → 选省市 → 确认 → 支付 → 合同签署 | +| **referral-service** | 3004 | 3 | 推荐关系树、团队统计、龙虎榜分值计算 | +| **reward-service** | 3005 | 4 | 10 类权益分配、奖励待领/已领/过期状态机 | +| **mpc-service** | 3006 | 5 | MPC 密钥管理，桥接 Go 版 MPC System | +| **leaderboard-service** | 3007 | 6 | 用户排行榜 | +| **reporting-service** | 3008 | 7 | 系统账户报表聚合 | +| **authorization-service** | 3009 | 8 | 社区/省公司/市公司授权，月度考核评估 | +| **admin-service** | 3010 | 9 | 后台管理（版本、用户、CDC） | +| **presence-service** | 3011 | 10 | 用户在线状态（180s 窗口，60s 快照） | +| **blockchain-service** | 3012 | 11 | KAVA 链交互、充提监控、热钱包管理 | + +**MPC System（Go 语言，独立网络）：** +- account-service / session-coordinator / message-router / server-party / server-party-api 等 9 个服务 +- gRPC + WebSocket 通信 +- TSS（门限签名）实现多方安全计算 + +### 3.3 前端应用 + +| 应用 | 技术栈 | 说明 | +|------|--------|------| +| **mobile-app** | Flutter (Dart) | 用户端 APP，17 个功能模块（认种/充值/提现/KYC/排行/交易等） | +| **admin-web** | Next.js 14 + React | 管理后台（仪表盘、用户管理、订单管理） | +| **mobile-upgrade** | Next.js 14 | APP 版本管理 & OTA 更新服务器 | + +### 3.4 核心业务流程概览 + +``` +用户注册 → 获取推荐码 → 被推荐人注册（建立推荐关系） + ↓ + 用户充值 USDT（链上） + ↓ + 创建认种订单（选省市 → 支付 → 签合同） + ↓ + 触发 10 类权益分配（见第 7 章） + ↓ + CDC 同步到 2.0（算力 → 挖矿） +``` + +--- + +## 4. 2.0 算力挖矿系统 + +### 4.1 部署模式 + +| 模式 | 网络 | 基础设施 | 适用场景 | +|------|------|----------|----------| +| **Shared（默认）** | services_rwa-network | 复用 1.0 的 PG/Redis/Kafka | 同机部署 | +| **Standalone** | rwa-2-network | 独立 postgres-2/redis-2 + 远程 Kafka 9093 | 分机部署 | + +### 4.2 后端服务清单 + +| 服务 | 端口 | Redis DB | 核心职责 | +|------|------|----------|----------| +| **contribution-service** | 3020 | 10 | CDC 消费 → 算力计算 → 15 级 + 3 阶梯分配 | +| **mining-service** | 3021 | 16 | 按秒分配 Share Token、挖矿账户管理 | +| **trading-service** | 3022 | 12 | eUSDT/fUSDT 交易撮合、做市商 | +| **mining-admin-service** | 3023 | 13 | 挖矿后台管理、池账户（销毁池/挖矿池） | +| **auth-service** | 3024 | 14 | 2.0 认证，CDC 同步 1.0 用户 | +| **mining-wallet-service** | 3025 | 15 | KAVA 链钱包管理 | +| **mining-blockchain-service** | 3026 | 8 | 链上操作（eUSDT/fUSDT/USDT）、区块扫描 | +| **mining-admin-web** | 3100 | — | 挖矿管理后台（Next.js） | + +### 4.3 核心业务流程概览 + +``` +1.0 认种订单 (MINING_ENABLED) + ↓ Debezium CDC +contribution-service 消费 → 算力计算（个人70% + 团队15级7.5% + 奖励3阶7.5%） + ↓ Outbox Event +mining-service 同步算力 → 每秒按占比分配 Share Token + ↓ +trading-service 提供 eUSDT/fUSDT 交易市场 + ↓ +mining-blockchain-service 处理链上充提 +``` + +--- + +## 5. 跨系统数据桥梁 — CDC + +### 5.1 CDC 数据流 + +| 源（1.0 表） | Kafka Topic | 消费者（2.0） | 用途 | +|---------------|-------------|---------------|------| +| identity.user_accounts | `cdc.identity.public.user_accounts` | auth-service, admin-service, contribution-service | 同步用户注册 | +| identity.wallet_addresses | `cdc.identity.public.wallet_addresses` | auth-service | 同步钱包地址 | +| planting.planting_orders | `cdc.planting.public.planting_orders` | contribution-service | 同步认种订单 → 算力 | +| referral.referral_relationships | `cdc.referral.public.referral_relationships` | contribution-service | 同步推荐关系 → 团队算力 | + +### 5.2 CDC 消息格式（ExtractNewRecordState 展平后） + +```json +{ + "order_id": 1, + "tree_count": 1, + "account_sequence": "D25122700015", + "status": "MINING_ENABLED", + "__op": "c", + "__table": "planting_orders", + "__source_ts_ms": 1767892060857, + "__deleted": "false" +} +``` + +### 5.3 消费顺序保证（contribution-service） + +contribution-service 采用 **Collect-Sort-Process** 模式： +1. **Phase 1**: 消费 `cdc.identity.public.user_accounts`（全量用户） +2. **Phase 2**: 消费 `cdc.referral.public.referral_relationships`（全量推荐关系） +3. **Phase 3**: 消费 `cdc.planting.public.planting_orders`（收集 → 按 order_id 排序 → 顺序处理） + +**严格顺序的原因**：计算团队算力必须先有推荐关系数据，否则分配错误。 + +### 5.4 幂等性保证 + +``` +每条 CDC 消息 → INSERT ProcessedCdcEvent(topic, offset) + → 若 UNIQUE 冲突则跳过 + → 业务逻辑在同一事务内执行 + → Serializable 隔离级别 +``` + +--- + +## 6. 推荐层级体系 + +### 6.1 数据模型 + +``` +ReferralRelationship（不可变） +├── userId / accountSequence（唯一标识） +├── referrerId（直接推荐人，null = 根节点） +├── ancestorPath: BigInt[]（从直接推荐人到根的链路） +├── depth（链路深度，0 = 根节点） +├── myReferralCode / usedReferralCode +└── directReferralCount / activeDirectCount + +TeamStatistics（实时更新） +├── selfPlantingCount / selfPlantingAmount +├── totalTeamPlantingCount / totalTeamPlantingAmount +├── maxSingleTeamPlantingCount（最大单腿） +├── effectivePlantingCountForRanking（龙虎榜分值） +└── provinceCityDistribution: JSON +``` + +### 6.2 推荐树结构示例 + +``` +Root (depth=0, ancestorPath=[]) +├── A (depth=1, ancestorPath=[Root]) +│ ├── B (depth=2, ancestorPath=[A, Root]) +│ │ └── D (depth=3, ancestorPath=[B, A, Root]) +│ └── C (depth=2, ancestorPath=[A, Root]) +└── E (depth=1, ancestorPath=[Root]) +``` + +### 6.3 龙虎榜分值公式 + +``` +effectivePlantingCountForRanking = totalTeamPlantingCount - maxSingleTeamPlantingCount +``` + +**设计目的**：鼓励均衡发展，防止"单腿烧伤"。 + +### 6.4 授权层级与考核 + +| 层级 | 要求 | 权益 | +|------|------|------| +| **社区（Community）** | 直推 ≥5，认种 ≥500 棵 | 社区权益分配 576 USDT/棵 | +| **市公司（City）** | 团队 ≥10,000 棵，本市占比 ≥50% | 市团队 288 + 市区域 252 USDT/棵 | +| **省公司（Province）** | 团队 ≥20,000 棵，本省占比 ≥60% | 省团队 144 + 省区域 108 USDT/棵 | + +**月度考核**：authorization-service 每月评估，根据阶梯目标判断是否保留/降级授权。 + +--- + +## 7. 认种与分配流程（1.0 核心） + +### 7.1 认种订单生命周期 + +``` +CREATED → 选省市 → 确认省市 → PAID（冻结资金）→ 合同签署 → 确认扣款 → 分配触发 + │ │ + │ contract.signed ✓ + │ contract.expired ✗ → 权益归系统 + │ + Outbox 发布事件: + planting.planting.created → referral-service + planting-events → authorization-service +``` + +### 7.2 三阶段支付安全机制 + +| 阶段 | 操作 | 说明 | +|------|------|------| +| **冻结** | wallet.freezeForPlanting() | 资金不可用但未扣除 | +| **合同** | 等待 contract.signed / expired | 24 小时签署窗口 | +| **确认** | wallet.confirmPlantingDeduction() | 冻结 → 实际扣款，触发分配 | + +### 7.3 十类权益分配（每棵树 15,831 USDT） + +#### 系统费用（自动分配，10,863 USDT） + +| # | 类型 | 金额 | 目标账户 | +|---|------|------|----------| +| 1 | 成本费 | 2,800 | S0000000002 | +| 2 | 运营费 | 2,100 | S0000000003 | +| 3 | 总部基金 | 203 | S0000000001 | +| 4 | RWAD 底池 | 5,760 | S0000000004 | + +#### 用户权益（基于推荐链，4,968 USDT + 算力） + +| # | 类型 | 金额 | 分配对象 | 附加 | +|---|------|------|----------|------| +| 5 | 分享权益 | 3,600 | 直接推荐人 | 无推荐人 → S0000000005 | +| 6 | 省团队权益 | 144 | 链路中最近的省公司授权者 | — | +| 7 | 省区域权益 | 108 | 被授权省份 | +1% 算力 | +| 8 | 市团队权益 | 288 | 链路中最近的市公司授权者 | — | +| 9 | 市区域权益 | 252 | 被授权城市 | +2% 算力 | +| 10 | 社区权益 | 576 | 链路中最近的社区管理者 | — | + +### 7.4 奖励状态机 + +``` +PENDING（24h 倒计时） + ├─ 用户再次认种 → SETTLEABLE（可结算） + │ └─ 用户主动结算 → SETTLED（已结算，入钱包余额） + └─ 24h 超时未领取 → EXPIRED（过期，归总部社区） +``` + +### 7.5 Kafka 事件流 + +``` +planting-service ──planting.planting.created──→ referral-service + │ + 更新团队统计 + 等待合同 + │ + contract.signed / expired + │ + confirmDeduction → wallet + │ + ┌─ planting.order.paid ──→ reward-service → distributeRewards() + └─ planting.order.expired → reward-service → 权益归系统账户 +``` + +--- + +## 8. 算力与挖矿流程（2.0 核心） + +### 8.1 算力（Contribution）计算 + +**触发**：1.0 认种订单状态变为 `MINING_ENABLED` 时，通过 CDC 同步到 contribution-service。 + +#### 算力分配比例 + +| 来源 | 比例 | 说明 | +|------|------|------| +| **个人算力（PERSONAL）** | 70% | 认种即生效 | +| **团队层级（TEAM_LEVEL）** | 7.5% | 15 级，每级 0.5% | +| **团队奖励（TEAM_BONUS）** | 7.5% | 3 阶梯，每阶 2.5% | +| **运营费** | 12% | 系统账户 | +| **省公司** | 1% | 省区域系统账户 | +| **市公司** | 2% | 市区域系统账户 | + +#### 团队算力解锁条件 + +| 层级 | 条件 | +|------|------| +| Level 1-5（2.5%） | 用户自己有认种即可 | +| Level 6-10（2.5%） | 直推 ≥3 人且有认种 | +| Level 11-15（2.5%） | 直推 ≥5 人且有认种 | +| Bonus Tier 1（2.5%） | 用户自己有认种 | +| Bonus Tier 2（2.5%） | 直推 ≥2 人且有认种 | +| Bonus Tier 3（2.5%） | 直推 ≥4 人且有认种 | + +#### 每棵树算力值 + +``` +contribution_per_tree = 22617 × (1 + currentUnit × 0.003) + +currentUnit 每 100 棵全网认种递增一次： + Trees 1-999: unit=0, multiplier=1.000 + Trees 1000-1099: unit=1, multiplier=1.003 + Trees 1100-1199: unit=2, multiplier=1.006 + ... +``` + +### 8.2 挖矿（Mining）分配 + +**全局参数：** + +| 参数 | 值 | +|------|------| +| 总份额 | 100.02 亿 Share | +| 初始分配池 | 2 亿 Share | +| 减半周期 | 2 年（63,072,000 秒） | + +**分配公式：** + +``` +每秒全网分配量 = secondDistribution（随时代递减） + +用户每秒挖矿 = secondDistribution × (用户有效算力 / 全网总算力) + +有效算力 = 个人算力 + 已解锁的团队算力 +``` + +**挖矿价格：** + +``` +price = sharePool / (TOTAL_SHARES - blackHole - circulationPool) +``` + +### 8.3 交易市场 + +- **eUSDT（积分股）**：代表挖矿产出的 Share Token 对应价值 +- **fUSDT（积分值）**：代表未来价值 +- trading-service 提供 eUSDT/fUSDT 交易撮合 +- 做市商账户由 mining-admin-service 管理 +- **销毁池（Burn Pool）**：100 亿 Token +- **挖矿池（Mining Pool）**：200 万 Token + +--- + +## 9. 代币与链上体系 + +### 9.1 链上合约 + +| 合约 | 链 | 地址 | +|------|------|------| +| dUSDT (DurianUSDT) | KAVA | 0xA9F3A35dBa8699c8C681D8db03F0c1A8CEB9D7c3 | +| eUSDT (Energy USDT) | KAVA | 0x7C3275D808eFbAE90C06C7E3A9AfDdcAa8563931 | +| fUSDT (Future USDT) | KAVA | 0x14dc4f7d3E4197438d058C3D156dd9826A161134 | +| USDT (BSC 备用) | BSC | 0x55d398326f99059fF775485246999027B3197955 | + +### 9.2 MPC 多方计算钱包 + +- Go 语言实现，9 个服务组件 +- TSS（门限签名）保障私钥安全 +- 用户无需直接管理私钥，通过 MPC 协议完成签名 +- 热钱包提现由 blockchain-service 调度 + +### 9.3 区块扫描 + +- 扫描间隔：5 秒 +- 确认块数：12 块 +- RPC 故障自动切换（4 个 KAVA RPC 端点，3 分钟切换） + +--- + +## 10. 安全加固与运维要点 + +### 10.1 端口安全 + +| 服务 | 绑定 | 说明 | +|------|------|------| +| PostgreSQL | 127.0.0.1:5432 | 仅本地访问 | +| Debezium REST | 127.0.0.1:8084 | 防 SSRF（历史事故：3 个恶意连接器注入） | +| Redis | 127.0.0.1:6379 | 仅本地访问 | + +### 10.2 WAL 安全 + +- `max_slot_wal_keep_size=10GB` — 上限防 WAL 爆盘（历史事故：305GB） +- `OFFSET_FLUSH_INTERVAL_MS=10000` — Debezium 偏移刷新加速 + +### 10.3 密钥管理 + +- JWT_SECRET / SERVICE_JWT_SECRET — 服务间认证 +- MPC_JWT_SECRET — MPC 系统认证 +- WALLET_ENCRYPTION_SALT — 钱包加密 +- SHARE_MASTER_KEY — MPC 主密钥 +- Aliyun API Keys — SMS / KYC 三方服务 + +### 10.4 可靠性模式 + +| 模式 | 说明 | +|------|------| +| **Outbox Pattern** | 数据库事务 + 事件发布原子性，指数退避重试（最长 4 小时） | +| **Idempotency** | ProcessedEvent + ProcessedCdcEvent 表防重复消费 | +| **Compensation** | payment_compensations 表处理冻结失败/确认失败/分配失败 | +| **Health Check** | 所有服务 /api/v1/health 或 /api/v2/health，30s 间隔 | +| **Restart Policy** | unless-stopped 自动重启 | + +--- + +## 11. 关键文件索引 + +### 11.1 编排文件 + +| 文件 | 用途 | +|------|------| +| `backend/services/docker-compose.yml` | 1.0 系统全量编排（13 服务 + 基础设施） | +| `docker-compose.2.0.yml` | 2.0 系统编排（7 服务 + 前端 + 可选基础设施） | +| `backend/mpc-system/docker-compose.yml` | MPC 系统编排 | + +### 11.2 核心业务代码 + +| 路径 | 说明 | +|------|------| +| `backend/services/planting-service/src/application/` | 认种订单业务逻辑 | +| `backend/services/reward-service/src/application/` | 分配计算与奖励状态机 | +| `backend/services/referral-service/src/application/` | 推荐关系与团队统计 | +| `backend/services/authorization-service/src/application/` | 授权层级与月度考核 | +| `backend/services/contribution-service/src/application/` | 算力计算与 CDC 消费 | +| `backend/services/mining-service/src/domain/services/` | 挖矿分配算法 | +| `backend/services/wallet-service/src/application/` | 钱包操作（冻结/解冻/分配） | +| `backend/services/blockchain-service/src/` | 链上交互与区块扫描 | + +### 11.3 数据库 Schema + +| 路径 | 说明 | +|------|------| +| `backend/services/*/prisma/schema.prisma` | 各服务 Prisma Schema | +| `backend/services/scripts/init-databases.sh` | 13 个数据库初始化脚本 | + +### 11.4 前端入口 + +| 路径 | 说明 | +|------|------| +| `frontend/mobile-app/lib/main.dart` | Flutter 用户端入口 | +| `frontend/mobile-app/lib/features/` | 17 个功能模块 | +| `frontend/admin-web/src/app/` | Next.js 管理后台 | +| `frontend/mining-admin-web/src/app/` | Next.js 挖矿后台 | + +### 11.5 智能合约 + +| 路径 | 说明 | +|------|------| +| `contracts/DurianUSDT.sol` | ERC-20 代币合约 | +| `contracts/build/DurianUSDT.abi` | 编译后 ABI | + +--- + +## 附录：账户编号规则 + +| 格式 | 示例 | 说明 | +|------|------|------| +| D + YYMMDD + 5位序号 | D25121400002 | 用户账户 | +| S + 10位序号 | S0000000001 | 系统账户（总部/成本/运营/底池） | +| 9 + 省代码 | 9440000 | 省级系统账户 | +| 8 + 市代码 | 8440100 | 市级系统账户 | +| 7 + 省代码 | 7440000 | 省团队默认账户 | +| 6 + 市代码 | 6440100 | 市团队默认账户 | diff --git a/docs/pre-planting-implementation-plan.md b/docs/pre-planting-implementation-plan.md new file mode 100644 index 00000000..01435ccd --- /dev/null +++ b/docs/pre-planting-implementation-plan.md @@ -0,0 +1,745 @@ +# 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 份 → 凑满合并