huang
b9733c4913
1. 修正 retail_price 架构：
- 删除 batch-pricing 接口的 pricing_target 字段和 retail_price 分支
（上级只能改下级成本价，不能改零售价）
- 新增 PATCH /api/admin/packages/:id/retail-price 接口
（代理自己改自己的零售价，校验 retail_price >= cost_price）
2. 清理旧微信 YAML 配置（已全部迁移到数据库 tb_wechat_config）：
- 删除 config.yaml 中 wechat.official_account 配置节
- 删除 NewOfficialAccountApp() 旧工厂函数
- 清理 personal_customer service 中的死代码（旧登录/绑定微信方法）
- 清理 docker-compose.prod.yml 中旧微信环境变量和证书挂载注释
3. 归档四个已完成提案到 openspec/changes/archive/
4. 新增前端接口变更说明文档（docs/前端接口变更说明.md）
5. 修正归档提案和 specs 中关于 pricing_target 的错误描述
6.6 KiB
设计文档：客户端换货系统（client-exchange-system）
背景与上下文
现有换卡能力基于 CardReplacementRecord，仅覆盖“老卡→新卡”的窄场景，无法支撑本次目标中的完整换货闭环（后台发起、客户端填收货、后台发货、确认完成、可选全量迁移、旧资产转新再销售）。
当前主要问题：
-
模型能力不足（
internal/model/card_replacement.go:11-71）- 只支持卡换卡，不支持设备换设备。
- 缺少客户端收货地址、后台物流信息、迁移结果字段。
- 状态机不匹配本次流程（待填写→待发货→已发货待确认→已完成/已取消）。
-
历史代码字段不一致风险（
internal/store/postgres/iot_card_store.go:644-655）- 现有查询使用
old_iot_card_id维度过滤换卡记录，但旧模型字段命名是old_card_id，存在语义/列名不一致隐患。 is_replaced逻辑依赖旧表，不适配新换货单模型。
- 现有查询使用
-
旧模型未纳入统一迁移体系
CardReplacementRecord没有持续参与当前主线 AutoMigrate 维护，演进风险高。
-
资产迁移链路涉及多模型联动，旧方案无法表达
- 钱包与流水：
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）
- 钱包与流水：
-
模块接入需遵循统一 Bootstrap 装配模式
- 参考
internal/bootstrap/handlers.go:12-62、internal/bootstrap/types.go:13-60。
- 参考
目标与非目标
Goals
- 提供完整换货生命周期能力：
- 后台 7 个接口（H1~H7）
- 客户端 2 个接口（G1~G2）
- 在 H5 确认完成时支持可选“全量迁移”（11 张表规则）。
- 支持旧资产“转新”再销售（generation+1、状态重置、历史隔离）。
- 替换旧换卡模型引用，统一到 ExchangeOrder。
Non-Goals
- 不对接第三方物流轨迹查询（仅记录物流公司/单号）。
- 不实现主动消息推送（客户端通过 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 层校验，不使用数据库触发器。理由：
- 业务规则集中在 Go 代码，便于复用和审计。
- 避免跨环境数据库触发器差异。
- 更易与错误码体系、权限体系协同。
决策 3：发货时执行同类型资产校验
在 H4 发货阶段强制校验：
new_asset_type == old_asset_type（卡换卡 / 设备换设备）。- 新资产必须
asset_status=1（在库）。
该校验放在“发货”而非“创建”，因为创建时允许先立单、后备货。
决策 4：全量迁移使用单一大事务（11 张表）
H5 在 migrate_data=true 时，使用一个数据库事务完成 11 张表相关操作。理由：
- 迁移一致性优先，必须保证“要么全成功，要么全失败”。
- 换货属于低频运营操作，非高并发核心交易路径。
- 单资产迁移涉及行数有限，可接受事务时间。
补充规则：设备换设备时，不迁移 DeviceSimBinding（新设备视为自带新卡体系）。
决策 5：转新采用 generation 隔离历史
H7 转新时：
generation = generation + 1- 不删除旧代际历史数据（订单、充值、分佣、流量等）
- 创建新空钱包（新
wallet_id天然隔离流水） - 清除累计充值/首充触发状态
- 清除客户绑定关系
通过“新代际 + 新钱包”实现可回收再销售，同时不破坏历史可追溯。
决策 6：旧模型降级为 legacy，不回灌迁移
CardReplacementRecord 对应表改名为 tb_card_replacement_record_legacy，但不迁移历史数据到新表。理由：
- 旧数据量小，保留查询价值即可。
- 历史数据结构与新模型语义不完全一致，强行回灌成本高且收益低。
iot_card_store.go 中 is_replaced 过滤逻辑改为查询 ExchangeOrder，不再依赖旧表。
决策 7：依托现有多租户 Callback 自动过滤
ExchangeOrder 增加 shop_id 字段，直接接入现有 GORM 数据权限 Callback，避免重复实现权限 where 条件。
风险与权衡
-
[风险] 全量迁移事务锁表时间增长
- 权衡：换货低频，且单次仅操作单资产关联记录，影响可接受。
-
[风险] 转新后旧客户仍持有旧虚拟号认知
- 权衡：
PersonalCustomerDevice绑定会清除，旧客户再次登录会被要求重新绑定，避免继续访问新代际资产。
- 权衡：
-
[风险] 设备换设备不迁移 DeviceSimBinding 造成“看起来少迁移”
- 权衡：这是显式设计决策；新设备按“新硬件+新卡”交付，旧设备卡绑定保留历史关系。
-
[风险] 迁移期 CMP 与 Gateway 状态观测不一致
- 权衡：本次迁移仅操作 CMP 数据库，不调用 Gateway；运营商侧状态由新资产实际使用逐步收敛。
迁移计划
- 新建
tb_exchange_order表。 - 将
tb_card_replacement_record改名为tb_card_replacement_record_legacy。 - 代码层替换：
- Store/Service/Handler 查询改用 ExchangeOrder
is_replaced等旧逻辑改为新表判定
- 在 bootstrap、routes、docs 生成器中注册新 Handler（含
cmd/api/docs.go与cmd/gendocs/main.go）。