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

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

## 一、数据库字段新增

### 表：`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": "直接换货"
}
```