fix: order

openspec/changes/update-order-management-response-semantics/design.md

@@ -0,0 +1,63 @@
+# Design: 订单管理响应语义升级
+
+## Context
+
+订单管理功能已经有初步页面和类型定义，但其实现建立在较早的接口语义上。最新后端返回已经把以下概念拆分清楚：
+
+- 操作者是谁
+- 订单业务归属到哪个销售店铺
+- 佣金流程走到哪一步
+- 佣金业务结果是什么
+
+当前页面仍然把这些概念部分混用，导致 UI 语义不稳定，也容易让后续实现继续复制错误判断。
+
+## Goals / Non-Goals
+
+- Goals:
+  - 让订单模块的类型定义、列表页、详情页统一按新语义工作
+  - 消除对 `commission_status` 的错误业务推断
+  - 在页面上明确区分“操作者”和“销售店铺”
+- Non-Goals:
+  - 不改动 `purchase-check` 和 `cancel` 接口流程
+  - 不改造后端返回结构
+  - 不新增全新的订单业务流程
+
+## Decisions
+
+- Decision: 在前端类型层面显式补齐新增字段，而不是通过 `any` 或临时属性兼容
+  - Rationale: 这次变化的核心是语义纠偏。如果类型层继续缺字段，页面很容易回退到旧假设。
+
+- Decision: 列表页必须同时呈现佣金流程状态和佣金业务结果，但不强制唯一 UI 形式
+  - Rationale: `commission_status_name` 仅代表流程状态，`commission_result_name` 代表业务结果。无论是两列展示，还是“主状态 + 副标签”，都必须让用户能明确区分这两个维度。
+
+- Decision: 详情页将“操作者信息”和“业务归属信息”拆成两组展示项
+  - Rationale: 同一信息块内混放会继续强化旧认知，不利于用户理解订单责任归属。
+
+- Decision: 所有“是否有佣金”的判断必须同时参考 `commission_status` 与 `commission_result`
+  - Rationale: 后端已经把流程状态和业务结果拆开，单独读取 `commission_status` 会产生错误结论。
+
+## Risks / Trade-offs
+
+- 风险: 订单模块以外可能也有复用订单类型或字段语义的代码。
+  - Mitigation: 实施前使用全局搜索盘点 `operator_name`、`commission_status`、`commission_result` 的相关用法。
+
+- 风险: 列表新增列后表格宽度会增加。
+  - Mitigation: 优先保留关键列，可通过列宽、固定列或列配置能力控制首屏拥挤度。
+
+## Migration Plan
+
+1. 先调整订单类型定义和展示 helper，建立统一语义基础。
+2. 再修改订单列表页，确保两类状态与店铺信息展示正确。
+3. 最后修改详情页，把操作者信息和业务归属信息拆开。
+4. 通过接口联调样例验证典型场景：
+   - 平台订单返回 `operator_name = admin`
+   - 已完成且有佣金
+   - 已完成但无佣金
+   - 链路异常待人工处理
+
+## Open Questions
+
+- 订单列表中的佣金信息最终采用哪种视觉结构更合适：
+  - 两列展示
+  - 主状态 + 副标签
+  - 只要能同时表达“流程状态”和“业务结果”，两种方案都符合本次提案范围