# 树转让功能详细实施方案

> 版本：v1.0 | 日期：2026-02-18 | 状态：待审批

---

## 一、概述与设计原则

### 1.1 功能目标

实现已认种树（状态为 `MINING_ENABLED`）在用户间的所有权转让，包括：
- 持仓变更（planting-service）
- 算力增量调整（contribution-service）
- 团队统计增减（referral-service）
- 资金结算（wallet-service）

### 1.2 核心设计原则

| # | 原则 | 说明 |
|---|------|------|
| 1 | **纯新增** | 各现有服务只新增事件消费者、方法、数据表，不修改已有业务逻辑 |
| 2 | **事务流水型** | 所有算力变动通过追加新流水记录实现，历史记录零修改、零删除 |
| 3 | **保持原始值** | 转让时沿用树的原始 `contributionPerTree`，不按转让日重算 |
| 4 | **历史不追回** | 已分配给卖方链路的历史算力记录保持不变，只从转让时刻起追加对冲/新增流水 |
| 5 | **可回滚** | Saga 编排每一步都有对应的补偿操作 |
| 6 | **奖励不重分** | reward-service 的历史分配记录（USDT 权益）不受转让影响 |
| 7 | **运营算力不动** | 仅运营账户 12% 为全局固定分配不受影响；省公司 1% 和市公司 2% 需随所有权变更调整 |
| 8 | **快照自动适配** | 挖矿快照每日按最新 effectiveContribution 全量生成，无需特殊处理 |

### 1.3 转让单位

- 转让以 **PlantingOrder（认种订单）** 为单位
- 支持整单转让（全部树）和部分转让（订单内指定棵数）
- 部分转让时，原订单不修改，通过 TransferRecord 追踪已转出的棵数

### 1.4 转让资格

- 卖方：树状态为 `MINING_ENABLED` 且未被锁定
- 买方：已完成实名认证的平台用户
- 同一棵树可多次转让（每次创建新的转让记录）

---

## 二、transfer-service 新微服务设计

### 2.1 服务概要

| 项目 | 值 |
|------|-----|
| 服务名 | transfer-service |
| 容器名 | rwa-transfer-service |
| 端口 | 3013 |
| Redis DB | 12 |
| 数据库 | rwa_transfer |
| 技术栈 | NestJS 10 + Prisma 5.7 + PostgreSQL 16 |
| Kafka Consumer Group | transfer-service-group |

### 2.2 数据模型

#### TransferOrder（转让订单 - Saga 聚合根）

```prisma
model TransferOrder {
  id                     BigInt    @id @default(autoincrement())
  transferOrderNo        String    @unique @map("transfer_order_no") @db.VarChar(50)

  // ========== 卖方信息 ==========
  sellerUserId           BigInt    @map("seller_user_id")
  sellerAccountSequence  String    @map("seller_account_sequence") @db.VarChar(20)

  // ========== 买方信息 ==========
  buyerUserId            BigInt    @map("buyer_user_id")
  buyerAccountSequence   String    @map("buyer_account_sequence") @db.VarChar(20)

  // ========== 转让标的 ==========
  sourceOrderNo          String    @map("source_order_no") @db.VarChar(50)      // 原认种订单号
  sourceAdoptionId       BigInt    @map("source_adoption_id")                    // 原认种ID
  treeCount              Int       @map("tree_count")                            // 转让棵数
  contributionPerTree    Decimal   @map("contribution_per_tree") @db.Decimal(20, 10) // 原始每棵算力值
  originalAdoptionDate   DateTime  @map("original_adoption_date") @db.Date       // 原始认种日期
  originalExpireDate     DateTime  @map("original_expire_date") @db.Date         // 原始算力到期日
  selectedProvince       String    @map("selected_province") @db.VarChar(10)     // 树所在省
  selectedCity           String    @map("selected_city") @db.VarChar(10)         // 树所在市

  // ========== 价格与费用 ==========
  transferPrice          Decimal   @map("transfer_price") @db.Decimal(20, 8)     // 转让总价（USDT）
  platformFeeRate        Decimal   @map("platform_fee_rate") @db.Decimal(5, 4)   // 平台手续费率
  platformFeeAmount      Decimal   @map("platform_fee_amount") @db.Decimal(20, 8) // 平台手续费
  sellerReceiveAmount    Decimal   @map("seller_receive_amount") @db.Decimal(20, 8) // 卖方实收

  // ========== Saga 状态 ==========
  status                 String    @default("PENDING") @map("status") @db.VarChar(30)
  sagaStep               String    @default("INIT") @map("saga_step") @db.VarChar(30)
  failReason             String?   @map("fail_reason") @db.VarChar(500)
  retryCount             Int       @default(0) @map("retry_count")

  // ========== 各步骤确认时间戳 ==========
  sellerConfirmedAt      DateTime? @map("seller_confirmed_at")
  paymentFrozenAt        DateTime? @map("payment_frozen_at")
  treesLockedAt          DateTime? @map("trees_locked_at")
  ownershipTransferredAt DateTime? @map("ownership_transferred_at")
  contributionAdjustedAt DateTime? @map("contribution_adjusted_at")
  statsUpdatedAt         DateTime? @map("stats_updated_at")
  paymentSettledAt       DateTime? @map("payment_settled_at")
  completedAt            DateTime? @map("completed_at")
  cancelledAt            DateTime? @map("cancelled_at")
  rolledBackAt           DateTime? @map("rolled_back_at")

  createdAt              DateTime  @default(now()) @map("created_at")
  updatedAt              DateTime  @updatedAt @map("updated_at")

  @@index([sellerUserId])
  @@index([buyerUserId])
  @@index([sourceOrderNo])
  @@index([status])
  @@index([createdAt])
  @@map("transfer_orders")
}
```

#### TransferStatusLog（状态变更日志 - 审计）

```prisma
model TransferStatusLog {
  id               BigInt   @id @default(autoincrement())
  transferOrderNo  String   @map("transfer_order_no") @db.VarChar(50)
  fromStatus       String   @map("from_status") @db.VarChar(30)
  toStatus         String   @map("to_status") @db.VarChar(30)
  fromSagaStep     String   @map("from_saga_step") @db.VarChar(30)
  toSagaStep       String   @map("to_saga_step") @db.VarChar(30)
  operatorType     String   @map("operator_type") @db.VarChar(20)   // USER / SYSTEM / ADMIN
  operatorId       String?  @map("operator_id") @db.VarChar(50)
  remark           String?  @db.VarChar(500)
  createdAt        DateTime @default(now()) @map("created_at")

  @@index([transferOrderNo])
  @@map("transfer_status_logs")
}
```

#### OutboxEvent（复用标准 Outbox 结构）

与其他服务完全相同的 Outbox 表结构。

### 2.3 Saga 状态机

#### TransferOrderStatus 枚举

```
PENDING              - 待卖方确认
SELLER_CONFIRMED     - 卖方已确认
PAYMENT_FROZEN       - 买方资金已冻结
TREES_LOCKED         - 卖方树已锁定
OWNERSHIP_TRANSFERRED - 所有权已变更
CONTRIBUTION_ADJUSTED - 算力已调整
STATS_UPDATED        - 团队统计已更新
PAYMENT_SETTLED      - 资金已结算
COMPLETED            - 转让完成

CANCELLED            - 已取消（PENDING/SELLER_CONFIRMED 阶段可取消）
FAILED               - 失败
ROLLING_BACK         - 补偿中
ROLLED_BACK          - 已回滚
```

#### SagaStep 枚举（编排步骤）

```
INIT                     - 初始化
FREEZE_BUYER_PAYMENT     - 冻结买方资金
LOCK_SELLER_TREES        - 锁定卖方树
TRANSFER_OWNERSHIP       - 变更所有权
ADJUST_CONTRIBUTION      - 调整算力
UPDATE_TEAM_STATS        - 更新团队统计
SETTLE_PAYMENT           - 结算资金
FINALIZE                 - 完成

COMPENSATE_UNLOCK_TREES  - 补偿：解锁树
COMPENSATE_UNFREEZE      - 补偿：解冻资金
```

#### 状态机流转图

