提案

openspec/changes/add-direct-exchange-flow/specs/exchange-data-migration/spec.md

@@ -0,0 +1,132 @@
+## MODIFIED Requirements
+
+### Requirement: 完成换货事务边界
+
+系统 MUST 在换货完成时使用**单一数据库事务**执行“完成换货必做切换”，并在 `migrate_data=true` 时把全量迁移纳入同一事务。
+
+该事务 SHALL 覆盖：
+- 旧资产合法性校验
+- 新资产合法性校验
+- 新旧资产归属一致性校验
+- 旧资产 `asset_status -> 3`
+- 新资产 `asset_status -> 2`
+- 个人客户绑定切换
+- `migrate_data=true` 时的钱包、套餐、标签、累计状态迁移
+- 换货单 `migration_completed`、`migration_balance`、`completed_at`、`status=4` 更新
+
+任一步骤失败 MUST 回滚。`shipping` 确认完成失败时，换货单状态保持未完成；`direct` 创建即完成失败时，系统 MUST 回滚整笔创建事务且不保留半成品 `direct` 换货单。
+
+该事务适用范围 MUST 包括：
+- `shipping` 流程的 H5 确认完成
+- `direct` 流程的创建即完成
+
+#### Scenario: 迁移中途失败回滚
+- **WHEN** 完成换货事务第 N 步发生数据库错误
+- **THEN** 系统 MUST 回滚整个事务，换货单状态保持未完成
+
+#### Scenario: direct 完成事务失败不落单
+- **WHEN** `direct` 创建即完成事务第 N 步失败
+- **THEN** 系统 MUST 回滚整个事务
+- **AND** MUST NOT 保留本次创建的换货单
+
+#### Scenario: 不迁移也必须使用完成事务
+- **WHEN** `migrate_data=false` 且执行 `shipping` 完成或 `direct` 创建即完成
+- **THEN** 系统 MUST 仍然在事务中执行旧资产状态切换、新资产状态切换、绑定切换和单据完成
+
+---
+
+### Requirement: 完成换货必做切换规则
+
+系统 SHALL 将以下动作定义为“完成换货必做切换”，无论 `migrate_data` 为真或假都必须执行：
+
+1. 校验新资产存在且与旧资产同类型。
+2. 校验旧资产当前 `asset_status=2`（已销售）。
+3. 校验新资产当前 `asset_status=1`（在库）。
+4. 校验新旧资产 `shop_id` 一致，含二者同为平台库存 `NULL`。
+5. 校验新资产未被当前换货单之外的有效客户绑定或进行中换货单占用。
+6. 将旧资产 `asset_status` 更新为 `3`（已换货）。
+7. 将新资产 `asset_status` 更新为 `2`（已销售）。
+8. 若旧资产存在 `PersonalCustomerDevice` 绑定，则将绑定记录中的资产标识字段更新为新资产资产绑定键。
+9. 记录换货单 `completed_at`。
+10. 将换货单状态更新为 `4`。
+
+若旧资产存在客户绑定但新资产无法承接绑定，系统 MUST 视为完成换货失败并回滚。
+
+#### Scenario: 不迁移但完成换货
+- **WHEN** 后台执行换货完成且 `migrate_data=false`
+- **THEN** 系统 MUST 仍然将旧资产标记为已换货
+- **AND** MUST 将新资产标记为已销售
+- **AND** MUST 更新客户绑定关系
+
+#### Scenario: 新资产无法承接客户绑定
+- **WHEN** 旧资产存在个人客户绑定，但新资产缺少可承接的资产绑定键
+- **THEN** 系统 MUST 拒绝完成换货并回滚
+
+#### Scenario: 新资产被其他进行中换货占用
+- **WHEN** 新资产已经作为其他 `shipping + status=3` 换货单的新资产
+- **THEN** 系统 MUST 拒绝完成换货并回滚
+
+---
+
+### Requirement: 11 张表迁移规则
+
+系统 SHALL 在 `migrate_data=true` 时按以下规则处理 11 张表：
+
+1. `tb_asset_wallet`：将旧资产钱包余额转移到新资产钱包。
+2. `tb_asset_wallet_transaction`：生成一条迁移流水记录（明确来源钱包、目标钱包、金额、业务类型）。
+3. `tb_asset_recharge_record`：历史充值记录保留，不做更新。
+4. `tb_package_usage`：将生效套餐关联到新资产（更新 `iot_card_id` 或 `device_id`）。
+5. `tb_package_usage_daily_record`：随 `tb_package_usage` 关系迁移（保持套餐日明细连续性）。
+6. `tb_order`：历史订单保留，不做更新。
+7. `tb_commission`：历史分佣记录保留，不做更新。
+8. `tb_data_usage_record`：历史流量记录保留，不做更新。
+9. `tb_resource_tag`：复制旧资产标签到新资产。
+10. `tb_personal_customer_device`：若旧资产存在绑定，绑定记录中的资产标识字段更新为新资产资产绑定键。
+11. `tb_iot_card`/`tb_device`：复制累计充值与首充状态到新资产。
+
+旧资产 `asset_status -> 3` 与新资产 `asset_status -> 2` 属于“完成换货必做切换”，不再视为仅在迁移开启时执行的动作。
+
+钱包迁移 MUST 满足：
+- 旧资产钱包存在 `frozen_balance > 0` 时，系统 MUST 拒绝迁移并回滚整个完成事务
+- 系统 MUST NOT 对冻结余额做部分迁移或静默清零
+- 旧资产没有钱包时，迁移余额按 `0` 处理
+- 新资产没有钱包时，系统 MAY 在同一事务内创建新钱包
+- 写入迁移流水时 MUST 使用能表达“换货迁移”的业务类型或备注，不能伪装为普通充值、退款或消费
+
+#### Scenario: 钱包余额转移并记录流水
+- **WHEN** 旧资产钱包余额为 5000 分
+- **THEN** 新资产钱包余额增加 5000 分，旧钱包余额按迁移策略清零，并写入迁移流水
+
+#### Scenario: 旧钱包存在冻结余额
+- **WHEN** `migrate_data=true` 且旧资产钱包 `frozen_balance > 0`
+- **THEN** 系统 MUST 拒绝完成换货并回滚
+- **AND** MUST 返回钱包冻结余额未处理的错误语义
+
+---
+
+### Requirement: 设备换设备特殊规则
+
+设备换设备流程 MUST NOT 迁移 `DeviceSimBinding`。
+
+系统 SHALL 视新设备为新硬件交付，新设备卡绑定由其自身体系决定，旧设备绑定关系保留历史。
+
+#### Scenario: 设备换设备不复制绑定卡
+- **WHEN** 执行设备换设备全量迁移
+- **THEN** 系统 MUST 不创建或复制任何 `DeviceSimBinding` 记录到新设备
+
+---
+
+### Requirement: 转新规则
+
+系统 SHALL 在 H7 转新时执行代际隔离策略：
+- 资产 `generation + 1`
+- 创建新空钱包（新 `wallet_id`）
+- 清除累计充值状态与首充触发状态
+- 清除 `PersonalCustomerDevice` 绑定
+- 不删除历史业务数据
+
+系统 MUST NOT 在换货完成阶段变更 `generation`。
+
+#### Scenario: 转新后历史数据保留
+- **WHEN** 资产转新完成
+- **THEN** 历史订单、充值、分佣、流量数据 MUST 仍可在旧代际查询链路中追溯