64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# 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
|
||
|
||
- 订单列表中的佣金信息最终采用哪种视觉结构更合适：
|
||
- 两列展示
|
||
- 主状态 + 副标签
|
||
- 只要能同时表达“流程状态”和“业务结果”，两种方案都符合本次提案范围
|