# 设计文档：客户端换货系统（client-exchange-system）

## 背景与上下文

现有换卡能力基于 `CardReplacementRecord`，仅覆盖“老卡→新卡”的窄场景，无法支撑本次目标中的完整换货闭环（后台发起、客户端填收货、后台发货、确认完成、可选全量迁移、旧资产转新再销售）。

当前主要问题：

1. **模型能力不足**（`internal/model/card_replacement.go:11-71`）
   - 只支持卡换卡，不支持设备换设备。
   - 缺少客户端收货地址、后台物流信息、迁移结果字段。
   - 状态机不匹配本次流程（待填写→待发货→已发货待确认→已完成/已取消）。

2. **历史代码字段不一致风险**（`internal/store/postgres/iot_card_store.go:644-655`）
   - 现有查询使用 `old_iot_card_id` 维度过滤换卡记录，但旧模型字段命名是 `old_card_id`，存在语义/列名不一致隐患。
   - `is_replaced` 逻辑依赖旧表，不适配新换货单模型。

3. **旧模型未纳入统一迁移体系**
   - `CardReplacementRecord` 没有持续参与当前主线 AutoMigrate 维护，演进风险高。

4. **资产迁移链路涉及多模型联动，旧方案无法表达**
   - 钱包与流水：`internal/model/asset_wallet.go:9-35`（`resource_type + resource_id`）
   - 套餐使用：`internal/model/package.go:57-87`
   - 标签：`internal/model/tag.go:25-41`
   - 客户设备绑定：`internal/model/personal_customer_device.go:9-23`
   - 设备卡绑定：`internal/model/device_sim_binding.go:9-24`
   - 分佣记录：`internal/model/commission.go:9-30`
   - 流量明细：`internal/model/data_usage.go:7-23`
   - 卡累计字段：`internal/model/iot_card.go:41-44`（`FirstCommissionPaid`、`AccumulatedRecharge`、`AccumulatedRechargeBySeriesJSON`、`FirstRechargeTriggeredBySeriesJSON`）

5. **模块接入需遵循统一 Bootstrap 装配模式**
   - 参考 `internal/bootstrap/handlers.go:12-62`、`internal/bootstrap/types.go:13-60`。

## 目标与非目标

### Goals

1. 提供完整换货生命周期能力：
   - 后台 7 个接口（H1~H7）
   - 客户端 2 个接口（G1~G2）
2. 在 H5 确认完成时支持可选“全量迁移”（11 张表规则）。
3. 支持旧资产“转新”再销售（generation+1、状态重置、历史隔离）。
4. 替换旧换卡模型引用，统一到 ExchangeOrder。

### Non-Goals

1. 不对接第三方物流轨迹查询（仅记录物流公司/单号）。
2. 不实现主动消息推送（客户端通过 G1 轮询换货通知）。

## 关键设计决策

### 决策 1：ExchangeOrder 模型设计

引入新模型 `ExchangeOrder`，作为换货生命周期唯一事实来源，字段覆盖：

- 基础字段：`gorm.Model + BaseModel`
- 单号：`exchange_no`
- 旧资产快照：`old_asset_type`、`old_asset_id`、`old_asset_identifier`
- 新资产快照：`new_asset_type`、`new_asset_id`、`new_asset_identifier`
- 收货信息：`recipient_name`、`recipient_phone`、`recipient_address`
- 物流信息：`express_company`、`express_no`
- 迁移结果：`migrate_data`、`migration_completed`、`migration_balance`
- 业务信息：`exchange_reason`、`remark`、`status`
- 多租户：`shop_id`

换货单号生成规则：`EXC` + 日期 + 随机数（示例：`EXC20260319XXXXXX`）。

### 决策 2：状态机由 Service 层强校验

`status` 采用 int 常量：

- 1 待填写信息
- 2 待发货
- 3 已发货待确认
- 4 已完成
- 5 已取消

状态流转在 Service 层校验，不使用数据库触发器。理由：

1. 业务规则集中在 Go 代码，便于复用和审计。
2. 避免跨环境数据库触发器差异。
3. 更易与错误码体系、权限体系协同。

### 决策 3：发货时执行同类型资产校验

在 H4 发货阶段强制校验：

1. `new_asset_type == old_asset_type`（卡换卡 / 设备换设备）。
2. 新资产必须 `asset_status=1`（在库）。

该校验放在“发货”而非“创建”，因为创建时允许先立单、后备货。

### 决策 4：全量迁移使用单一大事务（11 张表）

H5 在 `migrate_data=true` 时，使用**一个数据库事务**完成 11 张表相关操作。理由：

1. 迁移一致性优先，必须保证“要么全成功，要么全失败”。
2. 换货属于低频运营操作，非高并发核心交易路径。
3. 单资产迁移涉及行数有限，可接受事务时间。

补充规则：设备换设备时，不迁移 `DeviceSimBinding`（新设备视为自带新卡体系）。

### 决策 5：转新采用 generation 隔离历史

H7 转新时：

1. `generation = generation + 1`
2. 不删除旧代际历史数据（订单、充值、分佣、流量等）
3. 创建新空钱包（新 `wallet_id` 天然隔离流水）
4. 清除累计充值/首充触发状态
5. 清除客户绑定关系

通过“新代际 + 新钱包”实现可回收再销售，同时不破坏历史可追溯。

### 决策 6：旧模型降级为 legacy，不回灌迁移

`CardReplacementRecord` 对应表改名为 `tb_card_replacement_record_legacy`，但**不迁移历史数据到新表**。理由：

1. 旧数据量小，保留查询价值即可。
2. 历史数据结构与新模型语义不完全一致，强行回灌成本高且收益低。

`iot_card_store.go` 中 `is_replaced` 过滤逻辑改为查询 `ExchangeOrder`，不再依赖旧表。

### 决策 7：依托现有多租户 Callback 自动过滤

`ExchangeOrder` 增加 `shop_id` 字段，直接接入现有 GORM 数据权限 Callback，避免重复实现权限 where 条件。

## 风险与权衡

1. **[风险] 全量迁移事务锁表时间增长**
   - 权衡：换货低频，且单次仅操作单资产关联记录，影响可接受。

2. **[风险] 转新后旧客户仍持有旧虚拟号认知**
   - 权衡：`PersonalCustomerDevice` 绑定会清除，旧客户再次登录会被要求重新绑定，避免继续访问新代际资产。

3. **[风险] 设备换设备不迁移 DeviceSimBinding 造成“看起来少迁移”**
   - 权衡：这是显式设计决策；新设备按“新硬件+新卡”交付，旧设备卡绑定保留历史关系。

4. **[风险] 迁移期 CMP 与 Gateway 状态观测不一致**
   - 权衡：本次迁移仅操作 CMP 数据库，不调用 Gateway；运营商侧状态由新资产实际使用逐步收敛。

## 迁移计划

1. 新建 `tb_exchange_order` 表。
2. 将 `tb_card_replacement_record` 改名为 `tb_card_replacement_record_legacy`。
3. 代码层替换：
   - Store/Service/Handler 查询改用 ExchangeOrder
   - `is_replaced` 等旧逻辑改为新表判定
4. 在 bootstrap、routes、docs 生成器中注册新 Handler（含 `cmd/api/docs.go` 与 `cmd/gendocs/main.go`）。