mini-starter/docs/stories/007.002.user-module-multi-tenant-replication.md

Story 007.002: 用户模块多租户复制和租户支持

Status

Draft

Story

As a 系统管理员， I want 复制用户模块为多租户版本并添加租户ID字段支持， so that 用户数据可以实现租户隔离，同时保持单租户版本完全可用。

Acceptance Criteria

1. 成功复制 @d8d/user-module 为 @d8d/user-module-mt
2. 在用户实体中添加租户ID字段，表名为 users_mt
3. 在角色实体中添加租户ID字段，表名为 roles_mt
4. 所有用户CRUD操作支持租户过滤
5. 租户数据隔离验证通过
6. 单租户版本功能完全保留且不受影响
7. API集成测试通过
8. 性能基准测试无明显下降

Tasks / Subtasks

• [x] 复制用户模块为多租户版本 (AC: 1)

  • 复制 packages/user-module 为 packages/user-module-mt
  • 更新包配置为 @d8d/user-module-mt
  • 添加多租户模块依赖：@d8d/file-module-mt 和 @d8d/auth-module-mt

• [x] 增强共享CRUD包支持租户隔离 (AC: 4) ✅ 已完成

  • 修改共享CRUD包，支持从认证中间件自动提取租户ID
  • 添加租户隔离配置选项到CRUD路由
  • 更新CRUD服务支持租户过滤
  • 更新共享CRUD包集成测试验证租户隔离功能
  • 创建租户隔离集成测试文件 packages/shared-crud/tests/integration/tenant-isolation.integration.test.ts
  • 所有11个租户隔离测试通过，验证了列表查询、创建、获取详情、更新、删除操作的租户隔离功能

• [ ] 更新多租户用户实体 (AC: 2)

  • 创建 UserEntityMt 实体，表名为 users_mt
  • 添加 tenantId 字段
  • 更新文件关联为 FileMt 实体
  • 保持其他字段与单租户版本一致

• [ ] 更新多租户角色实体 (AC: 3)

  • 创建 RoleMt 实体，表名为 roles_mt
  • 添加 tenantId 字段
  • 保持其他字段与单租户版本一致

• [ ] 更新多租户用户服务 (AC: 4)

  • 创建 UserServiceMt 服务
  • 所有查询操作自动添加租户过滤
  • 创建操作自动设置租户ID
  • 更新文件关联查询

• [ ] 更新多租户路由配置 (AC: 4)

  • 更新用户路由使用多租户实体和服务
  • 更新角色路由使用多租户实体和服务
  • 保持API接口与单租户版本一致

• [ ] 更新Schema定义 (AC: 4)

  • 创建多租户用户Schema UserSchemaMt
  • 创建多租户角色Schema RoleSchemaMt
  • 添加租户ID字段定义

• [ ] 实现租户数据隔离API测试 (AC: 5)

  • 编写租户数据隔离集成测试
  • 编写跨租户数据访问安全测试
  • 验证租户过滤功能正确性

• [ ] 验证单租户系统完整性 (AC: 6)

  • 运行单租户用户模块回归测试
  • 验证单租户API接口不受影响
  • 确认单租户数据库表结构不变

• [ ] 执行性能基准测试 (AC: 8)

  • 运行多租户用户模块性能测试
  • 比较单租户与多租户性能差异
  • 确保性能影响小于5%

Dev Notes

技术栈信息

[Source: architecture/tech-stack.md]

• 运行时: Node.js 20.18.3
• 框架: Hono 4.8.5 (Web框架和API路由)
• 数据库: PostgreSQL 17 + TypeORM 0.3.25
• 包管理: pnpm workspace

编码标准

[Source: architecture/coding-standards.md]

• 代码风格: TypeScript严格模式
• 测试框架: Vitest + hono/testing + shared-test-util
• 测试位置: packages/user-module-mt/tests/integration/
• 测试重点: API集成测试、租户数据隔离验证

项目结构

[Source: architecture/source-tree.md]

• 包位置: packages/user-module-mt/
• 实体位置: packages/user-module-mt/src/entities/
• 服务位置: packages/user-module-mt/src/services/
• 路由位置: packages/user-module-mt/src/routes/
• Schema位置: packages/user-module-mt/src/schemas/

多租户架构要求

[Source: docs/prd/epic-007-multi-tenant-package-replication.md]

• 包命名: 使用 -mt 后缀区分多租户版本
• 表命名: 使用 _mt 后缀避免冲突
• 租户ID: 所有实体添加 tenantId 字段
• 数据隔离: 所有查询自动添加租户过滤
• 依赖关系: 多租户模块间正常依赖

文件关联

[Source: packages/user-module/src/entities/user.entity.ts]

• 用户实体与文件实体关联：avatarFileId 和 avatarFile
• 多租户版本需要关联 FileMt 实体
• 保持关联关系与单租户版本一致

测试要求

[Source: architecture/testing-strategy.md]

• 集成测试: packages/user-module-mt/tests/integration/**/*.test.ts
• 测试框架: Vitest + shared-test-util
• 测试重点: API功能验证、租户数据隔离、跨租户安全

依赖关系

• 必需依赖: @d8d/file-module-mt, @d8d/auth-module-mt
• 共享依赖: @d8d/shared-crud, @d8d/shared-types, @d8d/shared-utils
• 测试依赖: @d8d/shared-test-util

共享CRUD包租户隔离支持

[Source: packages/shared-crud/src/routes/generic-crud.routes.ts]

• 当前状态: ✅ 已完成增强，支持完整的租户隔离功能
• 实现功能:
  • 认证中间件设置租户ID到Hono上下文
  • CRUD路由自动从认证中间件提取租户ID
  • CRUD服务支持租户过滤（列表查询、创建、获取详情、更新、删除）
  • 完整的租户隔离集成测试验证
• 配置选项:
  • tenantOptions.enabled: 启用/禁用租户隔离
  • tenantOptions.tenantIdField: 租户ID字段名（默认 'tenantId'）
  • tenantOptions.autoExtractFromContext: 自动从上下文提取租户ID
• 测试验证: 11个集成测试全部通过，验证了所有CRUD操作的租户隔离

数据库变更

• 新表: users_mt, roles_mt
• 索引: 为 tenantId 字段创建索引
• 迁移: 使用独立迁移文件，不影响现有表

Change Log

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

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results