## MODIFIED Requirements

### Requirement: H1 发起换货单

系统 SHALL 提供 `POST /api/admin/exchanges`（需后台认证 `Auth=true`），用于发起换货单。

请求体 MUST 包含：`old_asset_type`、`old_identifier`、`exchange_reason`，可选 `flow_type`、`remark`。

`flow_type` 未传或为空时，系统 MUST 按 `shipping` 处理，以兼容旧后台调用；传入非空且不属于 `shipping/direct` 时，系统 MUST 返回参数错误。

当 `flow_type=shipping` 时：
- 请求体 MUST NOT 要求 `new_identifier`
- 请求体 MUST NOT 要求 `migrate_data`
- 系统创建成功后 SHALL 返回新建换货单信息（含 `id`、`exchange_no`、`flow_type=shipping`、`status=1`）

当 `flow_type=direct` 时：
- 请求体 MUST 额外包含 `new_identifier`
- 请求体 MAY 包含 `migrate_data`；未传时 MUST 按 `false` 处理
- 系统 MUST 在创建接口内完成新资产校验与换货完成事务
- 创建成功后 SHALL 返回新建换货单信息（含 `id`、`exchange_no`、`flow_type=direct`、`status=4`、`completed_at`）
- 任一步失败时 MUST 回滚整个事务，且 MUST NOT 保留半成品 `direct` 换货单

系统 MUST 校验：
- 旧资产存在且当前用户有权限
- 旧资产当前 `asset_status=2`（已销售）
- 同一资产不存在进行中的 `shipping` 换货单（`status IN (1,2,3)`）
- `direct` 场景下新资产存在
- `direct` 场景下新资产当前用户有权限
- `direct` 场景下新旧资产类型必须一致（卡换卡/设备换设备）
- `direct` 场景下新资产必须 `asset_status=1`（在库）
- `direct` 场景下新旧资产 `shop_id` 必须一致（含二者同为平台库存 `NULL`）
- 若旧资产存在客户绑定，则 `direct` 场景下新资产必须可承接绑定关系
- `direct` 场景下新资产不得存在 `status=1` 的有效客户绑定
- `direct` 场景下新资产不得已被其他 `shipping + status=3` 换货单占用

错误响应 MUST 至少包含：参数错误、资产不存在或无权限、旧资产状态不允许换货、存在进行中换货单、新资产不存在、资产类型不匹配、新资产非在库、新旧资产归属不一致、新资产已被占用、绑定无法承接、钱包冻结余额未处理、迁移失败。

#### Scenario: shipping 正常创建
- **WHEN** 后台以 `flow_type=shipping` 或未传 `flow_type` 发起换货，且旧资产为已销售并无进行中单据
- **THEN** 系统 MUST 创建 `status=1` 的换货单

#### Scenario: direct 创建即完成
- **WHEN** 后台以 `flow_type=direct` 发起换货且新旧资产校验通过
- **THEN** 系统 MUST 在同一事务内创建换货单并完成换货
- **AND** 返回结果 MUST 为 `status=4`

#### Scenario: direct 缺少新资产标识
- **WHEN** 后台以 `flow_type=direct` 发起换货但未传 `new_identifier`
- **THEN** 系统 MUST 拒绝创建并返回参数错误

#### Scenario: direct 迁移标记未传
- **WHEN** 后台以 `flow_type=direct` 发起换货且未传 `migrate_data`
- **THEN** 系统 MUST 按 `migrate_data=false` 创建并完成换货

#### Scenario: direct 完成失败不留半成品单据
- **WHEN** 后台以 `flow_type=direct` 发起换货，但完成事务中的绑定承接或迁移步骤失败
- **THEN** 系统 MUST 回滚整笔事务
- **AND** MUST NOT 查询到本次请求创建的半成品 direct 换货单

#### Scenario: 资产已有进行中 shipping 换货单
- **WHEN** 后台为同一资产重复发起 `shipping` 换货
- **THEN** 系统 MUST 拒绝创建并返回“存在进行中的换货单”

#### Scenario: 旧资产非已销售禁止换货
- **WHEN** 旧资产 `asset_status != 2`
- **THEN** 系统 MUST 拒绝创建并返回资产状态不允许换货

---

### Requirement: H2 换货单列表

系统 SHALL 提供 `GET /api/admin/exchanges`（`Auth=true`），支持分页与条件查询。

查询条件 SHOULD 支持：`status`、`flow_type`、`identifier`（资产标识搜索）、`created_at_start`、`created_at_end`、分页参数。

响应 SHALL 返回列表与分页元数据。
响应项 MUST 返回：旧/新资产标识、`flow_type`、`status`、`shipped_at`、`completed_at`。

#### Scenario: 按流程类型查询 direct 已完成单
- **WHEN** 运营查询 `flow_type=direct` 且 `status=4`
- **THEN** 系统返回所有 direct 已完成换货单并按创建时间倒序

---

### Requirement: H3 换货单详情

系统 SHALL 提供 `GET /api/admin/exchanges/:id`（`Auth=true`）查询换货单详情。

响应 MUST 返回旧/新资产信息、流程类型、收货信息、物流信息、迁移状态信息、`shipped_at`、`completed_at`。

错误响应 MUST 至少包含：换货单不存在或无权限。

#### Scenario: 查询 direct 换货单详情
- **WHEN** 查询一张 `flow_type=direct` 的已完成换货单
- **THEN** 响应 MUST 返回 `flow_type=direct`
- **AND** 收货信息与物流信息可以为空
- **AND** `completed_at` 必须存在

