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
parent df76e33105
commit e78f5794b9
41 changed files with 5242 additions and 10 deletions
--- a/openspec/changes/client-exchange-system/.openspec.yaml
+++ b/openspec/changes/client-exchange-system/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-18
--- a/openspec/changes/client-exchange-system/design.md
+++ b/openspec/changes/client-exchange-system/design.md
@@ -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`）。
--- a/openspec/changes/client-exchange-system/proposal.md
+++ b/openspec/changes/client-exchange-system/proposal.md
@@ -0,0 +1,162 @@
+## Why
+
+现有 `CardReplacementRecord` 模型仅支持简单换卡，无法满足完整换货需求：缺少收货地址、快递信息、设备换货、全量数据迁移等功能。客户端换货场景中，后台发起换货 → 客户端收到通知填写收货信息 → 后台发货+确认完成（含全量迁移）→ 旧资产可"转新"重新销售，是一个跨后台/客户端的完整业务闭环。
+
+**前置依赖**：提案 0（`asset_status`/`generation` 字段已就位）、提案 1（客户端认证）。
+
+## What Changes
+
+### 新增模型
+
+- **ExchangeOrder（换货单）**：完整的换货生命周期模型，包含旧/新资产信息、收货地址、物流信息、迁移状态。状态机：`1-待填写信息 → 2-待发货 → 3-已发货待确认 → 4-已完成`，1 或 2 时可取消(→5)
+
+### 删除旧模型
+
+- **CardReplacementRecord**：表改名为 `tb_card_replacement_record_legacy`，代码引用替换为 ExchangeOrder
+
+### 后台换货管理（模块 H，7 个接口）
+
+- **H1 发起换货** `POST /api/admin/exchanges`：验证资产无进行中换货单，创建 status=1
+- **H2 换货列表** `GET /api/admin/exchanges`：支持状态筛选、资产标识符搜索、时间范围
+- **H3 换货详情** `GET /api/admin/exchanges/:id`
+- **H4 发货** `POST /api/admin/exchanges/:id/ship`：填写物流信息+新资产标识符，验证 status=2、同类型资产、新资产 asset_status=1（在库）
+- **H5 确认完成** `POST /api/admin/exchanges/:id/complete`：验证 status=3，如 migrate_data=true 则执行全量迁移（11 张表事务内操作），旧资产 asset_status→3
+- **H6 取消换货** `POST /api/admin/exchanges/:id/cancel`：验证 status IN (1,2)，已发货不可取消
+- **H7 旧资产转新** `POST /api/admin/exchanges/:id/renew`：旧资产 asset_status 从 3→1，generation+1，清除客户绑定和累计状态，创建新空钱包
+
+### 客户端换货（模块 G，2 个接口）
+
+- **G1 查询换货通知** `GET /api/c/v1/exchange/pending?identifier=xxx`：查是否有进行中的换货单
+- **G2 填写收货信息** `POST /api/c/v1/exchange/:id/shipping-info`：验证 status=1，更新收货信息，status→2
+
+### 换货状态机
+
+```
+后台发起换货
+    │
+    ▼
+┌─────────────────────┐
+│ 1-待填写信息        │ ←── ExchangeOrder 创建
+│ (等待客户端填写)     │
+└──────────┬──────────┘
+           │
+    客户端填写收货信息 [G2]
+           │
+           ▼
+┌─────────────────────┐
+│ 2-待发货            │
+│ (等待后台填写物流)   │
+└──────────┬──────────┘
+           │
+    后台发货 [H4] (填物流+新资产)
+           │
+           ▼
+┌─────────────────────┐
+│ 3-已发货待确认      │
+│ (等待后台确认完成)   │
+└──────────┬──────────┘
+           │
+    后台确认完成 [H5]
+    (可选: 全量迁移)
+           │
+           ▼
+┌─────────────────────┐
+│ 4-已完成            │
+└─────────────────────┘
+
+取消: status=1 或 2 时可取消 → 5-已取消
+已发货(status=3)后不可取消
+```
+
+### 全量迁移流程（H5 确认完成时触发）
+
+```
+确认完成 (migrate_data=true)
+    │
+    ▼
+事务开始
+    │
+    ├── 1. 钱包余额转移
+    │   旧 AssetWallet.Balance → 新 AssetWallet
+    │   生成迁移流水 AssetWalletTransaction
+    │
+    ├── 2. 生效中套餐关联新资产
+    │   PackageUsage WHERE iot_card_id/device_id=旧 AND status IN (生效中)
+    │   → UPDATE iot_card_id/device_id = 新
+    │
+    ├── 3. 累计充值/首充状态迁移
+    │   IotCard/Device 的 AccumulatedRecharge/FirstCommissionPaid
+    │   等字段复制到新资产
+    │
+    ├── 4. 标签复制
+    │   ResourceTag WHERE resource_type=? AND resource_id=旧
+    │   → 为新资产创建相同标签
+    │
+    ├── 5. 个人客户绑定更新
+    │   PersonalCustomerDevice WHERE virtual_no=旧虚拟号
+    │   → UPDATE virtual_no = 新虚拟号
+    │
+    ├── 6. 旧资产标记
+    │   旧资产 asset_status → 3（已换货）
+    │
+    └── 7. 记录迁移信息
+        ExchangeOrder: migration_completed=true,
+        migration_balance=转移金额
+    │
+    ▼
+事务提交
+    │
+    ▼
+ExchangeOrder status → 4（已完成）
+
+注意:
+- 设备换设备时不迁移 DeviceSimBinding（卡绑定关系）
+- 新设备自带新的 SIM 卡，旧设备的卡绑定保持不变
+- 保留不修改的表: tb_order, tb_commission, tb_data_usage_record,
+  tb_asset_recharge_record（历史记录保留，通过 generation 隔离）
+```
+
+### 转新流程（H7）
+
+```
+旧资产 (asset_status=3 已换货)
+    │
+    ▼
+POST /api/admin/exchanges/:id/renew
+    │
+    ├── 1. asset_status: 3 → 1（在库）
+    ├── 2. generation: +1（进入新世代）
+    ├── 3. 清除: 累计充值状态、首充触发状态
+    ├── 4. 清除: PersonalCustomerDevice 绑定
+    ├── 5. 创建新空钱包（新 wallet_id）
+    └── 6. 不删除历史数据（通过 generation 隔离）
+    │
+    ▼
+旧资产可重新销售给新客户
+新客户查询时按当前 generation 过滤
+看不到旧周期数据
+```
+
+## Capabilities
+
+### New Capabilities
+
+- `exchange-order-model`：ExchangeOrder 模型定义、状态机、状态常量、换货单号生成规则
+- `exchange-admin-management`：后台换货管理 CRUD（H1~H3）、发货（H4，含同类型资产校验+新资产在库校验）、确认完成（H5，含全量迁移事务）、取消（H6）、转新（H7，含 generation 自增+状态重置）
+- `exchange-data-migration`：全量迁移逻辑，11 张数据表的事务内操作规则，设备不迁移卡绑定的特殊规则
+- `exchange-client-notification`：客户端换货通知查询（G1）、收货信息填写（G2）
+
+### Modified Capabilities
+
+- `iot-card`：IotCard 新增换货相关行为——`asset_status=3` 标记、转新时 generation 自增+状态重置
+- `device`：Device 同上
+- `personal-customer`：PersonalCustomerDevice 绑定关系在换货迁移时更新虚拟号
+- `card-replacement`：**REMOVED** — CardReplacementRecord 模型废弃，表改名为 legacy，代码引用替换为 ExchangeOrder
+
+## Impact
+
+- **新增文件**：`internal/model/exchange_order.go`（模型）；`internal/handler/admin/exchange.go`（后台 Handler）；`internal/handler/app/client_exchange.go`（客户端 Handler）；`internal/service/exchange/service.go`（Service，含迁移逻辑）；`internal/store/postgres/exchange_order_store.go`（Store）；DTO 文件；迁移文件；常量和错误码
+- **修改文件**：`internal/model/card_replacement.go`（删除或标记废弃）；`internal/store/postgres/iot_card_store.go`（移除 `is_replaced` 过滤改为查新表）；`internal/model/system.go`（AutoMigrate 移除旧模型+注册新模型）；`internal/routes/`（新增后台+客户端路由）；`internal/bootstrap/`（注册新模块）；`cmd/api/docs.go` + `cmd/gendocs/main.go`（文档生成器）
+- **新增 API 路由**：后台 `/api/admin/exchanges/` 下 7 个端点 + 客户端 `/api/c/v1/exchange/` 下 2 个端点
+- **数据库变更**：新建 `tb_exchange_order` 表；旧表 `tb_card_replacement_record` 改名为 `tb_card_replacement_record_legacy`
+- **全量迁移涉及 11 张表**：`tb_asset_wallet`、`tb_asset_wallet_transaction`、`tb_asset_recharge_record`、`tb_package_usage`、`tb_package_usage_daily_record`、`tb_order`、`tb_commission`、`tb_data_usage_record`、`tb_resource_tag`、`tb_personal_customer_device`、`tb_iot_card`/`tb_device`
--- a/openspec/changes/client-exchange-system/specs/card-replacement/spec.md
+++ b/openspec/changes/client-exchange-system/specs/card-replacement/spec.md
@@ -0,0 +1,31 @@
+## 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 表
--- a/openspec/changes/client-exchange-system/specs/device/spec.md
+++ b/openspec/changes/client-exchange-system/specs/device/spec.md
@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: 设备换货状态语义扩展
+
+系统 SHALL 将 `asset_status=3` 定义为“已换货”，用于标记已被换出的旧设备资产。
+
+#### Scenario: 换货完成后旧设备标记
+- **WHEN** H5 确认完成且旧资产为设备
+- **THEN** 系统 MUST 将旧设备 `asset_status` 更新为 `3`
+
+---
+
+### Requirement: 设备转新重置规则
+
+系统 SHALL 在 H7 转新时对设备执行以下重置：
+- `generation = generation + 1`
+- `asset_status = 1`（在库）
+- 清空累计充值与首充触发相关状态
+- 清除个人客户绑定关系
+- 创建新空钱包并与新代际设备关联
+
+#### Scenario: 转新后设备可重新销售
+- **WHEN** 对已换货设备执行转新
+- **THEN** 系统 MUST 使该设备进入新代际并恢复在库可售
--- a/openspec/changes/client-exchange-system/specs/exchange-admin-management/spec.md
+++ b/openspec/changes/client-exchange-system/specs/exchange-admin-management/spec.md
@@ -0,0 +1,121 @@
+## ADDED Requirements
+
+### Requirement: H1 发起换货单
+
+系统 SHALL 提供 `POST /api/admin/exchanges`（需后台认证 `Auth=true`），用于发起换货单。
+
+请求体 MUST 包含：`old_asset_type`、`old_identifier`、`exchange_reason`，可选 `remark`。
+
+系统 MUST 校验：
+- 旧资产存在且当前用户有权限
+- 同一资产不存在进行中的换货单（`status IN (1,2,3)`）
+
+成功响应 SHALL 返回新建换货单信息（含 `id`、`exchange_no`、`status=1`）。
+
+错误响应 MUST 至少包含：参数错误、资产不存在或无权限、存在进行中换货单。
+
+#### Scenario: 资产已有进行中换货单
+- **WHEN** 后台为同一资产重复发起换货
+- **THEN** 系统 MUST 拒绝创建并返回“存在进行中的换货单”
+
+---
+
+### Requirement: H2 换货单列表
+
+系统 SHALL 提供 `GET /api/admin/exchanges`（`Auth=true`），支持分页与条件查询。
+
+查询条件 SHOULD 支持：`status`、`identifier`（资产标识搜索）、`created_at_start`、`created_at_end`、分页参数。
+
+响应 SHALL 返回列表与分页元数据。
+
+#### Scenario: 按状态查询待发货单
+- **WHEN** 运营查询 `status=2`
+- **THEN** 系统返回所有待发货换货单并按创建时间倒序
+
+---
+
+### Requirement: H3 换货单详情
+
+系统 SHALL 提供 `GET /api/admin/exchanges/:id`（`Auth=true`）查询换货单详情。
+
+响应 MUST 返回旧/新资产信息、收货信息、物流信息、迁移状态信息。
+
+错误响应 MUST 至少包含：换货单不存在或无权限。
+
+#### Scenario: 查询不存在换货单
+- **WHEN** 查询不存在的换货单 ID
+- **THEN** 系统 MUST 返回“资源不存在或无权限”
+
+---
+
+### Requirement: H4 发货
+
+系统 SHALL 提供 `POST /api/admin/exchanges/:id/ship`（`Auth=true`）。
+
+请求体 MUST 包含：`express_company`、`express_no`、`new_identifier`、`migrate_data`。
+
+系统 MUST 校验：
+- 当前状态必须为 `2`
+- 新旧资产类型必须一致（卡换卡/设备换设备）
+- 新资产必须 `asset_status=1`（在库）
+
+成功后 SHALL 更新新资产信息、物流信息并将状态改为 `3`。
+
+错误响应 MUST 至少包含：非法状态、资产类型不匹配、新资产非在库、资产不存在或无权限。
+
+#### Scenario: 新资产类型不一致
+- **WHEN** 旧资产为 iot_card 且新资产为 device
+- **THEN** 系统 MUST 拒绝发货并返回“换货资产类型必须一致”
+
+---
+
+### Requirement: H5 确认完成
+
+系统 SHALL 提供 `POST /api/admin/exchanges/:id/complete`（`Auth=true`）。
+
+系统 MUST 校验当前状态为 `3`。当 `migrate_data=true` 时，系统 MUST 执行全量迁移事务（见 `exchange-data-migration` 能力）。
+
+成功后 SHALL：
+- `migration_completed=true`（若执行迁移）
+- 换货单状态更新为 `4`
+
+错误响应 MUST 至少包含：非法状态、迁移失败、换货单不存在或无权限。
+
+#### Scenario: 需要迁移并完成
+- **WHEN** 状态为 `3` 且 `migrate_data=true`
+- **THEN** 系统 MUST 在事务成功后将状态变为 `4` 并记录迁移结果
+
+---
+
+### Requirement: H6 取消换货
+
+系统 SHALL 提供 `POST /api/admin/exchanges/:id/cancel`（`Auth=true`）。
+
+系统 MUST 仅允许在 `status IN (1,2)` 时取消，成功后状态更新为 `5`。
+
+系统 MUST 禁止已发货单取消（`status=3`）。
+
+#### Scenario: 已发货单取消失败
+- **WHEN** 换货单状态为 `3` 发起取消
+- **THEN** 系统 MUST 返回状态非法错误
+
+---
+
+### Requirement: H7 旧资产转新
+
+系统 SHALL 提供 `POST /api/admin/exchanges/:id/renew`（`Auth=true`）。
+
+系统 MUST 校验旧资产当前 `asset_status=3`（已换货），并执行：
+- `generation + 1`
+- `asset_status -> 1`
+- 清除累计充值/首充相关状态
+- 清除个人客户绑定
+- 创建新空钱包
+
+系统 MUST 保留历史数据，不执行历史删除。
+
+错误响应 MUST 至少包含：资产状态不满足转新条件、换货单不存在或无权限。
+
+#### Scenario: 旧资产未处于已换货状态
+- **WHEN** 旧资产 `asset_status != 3` 发起转新
+- **THEN** 系统 MUST 拒绝并返回“资产当前状态不允许转新”
--- a/openspec/changes/client-exchange-system/specs/exchange-client-notification/spec.md
+++ b/openspec/changes/client-exchange-system/specs/exchange-client-notification/spec.md
@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: G1 查询进行中换货通知
+
+系统 SHALL 提供 `GET /api/c/v1/exchange/pending?identifier=xxx`（需个人客户认证 `Auth=true`）。
+
+系统 MUST 根据资产标识查询当前客户可见的进行中换货单，仅返回 `status IN (1,2,3)` 的记录。
+
+响应 SHALL 至少包含：换货单 ID、单号、状态、换货原因、创建时间。
+
+错误响应 MUST 至少包含：参数错误、资产不存在或无权限。
+
+#### Scenario: 命中进行中换货单
+- **WHEN** 客户按资产标识查询且存在状态为 2 的换货单
+- **THEN** 系统返回该换货单并标识当前状态为待发货
+
+---
+
+### Requirement: G2 填写收货信息
+
+系统 SHALL 提供 `POST /api/c/v1/exchange/:id/shipping-info`（需个人客户认证 `Auth=true`）。
+
+请求体 MUST 包含：`recipient_name`、`recipient_phone`、`recipient_address`。
+
+系统 MUST 校验：
+- 换货单存在且当前客户有权限
+- 当前状态必须为 `1`
+
+成功后 SHALL 写入收货信息并将状态更新为 `2`。
+
+错误响应 MUST 至少包含：参数错误、状态非法、换货单不存在或无权限。
+
+#### Scenario: 非待填写状态禁止更新收货信息
+- **WHEN** 换货单当前状态为 `2` 或 `3`
+- **THEN** 系统 MUST 拒绝填写并返回状态非法错误
--- a/openspec/changes/client-exchange-system/specs/exchange-data-migration/spec.md
+++ b/openspec/changes/client-exchange-system/specs/exchange-data-migration/spec.md
@@ -0,0 +1,60 @@
+## ADDED Requirements
+
+### Requirement: 全量迁移事务边界
+
+系统 MUST 在 H5 确认完成且 `migrate_data=true` 时，使用**单一数据库事务**执行全量迁移。
+
+该事务 SHALL 覆盖资产钱包、套餐、标签、客户绑定及资产状态更新等所有步骤；任一步骤失败 MUST 回滚。
+
+#### Scenario: 迁移中途失败回滚
+- **WHEN** 迁移第 N 步发生数据库错误
+- **THEN** 系统 MUST 回滚整个事务，换货单状态保持未完成
+
+---
+
+### Requirement: 11 张表迁移规则
+
+系统 SHALL 按以下规则处理 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`：将绑定记录中的 `virtual_no` 更新为新资产虚拟号。
+11. `tb_iot_card`/`tb_device`：迁移累计充值与首充状态到新资产，并将旧资产 `asset_status -> 3`。
+
+#### Scenario: 钱包余额转移并记录流水
+- **WHEN** 旧资产钱包余额为 5000 分
+- **THEN** 新资产钱包余额增加 5000 分，旧钱包余额按迁移策略清零，并写入迁移流水
+
+---
+
+### Requirement: 设备换设备特殊规则
+
+设备换设备流程 MUST NOT 迁移 `DeviceSimBinding`。
+
+系统 SHALL 视新设备为新硬件交付，新设备卡绑定由其自身体系决定，旧设备绑定关系保留历史。
+
+#### Scenario: 设备换设备不复制绑定卡
+- **WHEN** 执行设备换设备全量迁移
+- **THEN** 系统 MUST 不创建或复制任何 `DeviceSimBinding` 记录到新设备
+
+---
+
+### Requirement: 转新规则
+
+系统 SHALL 在 H7 转新时执行代际隔离策略：
+- 资产 `generation + 1`
+- 创建新空钱包（新 `wallet_id`）
+- 清除累计充值状态与首充触发状态
+- 清除 `PersonalCustomerDevice` 绑定
+- 不删除历史业务数据
+
+#### Scenario: 转新后历史数据保留
+- **WHEN** 资产转新完成
+- **THEN** 历史订单、充值、分佣、流量数据 MUST 仍可在旧代际查询链路中追溯
--- a/openspec/changes/client-exchange-system/specs/exchange-order-model/spec.md
+++ b/openspec/changes/client-exchange-system/specs/exchange-order-model/spec.md
@@ -0,0 +1,69 @@
+## ADDED Requirements
+
+### Requirement: ExchangeOrder 换货单模型定义
+
+系统 SHALL 定义 `ExchangeOrder` 模型并映射到 `tb_exchange_order`，用于承载客户端换货完整生命周期。
+
+模型字段 MUST 至少包含：
+- 基础：`id`、`created_at`、`updated_at`、`deleted_at`、`creator`、`updater`
+- 单号：`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`
+
+`ExchangeOrder` SHALL 嵌入 `BaseModel` 并实现 `TableName() string`，返回 `tb_exchange_order`。
+
+#### Scenario: 创建换货单模型实例
+- **WHEN** 系统创建新的换货单记录
+- **THEN** 记录 MUST 同时包含旧资产快照、收货信息占位、迁移状态字段和多租户字段
+
+---
+
+### Requirement: 换货状态常量定义
+
+系统 MUST 使用 int 常量定义换货状态：
+- `1` 待填写信息
+- `2` 待发货
+- `3` 已发货待确认
+- `4` 已完成
+- `5` 已取消
+
+#### Scenario: 状态常量一致性
+- **WHEN** Service、Store、Handler 读取或更新换货状态
+- **THEN** 各层 MUST 使用统一常量值，禁止硬编码散落魔法数字
+
+---
+
+### Requirement: 换货状态机流转规则
+
+系统 SHALL 执行以下状态机：
+- 创建换货单后：`1`
+- 客户填写收货信息后：`1 -> 2`
+- 后台发货后：`2 -> 3`
+- 后台确认完成后：`3 -> 4`
+- 取消：仅允许 `1/2 -> 5`
+
+系统 MUST 禁止非法流转（如 `3 -> 5`、`4 -> 2`）。
+
+#### Scenario: 已发货不可取消
+- **WHEN** 换货单状态为 `3` 且请求取消
+- **THEN** 系统 MUST 拒绝并返回状态流转非法错误
+
+---
+
+### Requirement: 换货单号生成规则
+
+系统 MUST 为每个换货单生成全局可追踪单号，格式为：`EXC + 时间戳片段 + 随机数片段`。
+
+生成规则 SHALL 满足：
+- 前缀固定为 `EXC`
+- 包含日期/时间信息用于人工排查
+- 包含随机片段降低并发冲突概率
+
+#### Scenario: 生成换货单号
+- **WHEN** 后台发起换货并创建新单
+- **THEN** 系统 MUST 生成形如 `EXC20260319XXXXXX` 的单号并写入 `exchange_no`
--- a/openspec/changes/client-exchange-system/specs/iot-card/spec.md
+++ b/openspec/changes/client-exchange-system/specs/iot-card/spec.md
@@ -0,0 +1,23 @@
+## MODIFIED Requirements
+
+### Requirement: IoT 卡换货状态语义扩展
+
+系统 SHALL 将 `asset_status=3` 定义为“已换货”，用于标记已被换出、不可继续作为当前代际在售资产的 IoT 卡。
+
+#### Scenario: 换货完成后旧卡标记为已换货
+- **WHEN** H5 确认完成且旧资产为 IoT 卡
+- **THEN** 系统 MUST 将旧卡 `asset_status` 更新为 `3`
+
+---
+
+### Requirement: IoT 卡转新重置规则
+
+系统 SHALL 在 H7 转新时对 IoT 卡执行以下重置：
+- `generation = generation + 1`
+- `asset_status = 1`（在库）
+- 清空累计充值与首充触发相关状态（含 `AccumulatedRecharge`、`FirstCommissionPaid`、系列首充/累计字段）
+- 清除个人客户绑定关系
+
+#### Scenario: 转新后进入新代际
+- **WHEN** 对旧卡执行转新
+- **THEN** 系统 MUST 使该卡进入新代际并以在库状态重新销售
--- a/openspec/changes/client-exchange-system/specs/personal-customer/spec.md
+++ b/openspec/changes/client-exchange-system/specs/personal-customer/spec.md
@@ -0,0 +1,21 @@
+## MODIFIED Requirements
+
+### Requirement: 换货迁移时更新个人客户资产绑定
+
+系统 SHALL 在 H5 全量迁移成功后，更新 `PersonalCustomerDevice` 的资产标识绑定关系：
+- 若旧资产存在客户绑定，绑定中的 `virtual_no` MUST 更新为新资产 `virtual_no`
+- 更新后客户对资产访问连续，不需重新登录即可看到新资产
+
+#### Scenario: 迁移后客户绑定跟随新资产
+- **WHEN** 旧资产存在个人客户绑定且执行了 `migrate_data=true`
+- **THEN** 系统 MUST 将绑定记录的 `virtual_no` 更新为新资产虚拟号
+
+---
+
+### Requirement: 转新时清除个人客户绑定
+
+系统 SHALL 在 H7 转新时清除该资产在 `PersonalCustomerDevice` 中的绑定关系，避免旧客户继续访问新代际资产。
+
+#### Scenario: 转新后旧客户需重新绑定
+- **WHEN** 资产转新完成
+- **THEN** 系统 MUST 删除或失效对应客户绑定，使旧客户再次访问时触发重新绑定流程
--- a/openspec/changes/client-exchange-system/tasks.md
+++ b/openspec/changes/client-exchange-system/tasks.md
@@ -0,0 +1,37 @@
+- [x] 1.1 定义 ExchangeOrder 模型（含 BaseModel、旧/新资产字段、收货字段、物流字段、迁移字段、shop_id）
+- [x] 1.2 新增换货状态常量（1待填写、2待发货、3已发货待确认、4已完成、5已取消）
+- [x] 1.3 实现换货单号生成函数（EXC + 日期时间 + 随机数）
+- [x] 1.4 新增后台/客户端换货相关 DTO（请求参数、响应结构、错误字段）
+
+- [x] 2.1 创建数据库迁移：新增 tb_exchange_order 表
+- [x] 2.2 创建数据库迁移：将 tb_card_replacement_record 改名为 tb_card_replacement_record_legacy
+
+- [x] 3.1 实现 ExchangeOrderStore：创建换货单、按ID查询、按条件分页查询
+- [x] 3.2 实现 ExchangeOrderStore：状态更新（含前置状态校验）
+- [x] 3.3 实现 ExchangeOrderStore：按旧资产查询进行中换货单
+
+- [x] 4.1 实现换货 Service：H1 创建换货单与重复进行中校验
+- [x] 4.2 实现换货 Service：状态流转校验（1->2->3->4、1/2->5）
+- [x] 4.3 实现换货 Service：H4 发货同类型资产校验与新资产在库校验
+- [x] 4.4 实现换货 Service：H5 确认完成与可选全量迁移入口
+- [x] 4.5 实现换货 Service：全量迁移事务（11张表规则）
+- [x] 4.6 实现换货 Service：H7 转新逻辑（generation+1、状态重置、清除绑定、新钱包）
+
+- [x] 5.1 新增后台 Exchange Handler（H1~H7）
+- [x] 5.2 在 admin 路由注册 H1~H7（使用 Register() + RouteSpec 完整元数据）
+
+- [x] 6.1 新增客户端 Exchange Handler（G1~G2）
+- [x] 6.2 在客户端路由注册 G1~G2（使用 Register() + RouteSpec 完整元数据）
+
+- [x] 7.1 清理旧模型引用：移除/停用 card_replacement.go 在业务流程中的使用
+- [x] 7.2 修改 iot_card_store.go 的 is_replaced 过滤逻辑，改为查询 ExchangeOrder
+
+- [x] 8.1 更新 bootstrap/types.go：新增后台与客户端换货 Handler 字段
+- [x] 8.2 更新 bootstrap/handlers.go：实例化换货相关 Handler
+- [x] 8.3 更新 cmd/api/docs.go：注册换货 Handler 到文档生成器
+- [x] 8.4 更新 cmd/gendocs/main.go：注册换货 Handler 到文档生成器
+
+- [x] 9.1 执行 go build 验证编译通过
+- [x] 9.2 执行 lsp_diagnostics 检查改动文件诊断信息
+- [x] 9.3 使用数据库验证流程核对 tb_exchange_order 与 legacy 表结构
+- [x] 9.4 在 docs/client-exchange-system/ 补充功能总结文档