```
用户发起转让
    ↓
PENDING (INIT)
    ↓ 卖方确认
SELLER_CONFIRMED (FREEZE_BUYER_PAYMENT)
    ↓ 冻结买方资金 → wallet-service
PAYMENT_FROZEN (LOCK_SELLER_TREES)
    ↓ 锁定卖方树 → planting-service
TREES_LOCKED (TRANSFER_OWNERSHIP)
    ↓ 变更所有权 → planting-service（发布事件）
OWNERSHIP_TRANSFERRED (ADJUST_CONTRIBUTION)
    ↓ 等待 contribution-service 确认（事件驱动）
CONTRIBUTION_ADJUSTED (UPDATE_TEAM_STATS)
    ↓ 等待 referral-service 确认（事件驱动）
STATS_UPDATED (SETTLE_PAYMENT)
    ↓ 结算资金 → wallet-service
PAYMENT_SETTLED (FINALIZE)
    ↓
COMPLETED

失败补偿路径（任何步骤失败）：
  FAILED → ROLLING_BACK
    → COMPENSATE_UNLOCK_TREES（如果树已锁定）
    → COMPENSATE_UNFREEZE（如果资金已冻结）
    → ROLLED_BACK
```

### 2.4 API 设计

#### 用户端 API

```
POST   /transfers                    - 发起转让（买方向卖方购买）
POST   /transfers/:id/seller-confirm - 卖方确认
POST   /transfers/:id/cancel         - 取消转让
GET    /transfers                    - 查询我的转让记录（买/卖）
GET    /transfers/:id                - 转让详情
```

#### 管理端 API

```
GET    /admin/transfers              - 转让列表（筛选、分页）
GET    /admin/transfers/:id          - 转让详情
GET    /admin/transfers/stats        - 转让统计
POST   /admin/transfers/:id/force-cancel - 强制取消
```

### 2.5 转让号生成规则

```
TRF + YYMMDD + 随机字符串（8位）
示例：TRF260218A3B7C9D1
```

---

## 三、planting-service 纯新增设计

### 3.1 新增数据表

#### PlantingTransferRecord（转让记录）

```prisma
model PlantingTransferRecord {
  id                     BigInt    @id @default(autoincrement())
  transferOrderNo        String    @unique @map("transfer_order_no") @db.VarChar(50)

  // ========== 原订单信息 ==========
  sourceOrderNo          String    @map("source_order_no") @db.VarChar(50)
  sourceOrderId          BigInt    @map("source_order_id")

  // ========== 卖方 ==========
  fromUserId             BigInt    @map("from_user_id")
  fromAccountSequence    String    @map("from_account_sequence") @db.VarChar(20)

  // ========== 买方 ==========
  toUserId               BigInt    @map("to_user_id")
  toAccountSequence      String    @map("to_account_sequence") @db.VarChar(20)

  // ========== 转让内容 ==========
  treeCount              Int       @map("tree_count")
  selectedProvince       String    @map("selected_province") @db.VarChar(10)
  selectedCity           String    @map("selected_city") @db.VarChar(10)
  contributionPerTree    Decimal   @map("contribution_per_tree") @db.Decimal(20, 10)
  originalAdoptionDate   DateTime  @map("original_adoption_date") @db.Date
  originalExpireDate     DateTime  @map("original_expire_date") @db.Date

  // ========== 状态 ==========
  status                 String    @default("LOCKED") @map("status") @db.VarChar(20)
  // LOCKED → TRANSFERRED → ROLLED_BACK

  lockedAt               DateTime? @map("locked_at")
  transferredAt          DateTime? @map("transferred_at")
  rolledBackAt           DateTime? @map("rolled_back_at")
  createdAt              DateTime  @default(now()) @map("created_at")

  @@index([sourceOrderNo])
  @@index([fromUserId])
  @@index([toUserId])
  @@index([status])
  @@map("planting_transfer_records")
}
```

### 3.2 PlantingOrder 新增字段

在 PlantingOrder 表上新增一个字段用于标记转让锁定状态（通过 Prisma migration 新增列）：

```prisma
// 新增字段（可空，不影响现有数据）
transferLockedCount    Int       @default(0) @map("transfer_locked_count")  // 被锁定的转让棵数
```

**可转让棵数** = `treeCount - transferLockedCount - 已完成转让的棵数`

已完成转让的棵数通过查询 `PlantingTransferRecord` 表（status = TRANSFERRED）聚合得到。

### 3.3 新增事件消费处理器

#### transfer-lock.handler.ts（锁定树）

- **消费 Topic**：`transfer.trees.lock`
- **处理逻辑**：
  1. 验证卖方持有该订单且有足够可转让棵数
  2. 创建 `PlantingTransferRecord`（status = LOCKED）
  3. 更新 `PlantingOrder.transferLockedCount += treeCount`
  4. 发布确认事件到 `transfer.trees.lock.ack`

#### transfer-execute.handler.ts（执行所有权变更）

- **消费 Topic**：`transfer.ownership.execute`
- **处理逻辑**：
  1. 查找对应的 `PlantingTransferRecord`
  2. 更新 `PlantingTransferRecord.status = TRANSFERRED`
  3. 更新卖方 `PlantingPosition`：
     - `effectiveTreeCount -= treeCount`
     - `totalTreeCount -= treeCount`
  4. 更新卖方 `PositionDistribution`（对应省市的持仓数 -= treeCount）
  5. 更新/创建买方 `PlantingPosition`：
     - `effectiveTreeCount += treeCount`
     - `totalTreeCount += treeCount`
  6. 更新/创建买方 `PositionDistribution`（对应省市的持仓数 += treeCount）
  7. 发布 Outbox 事件（3 个）：
     - `planting.transfer.completed`（通知 transfer-service）
     - `planting.ownership.removed`（通知 contribution + referral）
     - `planting.ownership.added`（通知 contribution + referral）

#### transfer-rollback.handler.ts（回滚锁定）

- **消费 Topic**：`transfer.trees.unlock`
- **处理逻辑**：
  1. 查找对应的 `PlantingTransferRecord`
  2. 更新 `PlantingTransferRecord.status = ROLLED_BACK`
  3. 更新 `PlantingOrder.transferLockedCount -= treeCount`
  4. 发布确认事件到 `transfer.trees.unlock.ack`

### 3.4 新增 Outbox 事件

| 事件 | Topic | AggregateType | Payload |
|------|-------|---------------|---------|
| `PlantingTransferLocked` | `planting.transfer.locked` | `PlantingTransfer` | transferOrderNo, sourceOrderNo, treeCount |
| `PlantingTransferCompleted` | `planting.transfer.completed` | `PlantingTransfer` | transferOrderNo, 完整卖方/买方信息 |
| `PlantingOwnershipRemoved` | `planting.ownership.removed` | `PlantingTransfer` | 卖方信息 + 树信息 |
| `PlantingOwnershipAdded` | `planting.ownership.added` | `PlantingTransfer` | 买方信息 + 树信息 |
| `PlantingTransferRolledBack` | `planting.transfer.rolledback` | `PlantingTransfer` | transferOrderNo |

---

## 四、referral-service 纯新增设计

### 4.1 新增事件处理器

#### planting-transferred.handler.ts

- **消费 Topic**：`planting.ownership.removed` + `planting.ownership.added`
- **Consumer Group**：`referral-service-transfer`

### 4.2 处理 planting.ownership.removed（卖方减少）

```typescript
async handleOwnershipRemoved(event: PlantingOwnershipRemovedEvent): Promise<void> {
  // 1. 更新卖方个人认种统计
  const sellerStats = await this.teamStatsRepo.findByUserId(event.sellerUserId);
  sellerStats.removePersonalPlanting(event.treeCount, event.provinceCode, event.cityCode);
  //   selfPlantingCount -= treeCount
  //   selfPlantingAmount -= treeCount * pricePerTree
  //   provinceCityDistribution 对应省市 -= treeCount
  await this.teamStatsRepo.save(sellerStats);

  // 2. 获取卖方的上级链
  const relationship = await this.referralRepo.findByUserId(event.sellerUserId);
  const ancestors = relationship.getAllAncestorIds();

  // 3. 批量更新上级团队统计（负数 delta）
  const updates = ancestors.map((ancestorId, i) => ({
    userId: ancestorId,
    countDelta: -event.treeCount,          // 关键：负数
    provinceCode: event.provinceCode,
    cityCode: event.cityCode,
    fromDirectReferralId: i === 0 ? event.sellerUserId : ancestors[0],
  }));

  await this.teamStatsRepo.batchUpdateTeamCountsForTransfer(updates);
  //   totalTeamPlantingCount -= treeCount
  //   DirectReferral.teamPlantingCount -= treeCount（increment 负数）
  //   重新扫描所有直推的 teamPlantingCount 找新 max（关键修正）
  //   effectivePlantingCountForRanking = totalTeamPlantingCount - newMax
}
```

### 4.3 处理 planting.ownership.added（买方增加）

