feat: 实现客户端换货系统（client-exchange-system）
新增完整换货生命周期管理：后台发起 → 客户端填收货信息 → 后台发货 → 确认完成（含可选全量迁移） → 旧资产转新再销售 后台接口（7个）： - POST /api/admin/exchanges（发起换货） - GET /api/admin/exchanges（换货列表） - GET /api/admin/exchanges/:id（换货详情） - POST /api/admin/exchanges/:id/ship（发货） - POST /api/admin/exchanges/:id/complete（确认完成+可选迁移） - POST /api/admin/exchanges/:id/cancel（取消） - POST /api/admin/exchanges/:id/renew（旧资产转新） 客户端接口（2个）： - GET /api/c/v1/exchange/pending（查询换货通知） - POST /api/c/v1/exchange/:id/shipping-info（填写收货信息） 核心能力： - ExchangeOrder 模型与状态机（1待填写→2待发货→3已发货→4已完成，1/2可取消→5） - 全量迁移事务（11张表：钱包、套餐、标签、客户绑定等） - 旧资产转新（generation+1、状态重置、新钱包、历史隔离） - 旧 CardReplacementRecord 表改名为 legacy，is_replaced 过滤改为查新表 - 数据库迁移：000085 新建 tb_exchange_order，000086 旧表改名
This commit is contained in:
149
openspec/changes/client-exchange-system/design.md
Normal file
149
openspec/changes/client-exchange-system/design.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 设计文档：客户端换货系统（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`）。
|
||||
Reference in New Issue
Block a user