junhong_cmp_fiber/docs/feature-001-order-operator-and-chain-commission-semantics/功能总结.md

订单操作者与产业链佣金语义修复功能总结

1. 变更目标

本次变更围绕两个历史语义问题展开：

1. 订单 operator_id/operator_type 混用了“真实操作者账号”和“代理店铺 ID”，导致平台订单无法稳定显示真实操作者。
2. 订单 commission_status 只区分“待计算/已计算”，无法表达“有佣金 / 无佣金 / 链路异常待人工处理”的真实业务结果。

2. 已完成的核心改动

2.1 订单操作者改为账号语义

• 新增权威字段：
  • operator_account_id
  • operator_account_type
  • operator_account_name
• 后台订单创建、H5 代理订单创建、客户端个人客户订单、自动购包订单都会写入真实操作者快照。
• 旧 operator_id/operator_type 保留为历史兼容字段，不再作为新语义权威来源。

2.2 订单响应分离“操作者账号”和“业务店铺”

• operator_id/operator_type/operator_name 现在按真实操作者账号语义返回。
• 新增 seller_shop_id/seller_shop_name，用于表达业务归属店铺展示。
• 历史订单优先使用新字段；若缺失，则按 creator、个人客户昵称、旧店铺型 operator_id 顺序兜底，避免平台旧订单出现空白操作者名称。

2.3 订单佣金状态拆成“流程状态 + 业务结果”

• commission_status 现在表示流程状态：
  • 1=待计算
  • 2=已完成
  • 3=待人工处理
• 新增 commission_result 表示业务结果：
  • 0=未知
  • 1=有佣金
  • 2=无佣金
  • 3=链路异常

2.4 差价佣金任务结果显式落单

• 佣金 worker 结束后会显式写回订单：
  • 已完成 + 有佣金
  • 已完成 + 无佣金
  • 待人工处理 + 链路异常
• 0 佣金订单不再长期停留在“待计算”。

2.5 入队与幂等语义修复

• 钱包支付创建订单后，所有仍处于 待计算 的适用订单都会入队佣金任务，不再只覆盖特定购买角色。
• 重复支付回调、重复钱包支付不会重复入队。
• worker 对 已完成/待人工处理 订单直接跳过，避免重复补偿处理。

3. 兼容策略

• migration 仅新增字段，不删除旧列。
• 历史订单读取时：
  • 优先使用 operator_account_*
  • 其次使用 creator 回填账号名
  • 对旧代理订单保留店铺名兜底展示
• 历史订单的 commission_result 若未回填，则在响应层按佣金记录只读推断。

4. 受影响文件

• internal/model/order.go
• internal/model/dto/order_dto.go
• internal/service/order/service.go
• internal/service/client_order/service.go
• internal/service/commission_calculation/service.go
• internal/store/postgres/order_store.go
• internal/task/auto_purchase.go
• pkg/constants/iot.go
• migrations/000140_add_order_operator_snapshot_and_commission_result.*.sql

5. 风险提示

• 历史订单若 creator 无法映射到账号，仍会退回旧店铺型操作者展示，仅保证“可读”而不强行伪造账号 ID。
• commission_result=0 仅作为历史兼容态存在；新计算链路应尽量落为明确业务结果。
• 本次不重构一次性佣金规则本身，只保证其异常待审记录能纳入订单最终流程结果判断。