junhong_cmp_fiber/openspec/changes/client-exchange-system/specs/card-replacement/spec.md at e78f5794b99d895588b23fa4c9d6bb3b161cfcec

csxj2026/junhong_cmp_fiber

Files

huang e78f5794b9 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 旧表改名

2026-03-19 13:26:54 +08:00

1.3 KiB

Raw Blame History

MODIFIED Requirements

Requirement: 废弃旧换卡模型能力

系统 MUST 废弃 CardReplacementRecord 作为主业务能力，原因是其仅覆盖卡换卡且缺少收货信息、物流信息、设备换货与全量迁移能力，无法满足当前换货闭环需求。

Scenario: 新换货流程不再写入旧模型

WHEN 执行任意新换货流程（H1~~H7、G1~~G2）
THEN 系统 MUST 仅读写 ExchangeOrder，不再创建 CardReplacementRecord 新记录

Requirement: 旧表迁移为 legacy 保留查询

系统 SHALL 将 tb_card_replacement_record 改名为 tb_card_replacement_record_legacy，仅用于历史查询保留。

系统 MUST NOT 将 legacy 数据回灌到 tb_exchange_order。

Scenario: legacy 数据保留但不参与新流程

WHEN 运营查询历史老换卡记录
THEN 系统可从 legacy 表读取历史数据，但新换货流程 SHALL 不依赖该表

Requirement: 旧代码引用替换

系统 MUST 将旧换卡引用替换为 ExchangeOrder，包括 iot_card_store.go 中 is_replaced 过滤逻辑。

Scenario: is_replaced 基于新换货单判定

WHEN 查询 IoT 卡并使用 is_replaced=true 过滤
THEN 系统 MUST 基于 ExchangeOrder 状态判定是否已发生换货，而非 legacy 表

1.3 KiB Raw Blame History Unescape Escape