device-voice-h5/docs/换货.md

换货流程升级接口变更说明

一、数据库字段新增

表：tb_exchange_order

新增以下字段，所有换货单相关接口响应均会返回：

字段	类型	说明
flow_type	string	流程类型：shipping（物流换货）或 direct（直接换货），历史数据为空时视为 shipping
shipped_at	string	null
completed_at	string	null

---

二、后台接口变更

1. 创建换货单

POST /api/admin/exchanges

新增请求参数

{
  "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	资产标识符模糊查询（同时匹配旧资产、新资产）

响应新增字段

{
  "flow_type": "shipping",
  "flow_type_name": "物流换货",
  "shipped_at": null,
  "completed_at": null
}

---

3. 换货单详情

GET /api/admin/exchanges/:id

响应新增字段

{
  "flow_type": "shipping",
  "flow_type_name": "物流换货",
  "shipped_at": null,
  "completed_at": null
}

说明

对于 direct 类型：

• 收货信息为空
• 物流信息为空

属于正常情况，前端需根据 flow_type 控制相关区块显示。

---

4. 发货

POST /api/admin/exchanges/:id/ship

新增限制

仅支持：

flow_type = shipping

不允许情况

flow_type = direct

返回：

{
  "code": 400,
  "message": "流程类型不支持该操作"
}

前端处理

exchange.flow_type === 'shipping'

---

5. 确认完成

POST /api/admin/exchanges/:id/complete

新增限制

仅支持：

flow_type = shipping
status = 3

不允许情况

flow_type = direct

返回错误。

---

6. 取消换货

POST /api/admin/exchanges/:id/cancel

新增限制

允许取消：

flow_type = shipping
status IN (1, 2)

不允许取消

direct 单据

flow_type = direct

已发货单据

flow_type = shipping
status = 3

返回错误。

---

三、客户端接口变更

1. 查询进行中的换货单

GET /api/c/v1/exchange/pending

变更后返回规则

仅返回：

flow_type = shipping
status IN (1, 2, 3)

不返回

flow_type = direct

客户端无需特殊处理。

---

2. 填写收货地址

POST /api/c/v1/exchange/:id/shipping-info

新增限制

仅支持：

flow_type = shipping
status = 1

不允许

flow_type = direct

返回错误。

---

四、前端 UI 改造建议

换货单详情页

新增展示字段

• 流程类型（flow_type_name）
• 完成时间（completed_at）
• 发货时间（shipped_at）

按流程类型控制按钮

direct

不显示：

• 发货
• 确认完成
• 取消

shipping + status = 1

显示：

• 取消

shipping + status = 2

显示：

• 发货
• 取消

shipping + status = 3

显示：

• 确认完成

信息区块控制

direct

隐藏：

• 收货信息
• 物流信息

或者显示：

不适用

---

创建换货单弹窗

新增字段

流程类型：

• 物流换货（shipping）
• 直接换货（direct）

选择 direct 时

显示：

• 新资产标识符（必填）
• 是否迁移数据（开关）

对应参数：

{
  "new_identifier": "xxx",
  "migrate_data": true
}

选择 shipping 时

隐藏：

• 新资产标识符
• 是否迁移数据

---

换货单列表页

新增表格列

流程类型

显示：

物流换货
直接换货

新增筛选项

流程类型

下拉选项：

全部
物流换货（shipping）
直接换货（direct）

---

五、流程状态说明

shipping（物流换货）

创建
 ↓
待填写信息（1）
 ↓
待发货（2）
 ↓
已发货（3）
 ↓
已完成（4）

direct（直接换货）

创建
 ↓
已完成（4）

---

六、状态与操作矩阵

flow_type	status	发货	确认完成	取消
shipping	1	❌	❌	✅
shipping	2	✅	❌	✅
shipping	3	❌	✅	❌
shipping	4	❌	❌	❌
direct	4	❌	❌	❌

---

七、枚举定义

flow_type

{
  "shipping": "物流换货",
  "direct": "直接换货"
}

flow_type_name 示例

{
  "flow_type": "shipping",
  "flow_type_name": "物流换货"
}

{
  "flow_type": "direct",
  "flow_type_name": "直接换货"
}