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

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

Status

Draft

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

Debug Log References

Completion Notes List

File List

QA Results

Results from QA Agent QA review of the completed story implementation