归档

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

@@ -1,11 +0,0 @@
-## 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 验证可见店铺精确命中、越权或不存在返回空分页、与其他条件取交集、缺省保持兼容，以及零/负数/非数字返回参数错误；若隔离环境不可用则如实记录未验证项。

openspec/changes/archive/2026-08-13-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. 文档与验证
+
+- [x] 2.1 运行 `gofmt` 并重新生成 OpenAPI，核对资金概况接口包含 `shop_id` 正整数查询参数。（gofmt 无差异；`docs/admin-openapi.yaml` 的 fund-summary 接口已含 `shop_id` 正整数查询参数）
+- [x] 2.2 运行 `go build ./cmd/api ./cmd/worker`、`openspec doctor --json`、`openspec validate --all` 和 `./scripts/context-health.sh`。（build 通过；doctor healthy；validate 全通过；context-health 因已存在的 `.scratch` 目录报「禁止目录或文件仍存在」）
+- [x] 2.3 在隔离环境 smoke 验证可见店铺精确命中、越权或不存在返回空分页、与其他条件取交集、缺省保持兼容，以及零/负数/非数字返回参数错误；若隔离环境不可用则如实记录未验证项。（隔离环境不可用：PostgreSQL 5432 与 Redis 6379 均未运行，如实记录为未验证）

openspec/specs/agent-funds-commission/spec.md

@@ -73,6 +73,30 @@
 - **WHEN** 补偿流程发现已退款且 `commission_deducted=false` 的退款单
 - **THEN** 系统恢复该退款单的唯一后处理请求，并在既有回扣成功后更新其回扣完成标记
 
+### 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** 系统继续按既有分页、数据范围、店铺名称和主账号用户名条件返回结果
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
@@ -92,30 +116,3 @@
 ### 提现配置管理
 
 `GET /api/admin/commission/withdrawal-settings`（提现配置列表）；`POST /api/admin/commission/withdrawal-settings`（新增提现配置）；`GET /api/admin/commission/withdrawal-settings/current`（获取当前生效的提现配置）。
-
-### Requirement: 佣金待计算状态可恢复
-
-系统 SHALL 将已支付订单的佣金待计算状态与可靠投递事实关联；投递异常不得静默遗留为无法继续处理的待计算订单。
-
-#### Scenario: 佣金投递链路异常
-
-- **WHEN** 佣金计算任务提交或消费链路发生可恢复异常
-- **THEN** 订单维持待计算且投递状态、重试次数和失败摘要可查询，恢复投递后按既有规则得出有佣金、无佣金或待人工修正结果
-
-### Requirement: 退款佣金回扣可靠完成
-
-系统 SHALL 在退款审批生效时持久化佣金回扣请求；回扣请求的投递或处理异常不得静默遗留，且退款单在全部应回扣佣金失效并完成对应钱包流水前不得标记为已回扣。
-
-#### Scenario: 已退款订单佣金回扣失败后恢复
-
-- **WHEN** 已退款订单的佣金回扣首次处理失败或进程中断
-- **THEN** 退款单保持佣金未回扣状态并保留可重试事实，后续成功处理后佣金记录失效、佣金钱包按既有规则扣减且退款单标记为已回扣
-
-### Requirement: 退款后处理可补偿
-
-系统 SHALL 对已退款但佣金未回扣或资产未完成后处理的退款单提供幂等补偿；重复补偿不得重复扣减佣金钱包、重复写回扣流水或重复处理资产。
-
-#### Scenario: 遗留退款单补偿
-
-- **WHEN** 补偿流程发现已退款且 `commission_deducted=false` 的退款单
-- **THEN** 系统恢复该退款单的唯一后处理请求，并在既有回扣成功后更新其回扣完成标记

openspec/specs/asset-device/spec.md

@@ -49,6 +49,25 @@
 - **WHEN** 查询临期资产列表并执行每日临期扫描
 - **THEN** 列表返回红色等级，且扫描创建当天的套餐临期通知
 
+### Requirement: 卡业务观测可靠事件标识
+
+系统 SHALL 为卡与设备控制及其后续网络、流量观测生成不超过公共可靠事件存储上限的稳定事件标识，相同业务事实重试时 SHALL 保持同一标识。
+
+#### Scenario: 停复机成功写入观测事件
+
+- **WHEN** 卡或设备停复机的上游调用成功且本地事务记录业务结果
+- **THEN** 系统在同一事务写入合法长度的业务观测可靠事件，不因事件标识超长回滚本地结果
+
+#### Scenario: 网络或流量变化写入可靠事件
+
+- **WHEN** 一次具有长观测标识的观测产生网络状态变化或流量正增量
+- **THEN** 系统写入合法长度且可重复计算的可靠事件标识
+
+#### Scenario: 非法可靠事件标识被边界拒绝
+
+- **WHEN** 生产者向公共可靠事件存储提交超过字段上限的事件标识或父事件标识
+- **THEN** 系统在持久化边界返回明确的参数错误而不是数据库字段错误
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。