补充退款列表应当让本店铺的人看见

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/.openspec.yaml

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

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/design.md

@@ -0,0 +1,31 @@
+## Context
+
+退款列表和详情当前共用按创建人过滤的数据访问方法。详情读取还被退款审批、退回和重新提交等写操作用于加载退款申请，因此直接把该方法改为按店铺过滤，会扩大既有写操作的对象范围。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 让代理仅在退款列表和详情读取时按当前登录账号的直接所属店铺查看退款。
+- 保持下级代理店铺不可见，并保持退款写操作的既有创建人权限边界。
+
+**Non-Goals:**
+- 不改变平台和超级管理员的可见范围。
+- 不改变代理创建退款、审批、退回、拒绝或重新提交的授权规则。
+- 不补齐历史退款中缺失的店铺归属数据。
+
+## Decisions
+
+- 读取路径以认证上下文中的直接 `ShopID` 与退款申请的 `ShopID` 精确匹配，不使用包含下级店铺的 `SubordinateShopIDs`。这是账号所属店铺的稳定事实，且能直接满足排除下级代理的要求。
+- 为列表与详情读取使用店铺可见范围；写操作继续通过创建人范围加载退款申请。读取与写入分别显式选择权限范围，避免共享查询方法导致查看权限扩展为操作权限。
+- 代理上下文没有有效 `ShopID` 时施加恒假条件，不回退至未过滤查询。备选方案是返回参数错误；选择空结果/不存在以与现有未授权对象查询行为一致，并避免暴露数据存在性。
+
+## Risks / Trade-offs
+
+- [历史退款的 `shop_id` 为空] → 该类记录不会对代理可见，仍由平台和超级管理员查询；不在本次改动中推断或回填归属。
+- [读取与写入使用不同权限方法] → 在方法名称和调用处明确区分读取可见性与操作授权，并在实现后逐一检查退款服务中全部按 ID 加载的调用者。
+
+## Migration Plan
+
+1. 发布应用代码；无需数据迁移。
+2. 使用同店铺不同账号、下级店铺和未绑定店铺账号分别验证列表及详情。
+3. 如需回滚，恢复代理退款读取的创建人过滤；数据库数据不受影响。

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/proposal.md

@@ -0,0 +1,24 @@
+## Why
+
+代理账号当前仅能按退款申请创建人查看退款，导致同一店铺的其他账号创建退款后，本店代理无法在退款管理中查询或查看详情。
+
+## What Changes
+
+- 将代理账号的退款列表和详情可见范围从“本人创建”调整为“与当前代理同一店铺”。
+- 同店铺内其他账号创建的退款申请对该店铺代理可见。
+- 代理账号仍不得因本次调整看到下级代理店铺的退款申请；平台和超级管理员既有全量可见范围不变。
+
+## Capabilities
+
+### New Capabilities
+
+- 无。
+
+### Modified Capabilities
+
+- `order-refund-exchange`: 调整代理账号查询退款列表和详情时的数据可见范围。
+
+## Impact
+
+- 影响 `GET /api/admin/refunds` 与 `GET /api/admin/refunds/{id}` 的代理数据权限过滤。
+- 预计修改退款数据访问层及其调用所依赖的当前账号店铺范围获取逻辑；不新增接口、依赖或数据库结构。

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/specs/order-refund-exchange/spec.md

@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: 代理退款查询按所属店铺隔离
+系统 SHALL 允许代理账号通过 `GET /api/admin/refunds` 查询其当前所属店铺的全部退款申请，并通过 `GET /api/admin/refunds/{id}` 查询其中任一申请详情，不以申请创建账号作为查询条件。该范围 SHALL 不包含下级代理店铺、其他店铺或未关联店铺的退款申请；代理账号未关联店铺时，列表 SHALL 为空且详情 SHALL 返回不存在。平台和超级管理员的既有退款查询范围 SHALL 保持不变。
+
+#### Scenario: 查看同店铺其他账号提交的退款
+- **GIVEN** 当前代理所属店铺存在由另一账号创建的退款申请
+- **WHEN** 该代理查询退款列表或该申请详情
+- **THEN** 系统返回该退款申请
+
+#### Scenario: 查询下级代理店铺的退款
+- **GIVEN** 当前代理的下级代理店铺存在退款申请
+- **WHEN** 当前代理查询退款列表或该申请详情
+- **THEN** 系统不返回该退款申请，详情查询返回不存在
+
+#### Scenario: 未绑定店铺的代理查询退款
+- **GIVEN** 当前代理账号未关联店铺
+- **WHEN** 该代理查询退款列表或退款申请详情
+- **THEN** 系统返回空列表或不存在，且不泄露任何退款申请

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/tasks.md

@@ -0,0 +1,10 @@
+## 1. 退款读取权限
+
+- [x] 1.1 在退款数据访问层区分读取可见范围与写操作创建人范围：代理读取按当前直接所属店铺精确过滤，未关联店铺时拒绝返回数据。
+- [x] 1.2 将退款列表和详情读取接入店铺可见范围，并逐一核对退款服务所有按 ID 加载的写操作仍使用既有创建人范围。
+
+## 2. 验证
+
+- [x] 2.1 执行 gofmt，并构建 `./cmd/api` 和 `./cmd/worker`，确认修改可编译。
+- [x] 2.2 以同店铺其他账号、下级代理店铺和未绑定店铺的代理身份，分别验证退款列表和详情的可见性（按用户决定跳过隔离环境人工验证）。
+- [x] 2.3 执行 `openspec validate agent-refund-shop-visibility --strict`，确认变更工件有效。