```typescript
async handleOwnershipAdded(event: PlantingOwnershipAddedEvent): Promise<void> {
  // 1. 更新买方个人认种统计
  const buyerStats = await this.teamStatsRepo.findByUserId(event.buyerUserId);
  buyerStats.addPersonalPlanting(event.treeCount, event.provinceCode, event.cityCode);
  await this.teamStatsRepo.save(buyerStats);

  // 2. 获取买方的上级链
  const relationship = await this.referralRepo.findByUserId(event.buyerUserId);
  const ancestors = relationship.getAllAncestorIds();

  // 3. 批量更新上级团队统计（正数 delta，复用现有 batchUpdateTeamCounts）
  const updates = ancestors.map((ancestorId, i) => ({
    userId: ancestorId,
    countDelta: event.treeCount,           // 正数
    provinceCode: event.provinceCode,
    cityCode: event.cityCode,
    fromDirectReferralId: i === 0 ? event.buyerUserId : ancestors[0],
  }));

  await this.teamStatsRepo.batchUpdateTeamCounts(updates);  // 复用现有方法
}
```

### 4.4 新增方法

#### TeamStatistics.removePersonalPlanting()（聚合根新增方法）

```typescript
removePersonalPlanting(count: number, provinceCode: string, cityCode: string): void {
  this._selfPlantingCount = Math.max(0, this._selfPlantingCount - count);
  this._selfPlantingAmount = this._selfPlantingAmount.minus(count * PRICE_PER_TREE);

  // 更新省市分布
  const dist = this._provinceCityDistribution;
  if (dist[provinceCode]?.[cityCode]) {
    dist[provinceCode][cityCode] = Math.max(0, dist[provinceCode][cityCode] - count);
  }

  this._updatedAt = new Date();
}
```

#### TeamStatisticsRepository.batchUpdateTeamCountsForTransfer()（新增方法）

与现有 `batchUpdateTeamCounts` 逻辑类似，但在处理负数 delta 时：

```typescript
// 关键差异：负数 delta 时重新扫描所有直推找 max
if (update.countDelta < 0) {
  // 更新直推的 teamPlantingCount（允许负数 increment）
  await tx.directReferral.updateMany({
    where: { referrerId: update.userId, referralId: update.fromDirectReferralId },
    data: { teamPlantingCount: { increment: update.countDelta } },
  });

  // 重新扫描所有直推的 teamPlantingCount 找最大值
  const allDirectReferrals = await tx.directReferral.findMany({
    where: { referrerId: update.userId },
    select: { teamPlantingCount: true },
  });
  const newMax = Math.max(0, ...allDirectReferrals.map(r => r.teamPlantingCount));

  const newTotal = currentStats.totalTeamPlantingCount + update.countDelta;
  const newEffective = Math.max(0, newTotal - newMax);

  await tx.teamStatistics.update({
    where: { userId: update.userId },
    data: {
      totalTeamPlantingCount: Math.max(0, newTotal),
      maxSingleTeamPlantingCount: newMax,
      effectivePlantingCountForRanking: newEffective,
    },
  });
}
```

### 4.5 发布确认事件

处理完成后发布事件到 `referral.transfer.stats-updated`，供 transfer-service 确认 Saga 步骤。

---

## 五、contribution-service 纯新增设计（核心）

### 5.1 算力调整原则

```
原则一：历史记录不修改、不删除
原则二：所有调整通过追加新流水记录实现（对冲式）
原则三：保持原始 contributionPerTree，沿用原认种参数
原则四：新记录的 expireDate = 原始认种的 expireDate（剩余有效期）
原则五：解锁状态需要更新（影响未来新认种的分配，但不追回历史）
原则六：调整 88%（个人70% + 团队层级7.5% + 个人加成7.5% + 省1% + 市2%），仅运营12% 不动
原则七：挖矿快照每日按最新 effectiveContribution 自动生成，无需干预
```

### 5.1.1 算力影响范围明确界定

| 算力类别 | 比例 | 分配对象 | 转让时需调整？ | 原因 |
|---------|------|---------|:---:|------|
| 个人算力 | 70% | 认种人 | **是** | 所有权转移，算力跟着树走 |
| 团队层级 | 7.5% | 认种人 15 级上线 | **是** | 上线链从卖方链路换成买方链路 |
| 个人加成 | 7.5% | 认种人（T1/T2/T3） | **是** | 所有权转移，加成跟着树走 |
| 省公司 | 1% | 按树所在省的系统账户 | **是** | 所有权变更，省公司授权体系随新所有者调整 |
| 市公司 | 2% | 按树所在市的系统账户 | **是** | 所有权变更，市公司授权体系随新所有者调整 |
| 运营账户 | 12% | OPERATION 系统账户 | **否** | 全局固定分配，与用户和地域无关 |

**结论**：转让需处理 88% 的算力调整，仅运营账户 12% 完全不受影响。

### 5.2 新增 sourceType 枚举值

在现有 ContributionRecord 的 sourceType 基础上新增：

```
// 转让转出（卖方侧，金额为负）
TRANSFER_OUT_PERSONAL        - 卖方个人算力转出
TRANSFER_OUT_TEAM_LEVEL      - 卖方上线团队层级算力转出
TRANSFER_OUT_BONUS           - 卖方个人加成算力转出

// 转让转入（买方侧，金额为正）
TRANSFER_IN_PERSONAL         - 买方个人算力转入
TRANSFER_IN_TEAM_LEVEL       - 买方上线团队层级算力转入
TRANSFER_IN_BONUS            - 买方个人加成算力转入

// 系统账户调整（省公司 1% + 市公司 2%，随所有权变更）
TRANSFER_OUT_SYSTEM_PROVINCE - 卖方省公司系统账户算力转出
TRANSFER_OUT_SYSTEM_CITY     - 卖方市公司系统账户算力转出
TRANSFER_IN_SYSTEM_PROVINCE  - 买方省公司系统账户算力转入
TRANSFER_IN_SYSTEM_CITY      - 买方市公司系统账户算力转入

// 注意：仅运营账户 12% 为全局固定分配，不受转让影响
```

### 5.3 ContributionRecord 新增字段

```prisma
// 新增可空字段（不影响现有数据）
transferOrderNo    String? @map("transfer_order_no") @db.VarChar(50)  // 关联转让订单号
```

### 5.4 卖方算力扣减流水（planting.ownership.removed 事件处理）

#### 5.4.1 个人算力扣减

```typescript
// 创建一条负数流水
ContributionRecord.create({
  accountSequence: seller.accountSequence,
  sourceType: 'TRANSFER_OUT_PERSONAL',
  sourceAdoptionId: originalAdoptionId,
  sourceAccountSequence: seller.accountSequence,
  treeCount: transferTreeCount,
  baseContribution: originalContributionPerTree,
  distributionRate: 0.70,
  amount: -(originalContributionPerTree * transferTreeCount * 0.70),  // 负数
  transferOrderNo: transferOrderNo,
  effectiveDate: transferDate,           // 转让日期次日
  expireDate: originalExpireDate,        // 原始到期日
  status: 'EFFECTIVE',
  remark: `转让转出至 ${buyer.accountSequence}`,
});

// 更新卖方 ContributionAccount
sellerAccount.personalContribution -= amount;
sellerAccount.effectiveContribution -= amount;
```

#### 5.4.2 卖方上线团队层级扣减

对卖方的 15 级上线，每级创建一条负数流水：

```typescript
for (let level = 1; level <= 15; level++) {
  const ancestor = sellerAncestorChain[level - 1];
  if (!ancestor) break;

  const levelAmount = originalContributionPerTree * transferTreeCount * 0.005;

  // 检查当时这一级是否已分配（查询原始 ContributionRecord）
  const originalRecord = await findOriginalTeamLevelRecord(
    ancestor.accountSequence, originalAdoptionId, level
  );

  if (originalRecord && originalRecord.status === 'EFFECTIVE') {
    // 原始记录是已生效的 → 创建负数对冲流水
    ContributionRecord.create({
      accountSequence: ancestor.accountSequence,
      sourceType: 'TRANSFER_OUT_TEAM_LEVEL',
      sourceAdoptionId: originalAdoptionId,
      sourceAccountSequence: seller.accountSequence,
      treeCount: transferTreeCount,
      baseContribution: originalContributionPerTree,
      distributionRate: 0.005,
      levelDepth: level,
      amount: -levelAmount,
      transferOrderNo: transferOrderNo,
      effectiveDate: transferDate,
      expireDate: originalExpireDate,
      status: 'EFFECTIVE',
      remark: `转让转出：${seller.accountSequence} → ${buyer.accountSequence}`,
    });

    // 更新上线 ContributionAccount
    ancestorAccount.effectiveContribution -= levelAmount;
    // 对应层级的 pending/unlocked 字段也需调整
  }
  // 如果原始记录在 UnallocatedContribution 中（上线未解锁），
  // 则不需要扣减（因为从未分配给该上线），但需标记该 Unallocated 记录已失效
}
```

