one-pipe-system/openspec/changes/update-exchange-inherited-shop-hint/specs/exchange-management/spec.md

ADDED Requirements

Requirement: 换货归属继承上下文展示

系统 SHALL 在换货创建和发货确认流程中展示旧资产当前所属店铺，并在用户选定新资产后以只读方式提示换货完成后的继承归属店铺，避免用户误认为可以手工指定目标店铺。

Scenario: 创建入口展示旧资产所属店铺

• GIVEN 用户进入现有换货创建入口
• WHEN 用户选择旧资产
• THEN 系统 MUST 显示该旧资产当前所属店铺名称
• AND 该所属店铺信息 MUST be read-only

Scenario: 选择新资产后展示继承归属提示

• GIVEN 用户正在换货创建或发货确认流程中操作
• WHEN 用户选择新资产
• THEN 系统 MUST 显示只读提示 换货完成后将归属：{店铺名称}
• AND {店铺名称} MUST 表示该新资产换货完成后的最终归属店铺

Scenario: 页面不提供目标店铺选择控件

• WHEN 用户查看换货创建或发货确认入口
• THEN 系统 MUST NOT 渲染目标店铺选择控件
• AND 用户 MUST NOT 能够手工覆盖继承归属店铺

Scenario: 直接换货新资产候选按旧资产店铺过滤

• GIVEN 用户正在创建直接换货单
• AND 用户已选择旧资产
• WHEN 前端加载或搜索新资产标识符候选项
• THEN 新 IoT 卡候选查询 MUST include the selected old asset shop_id
• AND 新设备候选查询 MUST include the selected old asset shop_id
• AND 查询 MUST continue to include status=1

Scenario: 未选择旧资产时不加载直接换货新资产候选

• GIVEN 用户正在创建直接换货单
• AND 用户尚未选择旧资产
• WHEN 新资产标识符候选项准备加载
• THEN 前端 MUST NOT request new asset candidates without the old asset shop_id
• AND 新资产候选列表 MUST remain empty until an old asset is selected

Requirement: 换货归属继承接口契约

系统 SHALL 复用现有换货创建、发货和确认完成接口，并在换货数据模型中返回继承后的店铺标识和店铺名称，供创建结果、发货结果、完成结果和详情页统一展示。

Scenario: 创建请求保持既有字段语义

• WHEN 前端调用 POST /api/admin/exchanges
• THEN 请求体 MUST 继续沿用旧资产、新资产、换货类型和资料迁移字段
• AND 请求体 MUST NOT 新增目标店铺字段

Scenario: 发货和完成请求不新增目标店铺字段

• WHEN 前端调用 POST /api/admin/exchanges/{id}/ship 或 POST /api/admin/exchanges/{id}/complete
• THEN 请求体 MUST NOT 新增目标店铺字段
• AND 后端 MUST 继续按现有换货流程处理归属继承

Scenario: 换货响应返回继承店铺字段

• WHEN 前端收到换货创建、发货、确认完成结果或读取换货详情
• THEN 返回的 data MUST 包含 inherited_shop_id:int64 和 inherited_shop_name:string
• AND inherited_shop_name MUST 表示换货完成后新资产最终归属的店铺名称

Requirement: 换货详情继承归属展示

系统 SHALL 在换货详情页展示继承后的店铺名称，并在关键操作成功后刷新详情数据，保证页面展示的归属信息与后端一致。

Scenario: 详情页展示继承后的店铺名称

• GIVEN 用户进入换货详情页
• WHEN 详情数据加载成功
• THEN 页面 MUST 展示继承后的店铺名称
• AND 页面 MUST NOT 隐藏该归属字段

Scenario: 发货或确认完成成功后刷新详情

• GIVEN 用户完成换货发货或确认完成操作
• WHEN 接口返回成功
• THEN 系统 MUST 重新拉取该换货单详情
• AND 刷新后的详情 MUST 展示最新的继承归属店铺信息

Requirement: 换货归属继承错误与提交状态处理

系统 SHALL 在新资产归属校验失败时展示后端错误，并在创建、发货、确认完成提交期间禁用操作按钮，防止重复提交，同时保证失败后可以重试。创建换货单接口失败 MUST use the unified HTTP error handling and MUST NOT render a duplicate local error alert inside the create dialog.

Scenario: 新资产属于其他店铺时展示后端错误

• GIVEN 用户选择了不允许用于当前换货流程的新资产
• WHEN 后端返回“新资产属于其他店铺”或等价归属校验错误
• THEN 系统 MUST 通过统一 HTTP 错误处理展示后端错误信息
• AND 系统 MUST NOT 提供手工修改目标店铺的替代入口
• AND 创建换货单弹窗内 MUST NOT 额外展示重复错误 Alert

Scenario: 提交期间禁用按钮防止重复提交

• WHEN 用户提交创建、发货或确认完成操作
• THEN 当前操作按钮 MUST 进入禁用或 loading 状态直到请求结束
• AND 在请求完成前的重复点击 MUST NOT 触发第二次提交

Scenario: 请求失败后恢复可重试状态

• WHEN 创建、发货或确认完成请求失败
• THEN 系统 MUST 恢复当前操作按钮可用状态
• AND 页面 MUST 保留当前已展示的资产与归属提示，便于用户修正后重试