Files
one-pipe-system/openspec/changes/update-order-management-response-semantics/design.md
sexygoat 1990a3ccba
All checks were successful
构建并部署前端到测试环境 / build-and-deploy (push) Successful in 4m4s
fix: bug
2026-05-11 15:51:50 +08:00

2.9 KiB
Raw Blame History

Design: 订单管理响应语义升级

Context

订单管理功能已经有初步页面和类型定义,但其实现建立在较早的接口语义上。最新后端返回已经把以下概念拆分清楚:

  • 操作者是谁
  • 订单业务归属到哪个销售店铺
  • 佣金流程走到哪一步
  • 佣金业务结果是什么

当前页面仍然把这些概念部分混用,导致 UI 语义不稳定,也容易让后续实现继续复制错误判断。

Goals / Non-Goals

  • Goals:
    • 让订单模块的类型定义、列表页、详情页统一按新语义工作
    • 消除对 commission_status 的错误业务推断
    • 在页面上明确区分“操作者”和“销售店铺”
  • Non-Goals:
    • 不改动 purchase-checkcancel 接口流程
    • 不改造后端返回结构
    • 不新增全新的订单业务流程

Decisions

  • Decision: 在前端类型层面显式补齐新增字段,而不是通过 any 或临时属性兼容

    • Rationale: 这次变化的核心是语义纠偏。如果类型层继续缺字段,页面很容易回退到旧假设。
  • Decision: 列表页必须同时呈现佣金流程状态和佣金业务结果,但不强制唯一 UI 形式

    • Rationale: commission_status_name 仅代表流程状态,commission_result_name 代表业务结果。无论是两列展示,还是“主状态 + 副标签”,都必须让用户能明确区分这两个维度。
  • Decision: 详情页将“操作者信息”和“业务归属信息”拆成两组展示项

    • Rationale: 同一信息块内混放会继续强化旧认知,不利于用户理解订单责任归属。
  • Decision: 所有“是否有佣金”的判断必须同时参考 commission_statuscommission_result

    • Rationale: 后端已经把流程状态和业务结果拆开,单独读取 commission_status 会产生错误结论。

Risks / Trade-offs

  • 风险: 订单模块以外可能也有复用订单类型或字段语义的代码。

    • Mitigation: 实施前使用全局搜索盘点 operator_namecommission_statuscommission_result 的相关用法。
  • 风险: 列表新增列后表格宽度会增加。

    • Mitigation: 优先保留关键列,可通过列宽、固定列或列配置能力控制首屏拥挤度。

Migration Plan

  1. 先调整订单类型定义和展示 helper建立统一语义基础。
  2. 再修改订单列表页,确保两类状态与店铺信息展示正确。
  3. 最后修改详情页,把操作者信息和业务归属信息拆开。
  4. 通过接口联调样例验证典型场景:
    • 平台订单返回 operator_name = admin
    • 已完成且有佣金
    • 已完成但无佣金
    • 链路异常待人工处理

Open Questions

  • 订单列表中的佣金信息最终采用哪种视觉结构更合适:
    • 两列展示
    • 主状态 + 副标签
    • 只要能同时表达“流程状态”和“业务结果”,两种方案都符合本次提案范围