diff --git a/.env.prod b/.env.prod index 6c7436a..df3188b 100644 --- a/.env.prod +++ b/.env.prod @@ -240,6 +240,7 @@ export JUNHONG_MIDDLEWARE_CORS_ALLOW_CREDENTIALS=true # ---------------------------------------------------------------------------- export JUNHONG_WORKER_ROLE='all' export JUNHONG_WORKER_INSTANCE_NAME='worker-all-1' +export JUNHONG_WORKER_AUDIT_RETENTION_CLEANUP_ENABLED='false' export JUNHONG_WECOM_BASE_URL='https://qyapi.weixin.qq.com' export JUNHONG_WECOM_TIMEOUT='10s' export JUNHONG_APPROVAL_LEGACY_REFUND_MANUAL_ENABLED='true' diff --git a/docs/deployment/production-runbook.md b/docs/deployment/production-runbook.md index d77437f..cb09fe8 100644 --- a/docs/deployment/production-runbook.md +++ b/docs/deployment/production-runbook.md @@ -45,7 +45,7 @@ GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o ./build/api ./cmd/api GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o ./build/worker ./cmd/worker ``` -本次迭代更新只上传 API 与 Worker 二进制;配置变化由维护者直接修改各运行目录的 `.env.prod`。生产迁移文件必须随本次发布上传到 API 目录下的 `migrations/`,供 `migrate` 记录和执行。生产服务器当前尚未安装 `migrate`;安装路径和版本待首次迁移前确认。 +本次迭代更新上传 API 与 Worker 二进制;配置变化由维护者直接修改各运行目录的 `.env.prod`。生产迁移文件必须随本次发布上传到 API 目录下的 `migrations/`,并同步上传当前分支的 `scripts/migrate.sh`,供 `migrate` 记录和执行。生产服务器当前尚未安装 `migrate`;安装路径和版本待首次迁移前确认。 ## 配置规则 @@ -60,7 +60,7 @@ GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o ./build/worker ./cmd/worker 已确认顺序:备份二进制和数据库 → 上传二进制及迁移文件 → 停止 systemd 服务 → 执行迁移 → 启动服务。 -生产当前迁移版本已于 2026-08-13 由维护者在 API 目录验证为 `140`(非 dirty)。历史迁移已归档,生产从 `140` 向后执行根目录 `migrations/` 的 `141+` 迁移;七月分支最终目标为 `206`。根目录不存在 `173` 号迁移,这是正常编号空档。执行前先以显式 `DB_*` 参数运行: +生产当前迁移版本已于 2026-08-13 由维护者在 API 目录验证为 `140`(非 dirty)。历史迁移已归档,生产从 `140` 向后执行根目录 `migrations/` 的 `141+` 迁移;七月分支最终目标为 `209`。根目录不存在 `173` 号迁移,这是正常编号空档。执行前先以显式 `DB_*` 参数运行: ```bash DB_HOST=<生产主机> DB_PORT=<端口> DB_USER=<用户> \ diff --git a/internal/query/retention/retention.go b/internal/query/retention/retention.go index faef33f..13211c7 100644 --- a/internal/query/retention/retention.go +++ b/internal/query/retention/retention.go @@ -3,6 +3,7 @@ package retention import ( "context" + "database/sql" "time" "gorm.io/gorm" @@ -55,17 +56,17 @@ func Load(ctx context.Context, db *gorm.DB, sources ...Source) (Info, error) { } func sourceBoundary(ctx context.Context, db *gorm.DB, source Source, location *time.Location) (time.Time, bool, error) { - var cleanedEnd *time.Time + var cleanedEnd sql.NullTime if err := db.WithContext(ctx).Model(&model.LogArchiveRun{}). Where("source = ? AND cleaned_at IS NOT NULL", source). Select("MAX(range_end)").Scan(&cleanedEnd).Error; err != nil { return time.Time{}, false, errors.Wrap(errors.CodeDatabaseError, err, "查询审计留存清理边界失败") } - if cleanedEnd != nil { - return cleanedEnd.In(location), true, nil + if cleanedEnd.Valid { + return cleanedEnd.Time.In(location), true, nil } - var earliest *time.Time + var earliest sql.NullTime table, column := "tb_audit_event", "occurred_at" if source == SourceIntegration { table, column = "tb_integration_log", "created_at" @@ -73,8 +74,8 @@ func sourceBoundary(ctx context.Context, db *gorm.DB, source Source, location *t if err := db.WithContext(ctx).Table(table).Select("MIN(" + column + ")").Scan(&earliest).Error; err != nil { return time.Time{}, false, errors.Wrap(errors.CodeDatabaseError, err, "查询审计在线数据边界失败") } - if earliest != nil { - return earliest.In(location), false, nil + if earliest.Valid { + return earliest.Time.In(location), false, nil } now := time.Now().In(location) return time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, location), false, nil diff --git a/internal/service/refund/service.go b/internal/service/refund/service.go index 1c857c1..8628b16 100644 --- a/internal/service/refund/service.go +++ b/internal/service/refund/service.go @@ -268,7 +268,7 @@ func (s *Service) Approve(ctx context.Context, id uint, req *dto.ApproveRefundRe return err } - refund, err := s.refundStore.GetByID(ctx, id) + refund, err := s.refundStore.GetByIDForOperation(ctx, id) if err != nil { return errors.New(errors.CodeNotFound, "退款申请不存在") } @@ -690,7 +690,7 @@ func (s *Service) Resubmit(ctx context.Context, id uint, req *dto.ResubmitRefund return errors.New(errors.CodeUnauthorized, "未授权访问") } - refund, err := s.refundStore.GetByID(ctx, id) + refund, err := s.refundStore.GetByIDForOperation(ctx, id) if err != nil { return errors.New(errors.CodeInvalidStatus, "仅已退回状态可重新提交") } diff --git a/internal/store/postgres/refund_store.go b/internal/store/postgres/refund_store.go index 8d2105c..63f3f66 100644 --- a/internal/store/postgres/refund_store.go +++ b/internal/store/postgres/refund_store.go @@ -33,7 +33,7 @@ func (s *RefundStore) Create(ctx context.Context, req *model.RefundRequest) erro return s.db.WithContext(ctx).Create(req).Error } -// GetByID 根据 ID 查询退款申请(含数据权限过滤) +// GetByID 根据 ID 查询退款申请详情(含读取数据权限过滤)。 func (s *RefundStore) GetByID(ctx context.Context, id uint) (*model.RefundRequest, error) { var req model.RefundRequest query := s.db.WithContext(ctx). @@ -41,7 +41,22 @@ func (s *RefundStore) GetByID(ctx context.Context, id uint) (*model.RefundReques Select("tb_refund_request.*, tb_shop.shop_name AS shop_name"). Joins("LEFT JOIN tb_shop ON tb_shop.id = tb_refund_request.shop_id AND tb_shop.deleted_at IS NULL"). Where("tb_refund_request.id = ?", id) - query = applyRefundScope(ctx, query) + query = applyRefundReadScope(ctx, query) + if err := query.First(&req).Error; err != nil { + return nil, err + } + return &req, nil +} + +// GetByIDForOperation 根据 ID 查询退款申请(含写操作数据权限过滤)。 +func (s *RefundStore) GetByIDForOperation(ctx context.Context, id uint) (*model.RefundRequest, error) { + var req model.RefundRequest + query := s.db.WithContext(ctx). + Model(&model.RefundRequest{}). + Select("tb_refund_request.*, tb_shop.shop_name AS shop_name"). + Joins("LEFT JOIN tb_shop ON tb_shop.id = tb_refund_request.shop_id AND tb_shop.deleted_at IS NULL"). + Where("tb_refund_request.id = ?", id) + query = applyRefundOperationScope(ctx, query) if err := query.First(&req).Error; err != nil { return nil, err } @@ -70,7 +85,7 @@ func (s *RefundStore) List(ctx context.Context, opts *store.QueryOptions, filter Model(&model.RefundRequest{}). Select("tb_refund_request.*, tb_shop.shop_name AS shop_name"). Joins("LEFT JOIN tb_shop ON tb_shop.id = tb_refund_request.shop_id AND tb_shop.deleted_at IS NULL") - query = applyRefundScope(ctx, query) + query = applyRefundReadScope(ctx, query) if filters != nil { if filters.Status != nil { @@ -113,9 +128,25 @@ func (s *RefundStore) List(ctx context.Context, opts *store.QueryOptions, filter return requests, total, nil } -// applyRefundScope 应用退款单专属数据权限。 -// 退款申请对代理按创建人隔离,避免上级代理通过店铺层级看到下级申请。 -func applyRefundScope(ctx context.Context, query *gorm.DB) *gorm.DB { +// applyRefundReadScope 应用退款单读取数据权限。 +// 代理仅可查看直接所属店铺的申请,不包含下级代理店铺。 +func applyRefundReadScope(ctx context.Context, query *gorm.DB) *gorm.DB { + switch middleware.GetUserTypeFromContext(ctx) { + case constants.UserTypeSuperAdmin, constants.UserTypePlatform: + return query + case constants.UserTypeAgent: + shopID := middleware.GetShopIDFromContext(ctx) + if shopID == 0 { + return query.Where("1 = 0") + } + return query.Where("tb_refund_request.shop_id = ?", shopID) + default: + return query.Where("1 = 0") + } +} + +// applyRefundOperationScope 应用退款单写操作数据权限。 +func applyRefundOperationScope(ctx context.Context, query *gorm.DB) *gorm.DB { switch middleware.GetUserTypeFromContext(ctx) { case constants.UserTypeSuperAdmin, constants.UserTypePlatform: return query diff --git a/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/.openspec.yaml b/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/.openspec.yaml new file mode 100644 index 0000000..9567240 --- /dev/null +++ b/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-08-18 diff --git a/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/design.md b/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/design.md new file mode 100644 index 0000000..a44fc97 --- /dev/null +++ b/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. 如需回滚,恢复代理退款读取的创建人过滤;数据库数据不受影响。 diff --git a/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/proposal.md b/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/proposal.md new file mode 100644 index 0000000..cd9ffa1 --- /dev/null +++ b/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}` 的代理数据权限过滤。 +- 预计修改退款数据访问层及其调用所依赖的当前账号店铺范围获取逻辑;不新增接口、依赖或数据库结构。 diff --git a/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/specs/order-refund-exchange/spec.md b/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/specs/order-refund-exchange/spec.md new file mode 100644 index 0000000..dd49af5 --- /dev/null +++ b/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** 系统返回空列表或不存在,且不泄露任何退款申请 diff --git a/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/tasks.md b/openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/tasks.md new file mode 100644 index 0000000..4ccc1da --- /dev/null +++ b/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`,确认变更工件有效。 diff --git a/openspec/changes/fix-audit-retention-null-boundary/.openspec.yaml b/openspec/changes/fix-audit-retention-null-boundary/.openspec.yaml new file mode 100644 index 0000000..9567240 --- /dev/null +++ b/openspec/changes/fix-audit-retention-null-boundary/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-08-18 diff --git a/openspec/changes/fix-audit-retention-null-boundary/design.md b/openspec/changes/fix-audit-retention-null-boundary/design.md new file mode 100644 index 0000000..3544ceb --- /dev/null +++ b/openspec/changes/fix-audit-retention-null-boundary/design.md @@ -0,0 +1,45 @@ +## Context + +`internal/query/retention` 以聚合查询计算审计与外部交互日志的在线留存边界。PostgreSQL 在没有匹配行时会为 `MAX` 和 `MIN` 返回 `NULL`,而当前扫描目标不能接收空值,导致所有依赖该边界的审计调查接口失败。 + +## Goals / Non-Goals + +**Goals:** + +- 将空聚合结果识别为“尚无边界”,而非数据库错误。 +- 保持已有已清理边界、最早在线记录和当月兜底的语义。 +- 修复所有通过同一留存边界查询函数进入的审计接口。 + +**Non-Goals:** + +- 不执行审计物理清理,不改变归档或保留策略。 +- 不修改数据库结构、迁移记录或历史审计数据。 +- 不修改 API 路由、权限或响应字段。 + +## Decisions + +### 使用可空时间承接 SQL 聚合结果 + +留存边界查询使用标准库可空时间值承接 `MAX(range_end)` 与 `MIN()`。仅在值有效时转换为目标时区并作为边界返回。 + +拒绝将聚合结果用当前时间或固定时间 SQL `COALESCE`:这会把“尚未清理”误判为已归档,改变响应中的留存语义。 + +### 同时覆盖已清理和最早在线两个聚合路径 + +`MAX(range_end)` 是本次线上错误入口;`MIN` 在在线表为空时具有相同的空值扫描风险。两个路径共用相同的可空聚合边界,应一次修复。 + +## Risks / Trade-offs + +- [风险] 空边界被误判为已清理,错误拒绝历史查询 → 仅在聚合值有效时设置已清理标记与归档边界。 +- [风险] 修复遗漏其他审计接口 → 保持修改在所有审计查询共用的留存边界函数内。 + +## Migration Plan + +1. 修改留存边界的空时间扫描逻辑。 +2. 格式化并构建 API。 +3. 仅替换 API 二进制并重启 API Unit。 +4. 以 `GET /api/admin/audit/events?page=1&page_size=20` 验证无已清理记录时接口不再返回 500。 + +### Rollback + +无数据库迁移。若 API 启动或查询异常,覆盖回本次发布前 API 二进制并重启 API Unit。 diff --git a/openspec/changes/fix-audit-retention-null-boundary/proposal.md b/openspec/changes/fix-audit-retention-null-boundary/proposal.md new file mode 100644 index 0000000..386b2f1 --- /dev/null +++ b/openspec/changes/fix-audit-retention-null-boundary/proposal.md @@ -0,0 +1,26 @@ +## Why + +生产环境尚未执行审计物理清理时,留存边界查询中的 `MAX(range_end)` 返回 SQL `NULL`,当前实现无法扫描该值,导致 `GET /api/admin/audit/events` 等审计查询返回服务端错误。 + +## What Changes + +- 将审计及外部交互日志留存边界的可空聚合结果作为可空时间处理。 +- 没有完成物理清理记录时,审计查询继续返回在线数据,且 `archived_before` 保持为空。 +- 没有在线审计或集成交互数据时,保留现有的当月起始时间兜底边界。 + +## Capabilities + +### New Capabilities + +无。 + +### Modified Capabilities + +- `operations-audit`: 审计调查在尚无已完成物理清理记录时仍可查询在线审计事实。 + +## Impact + +- 代码:`internal/query/retention/retention.go`。 +- API:修复全局审计事件、时间线、资源活动、风险和资金审计等依赖留存边界的既有查询。 +- 数据库:无迁移、无数据修复。 +- 部署:仅需重新构建和发布 API 二进制。 diff --git a/openspec/changes/fix-audit-retention-null-boundary/specs/operations-audit/spec.md b/openspec/changes/fix-audit-retention-null-boundary/specs/operations-audit/spec.md new file mode 100644 index 0000000..ac27a75 --- /dev/null +++ b/openspec/changes/fix-audit-retention-null-boundary/specs/operations-audit/spec.md @@ -0,0 +1,49 @@ +## MODIFIED Requirements + +### Requirement: 审计时间线 + +系统 SHALL 支持按事件、操作者、资源、请求、关联标识和资金维度查询已记录的审计事实。新建的 `tb_integration_log` 在已取得稳定审计事件时 SHALL 写入其内部 ID 作为 `audit_event_id`,并且该日志的非空 `integration_id` SHALL 出现在对应事件列表和事件详情的 `investigation_refs.integration_refs` 中;关联生成失败时系统 MUST 保留 Integration Log 并记录可排查告警,且 MUST NOT 按名称、时间或摘要推断关联。历史 Integration Log 不在本要求的回填范围内。审计事件的构造、校验或持久化失败 MUST 记录可关联的结构化错误日志和二次失败记录,且 MUST NOT 改变已通过业务校验的业务操作结果或接口响应。尚无完成物理清理记录时,审计调查接口 MUST 继续查询在线审计事实,且返回的留存边界不得将数据标记为已归档。 + +#### Scenario: 审计时间线 + +- **GIVEN** 审计事实已存在 +- **WHEN** 使用对应维度查询 +- **THEN** 返回匹配的事实与稳定动作编码,不用访问日志替代 + +#### Scenario: 事件返回已关联外部交互引用 + +- **GIVEN** 一个在线审计事件有 `tb_integration_log.audit_event_id` 指向其内部 ID 的外部交互记录 +- **WHEN** 查询全局审计事件列表或该事件详情 +- **THEN** 该事件的 `investigation_refs.integration_refs` 返回该记录的 `integration_id` + +#### Scenario: 事件没有关联外部交互引用 + +- **GIVEN** 一个在线审计事件没有稳定关联的外部交互记录 +- **WHEN** 查询全局审计事件列表或该事件详情 +- **THEN** `investigation_refs.integration_refs` 返回空数组 + +#### Scenario: 新外部交互日志具有稳定审计关联 + +- **GIVEN** 系统即将记录一次新的外部调用、入站回调或未发送裁决 +- **WHEN** 写入对应 Integration Log +- **THEN** 该记录保存非空 `audit_event_id`,且其目标 Audit Event 已存在 + +#### Scenario: 缺少审计关联时保留外部交互日志 + +- **GIVEN** 一次新的外部交互日志没有稳定审计事件关联 +- **WHEN** 系统尝试写入该 Integration Log +- **THEN** 系统持久化该 Integration Log、记录可排查告警,并返回空 `integration_refs` + +#### Scenario: 审计写入失败不阻断业务 + +- **GIVEN** 一个业务操作已通过自身输入、权限和状态校验 +- **WHEN** 该操作的审计事件构造、校验或持久化失败 +- **THEN** 系统提交或返回该业务操作原本的结果,并以请求关联标识、动作编码和资源标识记录审计失败 + +#### Scenario: 尚无物理清理记录时查询在线审计 + +- **GIVEN** 审计或外部交互日志尚无完成物理清理的归档运行记录 +- **WHEN** 调用任一依赖留存边界的审计调查接口 +- **THEN** 系统返回当前在线数据或空列表 +- **AND** 响应中的 `archived_before` 为空 +- **AND** 系统不得因空留存边界返回服务端错误 diff --git a/openspec/changes/fix-audit-retention-null-boundary/tasks.md b/openspec/changes/fix-audit-retention-null-boundary/tasks.md new file mode 100644 index 0000000..50df53f --- /dev/null +++ b/openspec/changes/fix-audit-retention-null-boundary/tasks.md @@ -0,0 +1,10 @@ +## 1. 留存边界空值处理 + +- [x] 1.1 将已清理边界与最早在线记录的聚合结果改为可空时间扫描,仅在结果有效时设置对应边界。 +- [x] 1.2 保持无已清理记录时 `archived_before` 为空,以及无在线记录时按当月起始时间兜底的现有语义。 + +## 2. 验证与发布 + +- [x] 2.1 格式化修改文件并构建 API。 +- [ ] 2.2 验证未执行物理清理时 `GET /api/admin/audit/events?page=1&page_size=20` 不再返回服务端错误。 +- [ ] 2.3 仅发布并重启 API 二进制;不执行数据库迁移、不改 Worker 配置。 diff --git a/openspec/specs/order-refund-exchange/spec.md b/openspec/specs/order-refund-exchange/spec.md index 5fd20f0..e7f9ee5 100644 --- a/openspec/specs/order-refund-exchange/spec.md +++ b/openspec/specs/order-refund-exchange/spec.md @@ -16,6 +16,28 @@ - **WHEN** 再次审批、发货、完成、取消或重新提交 - **THEN** 系统返回状态冲突且不重复改变资产、余额或业务状态 +### 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** 系统返回空列表或不存在,且不泄露任何退款申请 + ## 可达操作索引 本节只用于入口导航,不是行为 Requirement;业务义务以上述 Requirements 为准。