2.9 KiB
2.9 KiB
01 — 统一换货资产解析与权威快照
What to build: 运营人员继续使用接口已支持的任一资产标识发起或执行换货，但系统在物流换货创建、直接换货创建和物流发货三个入口统一解析真实资产并保存权威快照。IoT 卡的新旧资产快照始终保存数据库中的完整 ICCID；设备快照依次选择虚拟号、IMEI、SN 中首个非空标识，不保存请求原文。三个入口必须共享同一套解析与规范化规则，自动化测试、接口文档和中文功能说明同步证明该行为可以独立发布和验收。
Blocked by: None — can start immediately.
Status: done（后端）— 前端/人工待验收
架构通道: 主通道为复杂写，辅助通道为 Infrastructure Adapter。资产解析和权威标识选择作为换货写用例复用能力收口；既有 Service 可以作为迁移门面调用该能力，但规则不得继续散落在多个流程分支。
完整业务边界: 本票收口资产标识解析、权威快照选择以及物流创建、直接创建、物流发货三个快照写入入口，并包含对应自动化测试、OpenAPI 契约和中文发布说明。明确不迁移换货状态机、确认完成、取消、资料迁移、旧资产转新、客户绑定切换等旧逻辑；不回填或改写历史换货单，不依赖 UR#86 或 UR#98 的实现。
- 使用 ICCID、接入号或虚拟号定位旧 IoT 卡时，新建物流换货单的旧资产快照均为该卡数据库中的完整 ICCID。
- 直接换货的新旧资产和物流换货发货时的新资产均复用相同规范化能力，IoT 卡快照不保存请求原文、接入号或虚拟号。
- 设备无论通过虚拟号、IMEI 或 SN 定位，快照都按“虚拟号 → IMEI → SN”的优先级选择首个非空稳定标识。
- 标识解析仍执行既有资产权限、资产类型、状态和并发校验，不扩大可操作资产范围，也不改变换货生命周期规则。
- 资产不存在、类型不匹配或数据库失败时返回既有统一错误体系中的脱敏错误，不向客户端透出底层错误。
- 自动化测试覆盖卡的三种输入标识、设备的三种输入标识及设备标识优先级，并分别验证物流创建、直接创建和物流发货的持久化快照。
- 端到端回归验证三个写入入口产生的快照可由现有换货详情或列表响应读取，且构造的历史非规范快照保持原值、不被自动回填。
- OpenAPI 中创建换货和物流发货的请求标识说明、响应快照语义与实际实现一致，并完成文档重新生成验证。
- UR#45 中文功能总结记录卡与设备快照规则、历史数据不回填策略、错误边界、发布与回滚注意事项；README 增加对应索引。
- 所有新增或修改的导出符号、复杂逻辑注释和日志均使用中文，并通过相关 Go 测试与格式检查。