refactor: 数据权限过滤从 GORM Callback 改为 Store 层显式调用

- 移除 RegisterDataPermissionCallback 和 SkipDataPermission 机制
- 在 Auth 中间件预计算 SubordinateShopIDs 并注入 Context
- 新增 ApplyShopFilter/ApplyEnterpriseFilter/ApplyOwnerShopFilter 等 Helper 函数
- 所有 Store 层查询方法显式调用数据权限过滤函数
- 权限检查函数 CanManageShop/CanManageEnterprise 改为从 Context 获取数据

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

openspec/specs/data-permission/spec.md

@@ -1,77 +1,60 @@
 # data-permission Specification
 
 ## Purpose
-TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.
+
+数据权限过滤机制，通过业务层显式调用实现数据隔离。
+
 ## Requirements
-### Requirement: GORM Callback Data Permission
-
-系统 SHALL 使用 GORM Callback 机制自动为所有查询添加数据权限过滤。
-
-#### Scenario: 自动应用权限过滤
-- **WHEN** 执行 GORM 查询
-- **AND** Context 包含用户信息
-- **AND** 表包含 owner_id 字段
-- **THEN** 自动添加 WHERE owner_id IN (subordinateIDs) 条件
-
-#### Scenario: Root 用户跳过过滤
-- **WHEN** 当前用户是 Root 用户
-- **THEN** 不添加任何数据权限过滤条件
-- **AND** 可查询所有数据
-
-#### Scenario: 无 owner_id 字段的表
-- **WHEN** 表不包含 owner_id 字段
-- **THEN** 不添加数据权限过滤条件
-
-#### Scenario: 授权记录表特殊处理
-- **WHEN** 查询 `tb_enterprise_card_authorization` 表
-- **AND** 当前用户是代理用户
-- **THEN** 自动添加 WHERE enterprise_id IN (SELECT id FROM tb_enterprise WHERE owner_shop_id = 当前店铺ID) 条件
-- **AND** 不包含下级店铺的数据
-
-#### Scenario: 平台用户查询授权记录
-- **WHEN** 查询 `tb_enterprise_card_authorization` 表
-- **AND** 当前用户是平台用户或超级管理员
-- **THEN** 不添加数据权限过滤条件
-- **AND** 可查询所有授权记录
-
-### Requirement: Skip Data Permission
-
-系统 SHALL 支持通过 Context 绕过数据权限过滤。
-
-#### Scenario: 显式跳过权限过滤
-- **WHEN** 调用 SkipDataPermission(ctx) 获取新 Context
-- **AND** 使用该 Context 执行 GORM 查询
-- **THEN** 不添加任何数据权限过滤条件
-
-#### Scenario: 内部操作跳过过滤
-- **WHEN** 执行内部同步、批量操作或管理员操作
-- **THEN** 应使用 SkipDataPermission 绕过过滤
 
 ### Requirement: Subordinate IDs Caching
 
-系统 SHALL 缓存用户的下级 ID 列表以提高查询性能。
+系统 SHALL 缓存用户的下级店铺 ID 列表以提高查询性能。
 
 #### Scenario: 缓存命中
-- **WHEN** 获取用户下级 ID 列表
+- **WHEN** 获取用户下级店铺 ID 列表
 - **AND** Redis 缓存存在
 - **THEN** 直接返回缓存数据
 
 #### Scenario: 缓存未命中
-- **WHEN** 获取用户下级 ID 列表
+- **WHEN** 获取用户下级店铺 ID 列表
 - **AND** Redis 缓存不存在
-- **THEN** 执行递归 CTE 查询获取下级 ID
+- **THEN** 执行递归查询获取下级店铺 ID
 - **AND** 将结果缓存到 Redis（30 分钟过期）
 
-### Requirement: Callback Registration
+#### Scenario: 请求级别复用
+- **WHEN** 同一请求内多次需要下级店铺 ID 列表
+- **THEN** 从 Context 中获取预计算的值
+- **AND** 不重复查询 Redis 或数据库
 
-系统 SHALL 在应用启动时注册 GORM 数据权限 Callback。
+### Requirement: Store 层显式数据权限过滤
 
-#### Scenario: 注册 Callback
-- **WHEN** 调用 RegisterDataPermissionCallback(db, accountStore)
-- **THEN** 注册 Query Before Callback
-- **AND** Callback 名称为 "data_permission"
+系统 SHALL 在 Store 层查询方法中显式调用数据权限过滤函数。
 
-#### Scenario: AccountStore 依赖
-- **WHEN** 注册 Callback 时
-- **THEN** 需要传入 AccountStore 实例用于获取下级 ID
+#### 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** 可查询所有数据

openspec/specs/data-scope-middleware/spec.md

