# 禅道补充需求：换货归属与资产换货标识

> 来源：禅道 #98、#86。最终口径以标准评审稿为准。

## 一、现状

当前换货要求新旧资产已经属于同一店铺；归属不一致时直接拒绝。换货完成只更新资产状态，没有把旧资产店铺归属赋给平台库存中的新资产。

资产已有 `asset_status`、`generation`，换货单也保存新旧资产 ID，但资产详情没有统一返回前代和后代资产关系。

## 二、换货归属规则

- 新资产处于平台库存或已经属于旧资产店铺时可以换入。
- 新资产已经属于其他店铺时拒绝换货，不能覆盖其他代理资产。
- 换货完成事务内，新资产继承旧资产 `shop_id` 和租户标签，并写资产分配记录。
- 旧资产保留原 `shop_id`，状态改为已换货，继续用于历史订单、退款和换货查询。
- 前端不提供目标店铺选择；选择新资产后展示将继承的店铺名称。

处理顺序：

```text
锁定换货单和新旧资产
  -> 校验新资产库存及归属
  -> 新资产继承旧资产店铺
  -> 迁移客户绑定、钱包和套餐资料
  -> 更新新旧资产状态
  -> 完成换货单
  -> 写资产分配记录和审计事件
```

任一步失败整笔事务回滚。

## 三、资产详情换货链

卡和设备详情统一返回：

```json
{
  "exchange_trace": {
    "previous_asset": {
      "asset_type": "iot_card",
      "asset_id": 1001,
      "identifier": "89860...001",
      "exchange_no": "EXC202607170001"
    },
    "next_asset": {
      "asset_type": "iot_card",
      "asset_id": 1003,
      "identifier": "89860...003",
      "exchange_no": "EXC202607180001"
    }
  }
}
```

- 有前代时显示“换货新资产”。
- 有后代时显示“已换出旧资产”。
- A→B→C 场景中，B 可以同时展示前代 A 和后代 C。
- 关联资产必须再次经过后端数据权限校验；无权限时只返回标识，不返回可跳转 ID。

复用 `tb_exchange_order`，补充按旧资产查询已完成换货的方法，以及 `new_asset_type + new_asset_id + status` 查询索引，不新增关系表。

## 四、接口与前端

现有卡、设备详情接口增加 `exchange_trace`，不新增独立换货链接口。

前端在资产基础信息附近展示状态标签和关联资产链接。链接进入对应卡或设备详情，不直接跳换货单；换货单号作为辅助信息展示。

## 五、审计

记录旧资产、新资产、换货单、原店铺、新店铺、状态变更和操作人。新资产归属继承属于关键资产变更，必须与换货事务同时写 Audit Event。

