mini-starter/docs/epic-009-multi-tenant-core-module-consolidation.md

Epic-009: 多租户核心模块整合 - Brownfield Enhancement

Epic Goal

解决多租户架构中user-module-mt、auth-module-mt、file-module-mt三个包的循环依赖问题，通过合并为单一@d8d/core-module-mt包，在包内保持三个模块的独立目录结构，同时消除循环依赖。

Epic Description

Existing System Context

• 当前相关功能：基于Epic-007的多租户包复制方案，已创建10个多租户模块包和10个多租户管理界面包
• 技术栈：TypeScript + Hono + TypeORM + pnpm workspace + PostgreSQL + MinIO
• 集成点：
  • 实体关系：UserEntityMt ↔ FileMt（头像文件关联）
  • 服务层：AuthService → UserServiceMt
  • 中间件：所有路由依赖authMiddleware
  • Schema：多个模块依赖UserSchemaMt和FileSchema

Enhancement Details

• 新增/变更内容：将user-module-mt、auth-module-mt、file-module-mt合并为单一@d8d/core-module-mt包，在包内保持三个模块的独立目录结构
• 集成方式：
  • 创建@d8d/core-module-mt包，包含所有功能
  • 原来的三个包改为适配器包，只依赖核心包并导出原有接口
  • 其他包完全不需要修改，只需更新依赖版本

• 合并后包结构：

  @d8d/core-module-mt/
  ├── src/
  │   ├── modules/                # 模块层
  │   │   ├── user/               # 用户模块（原user-module-mt）
  │   │   │   ├── entities/
  │   │   │   │   ├── user.entity.mt.ts
  │   │   │   │   ├── role.entity.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   ├── services/
  │   │   │   │   ├── user.service.mt.ts
  │   │   │   │   ├── role.service.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   ├── schemas/
  │   │   │   │   ├── user.schema.mt.ts
  │   │   │   │   ├── role.schema.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   ├── routes/
  │   │   │   │   ├── user.routes.mt.ts
  │   │   │   │   ├── role.routes.mt.ts
  │   │   │   │   ├── custom.routes.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   └── index.ts
  │   │   ├── auth/               # 认证模块（原auth-module-mt）
  │   │   │   ├── services/
  │   │   │   │   ├── auth.service.mt.ts
  │   │   │   │   ├── mini-auth.service.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   ├── schemas/
  │   │   │   │   ├── auth.schema.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   ├── routes/
  │   │   │   │   ├── login.route.mt.ts
  │   │   │   │   ├── register.route.mt.ts
  │   │   │   │   ├── mini-login.route.mt.ts
  │   │   │   │   └── ...
  │   │   │   ├── middleware/
  │   │   │   │   ├── auth.middleware.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   └── index.ts
  │   │   ├── file/               # 文件模块（原file-module-mt）
  │   │   │   ├── entities/
  │   │   │   │   ├── file.entity.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   ├── services/
  │   │   │   │   ├── file.service.mt.ts
  │   │   │   │   ├── minio.service.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   ├── schemas/
  │   │   │   │   ├── file.schema.mt.ts
  │   │   │   │   └── index.ts
  │   │   │   ├── routes/
  │   │   │   │   ├── upload-policy/
  │   │   │   │   ├── multipart-policy/
  │   │   │   │   ├── [id]/
  │   │   │   │   └── index.ts
  │   │   │   └── index.ts
  │   │   └── index.ts
  │   ├── shared/                 # 共享层
  │   │   ├── middleware/
  │   │   │   ├── auth.middleware.mt.ts
  │   │   │   └── index.ts
  │   │   └── index.ts
  │   └── index.ts               # 包入口
  

• 适配器包设计：

  # 原来的user-module-mt包（现在作为适配器）
  @d8d/user-module-mt/
  ├── package.json
  │   └── dependencies: { "@d8d/core-module-mt": "workspace:*" }
  └── src/
    └── index.ts
      ├── export { UserEntityMt } from '@d8d/core-module-mt/modules/user/entities'
      ├── export { UserServiceMt } from '@d8d/core-module-mt/modules/user/services'
      ├── export { UserSchemaMt } from '@d8d/core-module-mt/modules/user/schemas'
      └── export { authMiddleware } from '@d8d/core-module-mt/shared/middleware'
  
  # 其他包完全不需要修改
  @d8d/goods-module-mt/
  └── package.json
    └── dependencies: { "@d8d/user-module-mt": "workspace:*" }  # 保持不变
  

• 成功标准：

  • 消除循环依赖警告
  • 所有现有功能正常工作
  • 构建和测试通过
  • 其他包完全不需要修改代码

Stories

1. Story 1: 创建@d8d/core-module-mt包并迁移用户、认证、文件管理功能到内部模块目录 - ✅ Completed
2. Story 2: 将原来的三个包改为适配器包，只依赖核心包并导出原有接口 - ✅ Completed

Compatibility Requirements

• 现有API保持不变
• 数据库Schema保持向后兼容
• UI模式遵循现有模式
• 性能影响最小

Risk Mitigation

• 主要风险：迁移过程中可能破坏现有功能
• 缓解措施：
  • 分阶段迁移，保持向后兼容
  • 充分测试确保功能完整性
  • 保持现有包在迁移期间可用
• 回滚计划：如果出现问题，可以回退到使用独立的三个包

Definition of Done

• Story 1完成且验收标准满足
• 通过测试验证现有功能（119个测试全部通过）
• 集成点正常工作
• 文档适当更新
• 现有功能无回归

Validation Checklist

Scope Validation

• Epic可在1-3个故事内完成
• 不需要架构文档
• 增强遵循现有模式
• 集成复杂度可控

Risk Assessment

• 对现有系统风险低
• 回滚计划可行
• 测试方法覆盖现有功能
• 团队对集成点有足够了解

Completeness Check

• Epic目标清晰可实现
• 故事范围适当
• 成功标准可衡量
• 依赖关系已识别

---

Story Manager Handoff:

"请为这个棕地epic开发详细的用户故事。关键考虑：

• 这是对运行TypeScript + Hono + TypeORM + pnpm workspace的现有系统的增强
• 集成点：实体关系、服务层依赖、中间件依赖、Schema依赖
• 要遵循的现有模式：多租户包架构、模块化设计
• 关键兼容性要求：保持API不变、数据库Schema兼容
• 每个故事必须包含验证现有功能保持完整的验证

该epic应在保持系统完整性的同时交付解决循环依赖问题的目标。"