mini-starter/docs/stories/007.004.auth-module-multi-tenant-replication.md

Story 007.004: 认证模块多租户复制和租户支持

Status

Draft

Story

As a 系统管理员， I want 复制认证模块为多租户版本并修改认证中间件逻辑集成租户上下文管理， so that 认证系统能够支持多租户场景，同时保持单租户版本完全可用。

Acceptance Criteria

1. 成功复制 @d8d/auth-module 为 @d8d/auth-module-mt
2. 修改认证中间件逻辑，集成租户上下文管理（中间件名字保持不变）
3. 在认证逻辑中添加租户支持
4. 验证多租户认证功能
5. 保持单租户版本完全可用

Tasks / Subtasks

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

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

• [ ] 更新多租户认证中间件 (AC: 2)

  • 重命名认证中间件文件为多租户版本
  • 修改认证中间件逻辑集成租户上下文管理
  • 保持中间件名字 authMiddleware 不变
  • 从用户信息中提取租户ID并设置租户上下文

• [ ] 更新多租户认证服务 (AC: 3)

  • 重命名认证服务文件为多租户版本
  • 更新认证服务支持租户过滤
  • 更新用户服务依赖为多租户版本
  • 确保所有认证操作支持租户隔离

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

  • 更新认证路由使用多租户实体和服务
  • 保持API接口与单租户版本一致
  • 更新路由配置支持租户ID提取

• [ ] 实现租户认证隔离测试 (AC: 4)

  • 编写租户认证隔离集成测试
  • 编写跨租户认证安全测试
  • 验证租户认证功能正确性

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

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

Dev Notes

技术栈信息

[Source: architecture/tech-stack.md]

• 运行时: Node.js 20.18.3
• 框架: Hono 4.8.5 (Web框架和API路由)
• 数据库: PostgreSQL 17 + TypeORM 0.3.25
• 认证: JWT 9.0.2 (Bearer Token)

编码标准

[Source: architecture/coding-standards.md]

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

项目结构

• 包位置: packages/auth-module-mt/
• 中间件位置: packages/auth-module-mt/src/middleware/
• 服务位置: packages/auth-module-mt/src/services/
• 路由位置: packages/auth-module-mt/src/routes/
• Schema位置: packages/auth-module-mt/src/schemas/

多租户架构要求

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

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

认证模块特性

[Source: packages/auth-module/src/middleware/auth.middleware.ts]

• 认证中间件: authMiddleware 处理Bearer Token认证
• 用户验证: 通过UserService验证用户存在性
• 上下文设置: 设置用户上下文到Hono Context
• 错误处理: 统一的认证错误响应

多租户认证策略

• 租户上下文: 从用户信息中提取租户ID
• 中间件逻辑: 保持中间件名字不变，内部逻辑支持租户
• 认证隔离: 租户间用户认证完全隔离
• 用户关联: 用户实体必须包含租户ID字段

测试要求

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

依赖关系

• 必需依赖: @d8d/user-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]

• 当前状态: ✅ 已完成增强，支持完整的租户隔离功能
• 配置选项:
  • tenantOptions.enabled: 启用/禁用租户隔离
  • tenantOptions.tenantIdField: 租户ID字段名（默认 'tenantId'）
  • tenantOptions.autoExtractFromContext: 自动从上下文提取租户ID

数据库变更

• 新表: 认证模块本身不创建新表，依赖用户模块多租户表
• 索引: 依赖用户模块的租户ID索引
• 迁移: 使用独立迁移文件，不影响现有表

Testing

测试标准

[Source: architecture/testing-strategy.md]

• 测试架构: 模块化包测试架构，每个包独立测试
• 测试类型: 单元测试 + 集成测试，验证模块功能
• 测试位置: packages/auth-module-mt/tests/integration/
• 测试框架: Vitest + hono/testing + shared-test-util

认证模块测试要求

• 认证流程测试: 验证登录、注册、token验证等认证流程
• 租户隔离测试: 验证不同租户用户的认证隔离
• 安全测试: 验证跨租户访问的安全性
• 集成测试: 验证认证模块与其他模块的集成

测试数据工厂

• 使用 @d8d/shared-test-util 的测试数据库工具
• 设置测试数据库钩子：setupIntegrationDatabaseHooksWithEntities([UserEntityMt])
• 创建多租户测试用户数据

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

⏳ 质量保证验证待执行