# 客户端换货系统功能总结

## 1. 功能概述

本次实现完成了客户端换货系统的后台与客户端闭环能力，覆盖「后台建单 → 客户端填写收货信息 → 后台发货 → 后台确认完成（可选全量迁移） → 旧资产转新」完整流程。

## 2. 数据模型与迁移

- 新增 `tb_exchange_order` 表，承载换货生命周期全量字段：旧/新资产、收货信息、物流信息、迁移状态、业务状态、多租户字段。
- 保留历史能力：将旧表 `tb_card_replacement_record` 重命名为 `tb_card_replacement_record_legacy`。
- 新增迁移文件：
  - `000085_add_exchange_order.up/down.sql`
  - `000086_rename_card_replacement_to_legacy.up/down.sql`

## 3. 后端实现

### 3.1 Store 层

- 新增 `ExchangeOrderStore`：
  - 创建、按 ID 查询、分页列表查询
  - 条件状态流转更新（`WHERE status = fromStatus`）
  - 按旧资产查询进行中换货单（状态 `1/2/3`）

- 新增 `ResourceTagStore`：用于资源标签复制。

### 3.2 Service 层

- 新增 `internal/service/exchange/service.go`：
  - H1 创建换货单（资产存在校验、进行中校验、单号生成、状态初始化）
  - H2 列表查询
  - H3 详情查询
  - H4 发货（状态校验、同类型校验、新资产在库校验、物流与新资产快照写入）
  - H5 确认完成（状态校验，可选全量迁移）
  - H6 取消（仅允许 `1/2 -> 5`）
  - H7 转新（校验已换货状态、`generation+1`、状态重置、清理绑定、创建新钱包）
  - G1 查询待处理换货单
  - G2 提交收货信息（`1 -> 2`）

- 新增 `internal/service/exchange/migration.go`：
  - 单事务迁移实现
  - 钱包余额迁移并写入迁移流水
  - 套餐使用记录迁移（`tb_package_usage`）
  - 套餐日记录联动更新（`tb_package_usage_daily_record`）
  - 累计充值/首充字段复制（旧资产 -> 新资产）
  - 标签复制（`tb_resource_tag`）
  - 客户绑定 `virtual_no` 更新（`tb_personal_customer_device`）
  - 旧资产状态置为已换货（`asset_status=3`）
  - 换货单迁移结果回写（`migration_completed`、`migration_balance`）

## 4. Handler 与路由

### 4.1 后台换货接口

- 新增 `internal/handler/admin/exchange.go`
- 新增 `internal/routes/exchange.go`
- 注册接口（标签：`换货管理`）：
  - `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`

### 4.2 客户端换货接口

- 新增 `internal/handler/app/client_exchange.go`
- 在 `internal/routes/personal.go` 注册：
  - `GET /api/c/v1/exchange/pending`
  - `POST /api/c/v1/exchange/:id/shipping-info`

## 5. 兼容与替换

- `iot_card_store.go` 的 `is_replaced` 过滤逻辑已切换至 `tb_exchange_order`。
- 业务主流程不再依赖旧换卡表（仅模型与 legacy 表保留用于历史数据）。

## 6. 启动装配与文档生成

已完成换货模块在以下位置的全链路接入：

- `internal/bootstrap/types.go`
- `internal/bootstrap/stores.go`
- `internal/bootstrap/services.go`
- `internal/bootstrap/handlers.go`
- `internal/routes/admin.go`
- `pkg/openapi/handlers.go`
- `cmd/api/docs.go`
- `cmd/gendocs/main.go`

## 7. 验证结果

- 已执行：`go build ./...`，编译通过。
- 已执行：数据库迁移 `make migrate-up`，版本到 `86`。
- 已完成：变更文件 LSP 诊断检查（无 error 级问题）。