# data-permission Delta Specification

## Purpose

数据权限过滤机制从 GORM Callback 自动过滤改为业务层显式调用。

## REMOVED Requirements

### Requirement: GORM Callback Data Permission

**Reason**: GORM Callback 自动过滤存在以下问题：跳过率高（20+ 处 SkipDataPermission）、特殊处理多、重复查询、隐式行为难调试、原生 SQL 失效。改为业务层显式调用模式。

**Migration**:
1. Store 层查询方法显式调用 `ApplyShopFilter`、`ApplyEnterpriseFilter` 等 Helper 函数
2. 参考 `pkg/middleware/data_scope.go` 中的 Helper 函数用法

### Requirement: Skip Data Permission

**Reason**: 移除 GORM Callback 后，不再需要跳过机制。数据权限过滤由业务层显式控制。

**Migration**:
1. 删除所有 `SkipDataPermission(ctx)` 调用
2. 删除所有 `pkggorm.SkipDataPermission` 引用
3. 业务逻辑直接控制是否调用过滤函数

### Requirement: Callback Registration

**Reason**: 不再使用 GORM Callback 机制。数据权限范围在 Auth 中间件预计算，过滤在业务层显式调用。

**Migration**:
1. 移除 `RegisterDataPermissionCallback` 函数
2. 移除应用启动时的 Callback 注册调用
3. Auth 中间件配置 `ShopStore` 以支持预计算

## MODIFIED Requirements

### Requirement: Subordinate IDs Caching

系统 SHALL 缓存用户的下级店铺 ID 列表以提高查询性能。

#### Scenario: 缓存命中
- **WHEN** 获取用户下级店铺 ID 列表
- **AND** Redis 缓存存在
- **THEN** 直接返回缓存数据

#### Scenario: 缓存未命中
- **WHEN** 获取用户下级店铺 ID 列表
- **AND** Redis 缓存不存在
- **THEN** 执行递归查询获取下级店铺 ID
- **AND** 将结果缓存到 Redis（30 分钟过期）

#### Scenario: 请求级别复用
- **WHEN** 同一请求内多次需要下级店铺 ID 列表
- **THEN** 从 Context 中获取预计算的值
- **AND** 不重复查询 Redis 或数据库

## ADDED Requirements

### Requirement: Store 层显式数据权限过滤

系统 SHALL 在 Store 层查询方法中显式调用数据权限过滤函数。

#### Scenario: 有 shop_id 字段的表
- **WHEN** Store 执行列表查询
- **AND** 表包含 `shop_id` 字段
- **THEN** 显式调用 `ApplyShopFilter(ctx, query)`
- **AND** 代理用户只能查询 `shop_id IN (subordinateShopIDs)` 的数据

#### Scenario: 有 enterprise_id 字段的表
- **WHEN** Store 执行列表查询
- **AND** 表包含 `enterprise_id` 字段
- **AND** 当前用户为企业用户
- **THEN** 显式调用 `ApplyEnterpriseFilter(ctx, query)`
- **AND** 企业用户只能查询 `enterprise_id = ?` 的数据

#### Scenario: 有 owner_shop_id 字段的表
- **WHEN** Store 执行列表查询
- **AND** 表包含 `owner_shop_id` 字段（如 Enterprise 表）
- **THEN** 显式调用 `ApplyOwnerShopFilter(ctx, query)`
- **AND** 代理用户只能查询 `owner_shop_id IN (subordinateShopIDs)` 的数据

#### Scenario: NULL shop_id 不可见
- **WHEN** 代理用户查询有 `shop_id` 字段的表
- **AND** 记录的 `shop_id` 为 NULL（平台库存）
- **THEN** 该记录对代理用户不可见

#### Scenario: 平台用户/超管不过滤
- **WHEN** 平台用户或超级管理员执行查询
- **THEN** Helper 函数不添加任何过滤条件
- **AND** 可查询所有数据
