# 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

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

## Risk Mitigation

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

## Definition of Done

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

## Validation Checklist

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

### Risk Assessment
- [x] 对现有系统风险低
- [x] 回滚计划可行
- [x] 测试方法覆盖现有功能
- [x] 团队对集成点有足够了解

### Completeness Check
- [x] Epic目标清晰可实现
- [x] 故事范围适当
- [x] 成功标准可衡量
- [x] 依赖关系已识别

---

**Story Manager Handoff:**

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

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

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