#### 5.4.3 卖方加成扣减

对卖方自身已生效的加成档位，创建负数流水：

```typescript
for (let tier = 1; tier <= 3; tier++) {
  // 查询卖方在原始认种中该档位是否已获得
  const originalBonusRecord = await findOriginalBonusRecord(
    seller.accountSequence, originalAdoptionId, tier
  );

  if (originalBonusRecord && originalBonusRecord.status === 'EFFECTIVE') {
    const bonusAmount = originalContributionPerTree * transferTreeCount * 0.025;

    ContributionRecord.create({
      accountSequence: seller.accountSequence,
      sourceType: 'TRANSFER_OUT_BONUS',
      sourceAdoptionId: originalAdoptionId,
      sourceAccountSequence: seller.accountSequence,
      treeCount: transferTreeCount,
      baseContribution: originalContributionPerTree,
      distributionRate: 0.025,
      bonusTier: tier,
      amount: -bonusAmount,
      transferOrderNo: transferOrderNo,
      effectiveDate: transferDate,
      expireDate: originalExpireDate,
      status: 'EFFECTIVE',
      remark: `转让转出加成T${tier}`,
    });

    sellerAccount.effectiveContribution -= bonusAmount;
  }
}
```

#### 5.4.4 卖方解锁状态更新

```typescript
// 重新计算卖方的 selfPlantingCount
const remainingAdoptions = await syncedDataRepository.countAdoptionsByAccount(
  seller.accountSequence, excludeTransferred: true
);

if (remainingAdoptions === 0) {
  // 卖方不再持有任何树
  sellerAccount.hasAdopted = false;
  sellerAccount.unlockedLevelDepth = 0;
  // unlockedBonusTiers 的 T1 失效，但 T2/T3 取决于 directReferralAdoptedCount
  sellerAccount.recalculateUnlockStatus();
}

// 检查卖方的推荐人的 directReferralAdoptedCount 是否需要更新
if (remainingAdoptions === 0) {
  const sellerReferrer = await findReferrer(seller.accountSequence);
  if (sellerReferrer) {
    const newCount = await recalculateDirectReferralAdoptedCount(sellerReferrer.accountSequence);
    if (newCount < sellerReferrer.directReferralAdoptedCount) {
      sellerReferrerAccount.directReferralAdoptedCount = newCount;
      sellerReferrerAccount.recalculateUnlockStatus();
      // 注意：不追回历史分配，只更新状态（影响未来分配）
    }
  }
}
```

### 5.5 买方算力新增流水（planting.ownership.added 事件处理）

#### 5.5.1 买方个人算力

```typescript
ContributionRecord.create({
  accountSequence: buyer.accountSequence,
  sourceType: 'TRANSFER_IN_PERSONAL',
  sourceAdoptionId: originalAdoptionId,
  sourceAccountSequence: buyer.accountSequence,  // 新的所有者
  treeCount: transferTreeCount,
  baseContribution: originalContributionPerTree,  // 保持原始值
  distributionRate: 0.70,
  amount: originalContributionPerTree * transferTreeCount * 0.70,  // 正数
  transferOrderNo: transferOrderNo,
  effectiveDate: transferDate,
  expireDate: originalExpireDate,
  status: 'EFFECTIVE',
  remark: `转让转入来自 ${seller.accountSequence}`,
});

buyerAccount.personalContribution += amount;
buyerAccount.effectiveContribution += amount;
```

#### 5.5.2 买方上线团队层级分配

```typescript
for (let level = 1; level <= 15; level++) {
  const ancestor = buyerAncestorChain[level - 1];
  if (!ancestor) {
    // 无上线 → UnallocatedContribution（归总部）
    createUnallocatedContribution({
      sourceAdoptionId: originalAdoptionId,
      sourceAccountSequence: buyer.accountSequence,
      unallocType: 'TRANSFER_IN_LEVEL_NO_ANCESTOR',
      levelDepth: level,
      amount: levelAmount,
      transferOrderNo: transferOrderNo,
    });
    continue;
  }

  const ancestorAccount = await findContributionAccount(ancestor.accountSequence);

  if (ancestorAccount && ancestorAccount.unlockedLevelDepth >= level) {
    // 上线已解锁 → 直接分配
    ContributionRecord.create({
      accountSequence: ancestor.accountSequence,
      sourceType: 'TRANSFER_IN_TEAM_LEVEL',
      sourceAdoptionId: originalAdoptionId,
      sourceAccountSequence: buyer.accountSequence,
      levelDepth: level,
      amount: levelAmount,  // 正数
      transferOrderNo: transferOrderNo,
      effectiveDate: transferDate,
      expireDate: originalExpireDate,
      status: 'EFFECTIVE',
    });
    ancestorAccount.effectiveContribution += levelAmount;
  } else {
    // 上线未解锁 → UnallocatedContribution（待补发）
    createUnallocatedContribution({
      sourceAdoptionId: originalAdoptionId,
      sourceAccountSequence: buyer.accountSequence,
      unallocType: 'LEVEL_OVERFLOW',
      wouldBeAccountSequence: ancestor.accountSequence,
      levelDepth: level,
      amount: levelAmount,
      transferOrderNo: transferOrderNo,
    });
  }
}
```

#### 5.5.3 买方加成分配

```typescript
const buyerUnlockedBonusTiers = calculateUnlockedBonusTiers(
  buyerAccount.hasAdopted || true,  // 买方获得树后 hasAdopted = true
  buyerAccount.directReferralAdoptedCount
);

for (let tier = 1; tier <= 3; tier++) {
  if (buyerUnlockedBonusTiers >= tier) {
    ContributionRecord.create({
      accountSequence: buyer.accountSequence,
      sourceType: 'TRANSFER_IN_BONUS',
      bonusTier: tier,
      amount: bonusAmount,
      transferOrderNo: transferOrderNo,
      // ...
    });
    buyerAccount.effectiveContribution += bonusAmount;
  } else {
    createUnallocatedContribution({
      unallocType: `BONUS_TIER_${tier}_PENDING`,
      wouldBeAccountSequence: buyer.accountSequence,
      amount: bonusAmount,
      transferOrderNo: transferOrderNo,
    });
  }
}
```

#### 5.5.4 买方解锁状态更新

```typescript
// 更新买方 hasAdopted
if (!buyerAccount.hasAdopted) {
  buyerAccount.markAsAdopted();  // hasAdopted = true, unlockedLevelDepth = 5, unlockedBonusTiers = 1
}

// 检查买方的推荐人的 directReferralAdoptedCount 是否需要更新
const buyerReferrer = await findReferrer(buyer.accountSequence);
if (buyerReferrer) {
  const newCount = await recalculateDirectReferralAdoptedCount(buyerReferrer.accountSequence);
  if (newCount > buyerReferrer.directReferralAdoptedCount) {
    // 可能触发 checkAndClaimBonus()（复用现有逻辑）
    await bonusClaimService.checkAndClaimBonus(
      buyerReferrer.accountSequence,
      buyerReferrer.directReferralAdoptedCount,
      newCount
    );
    buyerReferrerAccount.directReferralAdoptedCount = newCount;
    buyerReferrerAccount.recalculateUnlockStatus();
  }
}
```

### 5.6 系统账户处理

**运营账户 12% 不受影响**（全局固定分配）。

**省公司 1% 和市公司 2% 需随所有权变更调整**：

```typescript
// 卖方省市系统账户：创建负数对冲流水
const provinceAmount = originalContributionPerTree * transferTreeCount * 0.01;
const cityAmount = originalContributionPerTree * transferTreeCount * 0.02;

// 卖方省公司系统账户扣减
SystemContributionRecord.create({
  accountType: 'PROVINCE',
  regionCode: sellerSelectedProvince,   // 原始认种时选择的省
  sourceType: 'TRANSFER_OUT_SYSTEM_PROVINCE',
  sourceAdoptionId: originalAdoptionId,
  amount: -provinceAmount,              // 负数
  transferOrderNo: transferOrderNo,
  effectiveDate: transferDate,
  expireDate: originalExpireDate,
});
// 更新 SystemAccount (PROVINCE, sellerSelectedProvince) 的 contributionBalance

// 卖方市公司系统账户扣减
SystemContributionRecord.create({
  accountType: 'CITY',
  regionCode: sellerSelectedCity,       // 原始认种时选择的市
  sourceType: 'TRANSFER_OUT_SYSTEM_CITY',
  sourceAdoptionId: originalAdoptionId,
  amount: -cityAmount,
  transferOrderNo: transferOrderNo,
  effectiveDate: transferDate,
  expireDate: originalExpireDate,
});

// 买方省公司系统账户增加
SystemContributionRecord.create({
  accountType: 'PROVINCE',
  regionCode: buyerSelectedProvince,    // 买方的省（来自 PlantingOwnershipAdded 事件）
  sourceType: 'TRANSFER_IN_SYSTEM_PROVINCE',
  sourceAdoptionId: originalAdoptionId,
  amount: +provinceAmount,
  transferOrderNo: transferOrderNo,
  effectiveDate: transferDate,
  expireDate: originalExpireDate,
});

// 买方市公司系统账户增加
SystemContributionRecord.create({
  accountType: 'CITY',
  regionCode: buyerSelectedCity,
  sourceType: 'TRANSFER_IN_SYSTEM_CITY',
  sourceAdoptionId: originalAdoptionId,
  amount: +cityAmount,
  transferOrderNo: transferOrderNo,
  effectiveDate: transferDate,
  expireDate: originalExpireDate,
});
```

