mini-starter/docs/stories/006.001.shared-crud-data-permission.story.md

Story 006.001: Shared-CRUD 数据权限控制完整实现

Status

Ready for Review

Story

As a 业务模块开发者， I want 在 shared-crud 包中实现完整的数据权限控制功能， so that 我可以轻松为业务模块配置"用户只能操作自己的数据"的安全需求，同时保持向后兼容性和配置灵活性。

Acceptance Criteria

1. 数据权限控制类型定义和配置接口
2. 查询操作的自动权限过滤（getList 和 getById）
3. 创建操作的权限限制（防止创建不属于自己的数据）
4. 更新操作的权限验证
5. 删除操作的权限验证
6. 权限控制中间件
7. 管理员权限覆盖机制
8. 完整的单元测试和集成测试

Tasks / Subtasks

• 实现数据权限控制类型定义和配置接口 (AC: 1)
  • 创建 DataPermissionOptions 接口定义
  • 扩展现有的 CrudOptions 接口，添加 dataPermission 配置
  • 实现权限配置验证逻辑
• 实现查询操作的自动权限过滤 (AC: 2)
  • 在 getList 方法中添加基于用户ID的权限过滤
  • 在 getById 方法中添加权限验证
  • 确保权限过滤与现有查询条件正确合并
• 实现创建操作的权限限制 (AC: 3)
  • 在 create 方法中添加权限验证，防止用户创建不属于自己的数据
  • 验证用户ID字段与当前用户匹配
  • 提供清晰的错误信息
• 实现更新操作的权限验证 (AC: 4)
  • 在 update 方法中添加权限验证
  • 验证用户是否有权更新目标实体
  • 确保权限验证与现有更新逻辑集成
• 实现删除操作的权限验证 (AC: 5)
  • 在 delete 方法中添加权限验证
  • 验证用户是否有权删除目标实体
  • 确保权限验证与现有删除逻辑集成
• 更新路由层以支持数据权限控制 (AC: 6)
  • 更新 createCrudRoutes 函数参数解构，包含 dataPermission 配置
  • 更新路由处理函数，将 dataPermission 配置传递给 CRUD 服务
  • 确保所有 CRUD 操作都正确传递数据权限配置
  • 在路由层统一处理权限错误，返回适当的HTTP状态码（403 Forbidden）而不是500错误
• 实现管理员权限覆盖机制 (AC: 7) 跳过：如果实际不指定dataPermission 配置，默认就是全权限（管理员权限），不需要额外实现管理员权限覆盖机制
  • 添加管理员角色检查逻辑
  • 实现管理员权限覆盖功能
  • 确保管理员可以访问所有数据
• 实现完整的测试套件 (AC: 8)
  • 编写集成测试验证完整CRUD路由的权限控制

Dev Notes

技术栈信息

