fix: some

openspec/changes/add-commission-clawback-records/proposal.md

@@ -0,0 +1,60 @@
+# 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`。

openspec/changes/add-commission-clawback-records/specs/commission-management/spec.md

@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: 佣金记录列表回溯行与状态筛选
+佣金记录列表（`GET /api/admin/shops/{shop_id}/commission-records`）MUST 支持 `status` 查询参数（1 已冻结 / 2 解冻中 / 3 已发放 / 4 已失效 / 5 回溯 / 99 待人工修正），且 MUST NOT 提供 `source` 查询参数；`status=5` 即等价于只看回溯行。
+
+#### Scenario: 只看回溯行
+- **GIVEN** 用户在佣金记录列表选择状态「回溯」
+- **WHEN** 前端发起列表查询
+- **THEN** 前端 MUST 只传 `status=5`
+- **AND** 前端 MUST NOT 传 `source` 参数
+
+### Requirement: 佣金记录行新增字段与兜底
+列表响应的每一行 MUST 支持 `source`（`original` / `clawback`）；回溯行 MUST 支持 `original_commission_id`、`refund_id`、`refund_no`、`withdrawable`（恒 `false`）与可为负数的 `amount`、`balance_after`；原佣金行 MUST 支持 `clawback_records` 摘要与 `clawback_total_amount`（负值）。后端 `omitempty` 缺省字段前端 MUST 以 `?? []` / `?? 0` 兜底，金额单位为分。
+
+#### Scenario: 缺省字段兜底
+- **GIVEN** 列表响应中的原佣金行未返回 `clawback_records`
+- **WHEN** 前端渲染该行
+- **THEN** 前端 MUST 按空数组处理并正常渲染
+- **AND** 前端 MUST NOT 因缺省字段报错或渲染 `undefined`
+
+### Requirement: 列表行标识与负数渲染
+列表 MUST 使用 `source + ':' + id` 作为行 key（原佣金与回溯 ID 空间独立，同一页可能出现相同 `id`）；回溯行 MUST 展示「不可提现」标识；负数 `amount` 与 `balance_after` MUST 标红显示；任何跳转详情的入口 MUST 携带该行的 `source`，缺省按原佣金处理。
+
+#### Scenario: 同一页出现重复 id
+- **GIVEN** 同一页列表中同时存在原佣金行与回溯行且 `id` 相同
+- **WHEN** 前端渲染表格
+- **THEN** 前端 MUST 以 `source + ':' + id` 区分两行
+- **AND** 前端 MUST NOT 出现行复用或渲染错位
+
+#### Scenario: 负数金额标红
+- **GIVEN** 某回溯行 `amount` 为负值
+- **WHEN** 前端渲染金额列
+- **THEN** 前端 MUST 标红展示该负值
+
+### Requirement: 佣金记录详情接口封装
+前端 MUST 提供 `GET /api/admin/shops/{shop_id}/commission-records/{id}` 的详情封装，并支持可选 `source`：`source=clawback` 时返回回溯详情，`source` 省略时按原佣金处理。原佣金详情 MUST 返回 `clawback_records`；回溯详情 MUST 返回 `original_commission`；越权与不存在 MUST 返回同一结果（佣金明细不存在），前端 MUST NOT 用该接口做存在性判断。
+
+#### Scenario: 打开回溯行详情
+- **GIVEN** 用户在列表点击某条回溯行
+- **WHEN** 前端请求详情
+- **THEN** 前端 MUST 携带 `source=clawback` 与该行 `id`
+- **AND** 详情 MUST 展示来源 `original_commission`
+
+#### Scenario: 越权统一提示
+- **GIVEN** 详情接口返回「佣金明细不存在」
+- **WHEN** 前端渲染详情
+- **THEN** 前端 MUST 展示统一不存在提示
+- **AND** 前端 MUST NOT 区分越权与不存在两种原因

openspec/changes/add-commission-clawback-records/specs/export-task-management/spec.md

@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: 佣金记录导出场景
+前端 MUST 支持导出场景 `scene=commission_record`（后端已进白名单），并在导出管理中提供该场景的任务列表入口；创建导出任务时 MUST 提交固定 `scene=commission_record`。导出粒度为佣金记录：原佣金与回溯各占一行，金额与余额同样按分转元、负数带 `-` 展示。
+
+#### Scenario: 场景页固定查询
+- **GIVEN** 用户打开导出佣金记录页面
+- **WHEN** 页面查询导出任务列表
+- **THEN** 前端 MUST 调用 `GET /api/admin/export-tasks` 且带 `scene=commission_record`
+- **AND** 用户 MUST NOT 能在该页面切换到其他场景
+
+### Requirement: 佣金记录导出筛选受限
+佣金记录列表发起导出时，`query` MUST 只包含后端支持的筛选 key：`shop_id`、`status`、`commission_source`、`order_no`；MUST NOT 提交 `iccid`、`virtual_no` 及时间筛选，导出弹窗 MUST NOT 直接复用列表全部条件。
+
+#### Scenario: 列表筛选含不支持的 key
+- **GIVEN** 佣金记录列表当前筛选包含 `iccid` 与时间范围
+- **WHEN** 用户确认创建导出任务
+- **THEN** 提交的 `query` MUST NOT 包含 `iccid`、`virtual_no` 或时间字段
+- **AND** 提交的 `query` MUST 仅保留 `shop_id`、`status`、`commission_source`、`order_no` 中已填写的项

openspec/changes/add-commission-clawback-records/tasks.md

@@ -0,0 +1,27 @@
+## 1. 类型与 API 层（commission-api）
+- [x] 1.1 `CommissionStatus` 补充 5（回溯）；修正 `CommissionRecordQueryParams.status` 过期注释并支持回溯值
+- [x] 1.2 `ShopCommissionRecordItem` 新增 `source`、`original_commission_id`、`refund_id`、`refund_no`、`withdrawable`、`clawback_records`、`clawback_total_amount`
+- [x] 1.3 新增回溯摘要与佣金记录详情类型（原佣金详情含 `clawback_records`，回溯详情含 `original_commission`）
+- [x] 1.4 `CommissionService` 新增 `getShopCommissionRecordDetail(shopId, id, source?)`
+
+## 2. 列表页（commission-records-list）
+- [x] 2.1 行 key 改为 `source + ':' + id`（`my-commission` 与 `agent-fund-overview` 佣金明细）
+- [x] 2.2 回溯行展示「回溯」状态与「不可提现」标识
+- [x] 2.3 负数金额与可为负的 `balance_after` 标红渲染
+- [x] 2.4 `status` 筛选项新增「回溯」
+- [x] 2.5 列表新增详情入口，且请求必须携带该行 `source`
+
+## 3. 详情展示（commission-record-detail）
+- [x] 3.1 原佣金详情展示 `clawback_records` 摘要与 `clawback_total_amount`
+- [x] 3.2 回溯详情展示来源 `original_commission`
+- [x] 3.3 越权/不存在统一提示「佣金明细不存在」，不作为存在性判断依据
+
+## 4. 导出（commission-record-export）
+- [x] 4.1 `ExportTaskScene` 增加 `commission_record` 并补场景配置
+- [x] 4.2 新增导出佣金记录场景页、路由、菜单与中英文案
+- [x] 4.3 佣金记录列表新增导出入口，`query` 仅提交 `shop_id` / `status` / `commission_source` / `order_no`
+
+## 5. 验证
+- [x] 5.1 运行 `npm run build`（含 `vue-tsc --noEmit`）
+- [x] 5.2 运行 `npm run check:encoding`
+- [x] 5.3 运行 `openspec.cmd validate add-commission-clawback-records --strict`