**注意**：如果卖方和买方在同一省市，省市系统账户的对冲流水互相抵消，净变化为零，但流水记录仍然要写（审计需要）。

### 5.7 挖矿快照自动适配

**挖矿分配同样无需特殊处理**：

1. 转让完成后，受影响用户的 `ContributionAccount.effectiveContribution` 已实时更新
2. 每日定时任务 `SnapshotService.createDailySnapshot()` 读取最新的 `effectiveContribution`
3. 为每个用户生成新的 `contributionRatio = effectiveContribution / networkTotal`
4. `mining-service` 消费快照，按新占比分配挖矿收益

**无需任何代码处理**——快照天然支持算力变更。

### 5.7 发布确认事件

处理完成后发布事件到 `contribution.transfer.adjusted`，供 transfer-service 确认 Saga 步骤。

### 5.8 新增文件清单

| 文件 | 说明 |
|------|------|
| `src/application/event-handlers/ownership-removed.handler.ts` | 消费 planting.ownership.removed |
| `src/application/event-handlers/ownership-added.handler.ts` | 消费 planting.ownership.added |
| `src/application/services/transfer-adjustment.service.ts` | 转让算力调整编排服务 |
| `src/domain/services/transfer-contribution-calculator.service.ts` | 转让算力计算（查询原始记录 + 生成对冲/新增流水） |

---

## 六、wallet-service 复用方案

wallet-service **无需新增代码**，完全复用现有能力：

### 6.1 冻结买方资金

transfer-service 调用 wallet-service 的 `freezeForPlanting` 或通用 `freeze` 接口：

```
POST /wallet/freeze
{
  accountSequence: buyer.accountSequence,
  amount: transferPrice,
  assetType: "USDT",
  refOrderId: transferOrderNo,
  memo: "树转让冻结"
}
```

对应 LedgerEntry：`entryType = FREEZE`

### 6.2 结算（转账给卖方 + 平台手续费）

transfer-service 调用 wallet-service 的内部转账：

```
// 1. 从买方冻结余额中扣款
POST /wallet/confirm-deduction
{
  accountSequence: buyer.accountSequence,
  amount: transferPrice,
  refOrderId: transferOrderNo
}

// 2. 转账给卖方（实收金额 = 转让价 - 手续费）
POST /wallet/internal-transfer
{
  fromAccountSequence: buyer.accountSequence,
  toAccountSequence: seller.accountSequence,
  amount: sellerReceiveAmount,
  refOrderId: transferOrderNo
}

// 3. 手续费归集（平台收入）
POST /wallet/fee-collection
{
  fromAccountSequence: buyer.accountSequence,
  toAccountSequence: "S0000000006",  // 手续费归集账户
  amount: platformFeeAmount,
  refOrderId: transferOrderNo
}
```

### 6.3 回滚（解冻）

```
POST /wallet/unfreeze
{
  accountSequence: buyer.accountSequence,
  amount: transferPrice,
  refOrderId: transferOrderNo,
  memo: "树转让取消，解冻"
}
```

---

## 七、完整事件契约

### 7.1 transfer-service 发出的事件

| 事件 | Topic | Key | 消费者 |
|------|-------|-----|--------|
| `TransferTreesLockRequest` | `transfer.trees.lock` | transferOrderNo | planting-service |
| `TransferOwnershipExecute` | `transfer.ownership.execute` | transferOrderNo | planting-service |
| `TransferTreesUnlockRequest` | `transfer.trees.unlock` | transferOrderNo | planting-service |
| `TransferPaymentFreezeRequest` | `transfer.payment.freeze` | transferOrderNo | wallet-service |
| `TransferPaymentSettleRequest` | `transfer.payment.settle` | transferOrderNo | wallet-service |
| `TransferPaymentUnfreezeRequest` | `transfer.payment.unfreeze` | transferOrderNo | wallet-service |

### 7.2 planting-service 发出的事件

| 事件 | Topic | Key | 消费者 |
|------|-------|-----|--------|
| `PlantingTransferLocked` | `planting.transfer.locked` | transferOrderNo | transfer-service |
| `PlantingTransferCompleted` | `planting.transfer.completed` | transferOrderNo | transfer-service |
| `PlantingOwnershipRemoved` | `planting.ownership.removed` | sellerAccountSequence | contribution-service, referral-service |
| `PlantingOwnershipAdded` | `planting.ownership.added` | buyerAccountSequence | contribution-service, referral-service |
| `PlantingTransferRolledBack` | `planting.transfer.rolledback` | transferOrderNo | transfer-service |

### 7.3 contribution-service 发出的事件

| 事件 | Topic | Key | 消费者 |
|------|-------|-----|--------|
| `TransferContributionAdjusted` | `contribution.transfer.adjusted` | transferOrderNo | transfer-service |

### 7.4 referral-service 发出的事件

| 事件 | Topic | Key | 消费者 |
|------|-------|-----|--------|
| `TransferStatsUpdated` | `referral.transfer.stats-updated` | transferOrderNo | transfer-service |

### 7.5 标准 Payload 格式

#### PlantingOwnershipRemoved Payload

```json
{
  "eventType": "PlantingOwnershipRemoved",
  "transferOrderNo": "TRF260218A3B7C9D1",
  "sourceOrderNo": "PLT2501150001A2B3",
  "sourceAdoptionId": "12345",
  "sellerUserId": "100001",
  "sellerAccountSequence": "D25011500001",
  "treeCount": 2,
  "contributionPerTree": "22684.1000000000",
  "selectedProvince": "440000",
  "selectedCity": "440100",
  "originalAdoptionDate": "2025-01-15",
  "originalExpireDate": "2027-01-16",
  "transferDate": "2026-02-18"
}
```

#### PlantingOwnershipAdded Payload

```json
{
  "eventType": "PlantingOwnershipAdded",
  "transferOrderNo": "TRF260218A3B7C9D1",
  "sourceOrderNo": "PLT2501150001A2B3",
  "sourceAdoptionId": "12345",
  "buyerUserId": "200002",
  "buyerAccountSequence": "D25121400002",
  "treeCount": 2,
  "contributionPerTree": "22684.1000000000",
  "selectedProvince": "440000",
  "selectedCity": "440100",
  "originalAdoptionDate": "2025-01-15",
  "originalExpireDate": "2027-01-16",
  "transferDate": "2026-02-18"
}
```

---

## 八、完整 Saga 流程图

```
┌─────────────────────────────────────────────────────────────────────┐
│                        transfer-service (Saga 编排器)                │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
     Step 1: 买方发起转让         │
     ─────────────────────       │
     创建 TransferOrder          │
     status = PENDING            │
                                 │
     Step 2: 卖方确认             │
     ─────────────────────       │
     status = SELLER_CONFIRMED   │
                                 │
     Step 3: 冻结买方资金         │  ──── wallet-service ────
     ─────────────────────       │  freeze(buyer, transferPrice)
     status = PAYMENT_FROZEN     │  ← 确认冻结成功
                                 │
     Step 4: 锁定卖方树           │  ──── planting-service ────
     ─────────────────────       │  → transfer.trees.lock
     status = TREES_LOCKED       │  ← planting.transfer.locked
                                 │
     Step 5: 执行所有权变更       │  ──── planting-service ────
     ─────────────────────       │  → transfer.ownership.execute
     status = OWNERSHIP_         │  ← planting.transfer.completed
              TRANSFERRED        │
                                 │  planting-service 同时发布:
                                 │  → planting.ownership.removed
                                 │  → planting.ownership.added
                                 │
     Step 6: 等待算力调整确认     │  ──── contribution-service ────
     ─────────────────────       │  消费 planting.ownership.removed
     status = CONTRIBUTION_      │  消费 planting.ownership.added
              ADJUSTED           │  ← contribution.transfer.adjusted
                                 │
     Step 7: 等待统计更新确认     │  ──── referral-service ────
     ─────────────────────       │  消费 planting.ownership.removed
     status = STATS_UPDATED      │  消费 planting.ownership.added
                                 │  ← referral.transfer.stats-updated
                                 │
     Step 8: 结算资金             │  ──── wallet-service ────
     ─────────────────────       │  confirmDeduction(buyer)
     status = PAYMENT_SETTLED    │  internalTransfer(buyer→seller)
                                 │  feeCollection(buyer→S0000000006)
                                 │
     Step 9: 完成                 │
     ─────────────────────       │
     status = COMPLETED          │
                                 │
═══════════════════════════════════════════════════════════════════════
  补偿路径（从失败步骤反向执行）：
═══════════════════════════════════════════════════════════════════════
                                 │
  如果 Step 5/6/7 失败：         │
  → planting: transfer.trees.unlock (解锁树)
  → wallet: unfreeze (解冻资金)   │
                                 │
  如果 Step 4 失败：              │
  → wallet: unfreeze (解冻资金)   │
                                 │
  如果 Step 3 失败：              │
  → 直接标记 FAILED              │
```

