one-pipe-system/openspec/changes/update-exchange-migration-and-shop-import/proposal.md

Change: 换货迁移状态与店铺负责人导入字段对齐（AUG26-005）

Why

换货单新增业务数据迁移状态（migration_status），前端需要按新状态展示迁移结果，不能再以 migrate_data/migration_completed/migration_balance 推断；migration_status=failed 的单「确认完成」仅超管/平台账号可重试，代理/企业账号触发 403/1005。同时店铺负责人导入任务/行级接口按生成文档补齐 task_no、file_name、creator_name、started_at、completed_at、status_name 等字段，前端类型与页面展示需对齐。

What Changes

• 换货响应字段：GET /api/admin/exchanges、GET /api/admin/exchanges/{id} 以及创建/发货/完成接口返回的同一个换货对象新增 migration_status（not_migrated/pending/migrated/failed）、migration_status_name（中文名：不迁移/待迁移/已迁移/迁移失败）、migration_failure_reason（仅 migration_status=failed 时返回）；migrate_data、migration_completed、migration_balance 仍在、语义未变，但不再用于推断迁移结果。
• 换货列表：在「状态」列之后新增「迁移状态」列（中文名，failed 红色标记）；详情页新增迁移信息展示（迁移状态 + failed 时的失败原因）。
• 确认完成：非 failed 单沿用既有 exchange:complete 权限；failed 单仅超管/平台账号可重试，代理/企业账号前端不渲染入口（后端仍 403/1005 兜底）；迁移执行失败返回 code=1206，换货单保持「已发货待确认」，前端展示后端安全文案、修复条件后可重试。
• 导出：换货导出在「状态」列之后新增「迁移状态」列（15→16），不导出失败原因；前端导出为任务式、无列模板，前端零改动。
• 店铺负责人导入：任务对象（列表/详情/创建响应）按生成文档补齐 task_no/file_name/creator_name/started_at/completed_at/status_name；行级结果补齐 status_name；创建任务接口返回值对齐任务对象（含 id），导入页展示任务编号/文件名/创建人/开始·完成时间/状态中文名。
• 无新增路由、无新增列表筛选、请求入参与权限入口不变（发货 migrate_data 仍为「是否执行迁移」，决定状态落 pending 或 not_migrated）。

Not In Scope

• 后端实现（failed 单权限拦截、1206 返回与迁移执行），仅前端适配。
• 导出文件内容列（换货导出列 15→16 由后端模板生成）。
• migrate_data/migration_completed/migration_balance 字段删除或语义调整。
• 换货单请求入参、列表筛选、权限编码的新增与变更。

Impact

• Affected specs: exchange-management（新增）、shop-management（扩展）
• Affected code:
  • src/api/modules/exchange.ts（ExchangeResponse 迁移字段与枚举）
  • src/views/asset-management/exchange-management/index.vue、detail.vue
  • src/types/api/shop.ts（BusinessOwnerImportDetail/BusinessOwnerImportRow）
  • src/api/modules/shop.ts（createBusinessOwnerImport 返回值对齐）
  • src/views/shop-management/business-owner-import/index.vue
• API contracts: DtoExchangeOrderResponse 新增 3 个迁移字段；店铺负责人导入任务/行级字段对齐生成文档
• Dependencies:
  • docs/产品迭代8月份/换货和店铺负责人导入.md（7 个换货端点 + 3 个导入端点 OpenAPI）
  • AUG26-005 换货迁移状态接口变动说明
• Related active changes: update-exchange-flow-direct-type（同属换货流程，需合并考虑）；add-business-user-group-management（店铺负责人导入页面基础）

待确认

• 1206 响应走 HTTP 4xx 还是 200+code=1206：前端按现有统一错误处理展示后端 msg；如需要定制提示（如「迁移失败，修复后可重试」）需后端确认返回结构。
• failed 单「确认完成」的隐藏依据：按 user_type（代理/企业）在前端隐藏，超管/平台显示，权限码沿用 exchange:complete。
• 导入任务创建响应含 id：以生成文档为准，前端改为使用返回对象的 id 打开结果抽屉。