# 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`。