回溯佣金

openspec/changes/add-shop-id-fund-summary-filter/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-13

openspec/changes/add-shop-id-fund-summary-filter/design.md

@@ -0,0 +1,46 @@
+## Context
+
+资金概况列表当前由请求 DTO 绑定查询参数，Handler 将请求交给只读 Query；Query 先通过统一中间件给店铺表附加当前账号的数据范围，再应用店铺名称和主账号用户名条件。路由元数据直接引用该请求 DTO 生成 OpenAPI。行为目标见 proposal 与 delta spec。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 在既有只读查询链路中增加类型安全的店铺 ID 精确筛选。
+- 保持数据权限优先且所有筛选条件采用交集语义。
+- 让无效参数在 HTTP 边界被查询参数解析和显式正整数校验拒绝，并在 OpenAPI 中体现正整数约束。
+
+**Non-Goals:**
+
+- 不改变分页默认值、排序、响应结构或资金投影计算。
+- 不新增按多个店铺 ID 检索，也不改变店铺名称和主账号用户名的模糊检索语义。
+- 不修改数据库 Schema、索引、路由或 Handler 装配。
+
+## Decisions
+
+### 使用可选指针表达查询参数
+
+在资金概况请求 DTO 中将 `shop_id` 建模为 `*uint`，并声明 `omitempty,min=1` 与 OpenAPI 最小值。指针能区分“未提供”和具体值，符合仓库其他列表筛选 DTO 的既有模式。由于当前 Handler 不执行 DTO validator，查询参数无法解析时沿用 `QueryParser` 错误，成功解析为零时在 Handler 内显式返回参数错误。
+
+替代方案是使用 `uint` 的零值表示未提供，但这会弱化缺省与显式非法值的区分，不利于稳定执行正整数校验。
+
+### 在既有筛选函数中叠加主表精确条件
+
+在数据权限条件已经附加到店铺查询后，为非空 `shop_id` 增加店铺主键等值条件。该方式让 ID、名称、用户名和权限条件自然以 SQL `AND` 组合，并继续复用同一个查询对象完成总数与分页数据读取。
+
+替代方案是在 Handler 或 Query 中先按 ID 单独查询店铺，但会产生额外数据库访问，并可能通过“不存在”和“无权限”的不同错误泄露资源存在性。
+
+### 复用请求 DTO 自动更新 OpenAPI
+
+路由 RouteSpec 已引用资金概况请求 DTO，因此实现只需重新运行现有文档生成入口，无需新增路由或修改两套 Handler 占位装配。
+
+## Risks / Trade-offs
+
+- [Fiber 查询参数绑定对负数到无符号整数的错误表现依赖现有解析器] → 对解析错误使用现有统一参数错误映射，对解析成功的零值显式校验，并通过接口 smoke 覆盖零、负数和非数字输入。
+- [筛选条件书写时若使用未限定列名，未来联表可能产生歧义] → 对店铺主键使用当前主表列名，保持条件明确。
+
+## Migration Plan
+
+1. 发布 DTO、Query 和重新生成的 OpenAPI 文档；无需数据库迁移。
+2. 通过构建、OpenSpec 校验及隔离环境接口 smoke 验证新增和兼容场景。
+3. 回滚时恢复相关代码与生成文档即可，不涉及数据恢复。

openspec/changes/add-shop-id-fund-summary-filter/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+后台代理商资金概况列表目前只能按店铺名称或主账号用户名检索，运营人员已知店铺 ID 时无法直接定位目标记录。新增店铺 ID 精确筛选可减少歧义，同时继续受现有店铺数据权限约束。
+
+## What Changes
+
+- 为 `GET /api/admin/shops/fund-summary` 增加可选的 `shop_id` 查询参数，参数为正整数。
+- 提供 `shop_id` 时按店铺 ID 精确筛选，并与现有店铺名称、主账号用户名筛选条件及当前账号店铺数据范围取交集。
+- 无匹配或目标不在当前数据范围时返回空分页结果，不暴露店铺是否存在。
+- 同步生成的 OpenAPI 查询参数说明。
+
+## Capabilities
+
+### New Capabilities
+
+无。
+
+### Modified Capabilities
+
+- `agent-funds-commission`: 扩展代理商资金概况列表的可观察检索行为，支持在数据权限范围内按店铺 ID 精确筛选。
+
+## Impact
+
+- API：`GET /api/admin/shops/fund-summary` 新增兼容性的可选查询参数 `shop_id`。
+- 代码：影响资金概况请求 DTO 与 `internal/query/shop` 的只读筛选逻辑。
+- 文档：重新生成 OpenAPI；无需修改路由、Handler 装配、数据库 Schema 或外部集成。

openspec/changes/add-shop-id-fund-summary-filter/specs/agent-funds-commission/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: 代理商资金概况按店铺 ID 检索
+
+系统 SHALL 允许通过可选的正整数 `shop_id` 查询参数精确筛选 `GET /api/admin/shops/fund-summary` 的店铺资金概况；该条件 MUST 与当前账号的店铺数据范围及其他已提供筛选条件取交集，未提供时 MUST 保持既有列表行为。
+
+#### Scenario: 按可见店铺 ID 精确检索
+
+- **WHEN** 当前账号请求资金概况列表并提供其数据范围内的 `shop_id`
+- **THEN** 系统仅返回该 ID 且同时满足其他已提供筛选条件的店铺资金概况
+
+#### Scenario: 店铺 ID 不匹配或超出数据范围
+
+- **WHEN** 当前账号提供不存在、超出其数据范围或不满足其他已提供筛选条件的 `shop_id`
+- **THEN** 系统返回成功的空分页结果且不披露该店铺是否存在
+
+#### Scenario: 店铺 ID 参数无效
+
+- **WHEN** 当前账号提供零、负数或无法解析为正整数的 `shop_id`
+- **THEN** 系统返回参数错误且不执行资金概况查询
+
+#### Scenario: 未提供店铺 ID
+
+- **WHEN** 当前账号请求资金概况列表但未提供 `shop_id`
+- **THEN** 系统继续按既有分页、数据范围、店铺名称和主账号用户名条件返回结果

openspec/changes/add-shop-id-fund-summary-filter/tasks.md

@@ -0,0 +1,11 @@
+## 1. 请求契约与筛选实现
+
+- [x] 1.1 在资金概况列表请求 DTO 中增加可选正整数 `shop_id` 查询字段及中文 OpenAPI 描述。
+- [x] 1.2 在资金概况 Handler 的 HTTP 边界拒绝显式零值，并保持解析失败返回统一参数错误。
+- [x] 1.3 在既有店铺数据权限查询上叠加 `shop_id` 主键精确条件，使其与名称和用户名条件取交集。
+
+## 2. 文档与验证
+
+- [ ] 2.1 运行 `gofmt` 并重新生成 OpenAPI，核对资金概况接口包含 `shop_id` 正整数查询参数。
+- [ ] 2.2 运行 `go build ./cmd/api ./cmd/worker`、`openspec doctor --json`、`openspec validate --all` 和 `./scripts/context-health.sh`。
+- [ ] 2.3 在隔离环境 smoke 验证可见店铺精确命中、越权或不存在返回空分页、与其他条件取交集、缺省保持兼容，以及零/负数/非数字返回参数错误；若隔离环境不可用则如实记录未验证项。