---

### Requirement: H4 发货

系统 SHALL 提供 `POST /api/admin/exchanges/:id/ship`（`Auth=true`）。

请求体 MUST 包含：`express_company`、`express_no`、`new_identifier`、`migrate_data`。

系统 MUST 校验：
- 换货单 `flow_type` 必须为 `shipping`
- 当前状态必须为 `2`
- 旧资产当前必须仍为 `asset_status=2`（已销售）
- 新旧资产类型必须一致（卡换卡/设备换设备）
- 新资产必须 `asset_status=1`（在库）
- 新资产当前用户有权限
- 新旧资产 `shop_id` 必须一致（含二者同为平台库存 `NULL`）
- 新资产不得存在 `status=1` 的有效客户绑定
- 新资产不得已被其他 `shipping + status=3` 换货单占用
- 系统 MUST 通过条件更新、行锁或等效机制确保发货成功时新资产仍满足在库且未被占用

成功后 SHALL：
- 更新新资产信息
- 更新物流信息
- 写入 `migrate_data`
- 记录 `shipped_at`
- 将状态改为 `3`
- 将新资产视为被当前换货单占用；在确认完成前不改变新资产 `asset_status`

错误响应 MUST 至少包含：非法状态、流程类型不支持发货、旧资产状态不允许换货、资产类型不匹配、新资产非在库、新旧资产归属不一致、新资产已被占用、资产不存在或无权限。

#### Scenario: direct 单据禁止发货
- **WHEN** `flow_type=direct` 的换货单调用发货接口
- **THEN** 系统 MUST 拒绝并返回流程类型不支持该操作的错误

#### Scenario: 新资产类型不一致
- **WHEN** 旧资产为 `iot_card` 且新资产为 `device`
- **THEN** 系统 MUST 拒绝发货并返回“换货资产类型必须一致”

#### Scenario: 新资产已被其他换货单占用
- **WHEN** 新资产已经作为其他 `shipping + status=3` 换货单的新资产
- **THEN** 系统 MUST 拒绝发货并返回新资产已被占用

---

### Requirement: H5 确认完成

系统 SHALL 提供 `POST /api/admin/exchanges/:id/complete`（`Auth=true`）。

系统 MUST 校验：
- 换货单 `flow_type` 必须为 `shipping`
- 当前状态必须为 `3`

系统 MUST 在**单一数据库事务**中执行完成换货动作。该事务至少包括：
- 校验新资产快照完整且新资产仍满足换货条件
- 校验旧资产仍为 `asset_status=2`（已销售）
- 校验新资产仍为 `asset_status=1`（在库），且未被当前换货单之外的有效记录占用
- 旧资产 `asset_status -> 3`
- 新资产 `asset_status -> 2`
- 若旧资产存在 `PersonalCustomerDevice` 绑定，则绑定切换到新资产资产绑定键
- 若 `migrate_data=true`，执行全量迁移事务（见 `exchange-data-migration` 能力）
- 写入 `completed_at`
- 换货单状态更新为 `4`

成功后 SHALL：
- `migration_completed=true`（若执行迁移）
- 换货单状态更新为 `4`

错误响应 MUST 至少包含：非法状态、流程类型不支持确认完成、旧资产状态不允许换货、新资产状态不允许换货、迁移失败、绑定无法承接、钱包冻结余额未处理、换货单不存在或无权限。

#### Scenario: 需要迁移并完成
- **WHEN** `shipping` 换货单状态为 `3` 且 `migrate_data=true`
- **THEN** 系统 MUST 在同一事务成功后将状态变为 `4` 并记录迁移结果

#### Scenario: 不迁移也必须完成切换
- **WHEN** `shipping` 换货单状态为 `3` 且 `migrate_data=false`
- **THEN** 系统 MUST 仍然在事务内完成旧资产状态切换、新资产状态切换、绑定切换和单据完成

---

### Requirement: H6 取消换货

系统 SHALL 提供 `POST /api/admin/exchanges/:id/cancel`（`Auth=true`）。

系统 MUST 仅允许 `flow_type=shipping` 且 `status IN (1,2)` 时取消，成功后状态更新为 `5`。

系统 MUST 禁止已发货单取消（`status=3`）。
系统 MUST 禁止 `direct` 单据进入取消分支。

#### Scenario: 已发货单取消失败
- **WHEN** `shipping` 换货单状态为 `3` 发起取消
- **THEN** 系统 MUST 返回状态非法错误

#### Scenario: direct 单据取消失败
- **WHEN** `direct` 换货单发起取消
- **THEN** 系统 MUST 返回流程类型不支持该操作的错误

---

### Requirement: H7 旧资产转新

系统 SHALL 提供 `POST /api/admin/exchanges/:id/renew`（`Auth=true`）。

系统 MUST 校验旧资产当前 `asset_status=3`（已换货），并执行：
- `generation + 1`
- `asset_status -> 1`
- 清除累计充值/首充相关状态
- 清除个人客户绑定
- 创建新空钱包

系统 MUST 保留历史数据，不执行历史删除。
系统 MUST NOT 在换货完成阶段修改旧资产 `generation`；`generation` 仅在 `renew` 阶段递增。

错误响应 MUST 至少包含：资产状态不满足转新条件、换货单不存在或无权限。

#### Scenario: 旧资产未处于已换货状态
- **WHEN** 旧资产 `asset_status != 3` 发起转新
- **THEN** 系统 MUST 拒绝并返回“资产当前状态不允许转新”