@@ -0,0 +1,130 @@
+# data-scope-middleware Specification
+
+## Purpose
+
+数据权限范围中间件，负责在请求入口预计算用户的数据访问范围并注入 Context，供业务层显式使用。
+
+## Requirements
+
+### Requirement: UserContextInfo 扩展
+
+系统 SHALL 扩展 `UserContextInfo` 结构体以包含预计算的数据权限范围。
+
+#### Scenario: 代理用户包含下级店铺 ID 列表
+- **WHEN** 代理用户登录成功
+- **AND** 用户有关联的店铺 ID
+- **THEN** `UserContextInfo.SubordinateShopIDs` 包含自己店铺及所有下级店铺的 ID 列表
+
+#### Scenario: 平台用户/超管不限制
+- **WHEN** 平台用户或超级管理员登录成功
+- **THEN** `UserContextInfo.SubordinateShopIDs` 为 nil
+- **AND** nil 表示不受数据权限限制
+
+#### Scenario: 企业用户使用 EnterpriseID
+- **WHEN** 企业用户登录成功
+- **THEN** `UserContextInfo.EnterpriseID` 包含用户所属企业 ID
+- **AND** `UserContextInfo.SubordinateShopIDs` 为 nil
+
+### Requirement: Auth 中间件预计算
+
+系统 SHALL 在 Auth 中间件中预计算用户的数据访问范围。
+
+#### Scenario: 代理用户预计算下级店铺
+- **WHEN** Auth 中间件验证 token 成功
+- **AND** 用户类型为代理用户
+- **AND** 用户有关联的店铺 ID
+- **THEN** 调用 `GetSubordinateShopIDs` 获取下级店铺 ID 列表
+- **AND** 将结果设置到 `UserContextInfo.SubordinateShopIDs`
+
+#### Scenario: 获取下级店铺失败降级处理
+- **WHEN** 调用 `GetSubordinateShopIDs` 失败
+- **THEN** `SubordinateShopIDs` 降级为只包含用户自己的店铺 ID
+- **AND** 记录 Error 日志
+
+#### Scenario: 非代理用户跳过预计算
+- **WHEN** Auth 中间件验证 token 成功
+- **AND** 用户类型不是代理用户
+- **THEN** 不调用 `GetSubordinateShopIDs`
+- **AND** `SubordinateShopIDs` 保持为 nil
+
+### Requirement: Context 数据获取函数
+
+系统 SHALL 提供从 Context 获取数据权限范围的函数。
+
+#### Scenario: 获取下级店铺 ID 列表
+- **WHEN** 调用 `GetSubordinateShopIDs(ctx)`
+- **AND** Context 包含 `SubordinateShopIDs`
+- **THEN** 返回下级店铺 ID 列表
+
+#### Scenario: 获取空列表表示不限制
+- **WHEN** 调用 `GetSubordinateShopIDs(ctx)`
+- **AND** Context 中 `SubordinateShopIDs` 为 nil
+- **THEN** 返回 nil
+- **AND** 调用方应理解 nil 表示不受数据权限限制
+
+### Requirement: 查询过滤 Helper 函数
+
+系统 SHALL 提供查询过滤 Helper 函数，供 Store 层显式调用。
+
+#### Scenario: ApplyShopFilter 过滤店铺数据
+- **WHEN** 调用 `ApplyShopFilter(ctx, query)`
+- **AND** `SubordinateShopIDs` 不为 nil
+- **THEN** 返回添加了 `WHERE shop_id IN (?)` 条件的查询
+- **AND** 参数为 `SubordinateShopIDs`
+
+#### Scenario: ApplyShopFilter 不限制时不添加条件
+- **WHEN** 调用 `ApplyShopFilter(ctx, query)`
+- **AND** `SubordinateShopIDs` 为 nil
+- **THEN** 返回原查询，不添加任何条件
+
+#### Scenario: ApplyEnterpriseFilter 过滤企业数据
+- **WHEN** 调用 `ApplyEnterpriseFilter(ctx, query)`
+- **AND** 用户类型为企业用户
+- **AND** `EnterpriseID` 大于 0
+- **THEN** 返回添加了 `WHERE enterprise_id = ?` 条件的查询
+
+#### Scenario: ApplyEnterpriseFilter 非企业用户不添加条件
+- **WHEN** 调用 `ApplyEnterpriseFilter(ctx, query)`
+- **AND** 用户类型不是企业用户
+- **THEN** 返回原查询，不添加任何条件
+
+#### Scenario: ApplyOwnerShopFilter 过滤归属店铺数据
+- **WHEN** 调用 `ApplyOwnerShopFilter(ctx, query)`
+- **AND** `SubordinateShopIDs` 不为 nil
+- **THEN** 返回添加了 `WHERE owner_shop_id IN (?)` 条件的查询
+
+### Requirement: 权限检查函数改造
+
+系统 SHALL 改造权限检查函数，从 Context 获取数据而非传入 Store。
+
+#### Scenario: CanManageShop 从 Context 获取数据
+- **WHEN** 调用 `CanManageShop(ctx, targetShopID)`
+- **AND** 用户类型为代理用户
+- **THEN** 从 Context 获取 `SubordinateShopIDs`
+- **AND** 检查 `targetShopID` 是否在列表中
+
+#### Scenario: CanManageShop 平台用户自动通过
+- **WHEN** 调用 `CanManageShop(ctx, targetShopID)`
+- **AND** `SubordinateShopIDs` 为 nil
+- **THEN** 返回成功（不受限制）
+
+#### Scenario: CanManageEnterprise 从 Context 获取数据
+- **WHEN** 调用 `CanManageEnterprise(ctx, targetEnterpriseID)`
+- **AND** 用户类型为代理用户
+- **THEN** 从 Context 获取 `SubordinateShopIDs`
+- **AND** 查询目标企业的 `owner_shop_id`
+- **AND** 检查 `owner_shop_id` 是否在列表中
+
+### Requirement: AuthConfig 扩展
+
+系统 SHALL 扩展 `AuthConfig` 以支持传入 ShopStore。
+
+#### Scenario: AuthConfig 包含 ShopStore
+- **WHEN** 初始化 Auth 中间件
+- **THEN** `AuthConfig` 可选包含 `ShopStore ShopStoreInterface`
+- **AND** 用于调用 `GetSubordinateShopIDs`
+
+#### Scenario: ShopStore 未配置时跳过预计算
+- **WHEN** `AuthConfig.ShopStore` 为 nil
+- **THEN** 不预计算 `SubordinateShopIDs`
+- **AND** 所有用户的 `SubordinateShopIDs` 为 nil