---

## 九、补偿与回滚

### 9.1 补偿策略

| 失败步骤 | 需要补偿的操作 | 补偿方式 |
|---------|--------------|---------|
| 冻结资金失败 | 无 | 直接标记 FAILED |
| 锁定树失败 | 解冻买方资金 | wallet.unfreeze |
| 所有权变更失败 | 解锁树 + 解冻资金 | planting.unlock + wallet.unfreeze |
| 算力调整超时 | 重试 3 次后人工介入 | 算力为最终一致性，不阻塞流程 |
| 统计更新超时 | 重试 3 次后人工介入 | 统计为最终一致性，不阻塞流程 |
| 资金结算失败 | 反向变更所有权 + 解锁树 + 解冻资金 | 完整回滚 |

### 9.2 最终一致性策略

对于 Step 6（算力）和 Step 7（统计），采用**最终一致性**：

1. transfer-service 设置超时（5 分钟）
2. 超时后自动重试发送事件（最多 3 次）
3. 3 次重试后标记为 `CONTRIBUTION_PENDING` 或 `STATS_PENDING`
4. 定时任务扫描超时未完成的转让，发送告警
5. 管理员可通过 Admin API 手动触发重试或强制完成

### 9.3 幂等性保证

所有事件处理器通过 `ProcessedEvent` 表保证幂等性：

```typescript
const eventId = `transfer-${transferOrderNo}-${step}`;
const exists = await processedEventRepo.findByEventId(eventId);
if (exists) return; // 已处理，跳过
```

---

## 十、Admin Web 管理

### 10.1 转让管理页面

```
/admin/transfers          - 转让列表
/admin/transfers/:id      - 转让详情
```

#### 列表页功能

- 筛选条件：状态、日期范围、卖方/买方账号、转让编号
- 列表字段：转让编号、卖方、买方、棵数、金额、状态、创建时间
- 操作按钮：查看详情、强制取消（PENDING/SELLER_CONFIRMED 阶段）

#### 详情页功能

- 基本信息：转让双方、树信息、价格
- Saga 进度：每个步骤的状态和时间戳
- 算力流水：关联的 ContributionRecord 列表
- 团队统计变更：受影响的用户列表
- 操作日志：所有状态变更记录

### 10.2 Sidebar 入口

在 admin-web 的 Sidebar 中新增入口：

```
认种管理
  ├── 认种订单
  ├── 预种计划
  └── 转让管理    ← 新增
```

---

## 十一、Mobile App 用户界面

### 11.1 卖方入口

在持仓页面（PlantingPosition）的每棵树/每个订单旁新增「转让」按钮：

```
我的持仓（10棵树）
├── 订单 PLT250115... (5棵, 广东广州)
│   ├── 状态：挖矿中
│   └── [转让]
├── 订单 PLT250120... (3棵, 广东深圳)
│   ├── 状态：挖矿中
│   └── [转让]
└── 订单 PLT250201... (2棵, 北京朝阳)
    ├── 状态：挖矿中
    └── [转让]
```

### 11.2 转让发起页

```
┌──────────────────────────────┐
│  发起转让                     │
│                              │
│  转让订单：PLT250115...       │
│  棵数：5 棵（可调整）          │
│  树位置：广东广州              │
│  原始认种日期：2025-01-15     │
│  算力到期日：2027-01-16       │
│                              │
│  转让价格：______ USDT       │
│  平台手续费：2%               │
│  您将收到：______ USDT       │
│                              │
│  买方账号：D____________      │
│                              │
│  [确认转让]                   │
└──────────────────────────────┘
```

### 11.3 转让记录页

```
我的转让
├── [标签] 转出 | 转入 | 全部
├── TRF260218... 转出 5棵 → D25121400002
│   状态：已完成 | 收到 15000 USDT
│   2026-02-18 14:30
├── TRF260210... 转入 3棵 ← D25011500001
│   状态：已完成 | 支付 9500 USDT
│   2026-02-10 09:15
└── ...
```

---

## 十二、实施阶段计划

### Phase 1：基础框架（transfer-service + planting-service）

**目标**：完成转让订单的创建、锁定、所有权变更、资金结算的核心流程。

**交付内容**：
1. transfer-service 新微服务搭建
   - 项目脚手架（NestJS + Prisma + Kafka）
   - TransferOrder 数据模型 + Migration
   - Saga 状态机核心逻辑
   - REST API（用户端 + 管理端）
   - Outbox 事件发布

2. planting-service 纯新增
   - PlantingTransferRecord 数据表 + Migration
   - PlantingOrder.transferLockedCount 新增字段
   - 3 个事件处理器（lock / execute / rollback）
   - Outbox 事件发布（ownership.removed / ownership.added）

3. wallet-service 对接
   - 复用 freeze / unfreeze / internal-transfer 接口
   - 新增 LedgerEntryType: `TRANSFER_FREEZE` / `TRANSFER_PAYMENT`

4. Docker 配置
   - docker-compose.yml 新增 transfer-service
   - Kafka topic 创建脚本

**验收标准**：
- 完成转让全流程（不含算力和统计）
- 资金正确冻结、结算、回滚
- 持仓数量正确变更

---

### Phase 2：算力调整（contribution-service）

**目标**：完成算力的事务流水型增量调整。

**交付内容**：
1. contribution-service 纯新增
   - 新增 sourceType 枚举值（10 个 TRANSFER_OUT/IN 类型，含系统省市）
   - ContributionRecord.transferOrderNo 新增字段 + Migration
   - ownership-removed.handler.ts（卖方算力扣减）
   - ownership-added.handler.ts（买方算力分配）
   - transfer-adjustment.service.ts（编排服务）
   - transfer-contribution-calculator.service.ts（计算服务）

2. 解锁状态联动
   - 卖方 hasAdopted / unlockedLevelDepth / unlockedBonusTiers 重算
   - 买方 hasAdopted / unlockedLevelDepth / unlockedBonusTiers 更新
   - 买方推荐人 directReferralAdoptedCount 更新 + bonus 补发

3. 确认事件发布
   - `contribution.transfer.adjusted` 事件

**验收标准**：
- 卖方 effectiveContribution 正确减少
- 买方 effectiveContribution 正确增加
- 省市系统账户正确调整（卖方省市减少，买方省市增加）
- 全网算力总量守恒（卖方减少 = 买方增加 + UnallocatedContribution）
- 历史 ContributionRecord 零修改
- 次日快照正确反映新算力

---

### Phase 3：团队统计（referral-service）

**目标**：完成团队认种统计的增减和龙虎榜重算。

**交付内容**：
1. referral-service 纯新增
   - planting-transferred.handler.ts
   - TeamStatistics.removePersonalPlanting() 新增方法
   - TeamStatisticsRepository.batchUpdateTeamCountsForTransfer() 新增方法
   - 龙虎榜 max 重算逻辑修正（负数 delta 时全量扫描）

2. 确认事件发布
   - `referral.transfer.stats-updated` 事件

**验收标准**：
- 卖方链路 totalTeamPlantingCount 正确减少
- 买方链路 totalTeamPlantingCount 正确增加
- 龙虎榜排名正确更新
- selfPlantingCount 正确反映当前持仓

---

### Phase 4：前端（Admin Web + Mobile App）

**目标**：完成管理端和用户端的完整交互界面。

**交付内容**：
1. Admin Web（Next.js 14）
   - 转让管理列表页
   - 转让详情页（含 Saga 进度可视化）
   - Sidebar 入口
   - 统计看板

