# 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 | 市团队默认账户 |