one-pipe-system/openspec/changes/update-order-management-response-semantics/specs/order-management/spec.md

ADDED Requirements

Requirement: Updated Order Response Semantics

The system SHALL interpret the latest OrderResponse fields consistently across order creation, order list, and order detail experiences.

Scenario: Order response fields are typed and understood by new semantics

• GIVEN 前端接收到 POST /api/admin/orders、GET /api/admin/orders 或 GET /api/admin/orders/:id 返回的 OrderResponse
• WHEN 前端解析订单对象
• THEN operator_* MUST 被解释为真实操作者信息
• AND seller_shop_* MUST 被解释为订单业务归属店铺信息
• AND commission_status MUST 被解释为佣金流程状态
• AND commission_result MUST 被解释为佣金业务结果

Scenario: Created order response follows the same semantics

• GIVEN 用户成功调用 POST /api/admin/orders 创建订单
• WHEN 前端处理创建成功后返回的订单对象
• THEN 系统 MUST 按最新 OrderResponse 语义解析新增字段和语义变更字段
• AND 系统 MUST NOT 仅根据 commission_status 推断该订单“有佣金”

Requirement: Order List Must Distinguish Operator, Shop, and Commission Result

The system SHALL display order list data in a way that distinguishes real operator identity, seller shop ownership, commission workflow status, and commission business result.

Scenario: Order list shows operator and seller shop separately

• GIVEN 用户正在查看后台订单列表
• WHEN 某条订单同时存在 operator_name 和 seller_shop_name
• THEN 系统 MUST 将“操作者”展示为 operator_name
• AND 系统 MUST 将“销售店铺”或“归属店铺”展示为 seller_shop_name
• AND 系统 MUST NOT 把 operator_name 当成店铺名称展示

Scenario: Order list distinguishes workflow status from business result

• GIVEN 用户正在查看后台订单列表
• WHEN 某条订单返回 commission_status_name 与 commission_result_name
• THEN 系统 MUST 让用户同时看到佣金流程状态和佣金业务结果
• AND 系统 MAY 通过两列展示，或通过“主状态 + 副标签”展示
• AND “已完成且有佣金”与“已完成但无佣金” MUST 可被明确区分
• AND “链路异常待人工处理” MUST 可被明确区分

Requirement: Order Detail Must Separate Operator Info from Seller Shop Info

The system SHALL structure order detail views so that operator identity and seller shop ownership are displayed as separate concepts.

Scenario: Order detail splits operator and ownership information

• GIVEN 用户正在查看后台订单详情
• WHEN 订单详情返回 operator_id、operator_type、operator_name、seller_shop_id 与 seller_shop_name
• THEN 系统 MUST 单独展示操作者信息
• AND 系统 MUST 单独展示业务归属信息
• AND 页面 MUST 让用户明确区分“谁发起下单”和“订单归属哪个销售店铺”

Requirement: Commission Presence Must Not Be Inferred from Workflow Status Alone

The system SHALL avoid inferring commission presence from commission_status alone.

Scenario: Completed order still requires commission result to determine outcome

• GIVEN 某条订单的 commission_status = 2
• WHEN 前端需要判断该订单是否“有佣金”
• THEN 系统 MUST 继续读取 commission_result
• AND 仅当 commission_status = 2 且 commission_result = 1 时，系统才可判定为“有佣金”
• AND 当 commission_status = 2 且 commission_result = 2 时，系统 MUST 判定为“无佣金”