## Context 当前换货实现已经具备后台建单、客户端填写地址、后台发货、后台完成、旧资产转新的主链路，但实现上仍然是单一路径，且关键业务动作没有被统一到稳定的事务边界内。 当前实现存在四个直接问题： 1. `ExchangeOrder` 模型没有 `flow_type`，无法表达“走物流”与“直转新资产”两种流程，只能依赖状态字段隐式区分。 2. `Complete()` 不是单事务。当前 `migrate_data=true` 时，`executeMigration()` 会先独立提交一次事务，随后 `Complete()` 再单独把换货单状态改为已完成，存在“迁移已生效但单据仍停在待完成”的不一致窗口。 3. 旧资产 `asset_status -> 3` 只在迁移逻辑里执行。也就是说，`migrate_data=false` 时单据虽然可以完成，但旧资产不会被系统视为“已换货”，后续 `Renew()` 会直接失败。 4. 个人客户绑定切换当前只在迁移逻辑中执行。这会导致“换货成功但客户仍绑定旧资产”的脏状态，尤其在新增 `direct + migrate_data=false` 场景下会被明显放大。 本次变更横跨模型、DTO、后台/客户端接口、换货服务、迁移事务、资产追溯和生命周期语义，是一个典型的跨模块行为修正型变更。 ## Goals / Non-Goals **Goals:** - 在现有换货系统内新增 `direct` 流程，同时保留 `shipping` 原流程不变。 - 将换货流程类型与状态机拆开：`flow_type` 表达业务路径，`status` 继续表达处理阶段。 - 定义一个统一、可回滚的“完成换货”单事务，覆盖必做切换与可选迁移。 - 保证 `migrate_data=false` 仍然能形成业务闭环：旧资产被换出、新资产成为当前资产、客户绑定切到新资产、单据已完成。 - 明确旧资产/新资产/世代/追溯链的状态变化，使后续实现无需再靠推测还原业务语义。 - 保证 `iot_card` 与 `device` 两类资产都支持 `direct` 流程。 **Non-Goals:** - 不新增第三种换货流程类型。 - 不改变现有 `renew` 的业务定位，仍然由运营后台显式触发，而不是在换货完成时自动执行。 - 不新增自动消息推送或物流轨迹查询能力。 - 不在本次变更中回填历史换货单数据，也不把 legacy 记录回灌为新语义数据。 ## Decisions ### 决策 1：新增 `flow_type`，保留现有状态值不变 换货流程存在两条业务路径： - `shipping`：建单后等待客户填写收货地址，再由后台发货、后台确认完成。 - `direct`：建单时已经确定新资产，无需客户填写地址，也无需物流，建单即可完成。 如果继续只用 `status` 表达两种路径，会导致以下问题： - 客户端待处理查询无法区分“真的待客户处理”和“已跳过客户节点”。 - 后台列表中 `status=4` 的已完成单据看不出是走物流还是直转。 - 取消、发货、填写地址等接口无法自然约束适用范围。 因此本次设计明确： - `flow_type` 使用字符串枚举：`shipping` / `direct` - 为保持旧后台调用兼容，创建接口未传 `flow_type` 时按 `shipping` 处理 - 创建接口传入非空且不属于 `shipping/direct` 的 `flow_type` 时必须返回参数错误 - `status` 继续保留现有 int 常量：`1/2/3/4/5` - `shipping` 流程状态机保持不变 - `direct` 流程允许“创建后立即处于 `status=4`” 选择原因： - 对原流程兼容性最好，不需要重命名现有状态常量。 - 后台与客户端都能用 `flow_type + status` 明确判断当前单据语义。 - 查询、追溯和审计都更稳定。 备选方案与拒绝理由： - 方案 A：新增 `status=6 直转已完成` - 拒绝原因：状态值被混入路径语义，客户端和后台会被迫理解“特殊完成态”，长期维护成本更高。 - 方案 B：新增第二张 `direct_exchange_order` 表 - 拒绝原因：核心事实被拆散，追溯链和列表逻辑会重复实现。 ### 决策 2：完成换货拆为“必做切换 + 可选迁移”，并统一纳入单事务 完成换货后，系统至少要落定以下事实： - 本次换货单已经结束。 - 旧资产不能再继续作为当前客户资产使用。 - 新资产已经成为客户当前资产。 - 若客户原先已绑定旧资产，绑定关系必须切到新资产。 这些动作并不是“可选迁移”，而是换货成功本身的最小闭环。因此本次设计把完成换货分为两层： 1. 必做切换： - 校验新资产存在、类型一致、当前在库 - 写入 `new_asset_type/new_asset_id/new_asset_identifier` - 旧资产 `asset_status -> 3` - 新资产 `asset_status -> 2` - 若旧资产存在 `PersonalCustomerDevice` 绑定，则绑定切换到新资产资产绑定键 - 写 `completed_at` - 换货单 `status -> 4` 2. 可选迁移，仅 `migrate_data=true` 时执行： - 钱包余额迁移 - 迁移流水记录 - 套餐使用记录迁移 - 套餐日明细连续性保留 - 标签复制 - 累计充值/首充触发状态复制 上述两层必须在同一个数据库事务中完成。事务任一步失败，整个完成动作回滚，换货单保持未完成。 选择原因： - 避免 `migrate_data=false` 出现“单据完成但旧资产仍可被系统当成正常资产”的错误状态。 - 避免迁移提交成功但换货单状态未完成的分裂状态。 - 让 `direct` 与 `shipping` 共用同一个“完成换货”内核，只是入口不同。 备选方案与拒绝理由： - 方案 A：继续保留 `executeMigration()` 自己开事务，`Complete()` 外层只做单据状态更新 - 拒绝原因：状态不一致风险已经存在，不能带到新流程。 - 方案 B：`migrate_data=false` 时只更新单据状态，不更新资产和绑定 - 拒绝原因：这不是换货成功，只是“记录一张单子”。 ### 决策 3：`direct` 在创建接口里完成“建单 + 完成换货” `direct` 不是后台先建一个待处理单再调用 `complete`，而是后台在创建时就已经给出： - 旧资产 - 新资产 - 是否迁移；`migrate_data` 未传时按 `false` 处理，传入时必须是布尔值 - 换货原因 因此 `POST /api/admin/exchanges` 在 `flow_type=direct` 时应直接执行： 1. 校验旧资产存在、无进行中的换货单 2. 校验旧资产处于 `asset_status=2` 已销售 3. 校验新资产存在、类型一致、在库、归属店铺一致、未被有效客户绑定占用 4. 创建换货单并写入 `old_*` / `new_*` / `flow_type` / `migrate_data` 5. 在同一事务内执行“完成换货必做切换” 6. 若 `migrate_data=true`，继续执行可选迁移 7. 直接返回 `status=4` 事务语义： - `direct` 创建、完成切换、可选迁移必须共用同一个数据库事务 - 任一步失败时整个事务回滚，不保留 `status=1/2/3` 或其他半成品 `direct` 单据 - 成功返回时，数据库中已存在且只能存在 `status=4` 的 `direct` 单据 这样做的好处： - 不产生半成品 `direct` 单据 - 不需要为 `direct` 再暴露一个“后台补完成”的额外接口 - 事务边界清晰：创建成功即代表换货成功 ### 决策 4：`shipping` 的发货与完成职责分离，但完成时仍重用同一事务内核 `shipping` 流程保留现有操作感知： - 创建单据：`status=1` - 客户填写地址：`1 -> 2` - 后台发货：`2 -> 3` - 后台确认完成：`3 -> 4` 其中： - `ship` 只负责落新资产快照、物流信息、`migrate_data`、`shipped_at`，并把状态推进到 `3` - `complete` 负责执行“完成换货单事务” `shipping` 发货后的新资产占用规则： - `ship` 选择新资产时必须使用条件更新或行锁确认新资产仍为 `asset_status=1` - `ship` 成功后新资产已被该换货单占用，其他换货单或销售绑定不得再使用该新资产 - 若实现不新增独立“占用中”状态，则必须通过换货单 `new_asset_type/new_asset_id + status IN (3)` 的唯一性/查询校验阻止重复占用 - `complete` 时仍需再次校验新资产未被外部写入破坏；若不满足条件，完成失败并保持单据未完成 这样处理可以保留现有后台操作习惯，同时让 `shipping` 和 `direct` 的最终完成动作完全一致。 ### 决策 5：客户绑定切换属于必做动作，且需要可承接性前置校验 如果旧资产存在 `PersonalCustomerDevice` 绑定，则完成换货后客户必须继续指向新资产，否则业务上等于“客户仍在使用旧资产”。 因此本次设计将绑定切换定义为必做动作，并增加一个硬前置规则： - 若旧资产存在客户绑定，则新资产必须具备可写入绑定的资产绑定键 - IoT 卡使用 `virtual_no` 作为绑定键；设备优先使用 `virtual_no`，为空时可按现有登录绑定规则使用 `imei` - 新资产绑定键不得已存在 `status=1` 的 `PersonalCustomerDevice` 绑定记录，避免多个客户当前态混入同一资产 - 若新资产无法承接绑定，换货完成动作必须失败并回滚 这里不要求系统为缺失资产绑定键的新资产自动生成标识，因为那会扩大本次变更边界，也会影响其他资产管理能力。 ### 决策 6：新资产在换货完成后必须从“在库”切为“已销售” 当前 `ship` 和 `complete` 流程都要求新资产必须先是 `asset_status=1` 在库，但完成换货后，系统实际上已经把该资产交付给了当前客户。如果不更新新资产状态，会出现“库存资产已被客户使用”的脏状态。 因此本次设计明确： - 完成换货成功后，新资产 `asset_status -> 2` - 此规则同时适用于 `shipping` 与 `direct` - 旧资产必须在完成前为 `asset_status=2` 已销售；已换货、在库或已停用资产不得发起/完成换货 - 新资产必须在选择和完成时都满足 `asset_status=1` 在库 - 旧资产 `generation` 不变；新资产 `generation` 也不变 这与 `renew` 不冲突。`renew` 处理的是旧资产重新回炉，不是新资产接棒。 ### 决策 7：补充 `shipped_at` 和 `completed_at`，不再复用 `updated_at` 表达关键业务时间 当前资产历史订单追溯中的 `exchanged_at` 实际取的是换货单 `updated_at`，这会混淆以下行为： - 后台补备注 - 重新发货修正 - 迁移状态更新 本次设计要求： - `shipped_at`：仅在 `shipping` 发货成功时写入 - `completed_at`：仅在换货成功完成时写入，`shipping` 与 `direct` 共用 - 资产追溯里的 `exchanged_at` 改取 `completed_at` - 历史已完成换货单没有 `completed_at` 时，追溯接口必须兼容回退到 `updated_at` 这样可以避免追溯链把“最后更新时间”错当成“换货完成时间”。 ### 决策 8：`generation` 只在 `renew` 阶段递增 换货完成时的本质是“当前客户从旧资产切到新资产”，而不是“旧资产重新变成新货”。 因此： - 换货完成阶段： - 旧资产 `generation` 不变 - 新资产 `generation` 不变 - `renew` 阶段： - 旧资产 `generation + 1` - 旧资产 `asset_status -> 1` - 清空累计充值/首充状态 - 清理个人客户绑定 - 删除旧钱包并重建新空钱包 这样可以保证： - 换货链由 `ExchangeOrder.old_* / new_*` 表达 - 世代链由 `generation` 表达 - 两条语义链不互相污染 ### 决策 9：钱包冻结余额阻止可选迁移 `migrate_data=true` 时，旧资产钱包余额迁移会改写旧钱包余额并给新钱包入账。如果旧钱包存在冻结余额，说明仍有未完成扣款、退款、支付或其他资金占用。 因此： - 旧资产钱包 `frozen_balance > 0` 时必须拒绝迁移并回滚整个完成事务 - 不迁移可用余额、不迁移冻结余额，也不做部分迁移 - 后台需要先处理冻结业务，再重新执行换货完成或 direct 创建 这样避免把仍在占用中的资金静默搬到新资产，导致后续支付/退款按旧钱包执行失败。 ### 决策 10：多租户归属必须保持一致 换货不是跨店铺调拨能力。本次不扩大资产归属变更范围。 因此： - 旧资产和新资产必须都在当前操作者权限范围内 - 新旧资产 `shop_id` 必须一致，含二者同为平台库存 `NULL` - 换货单 `shop_id` 取旧资产 `shop_id` - 如业务未来需要跨店铺换入，必须另起提案处理调拨、审计和权限边界 ## Risks / Trade-offs - [风险] `direct` 创建接口职责变重，参数和校验分支增加 - 缓解：在 DTO 和 Service 层明确按 `flow_type` 分支校验，避免 handler 拼接复杂条件。 - [风险] 完成换货被收敛为大事务后，单次事务执行时间会增长 - 缓解：换货属于低频后台操作，可接受；同时将“必做切换”和“可选迁移”分层，避免未来继续在事务里堆无关动作。 - [风险] 新资产可承接绑定的约束可能暴露出历史库存数据不完整问题 - 缓解：把“无法承接绑定则完成失败”写成明确规则，避免系统默默产出脏数据；实际实现时通过错误码和后台提示引导运营修正库存数据。 - [风险] 主线 spec 与 archived spec 对 `personal-customer` 的换货 requirement 已有历史沉淀，修改时容易遗漏一致性 - 缓解：本次 change 直接修改主线 capability，不再依赖 archived 文档语义。 - [风险] 新增 `completed_at` 后，旧数据没有该字段值 - 缓解：本次不做历史回填；追溯逻辑对历史已完成单据统一回退到 `updated_at`，新完成单据必须写入并优先使用 `completed_at`。 ## Migration Plan 1. 数据库变更 - 为 `tb_exchange_order` 增加 `flow_type`、`shipped_at`、`completed_at` - 为 `flow_type` 设置默认值 `shipping` - 视查询需要补充 `flow_type + status`、`new_asset_type + new_asset_id` 等索引 2. 模型与 DTO 变更 - 更新 `ExchangeOrder` 模型 - 更新创建、发货、详情、列表、客户端待处理等 DTO 3. 服务层重构 - 提炼统一的“完成换货事务”内部方法 - 让 `shipping complete` 与 `direct create` 共用同一完成内核 - 将现有 `executeMigration()` 重构为可注入外部事务的内部步骤，而不是自开事务 4. 接口兼容与文档更新 - 后台创建接口支持 `flow_type` - 保持原 `shipping` 路径向后兼容 - 更新 OpenAPI 文档生成器注册与中文描述 5. 手工验证 - 执行 `go build ./...` - 使用 PostgreSQL MCP 核对字段、状态、时间字段和索引 - 手工验证 `shipping/direct`、`migrate_data=true/false`、`renew`、`include_previous=true` 等关键场景 6. 回滚策略 - 若实现尚未上线，可回滚代码并回滚新增字段 - 若已产生 `direct` 单据数据，则不能只回滚代码而不处理数据，必须连带考虑接口兼容和字段保留 ## Open Questions - 无。当前边界按兼容优先、失败回滚、不引入新流程状态处理。