迭代方案确认

docs/7月迭代/独立方案/新增需求/06-换货归属与资产换货标识.md

@@ -0,0 +1,72 @@
+# 禅道补充需求：换货归属与资产换货标识
+
+> 来源：禅道 #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。
+