2.9 KiB
2.9 KiB
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代表业务结果。无论是两列展示,还是“主状态 + 副标签”,都必须让用户能明确区分这两个维度。
- Rationale:
-
Decision: 详情页将“操作者信息”和“业务归属信息”拆成两组展示项
- Rationale: 同一信息块内混放会继续强化旧认知,不利于用户理解订单责任归属。
-
Decision: 所有“是否有佣金”的判断必须同时参考
commission_status与commission_result- Rationale: 后端已经把流程状态和业务结果拆开,单独读取
commission_status会产生错误结论。
- Rationale: 后端已经把流程状态和业务结果拆开,单独读取
Risks / Trade-offs
-
风险: 订单模块以外可能也有复用订单类型或字段语义的代码。
- Mitigation: 实施前使用全局搜索盘点
operator_name、commission_status、commission_result的相关用法。
- Mitigation: 实施前使用全局搜索盘点
-
风险: 列表新增列后表格宽度会增加。
- Mitigation: 优先保留关键列,可通过列宽、固定列或列配置能力控制首屏拥挤度。
Migration Plan
- 先调整订单类型定义和展示 helper,建立统一语义基础。
- 再修改订单列表页,确保两类状态与店铺信息展示正确。
- 最后修改详情页,把操作者信息和业务归属信息拆开。
- 通过接口联调样例验证典型场景:
- 平台订单返回
operator_name = admin - 已完成且有佣金
- 已完成但无佣金
- 链路异常待人工处理
- 平台订单返回
Open Questions
- 订单列表中的佣金信息最终采用哪种视觉结构更合适:
- 两列展示
- 主状态 + 副标签
- 只要能同时表达“流程状态”和“业务结果”,两种方案都符合本次提案范围