2. Mobile App（Flutter）
   - 持仓页转让入口
   - 转让发起页
   - 转让记录页（转出/转入）
   - 转让状态实时更新

**验收标准**：
- 完整的转让用户流程
- 管理端可查看所有转让记录和状态
- 异常状态有明确提示

---

### Phase 5：测试与上线

**交付内容**：
1. 单元测试
   - 算力计算正确性（卖方扣减 / 买方分配 / 解锁联动）
   - Saga 状态机全路径覆盖
   - 补偿逻辑验证

2. 集成测试
   - 完整转让流程 E2E
   - 补偿回滚 E2E
   - 并发转让冲突测试
   - 部分转让 + 多次转让场景

3. 压力测试
   - 大量并发转让请求
   - Kafka 事件积压恢复

4. 上线
   - 数据库 Migration 执行
   - 服务部署
   - 灰度放量

---

## 十三、算力流水示例

### 场景：A 转让 2 棵树给 B

**前提条件**：
- A 有 5 棵树（订单 PLT001），原始 contributionPerTree = 22617
- A 的上级链：R1 → R2 → R3（3 级，都已解锁）
- B 之前无树，B 的上级链：S1 → S2（2 级，S1 已解锁 5 级，S2 未解锁）
- 转让 2 棵

#### 卖方侧新增流水（全部为负数）

| # | accountSequence | sourceType | amount | remark |
|---|----------------|------------|--------|--------|
| 1 | A | TRANSFER_OUT_PERSONAL | -31,663.80 | 个人 22617×2×0.70 |
| 2 | R1 | TRANSFER_OUT_TEAM_LEVEL (L1) | -226.17 | R1 第1级 22617×2×0.005 |
| 3 | R2 | TRANSFER_OUT_TEAM_LEVEL (L2) | -226.17 | R2 第2级 |
| 4 | R3 | TRANSFER_OUT_TEAM_LEVEL (L3) | -226.17 | R3 第3级 |
| 5 | A | TRANSFER_OUT_BONUS (T1) | -1,130.85 | 加成T1 22617×2×0.025 |
| 6 | A | TRANSFER_OUT_BONUS (T2) | -1,130.85 | 加成T2（如已解锁） |
| 7 | SystemAccount(PROVINCE,440000) | TRANSFER_OUT_SYSTEM_PROVINCE | -452.34 | 省公司 22617×2×0.01 |
| 8 | SystemAccount(CITY,440100) | TRANSFER_OUT_SYSTEM_CITY | -904.68 | 市公司 22617×2×0.02 |

#### 买方侧新增流水（全部为正数）

假设买方 B 在北京朝阳（110000/110105），与卖方不同省市：

| # | accountSequence | sourceType | amount | remark |
|---|----------------|------------|--------|--------|
| 9 | B | TRANSFER_IN_PERSONAL | +31,663.80 | 个人 |
| 10 | S1 | TRANSFER_IN_TEAM_LEVEL (L1) | +226.17 | S1 第1级（已解锁） |
| 11 | S1 | TRANSFER_IN_TEAM_LEVEL (L2) | +226.17 | S1 第2级（已解锁） |
| 12 | S1 | TRANSFER_IN_TEAM_LEVEL (L3) | +226.17 | S1 第3级（已解锁） |
| 13 | S1 | TRANSFER_IN_TEAM_LEVEL (L4) | +226.17 | S1 第4级（已解锁） |
| 14 | S1 | TRANSFER_IN_TEAM_LEVEL (L5) | +226.17 | S1 第5级（已解锁） |
| 15 | → UnallocatedContribution | LEVEL_OVERFLOW (L6) | 226.17 | S2 第6级（未解锁） |
| 16 | → UnallocatedContribution | LEVEL_OVERFLOW (L7) | 226.17 | S2 第7级（未解锁） |
| ... | ... | ... | ... | L8-L15 类似 |
| 17 | B | TRANSFER_IN_BONUS (T1) | +1,130.85 | 加成T1（买方获树后解锁） |
| 18 | → UnallocatedContribution | BONUS_TIER_2_PENDING | 1,130.85 | T2（买方未达条件） |
| 19 | → UnallocatedContribution | BONUS_TIER_3_PENDING | 1,130.85 | T3（买方未达条件） |
| 20 | SystemAccount(PROVINCE,110000) | TRANSFER_IN_SYSTEM_PROVINCE | +452.34 | 买方省公司（北京） |
| 21 | SystemAccount(CITY,110105) | TRANSFER_IN_SYSTEM_CITY | +904.68 | 买方市公司（朝阳） |

#### 解锁状态联动

| 用户 | 变更前 | 变更后 | 说明 |
|------|--------|--------|------|
| A | hasAdopted=true | hasAdopted=true | A 还剩 3 棵 |
| B | hasAdopted=false | hasAdopted=true | 获得树后解锁 |
| B 的推荐人 | directAdoptedCount=N | directAdoptedCount=N+1 | 可能触发升档补发 |

---

## 十四、风险评估与应对

| 风险 | 影响 | 应对措施 |
|------|------|---------|
| Saga 步骤失败后补偿不完整 | 资金或树处于不一致状态 | 定时任务扫描异常状态 + Admin 手动介入 |
| 并发转让同一订单 | 超卖 | PlantingOrder.transferLockedCount 乐观锁 + 数据库约束 |
| contribution 事件丢失 | 算力不一致 | Outbox + ProcessedEvent 双保障 + 定时对账 |
| referral 统计出现负数 | 龙虎榜异常 | Math.max(0, ...) 兜底 + 告警 |
| 全网算力总量不守恒 | 挖矿分配异常 | 每日对账脚本：∑增加 = ∑减少 + ∑UnallocatedContribution |
| 大量转让导致 Kafka 积压 | 处理延迟 | 独立 Consumer Group + 限流 |
| 卖方转让后 selfPlantingCount=0 影响推荐人解锁 | 推荐人未来新认种的分配比例降低 | 这是正确的业务行为，无需应对 |

---

## 十五、对账与监控

### 15.1 每日对账任务

```sql
-- 算力守恒检查
-- 对于每一笔转让，验证：|卖方扣减| = |买方增加| + |UnallocatedContribution|
SELECT
  t.transfer_order_no,
  SUM(CASE WHEN cr.source_type LIKE 'TRANSFER_OUT_%' THEN ABS(cr.amount) ELSE 0 END) AS total_out,
  SUM(CASE WHEN cr.source_type LIKE 'TRANSFER_IN_%' THEN cr.amount ELSE 0 END) AS total_in,
  SUM(CASE WHEN uc.transfer_order_no IS NOT NULL THEN uc.amount ELSE 0 END) AS total_unallocated
FROM transfer_orders t
LEFT JOIN contribution_records cr ON cr.transfer_order_no = t.transfer_order_no
LEFT JOIN unallocated_contributions uc ON uc.transfer_order_no = t.transfer_order_no
WHERE t.status = 'COMPLETED'
GROUP BY t.transfer_order_no
HAVING ABS(total_out - total_in - total_unallocated) > 0.01;
-- 结果应为空（无差异）
```

### 15.2 监控告警

- Saga 步骤超时（> 5 分钟未完成）
- 补偿失败（ROLLING_BACK 状态超过 10 分钟）
- 算力守恒偏差 > 0.01
- 团队统计出现负数
- 每日转让量异常波动

---

## 十六、积分股转让（2.0 系统附加功能）

### 16.1 业务规则

| 规则 | 说明 |
|------|------|
| **正常情况** | 2.0 系统**不支持**用户间积分股（Share）转让 |
| **触发条件** | 树转让完成（TransferOrder.status = COMPLETED）后自动开启 |
| **参与方限制** | 仅限该笔树转让的买方和卖方双向互转 |
| **有效期** | 树转让完成后 24 小时内 |
| **到期处理** | 24 小时后窗口自动关闭，不可再发起 Share 转让 |
| **转让方向** | 双向：卖方→买方、买方→卖方 均可 |
| **转让次数** | 窗口期内不限次数 |
| **转让数量** | 不超过发起方的可用 Share 余额 |

### 16.2 数据模型（mining-wallet-service 新增）

#### ShareTransferWindow（积分股转让窗口）

```prisma
model ShareTransferWindow {
  id                     String    @id @default(uuid())
  transferOrderNo        String    @unique @map("transfer_order_no") @db.VarChar(50)  // 关联的树转让订单号

  partyAAccountSequence  String    @map("party_a_account_sequence") @db.VarChar(20)   // 卖方
  partyBAccountSequence  String    @map("party_b_account_sequence") @db.VarChar(20)   // 买方

  status                 String    @default("ACTIVE") @map("status") @db.VarChar(20)  // ACTIVE / EXPIRED / CLOSED
  openedAt               DateTime  @default(now()) @map("opened_at")
  expiresAt              DateTime  @map("expires_at")                                 // openedAt + 24h
  closedAt               DateTime? @map("closed_at")

  createdAt              DateTime  @default(now()) @map("created_at")

  @@index([partyAAccountSequence])
  @@index([partyBAccountSequence])
  @@index([status, expiresAt])
  @@map("share_transfer_windows")
}
```

