fix: 换货

docs/换货.md

@@ -0,0 +1,436 @@
+# 换货流程升级接口变更说明
+
+## 一、数据库字段新增
+
+### 表：`tb_exchange_order`
+
+新增以下字段，所有换货单相关接口响应均会返回：
+
+| 字段           | 类型            | 说明                                                         |
+| ------------ | ------------- | ---------------------------------------------------------- |
+| flow_type    | string        | 流程类型：`shipping`（物流换货）或 `direct`（直接换货），历史数据为空时视为 `shipping` |
+| shipped_at   | string | null | 发货时间，仅 `shipping` 流程发货后有值                                  |
+| completed_at | string | null | 换货完成时间，换货完成后有值                                             |
+
+---
+
+# 二、后台接口变更
+
+## 1. 创建换货单
+
+### POST /api/admin/exchanges
+
+### 新增请求参数
+
+```json
+{
+  "old_asset_type": "iot_card",
+  "old_identifier": "xxx",
+  "exchange_reason": "设备损坏",
+  "flow_type": "shipping",
+  "new_identifier": "yyy",
+  "migrate_data": false,
+  "remark": null
+}
+```
+
+### 参数说明
+
+| 字段             | 类型            | 必填         | 说明                                       |
+| -------------- | ------------- | ---------- | ---------------------------------------- |
+| flow_type      | string        | 否          | 流程类型：`shipping` / `direct`，默认 `shipping` |
+| new_identifier | string        | direct 时必填 | 新资产标识符                                   |
+| migrate_data   | boolean       | 否          | 是否迁移数据，默认 false                          |
+| remark         | string | null | 否          | 备注                                       |
+
+### 不同流程行为差异
+
+| flow_type | 创建后状态(status) | completed_at |
+| --------- | ------------- | ------------ |
+| shipping  | 1（待填写信息）      | null         |
+| direct    | 4（已完成）        | 当前时间         |
+
+### 说明
+
+* shipping 为原有流程
+* direct 创建后直接完成
+* direct 不需要填写地址
+* direct 不需要发货
+* direct 不需要确认完成
+* 非法 flow_type 返回参数错误
+
+---
+
+## 2. 换货单列表
+
+### GET /api/admin/exchanges
+
+### 新增查询参数
+
+| 参数         | 类型     | 说明                       |
+| ---------- | ------ | ------------------------ |
+| flow_type  | string | 按流程类型筛选（shipping/direct） |
+| identifier | string | 资产标识符模糊查询（同时匹配旧资产、新资产）   |
+
+### 响应新增字段
+
+```json
+{
+  "flow_type": "shipping",
+  "flow_type_name": "物流换货",
+  "shipped_at": null,
+  "completed_at": null
+}
+```
+
+---
+
+## 3. 换货单详情
+
+### GET /api/admin/exchanges/:id
+
+### 响应新增字段
+
+```json
+{
+  "flow_type": "shipping",
+  "flow_type_name": "物流换货",
+  "shipped_at": null,
+  "completed_at": null
+}
+```
+
+### 说明
+
+对于 direct 类型：
+
+* 收货信息为空
+* 物流信息为空
+
+属于正常情况，前端需根据 flow_type 控制相关区块显示。
+
+---
+
+## 4. 发货
+
+### POST /api/admin/exchanges/:id/ship
+
+### 新增限制
+
+仅支持：
+
+```text
+flow_type = shipping
+```
+
+### 不允许情况
+
+```text
+flow_type = direct
+```
+
+返回：
+
+```json
+{
+  "code": 400,
+  "message": "流程类型不支持该操作"
+}
+```
+
+### 前端处理
+
+```javascript
+exchange.flow_type === 'shipping'
+```
+
+---
+
+## 5. 确认完成
+
+### POST /api/admin/exchanges/:id/complete
+
+### 新增限制
+
+仅支持：
+
+```text
+flow_type = shipping
+status = 3
+```
+
+### 不允许情况
+
+```text
+flow_type = direct
+```
+
+返回错误。
+
+---
+
+## 6. 取消换货
+
+### POST /api/admin/exchanges/:id/cancel
+
+### 新增限制
+
+允许取消：
+
+```text
+flow_type = shipping
+status IN (1, 2)
+```
+
+### 不允许取消
+
+#### direct 单据
+
+```text
+flow_type = direct
+```
+
+#### 已发货单据
+
+```text
+flow_type = shipping
+status = 3
+```
+
+返回错误。
+
+---
+
+# 三、客户端接口变更
+
+## 1. 查询进行中的换货单
+
+### GET /api/c/v1/exchange/pending
+
+### 变更后返回规则
+
+仅返回：
+
+```text
+flow_type = shipping
+status IN (1, 2, 3)
+```
+
+### 不返回
+
+```text
+flow_type = direct
+```
+
+客户端无需特殊处理。
+
+---
+
+## 2. 填写收货地址
+
+### POST /api/c/v1/exchange/:id/shipping-info
+
+### 新增限制
+
+仅支持：
+
+```text
+flow_type = shipping
+status = 1
+```
+
+### 不允许
+
+```text
+flow_type = direct
+```
+
+返回错误。
+
+---
+
+# 四、前端 UI 改造建议
+
+## 换货单详情页
+
+### 新增展示字段
+
+* 流程类型（flow_type_name）
+* 完成时间（completed_at）
+* 发货时间（shipped_at）
+
+### 按流程类型控制按钮
+
+#### direct
+
+不显示：
+
+* 发货
+* 确认完成
+* 取消
+
+#### shipping + status = 1
+
+显示：
+
+* 取消
+
+#### shipping + status = 2
+
+显示：
+
+* 发货
+* 取消
+
+#### shipping + status = 3
+
+显示：
+
+* 确认完成
+
+### 信息区块控制
+
+#### direct
+
+隐藏：
+
+* 收货信息
+* 物流信息
+
+或者显示：
+
+```text
+不适用
+```
+
+---
+
+## 创建换货单弹窗
+
+### 新增字段
+
+流程类型：
+
+* 物流换货（shipping）
+* 直接换货（direct）
+
+### 选择 direct 时
+
+显示：
+
+* 新资产标识符（必填）
+* 是否迁移数据（开关）
+
+对应参数：
+
+```json
+{
+  "new_identifier": "xxx",
+  "migrate_data": true
+}
+```
+
+### 选择 shipping 时
+
+隐藏：
+
+* 新资产标识符
+* 是否迁移数据
+
+---
+
+## 换货单列表页
+
+### 新增表格列
+
+```text
+流程类型
+```
+
+显示：
+
+```text
+物流换货
+直接换货
+```
+
+### 新增筛选项
+
+```text
+流程类型
+```
+
+下拉选项：
+
+```text
+全部
+物流换货（shipping）
+直接换货（direct）
+```
+
+---
+
+# 五、流程状态说明
+
+## shipping（物流换货）
+
+```text
+创建
+ ↓
+待填写信息（1）
+ ↓
+待发货（2）
+ ↓
+已发货（3）
+ ↓
+已完成（4）
+```
+
+## direct（直接换货）
+
+```text
+创建
+ ↓
+已完成（4）
+```
+
+---
+
+# 六、状态与操作矩阵
+
+| flow_type | status | 发货 | 确认完成 | 取消 |
+| --------- | ------ | -- | ---- | -- |
+| shipping  | 1      | ❌  | ❌    | ✅  |
+| shipping  | 2      | ✅  | ❌    | ✅  |
+| shipping  | 3      | ❌  | ✅    | ❌  |
+| shipping  | 4      | ❌  | ❌    | ❌  |
+| direct    | 4      | ❌  | ❌    | ❌  |
+
+---
+
+# 七、枚举定义
+
+## flow_type
+
+```json
+{
+  "shipping": "物流换货",
+  "direct": "直接换货"
+}
+```
+
+## flow_type_name 示例
+
+```json
+{
+  "flow_type": "shipping",
+  "flow_type_name": "物流换货"
+}
+```
+
+```json
+{
+  "flow_type": "direct",
+  "flow_type_name": "直接换货"
+}
+```