one-pipe-system/openspec/changes/add-commission-clawback-records/proposal.md

Change: 退款佣金回扣改为独立回溯明细（前端适配）

Why

后端调整了退款佣金回扣口径：退款不再把原佣金整单置为「已失效」，而是原佣金行保持「已发放」不变，另新增一条独立负数、不可提现的「回溯明细」行。对应前端接口说明（简短版）要求：

• 佣金记录列表新增 status 查询参数（含 5 回溯）与行级 source 字段（original / clawback）。
• 新增佣金记录详情接口 GET /api/admin/shops/{shop_id}/commission-records/{id}?source=clawback。
• 新增导出场景 scene=commission_record（后端已进白名单）。
• 两个必改点：列表行 key 必须用 source + ':' + id（原佣金与回溯 ID 空间独立，同一页会重复）；渲染需支持负数金额（标红）与「不可提现」标识。

前端当前实现基于旧语义（ShopCommissionRecordItem 无 source，列表行 key 直接用 id，退款后原行被视为已失效），需按新口径适配。

What Changes

• 类型层：ShopCommissionRecordItem 新增 source、original_commission_id、refund_id、refund_no、withdrawable、clawback_records、clawback_total_amount；新增回溯摘要与详情类型；CommissionRecordQueryParams.status 支持 5（回溯）。
• API 层：新增 getShopCommissionRecordDetail(shopId, id, source?)，source 省略时按原佣金处理。
• 列表页（代理侧「我的佣金」与管理侧「代理资金概览 > 佣金明细」）：行 key 改为 source + ':' + id；回溯行展示「回溯」状态与「不可提现」标识；负数金额与可为负的 balance_after 标红；status 筛选项新增「回溯」；详情入口必须携带该行 source。
• 详情展示：原佣金详情展示 clawback_records 摘要与 clawback_total_amount；回溯详情展示来源 original_commission；越权/不存在统一提示「佣金明细不存在」，不做存在性判断。
• 导出：ExportTaskScene 增加 commission_record；新增导出佣金记录场景页、路由、菜单与 i18n；佣金记录列表导出入口只提交受支持的筛选 key（shop_id / status / commission_source / order_no）。
• 字段兜底：后端新增字段为 omitempty，前端取 ?? [] / ?? 0，金额单位为分。

Not In Scope

• 不实现后端接口、不改数据库、不改审批实例数据。
• 既有字段无改名/改类型；commission-stats、commission-daily-stats 口径未变，本次不动。
• 时间筛选属另一 Change（add-export-time-filter-standards），本次不涉及。
• 语义提醒：退款不再写 status=4，旧假设「退款后原行变已失效」已失效，需在文案/注释体现。

Impact

• Affected specs: commission-management、export-task-management
• Affected code:
  • src/types/api/commission.ts
  • src/api/modules/commission.ts
  • src/views/commission-management/my-commission/index.vue
  • src/views/commission-management/agent-fund-overview/index.vue
  • src/types/api/exportTask.ts
  • src/config/constants/exportTask.ts
  • src/views/asset-management/export-task-management/export-commission-record/index.vue
  • src/router/routes/asyncRoutes.ts、src/router/routesAlias.ts、src/locales/langs/{zh,en}.json
• Dependencies:
  • docs/产品迭代8月份/frontend-api-simple.md（后端契约）
  • 后端已把 scene=commission_record 加入导出场景白名单
  • 需确认导出场景权限编码与场景页是否必需（见 Open Questions）
• Breaking changes:
  • 列表行 key 由 id 改为 source + ':' + id；未携带 source 的详情请求会命中原佣金行。

接口确认结果（来自 OpenAPI）

• 详情响应 DtoShopCommissionRecordDetailResp：source、record（DtoShopCommissionRecordItem）、clawback_records（仅原佣金返回）、original_commission（仅回溯详情返回）。
• DtoShopCommissionRecordItem 新增 source、released_at、withdrawable（boolean，nullable，仅回溯行返回且恒 false）、original_commission_id、refund_id、refund_no、clawback_records、clawback_total_amount。
• DtoShopCommissionClawbackItem：id、amount（恒负）、balance_after（可为负）、original_commission_id、refund_id、refund_no、status（5 回溯）、status_name、withdrawable、created_at。
• 详情接口越权与不存在返回同一结果，前端统一提示「佣金明细不存在」。
• 已确认需要新增「导出佣金记录」菜单页。

待确认（已按仓库既有约定实现，如需调整请告知）

1. 导出场景权限编码：按既有约定实现为 export_task:commission_record_detail / export_task:commission_record_download。
2. 佣金记录列表导出按钮权限：按 agent_wallet_transaction:export 的同级约定实现为 commission_record:export。