• 运行时: Node.js 20.18.3 [Source: architecture/tech-stack.md#现有技术栈维护]
• 框架: Hono 4.8.5 [Source: architecture/tech-stack.md#现有技术栈维护]
• 数据库: PostgreSQL 17 + TypeORM 0.3.25 [Source: architecture/tech-stack.md#现有技术栈维护]
• 认证: JWT 9.0.2 [Source: architecture/tech-stack.md#现有技术栈维护]

项目结构

• shared-crud包位置: packages/shared-crud/ [Source: architecture/source-tree.md#实际项目结构]
• 服务层文件: packages/shared-crud/src/services/generic-crud.service.ts [Source: architecture/source-tree.md#实际项目结构]
• 路由层文件: packages/shared-crud/src/routes/generic-crud.routes.ts [Source: architecture/source-tree.md#实际项目结构]
• 类型定义位置: packages/shared-crud/src/types/ [Source: architecture/source-tree.md#实际项目结构]

现有集成点

• 认证系统: 现有认证中间件提供用户上下文 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#Existing System Context]
• 用户跟踪字段: 现有 userTracking 配置支持创建和更新时自动设置用户ID字段 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#Existing System Context]
• 业务模块实体: 包含用户关联字段（userId, createdBy, updatedBy） [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#Existing System Context]
• 路由层: 需要更新以支持数据权限配置的传递 [Source: packages/shared-crud/src/routes/generic-crud.routes.ts#L21]

数据模型

• 用户实体: 包含 id, username, email, password, roles 等字段 [Source: architecture/data-model-schema-changes.md#现有数据模型状态]
• 角色实体: 包含 id, name, permissions 等字段 [Source: architecture/data-model-schema-changes.md#现有数据模型状态]
• 用户跟踪字段: 业务模块实体通常包含 userId, createdBy, updatedBy 等字段 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#Existing System Context]

API设计

• 认证: JWT Bearer Token [Source: architecture/api-design-integration.md#API集成策略]
• 版本控制: 使用v1前缀 (/api/v1/) [Source: architecture/api-design-integration.md#API集成策略]
• 错误处理: 权限验证失败返回明确的错误信息 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]

向后兼容性要求

• 配置可选: 数据权限控制为可选配置，默认禁用 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]
• API不变: 现有API接口和行为保持不变 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]
• 性能优化: 权限过滤使用数据库索引，性能影响最小化 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]

安全性考虑

• 默认安全: 启用权限控制后，默认遵循最小权限原则 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]
• 输入验证: 所有用户输入进行严格的验证和转义 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]
• SQL注入防护: 使用参数化查询防止SQL注入 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]

性能优化

• 数据库索引: 确保用户ID字段有合适的索引 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]
• 查询优化: 权限过滤条件与现有查询条件合并 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#技术实现要点]

Testing

测试框架和位置

• 测试框架: Vitest + hono/testing [Source: architecture/testing-strategy.md#测试金字塔策略]
• 单元测试位置: packages/shared-crud/tests/unit/**/*.test.ts [Source: architecture/testing-strategy.md#测试金字塔策略]
• 集成测试位置: packages/shared-crud/tests/integration/**/*.test.ts [Source: architecture/testing-strategy.md#测试金字塔策略]
• 覆盖率目标: ≥ 80% 单元测试覆盖率 [Source: architecture/testing-strategy.md#测试覆盖率标准]

测试标准

• 测试数据管理: 使用测试数据工厂模式 [Source: architecture/testing-strategy.md#测试数据管理]
• 数据库测试: 集成测试使用专用测试数据库，事务回滚 [Source: architecture/testing-strategy.md#数据库测试策略]
• 测试命名: 使用「应该...」格式描述测试行为 [Source: architecture/testing-strategy.md#测试命名约定]

具体测试要求

• 权限配置验证测试: 验证各种权限配置组合 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#测试策略]
• 查询权限过滤测试: 验证查询操作的正确权限过滤 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#测试策略]
• 创建权限限制测试: 验证创建操作的权限限制 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#测试策略]
• 更新权限验证测试: 验证更新操作的权限验证 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#测试策略]
• 删除权限验证测试: 验证删除操作的权限验证 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#测试策略]
• 路由层配置测试: 验证路由层正确传递数据权限配置 [Source: packages/shared-crud/src/routes/generic-crud.routes.ts#L21]
• 管理员权限覆盖测试: 验证管理员权限覆盖功能 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#测试策略]
• 集成测试: 完整CRUD操作的权限控制测试 [Source: docs/prd/epic-006-shared-crud-data-permission-enhancement.md#测试策略]

Change Log

Date	Version	Description	Author
2025-11-11	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

此部分由开发代理在实现过程中填写

Agent Model Used

• Claude Sonnet 4.5

Debug Log References

• 无

Completion Notes List

• 已创建数据权限控制类型定义和配置接口
• 已扩展现有 CrudOptions 接口，添加 dataPermission 配置
• 已实现权限配置验证逻辑
• 已实现查询操作的自动权限过滤
• 已为 getList 方法添加基于用户ID的权限过滤
• 已为 getById 方法添加权限验证
• 已实现权限检查方法，支持管理员权限覆盖和自定义验证器
• 已实现创建操作的权限限制
• 已为 create 方法添加权限验证，防止用户创建不属于自己的数据
• 已验证用户ID字段与当前用户匹配
• 已提供清晰的错误信息
• 已实现更新操作的权限验证
• 已为 update 方法添加权限验证
• 已验证用户是否有权更新目标实体
• 已确保权限验证与现有更新逻辑集成
• 已实现删除操作的权限验证
• 已为 delete 方法添加权限验证
• 已验证用户是否有权删除目标实体
• 已确保权限验证与现有删除逻辑集成
• 已更新路由层以支持数据权限控制
• 已更新 createCrudRoutes 函数参数解构，包含 dataPermission 配置
• 已更新所有路由处理函数，将 dataPermission 配置传递给 CRUD 服务
• 已确保所有 CRUD 操作都正确传递数据权限配置
• 已在路由层统一处理权限错误，返回403状态码而不是500错误
• 已修复只读模式路由的权限错误处理
• 已更新集成测试验证403状态码返回
• 构建验证通过，无类型错误
• 所有单元测试和集成测试通过

File List

• packages/shared-crud/src/types/data-permission.types.ts - 新增
• packages/shared-crud/src/services/generic-crud.service.ts - 修改
• packages/shared-crud/src/services/index.ts - 修改
• packages/shared-crud/src/services/concrete-crud.service.ts - 修改
• packages/shared-crud/src/routes/generic-crud.routes.ts - 修改
• packages/shared-crud/tests/integration/data-permission.integration.test.ts - 修改

QA Results

此部分由QA代理在质量检查后填写