junhong_cmp_fiber/openspec/changes/fix-order-operator-and-chain-commission-semantics/tasks.md

1. 数据模型与迁移基线

• 1.1 梳理订单现有 operator_*、creator、commission_status 字段的历史语义与使用点，产出兼容映射清单，并用 lsp_diagnostics 确认相关模型文件当前无错误
• 1.2 创建订单操作者权威字段与佣金结果字段的 migration（保留旧字段不删除），并核对 up/down 文件命名、注释与回滚策略完整
• 1.3 更新订单模型常量与字段定义，明确“佣金流程状态”和“佣金业务结果”两套枚举，并用 lsp_diagnostics 确认 internal/model/order.go、pkg/constants/* 无错误

2. 订单操作者语义修复

• 2.1 调整后台订单创建链路，统一写入真实操作者账号信息，覆盖平台下单、代理自购、代理为下级代购、平台代扣代理钱包等场景，并用手工代码走查验证每条路径都有明确操作者来源
• 2.2 调整订单响应构建逻辑，按账号语义回填 operator_name，并将账号展示与业务店铺展示分离，用 lsp_diagnostics 确认 internal/service/order/service.go 与 DTO 文件无错误
• 2.3 设计并实现历史订单兼容读取策略：新字段优先，旧字段与 creator 兜底；手工抽查平台旧订单、代理旧订单各至少一条，确认不会再出现平台操作者名称默认空白

3. 链路型差价佣金模型修复

• 3.1 调整佣金计算服务，统一以 seller_shop_id 为起点沿完整父级链逐级计算差价佣金，移除对 operator_id/operator_type 的佣金归属依赖，并用代码走查确认顶级、二级、三级、多级场景口径一致
• 3.2 在佣金计算完成后显式写回“已完成+有佣金 / 已完成+无佣金 / 待人工处理+链路异常”结果，确保 0 佣金订单不再停留在待计算
• 3.3 保留并增强链路断裂待人工处理逻辑，手工检查断点备注、待审记录与订单状态结果三者一致

4. 佣金触发与补偿链修复

• 4.1 统一修复所有差价佣金适用路径的入队逻辑，覆盖支付回调、自动完单、平台代理扣代理钱包、代理钱包代购等场景，并用代码走查确认不会遗漏 self_purchase 的平台代理扣订单
• 4.2 调整佣金任务幂等判断与补偿扫描口径，使其基于新流程状态工作，避免“无佣金订单”被重复补偿入队
• 4.3 手工验证三类样本：顶级代理无佣金订单、多级代理有佣金订单、链路断裂待人工处理订单，确认任务执行后的订单状态与佣金记录符合预期

5. 订单查询与文档同步

• 5.1 更新订单列表/详情相关 DTO 与接口文档，明确操作者字段语义以及佣金流程状态/业务结果字段语义，并用 lsp_diagnostics 确认 DTO 与 Handler 文件无错误
• 5.2 若接口响应结构发生变化，按项目规范同步更新文档生成器相关注册与说明文档，确保 OpenAPI 输出与新语义一致
• 5.3 补充中文功能总结与手工验收清单，覆盖平台订单操作者展示、多级链路差价佣金、无佣金完成态、链路异常待人工处理四类核心验收场景

6. 最终手工验收

• 6.1 使用数据库查询逐条核对订单、佣金记录、钱包流水与操作者字段，确认核心样本数据落库符合新语义
• 6.2 对本次变更涉及的关键 Go 文件运行 lsp_diagnostics，确认无错误、无遗留坏状态
• 6.3 按验收清单完成后台订单列表/详情、补偿入队、异常订单识别的手工验证，确认提案范围内的业务流程可闭环