mini-starter/docs/stories/008.001.server-multi-tenant-package-replacement.md

Story 008.001: Server多租户包替换和集成

Status

Ready for Review

Story

As a 系统管理员， I want 将server从单租户包改为多租户包， so that 系统支持多租户数据隔离和租户管理功能

Acceptance Criteria

1. 在server的index.ts文件中，将单租户包替换为多租户包（如@d8d/user-module → @d8d/user-module-mt）
2. 包括包导入、实体初始化和路由注册
3. 多租户模块包直接依赖多租户认证模块的认证中间件
4. 更新server包测试中的包导入路径
5. 验证路由配置正确，API接口可访问，通过集成测试验证

Tasks / Subtasks

• 检查多租户包是否存在，确认包结构和版本
• 修改packages/server/src/index.ts文件中的包导入
  • 将@d8d/user-module改为@d8d/user-module-mt
  • 将@d8d/auth-module改为@d8d/auth-module-mt
  • 将@d8d/file-module改为@d8d/file-module-mt
  • 将@d8d/geo-areas改为@d8d/geo-areas-mt
  • 将@d8d/mini-payment改为@d8d/mini-payment-mt
  • 将@d8d/advertisements-module改为@d8d/advertisements-module-mt
  • 将@d8d/delivery-address-module改为@d8d/delivery-address-module-mt
  • 将@d8d/goods-module改为@d8d/goods-module-mt
  • 将@d8d/merchant-module改为@d8d/merchant-module-mt
  • 将@d8d/orders-module改为@d8d/orders-module-mt
  • 将@d8d/supplier-module改为@d8d/supplier-module-mt
• 更新实体导入和初始化
  • 修改UserEntity、Role、File等实体的导入路径
  • 更新initializeDataSource中的实体列表
• 更新路由注册
  • 修改userRoutes、authRoutes、fileApiRoutes、roleRoutes的导入路径
  • 确保路由路径保持不变（/api/v1/...）
• 更新server包的package.json依赖
  • 将所有单租户包依赖更新为多租户包依赖
  • 确保依赖包名与代码导入一致
• 验证多租户认证中间件集成
  • 确认多租户认证模块包中已包含租户上下文管理
  • 验证认证中间件设置租户上下文：c.set('tenantId', user.tenantId)
• 更新server包测试
  • 修改packages/server/tests/integration/auth.integration.test.ts中的包导入
  • 修改packages/server/tests/integration/users.integration.test.ts中的包导入
  • 修改packages/server/tests/integration/files.integration.test.ts中的包导入
  • 更新测试中的服务导入路径
  • 确保测试数据包含租户上下文
• 运行server包集成测试
  • 运行server包的所有测试
  • 验证路由配置正确，API接口可访问
  • 确认多租户上下文管理正常工作

Dev Notes

项目结构信息

• Server入口文件: packages/server/src/index.ts
• 当前包导入: 第4-6行导入单租户包
  • @d8d/user-module
  • @d8d/auth-module
  • @d8d/file-module
• 实体导入: 第10-21行导入各模块实体
• 路由注册: 第125-154行注册API路由
• 多租户包架构: 基于Epic-007方案，通过复制单租户包创建多租户版本

技术栈信息

[Source: architecture/tech-stack.md#现有技术栈维护]

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

多租户架构信息

[Source: architecture/source-tree.md#多租户架构]

• 包复制策略: 基于Epic-007方案，通过复制单租户包创建多租户版本
• 租户隔离: 通过租户ID实现数据隔离，支持多租户部署
• 后端包: 10个多租户模块包，支持租户数据隔离
• 认证中间件: 多租户认证模块包中已实现租户上下文管理

关键发现

• 多租户模块包直接依赖多租户认证模块的认证中间件
• 认证中间件中已实现租户上下文管理：c.set('tenantId', user.tenantId)
• 无需额外添加租户中间件，多租户包已集成租户上下文管理
• 现有单租户系统完全不变，直接替换为多租户包

测试更新注意事项

• 测试包导入更新：所有server测试文件中的包导入需要相应更新
  • packages/server/tests/integration/auth.integration.test.ts：第8行@d8d/user-module → @d8d/user-module-mt，第10行@d8d/auth-module → @d8d/auth-module-mt
  • packages/server/tests/integration/users.integration.test.ts：需要更新用户模块包导入
  • packages/server/tests/integration/files.integration.test.ts：需要更新文件模块包导入
• 测试目的和范围：server测试主要验证路由配置和API接口集成，具体业务逻辑测试在各模块包内部完成
• 测试数据要求：多租户包需要租户上下文，测试数据可能需要包含租户ID
• 测试服务实例：测试中创建的服务实例需要来自多租户包
• 回归测试重点：验证替换后API接口功能正常，多租户上下文管理正常工作

项目结构注意事项

• 保持现有API接口路径不变
• 实体初始化逻辑保持不变
• 路由注册模式保持不变
• 确保向后兼容性，现有单租户功能不受影响

Testing

[Source: architecture/testing-strategy.md#测试金字塔策略]

测试标准

• 测试框架: Vitest
• 测试位置: packages/server/tests/
• 覆盖率目标: ≥ 80%

测试要求

• 集成测试: 验证路由配置正确和API接口可访问
• 回归测试: 确保多租户上下文管理正常工作
• 重点: server测试主要验证路由集成，具体业务逻辑测试在各模块包内部完成

测试执行

# 运行server包测试
cd packages/server && pnpm test

# 运行集成测试
cd packages/server && pnpm test:integration

# 生成覆盖率报告
cd packages/server && pnpm test:coverage

测试验证点

• 路由配置正确，API接口可访问
• 多租户包正确导入和初始化
• 租户上下文管理正常工作
• 测试包导入正确更新
• 测试数据包含租户上下文

Change Log

Date	Version	Description	Author
2025-11-18	1.1	添加测试更新任务和注意事项	Bob
2025-11-18	1.0	初始故事创建	Bob

Dev Agent Record

This section is populated by the development agent during implementation

Agent Model Used

James - Full Stack Developer

Debug Log References

• 多租户包替换验证：所有包导入已更新为多租户版本
• 测试验证：多租户上下文管理正常工作，显示"设置租户上下文: 1"和"从存储的租户上下文中获取租户ID: 1"
• API集成：路由配置正确，API接口可访问

Completion Notes List

1. 多租户包替换已完成，server包现在使用所有多租户模块包
2. 包导入、实体初始化、路由注册和依赖管理已全部更新
3. 多租户认证中间件集成正常，租户上下文管理功能正常工作
4. 测试文件中的包导入已全部更新为多租户版本
5. 集成测试验证了多租户上下文管理和API接口功能

File List

• packages/server/src/index.ts - 更新包导入、实体导入和路由注册
• packages/server/package.json - 更新依赖包为多租户版本
• packages/server/tests/integration/auth.integration.test.ts - 更新包导入路径
• packages/server/tests/integration/users.integration.test.ts - 更新包导入路径
• packages/server/tests/integration/files.integration.test.ts - 更新包导入路径

QA Results

Results from QA Agent QA review of the completed story implementation