junhong_cmp_fiber/docs/feature-001-order-operator-and-chain-commission-semantics/兼容映射清单.md

订单操作者与佣金语义兼容映射清单

1. 历史字段现状

• tb_order.operator_id：历史上混用了“真实操作者账号 ID”和“代理店铺 ID”两种语义。
• tb_order.operator_type：历史上仅承载 platform/agent，且与 operator_id 的 ID 体系并不稳定一致。
• tb_order.creator：后台订单通常可回溯真实账号，但旧响应逻辑没有统一优先使用该字段补齐平台操作者展示。
• tb_order.commission_status：历史上仅有 1=待计算、2=已计算，无法表达“无佣金”和“链路异常待人工处理”。

2. 新增权威字段

• operator_account_id：真实操作者账号/主体 ID。
• operator_account_type：真实操作者类型，使用 platform/agent/enterprise/personal_customer 语义。
• operator_account_name：真实操作者名称快照。
• commission_result：佣金业务结果，使用 0=未知 1=有佣金 2=无佣金 3=链路异常。

3. 写路径兼容策略

• 新订单统一写入 operator_account_* 权威字段。
• 保留写入 legacy operator_id/operator_type，但仅作为兼容读取兜底，不再作为新语义权威来源。
• seller_shop_id 继续作为差价佣金链路起点，不再从 operator_id/operator_type 推导佣金归属。

4. 读路径兼容策略

• 响应层优先读取 operator_account_*。
• 若新字段为空：
  • 优先尝试 creator 回填后台账号名称。
  • 对客户端个人客户订单，回填个人客户昵称。
  • 对历史代理订单，若 operator_id/operator_type 仍承载店铺语义，则回退展示店铺名称，但不回写新字段。
• commission_result 为空时，按历史订单状态与佣金记录兜底推断，不直接篡改旧列值。

5. 高风险兼容点

• internal/store/postgres/order_store.go 中旧逻辑把 operator_id IN subordinateShopIDs 作为代理权限过滤条件；当 operator_id 不再表示店铺 ID 后，该条件必须迁移到 seller_shop_id，历史订单仅保留兜底分支。
• internal/service/order/service.go 当前 operator_name 仅在 operator_type=agent 时按店铺名称回填，会导致平台旧订单长期空白。
• internal/service/commission_calculation/service.go 当前仅把订单写成“已计算”，无法区分“有佣金 / 无佣金 / 链路异常”。

6. 本次实现范围内的迁移原则

• 只做增量字段迁移，不删除旧列。
• 不在本次 migration 中批量强制回填历史订单，只在运行时兼容读取并为后续人工校验提供依据。