junhong_cmp_fiber/openspec/changes/add-exchange-data-migration-status/specs/order-refund-exchange/spec.md

ADDED Requirements

Requirement: 换货业务数据迁移状态与失败恢复

系统 SHALL 为每张已持久化的物流换货单返回业务数据迁移状态 not_migrated（不迁移）、pending（待迁移）、migrated（已迁移）或 failed（迁移失败），以及对应的中文状态名称。未选择业务数据迁移的换货单状态 MUST 为 not_migrated；选择迁移但尚未成功完成的换货单状态 MUST 为 pending；完整迁移成功后状态 MUST 为 migrated；迁移执行失败后状态 MUST 为 failed，并保存最近一次可安全展示的失败原因。

换货列表和详情 SHALL 返回迁移状态及中文名称；仅当状态为 failed 时返回最近一次失败原因。既有 migrate_data、migration_completed 和迁移余额字段 SHALL 保持兼容，但客户端不得再通过它们推断迁移结果。直接换货创建失败继续按既有原子性整体回滚，不产生可查询的失败换货单。

Scenario: 不迁移的换货单

• WHEN 创建或发货时未选择业务数据迁移
• THEN 换货列表和详情返回 not_migrated 及“不迁移”，且不返回迁移失败原因

Scenario: 待迁移的换货单

• WHEN 换货单已选择业务数据迁移但尚未成功完成换货
• THEN 换货列表和详情返回 pending 及“待迁移”

Scenario: 成功完成业务数据迁移

• WHEN 换货完成时全部业务数据迁移成功
• THEN 系统原子完成换货及业务数据迁移，列表和详情返回 migrated 及“已迁移”，并清除最近一次失败原因

Scenario: 迁移失败后保留可恢复事实

• WHEN 换货完成时任一业务数据迁移步骤失败
• THEN 系统不得提交本次换货完成及任何部分迁移结果，换货单保持可确认完成状态，返回迁移失败，并在独立持久化事实中将迁移状态更新为 failed 和最近一次失败原因

Scenario: 管理员重试失败迁移

• WHEN 超级管理员或平台用户对处于可确认完成状态且迁移状态为 failed 的换货单再次确认完成
• THEN 系统重新原子执行完整业务数据迁移；成功后将状态更新为 migrated，再次失败则保留 failed 并覆盖为最近一次失败原因

Scenario: 非平台账号重试失败迁移

• WHEN 非超级管理员且非平台用户尝试再次确认迁移状态为 failed 的换货单
• THEN 系统拒绝该操作，换货单及迁移状态不变

Requirement: 换货业务数据迁移范围

系统 SHALL 仅在选择业务数据迁移的换货完成中迁移旧资产的钱包余额、有效套餐使用记录、累计充值字段和资产标签。资产归属与个人客户—资产绑定 SHALL 继续作为换货完成固有动作，不受业务数据迁移选项控制；手机号—资产关联 MUST NOT 随换货或业务数据迁移转移，新资产首次访问时按其适用的手机号绑定规则处理。

Scenario: 选择业务数据迁移完成换货

• WHEN 换货单选择业务数据迁移并成功确认完成
• THEN 系统迁移钱包余额、有效套餐使用记录、累计充值字段和资产标签，且不迁移手机号—资产关联

Scenario: 不选择业务数据迁移完成换货

• WHEN 换货单未选择业务数据迁移并确认完成
• THEN 系统仍完成资产归属与个人客户—资产绑定的固有换货动作，但不迁移钱包余额、套餐使用记录、累计充值字段或资产标签