#### ShareTransferRecord（积分股转让记录）

```prisma
model ShareTransferRecord {
  id                     String    @id @default(uuid())
  windowId               String    @map("window_id")                                  // 关联窗口
  transferOrderNo        String    @map("transfer_order_no") @db.VarChar(50)          // 关联的树转让订单号

  fromAccountSequence    String    @map("from_account_sequence") @db.VarChar(20)
  toAccountSequence      String    @map("to_account_sequence") @db.VarChar(20)
  amount                 Decimal   @map("amount") @db.Decimal(30, 8)                  // Share 数量

  status                 String    @default("COMPLETED") @map("status") @db.VarChar(20)
  createdAt              DateTime  @default(now()) @map("created_at")

  @@index([windowId])
  @@index([transferOrderNo])
  @@index([fromAccountSequence])
  @@index([toAccountSequence])
  @@map("share_transfer_records")
}
```

### 16.3 流程

```
树转让完成 (TransferOrder.status = COMPLETED)
    ↓
transfer-service 发布 Outbox 事件：
    → transfer.share-window.open
    payload: { transferOrderNo, sellerAccountSeq, buyerAccountSeq }
    ↓
mining-wallet-service 消费事件：
    → 创建 ShareTransferWindow (status=ACTIVE, expiresAt=now+24h)
    ↓
24小时内，双方通过 API 发起 Share 转让：
    POST /share-transfers
    {
      transferOrderNo: "TRF260218A3B7C9D1",
      toAccountSequence: "D25121400002",
      amount: 1000.00
    }
    ↓
mining-wallet-service 处理：
    1. 查找 ACTIVE 状态的 ShareTransferWindow
    2. 验证发起方和接收方都在窗口的 partyA/partyB 中
    3. 验证 expiresAt > now()
    4. 调用已有的 transferBetweenUsers() 执行 Share 转账
    5. 创建 ShareTransferRecord 记录
    6. 记录 UserWalletTransaction (transactionType=TRANSFER_OUT/TRANSFER_IN)
    ↓
24小时到期：
    → 定时任务扫描 expiresAt < now() 且 status=ACTIVE 的窗口
    → 更新 status = EXPIRED
```

### 16.4 API 设计（mining-wallet-service 新增）

```
POST   /share-transfers                    - 发起积分股转让
GET    /share-transfers/window/:orderNo    - 查询窗口状态和剩余时间
GET    /share-transfers/records            - 查询我的积分股转让记录
```

#### POST /share-transfers 请求体

```json
{
  "transferOrderNo": "TRF260218A3B7C9D1",
  "toAccountSequence": "D25121400002",
  "amount": 1000.00000000
}
```

#### POST /share-transfers 响应

```json
{
  "success": true,
  "data": {
    "recordId": "uuid",
    "fromAccountSequence": "D25011500001",
    "toAccountSequence": "D25121400002",
    "amount": "1000.00000000",
    "windowExpiresAt": "2026-02-19T14:30:00Z",
    "createdAt": "2026-02-18T15:00:00Z"
  }
}
```

#### GET /share-transfers/window/:orderNo 响应

```json
{
  "success": true,
  "data": {
    "transferOrderNo": "TRF260218A3B7C9D1",
    "status": "ACTIVE",
    "partyA": "D25011500001",
    "partyB": "D25121400002",
    "openedAt": "2026-02-18T14:30:00Z",
    "expiresAt": "2026-02-19T14:30:00Z",
    "remainingSeconds": 72000,
    "records": [
      { "from": "D25011500001", "to": "D25121400002", "amount": "1000.00", "at": "..." }
    ]
  }
}
```

### 16.5 mining-wallet-service 新增文件

| 文件 | 说明 |
|------|------|
| `src/application/services/share-transfer.service.ts` | 积分股转让业务服务 |
| `src/application/event-handlers/share-window-opened.handler.ts` | 消费树转让完成事件，创建窗口 |
| `src/application/schedulers/share-window-expiry.scheduler.ts` | 定时任务：过期窗口关闭 |
| `src/api/controllers/share-transfer.controller.ts` | REST API |

### 16.6 Mobile App 界面

树转让完成后，在转让详情页底部显示积分股转让入口：

```
┌──────────────────────────────┐
│  转让已完成 ✓                 │
│                              │
│  ┌────────────────────────┐  │
│  │ 积分股转让窗口           │  │
│  │ 剩余时间：18:45:30      │  │
│  │                        │  │
│  │ 您的 Share：12,345.67   │  │
│  │ 对方 Share：8,901.23    │  │
│  │                        │  │
│  │ 转让数量：________      │  │
│  │                        │  │
│  │ [转给对方]              │  │
│  └────────────────────────┘  │
│                              │
│  转让记录：                   │
│  • 您 → 对方 1,000 Share     │
│  • 对方 → 您 500 Share       │
└──────────────────────────────┘
```

### 16.7 实施归属

积分股转让功能归入 **Phase 2（算力调整）** 阶段，因为：
- 依赖树转让完成事件
- 在 mining-wallet-service（2.0）中实现
- 复用已有的 `transferBetweenUsers()` 方法
- 只需新增窗口管理和验证逻辑

---

## 附录 A：配置项

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| TRANSFER_PLATFORM_FEE_RATE | 0.02 | 平台手续费率 2% |
| TRANSFER_MIN_PRICE_PER_TREE | 0 | 每棵树最低转让价 |
| TRANSFER_MAX_PRICE_PER_TREE | 99999 | 每棵树最高转让价 |
| TRANSFER_SAGA_STEP_TIMEOUT_MS | 300000 | Saga 单步超时 5 分钟 |
| TRANSFER_SAGA_MAX_RETRIES | 3 | Saga 步骤最大重试次数 |
| TRANSFER_ENABLED | true | 转让功能总开关 |
| TRANSFER_DAILY_LIMIT_PER_USER | 10 | 每用户每日转让次数上限 |
| TRANSFER_COOLDOWN_DAYS | 0 | 认种后 N 天内不可转让 |
| SHARE_TRANSFER_WINDOW_HOURS | 24 | 积分股转让窗口有效期（小时） |
| SHARE_TRANSFER_ENABLED | true | 积分股转让功能开关 |

## 附录 B：新增 Kafka Topic 列表

| Topic | 生产者 | 消费者 |
|-------|--------|--------|
| `transfer.trees.lock` | transfer-service | planting-service |
| `transfer.trees.lock.ack` | planting-service | transfer-service |
| `transfer.ownership.execute` | transfer-service | planting-service |
| `transfer.trees.unlock` | transfer-service | planting-service |
| `transfer.trees.unlock.ack` | planting-service | transfer-service |
| `planting.transfer.completed` | planting-service | transfer-service |
| `planting.transfer.rolledback` | planting-service | transfer-service |
| `planting.ownership.removed` | planting-service | contribution-service, referral-service |
| `planting.ownership.added` | planting-service | contribution-service, referral-service |
| `contribution.transfer.adjusted` | contribution-service | transfer-service |
| `referral.transfer.stats-updated` | referral-service | transfer-service |
| `transfer.share-window.open` | transfer-service | mining-wallet-service |

## 附录 C：新增数据库表汇总

| 服务 | 表名 | 说明 |
|------|------|------|
| transfer-service | transfer_orders | 转让订单（Saga 聚合根） |
| transfer-service | transfer_status_logs | 状态变更日志 |
| transfer-service | outbox_events | Outbox 事件 |
| transfer-service | processed_events | 幂等性检查 |
| planting-service | planting_transfer_records | 转让记录 |
| mining-wallet-service | share_transfer_windows | 积分股转让窗口（24小时有效期） |
| mining-wallet-service | share_transfer_records | 积分股转让记录 |

## 附录 D：现有表新增字段汇总

| 服务 | 表名 | 新增字段 | 类型 | 说明 |
|------|------|---------|------|------|
| planting-service | planting_orders | transfer_locked_count | Int DEFAULT 0 | 被转让锁定的棵数 |
| contribution-service | contribution_records | transfer_order_no | VARCHAR(50) NULL | 关联转让订单号 |
| contribution-service | unallocated_contributions | transfer_order_no | VARCHAR(50) NULL | 关联转让订单号 |