📝 docs(epic): add epic document for multi-tenant core module consolidation

- document the goal of solving circular dependency issues among user, auth and file modules
- describe existing system context including current multi-tenant package structure
- outline enhancement details for merging three modules into @d8d/core-module-mt
- define stories, compatibility requirements and risk mitigation strategies
- include validation checklist and story manager handoff instructions

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

@@ -0,0 +1,177 @@
+# 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包并迁移用户、认证、文件管理功能到内部模块目录
+2. **Story 2:** 将原来的三个包改为适配器包，只依赖核心包并导出原有接口
+
+## Compatibility Requirements
+
+- [x] 现有API保持不变
+- [x] 数据库Schema保持向后兼容
+- [x] UI模式遵循现有模式
+- [x] 性能影响最小
+
+## Risk Mitigation
+
+- **主要风险**：迁移过程中可能破坏现有功能
+- **缓解措施**：
+  - 分阶段迁移，保持向后兼容
+  - 充分测试确保功能完整性
+  - 保持现有包在迁移期间可用
+- **回滚计划**：如果出现问题，可以回退到使用独立的三个包
+
+## Definition of Done
+
+- [ ] 所有故事完成且验收标准满足
+- [ ] 通过测试验证现有功能
+- [ ] 集成点正常工作
+- [ ] 文档适当更新
+- [ ] 现有功能无回归
+
+## 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应在保持系统完整性的同时交付解决循环依赖问题的目标。"