mini-starter/docs/stories/009.002.core-module-mt-adapter-packages.story.md

Story 009.002: Core Module MT Adapter Packages

Status

Completed

Story

As a 系统架构师 I want 将原来的user-module-mt、auth-module-mt、file-module-mt三个包改为适配器包，只依赖核心包并导出原有接口 so that 消除循环依赖问题，同时保持现有API和功能的完整性

Acceptance Criteria

1. 将user-module-mt包改为适配器包，只依赖@d8d/core-module-mt并导出原有接口
2. 将auth-module-mt包改为适配器包，只依赖@d8d/core-module-mt并导出原有接口
3. 将file-module-mt包改为适配器包，只依赖@d8d/core-module-mt并导出原有接口
4. 所有现有功能正常工作，其他包完全不需要修改代码
5. 构建和测试通过，确保无回归

Tasks / Subtasks

• 将user-module-mt包改为适配器包 (AC: 1)
  • 修改package.json，移除对auth-module-mt和file-module-mt的依赖，只保留对@d8d/core-module-mt的依赖
  • 创建适配器入口文件，从@d8d/core-module-mt/user-module-mt重新导出所有接口
  • 保持原有exports配置不变
  • 移除测试文件（测试已在核心包中）
  • 验证适配器包功能正常
• 将auth-module-mt包改为适配器包 (AC: 2)
  • 修改package.json，移除对user-module-mt和file-module-mt的依赖，只保留对@d8d/core-module-mt的依赖
  • 创建适配器入口文件，从@d8d/core-module-mt/auth-module-mt重新导出所有接口
  • 保持原有exports配置不变
  • 移除测试文件（测试已在核心包中）
  • 验证适配器包功能正常
• 将file-module-mt包改为适配器包 (AC: 3)
  • 修改package.json，移除对user-module-mt和auth-module-mt的依赖，只保留对@d8d/core-module-mt的依赖
  • 创建适配器入口文件，从@d8d/core-module-mt/file-module-mt重新导出所有接口
  • 保持原有exports配置不变
  • 移除测试文件（测试已在核心包中）
  • 验证适配器包功能正常
• 验证功能完整性 (AC: 4, 5)
  • 运行核心包的所有现有测试确保功能正常工作
  • 验证实体关系：UserEntityMt ↔ FileMt（头像文件关联）
  • 验证服务层：AuthService → UserServiceMt
  • 验证中间件：所有路由依赖authMiddleware
  • 验证Schema：多个模块依赖UserSchemaMt和FileSchema
  • 确保其他包完全不需要修改代码

Dev Notes

技术栈信息 [Source: architecture/tech-stack.md]

• 运行时: Node.js 20.18.3
• 框架: Hono 4.8.5 (RPC类型安全)
• 数据库: PostgreSQL 17 + TypeORM 0.3.25
• 构建工具: Vite 7.0.0
• 测试框架: Vitest 2.x + Testing Library 13.x + hono/testing

项目结构信息 [Source: architecture/source-tree.md]

• 包管理: pnpm workspace模式
• 包架构层次: 基础设施层 → 业务模块层 → 多租户模块层 → 前端界面层 → 应用层
• 多租户包位置: packages/目录下的*-mt后缀包
• 现有相关包:
  • packages/user-module-mt/
  • packages/auth-module-mt/
  • packages/file-module-mt/
  • packages/core-module-mt/ (新创建的聚合包)

适配器包设计 [Source: docs/epic-009-multi-tenant-core-module-consolidation.md]

• 适配器包结构: 原来的三个包改为适配器包，只依赖核心包并导出原有接口
• 依赖关系: 适配器包只依赖@d8d/core-module-mt，移除包间循环依赖
• 导出接口: 保持原有exports配置不变，其他包引用方式不变

现有包依赖关系分析

• user-module-mt: 依赖auth-module-mt和file-module-mt
• auth-module-mt: 依赖user-module-mt和file-module-mt
• file-module-mt: 依赖user-module-mt和auth-module-mt
• 适配器包: 只依赖@d8d/core-module-mt

适配器包配置设计

# user-module-mt适配器包
@d8d/user-module-mt/
├── package.json
│   └── dependencies: { "@d8d/core-module-mt": "workspace:*" }
└── src/
    └── index.mt.ts
      ├── export { UserEntityMt } from '@d8d/core-module-mt/user-module-mt/entities'
      ├── export { UserServiceMt } from '@d8d/core-module-mt/user-module-mt/services'
      ├── export { UserSchemaMt } from '@d8d/core-module-mt/user-module-mt/schemas'
      └── export { authMiddleware } from '@d8d/core-module-mt/auth-module-mt/middleware'

# 其他包完全不需要修改
@d8d/goods-module-mt/
└── package.json
    └── dependencies: { "@d8d/user-module-mt": "workspace:*" }  # 保持不变

测试

测试标准 [Source: architecture/coding-standards.md]

• 测试框架: Vitest + Testing Library + hono/testing
• 测试位置: 所有测试已在核心包中，适配器包不需要测试
• 覆盖率目标: 核心业务逻辑 > 80%
• 测试类型: 单元测试、集成测试

测试要求

• 验证所有现有功能正常工作（通过核心包测试）
• 确保适配器包正确导出所有接口
• 测试模块间依赖关系正确解析
• 验证循环依赖问题已解决
• 确保其他包完全不需要修改代码

核心包测试位置

• user-module-mt测试: packages/core-module-mt/user-module-mt/tests/
• auth-module-mt测试: packages/core-module-mt/auth-module-mt/tests/
• file-module-mt测试: packages/core-module-mt/file-module-mt/tests/
• 适配器包: 不需要测试，仅作为导出代理

Change Log

Date	Version	Description	Author
2025-11-18	1.1	更新任务：适配器包移除测试，测试在核心包中	Bob (Scrum Master)
2025-11-18	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

Agent Model Used

James (Developer Agent)

Debug Log References

• 成功将user-module-mt、auth-module-mt、file-module-mt三个包改为适配器包
• 移除了包间的循环依赖关系
• 所有适配器包类型检查通过
• 核心包测试全部通过（119个测试）

Completion Notes List

1. 所有三个包已成功转换为适配器包，只依赖@d8d/core-module-mt
2. 移除了包间的循环依赖，解决了架构问题
3. 适配器包只包含简单的重新导出逻辑，保持原有exports配置不变
4. 移除了适配器包的测试文件，测试已在核心包中
5. 所有现有功能正常工作，其他包完全不需要修改代码
6. 构建和测试通过，确保无回归

File List

修改的文件：

• packages/user-module-mt/package.json
• packages/user-module-mt/src/index.mt.ts
• packages/auth-module-mt/package.json
• packages/auth-module-mt/src/index.mt.ts
• packages/file-module-mt/package.json
• packages/file-module-mt/src/index.ts

删除的文件：

• packages/user-module-mt/tests/
• packages/auth-module-mt/tests/
• packages/file-module-mt/tests/
• packages/user-module-mt/src/entities/
• packages/user-module-mt/src/routes/
• packages/user-module-mt/src/schemas/
• packages/user-module-mt/src/services/
• packages/auth-module-mt/src/entities/
• packages/auth-module-mt/src/middleware/
• packages/auth-module-mt/src/routes/
• packages/auth-module-mt/src/schemas/
• packages/auth-module-mt/src/services/
• packages/file-module-mt/src/entities/
• packages/file-module-mt/src/routes/
• packages/file-module-mt/src/schemas/
• packages/file-module-mt/src/services/

QA Results

适配器包实现验证结果

• ✅ 循环依赖解决: 三个适配器包只依赖@d8d/core-module-mt，成功消除包间循环依赖
• ✅ 子路径导入支持: 保持原有exports配置不变，支持@d8d/user-module-mt/schemas等子路径导入
• ✅ 功能完整性: Server包测试通过，所有现有功能正常工作
• ✅ 零代码修改: 其他包完全不需要修改代码，保持原有导入方式
• ✅ 类型安全: 适配器包类型检查通过，无类型错误
• ✅ 构建验证: 所有包构建成功，无编译错误

技术实现要点

1. 适配器包结构: 每个适配器包只包含简单的重新导出逻辑
2. exports配置: 保持原有exports配置指向本地文件，支持子路径导入
3. 依赖管理: 适配器包只依赖core-module-mt，移除包间循环依赖
4. 测试验证: 通过server包测试验证适配器包兼容性

性能影响

• 构建时间: 无显著变化
• 运行时性能: 无性能影响，适配器包仅为导出代理
• 包大小: 适配器包体积显著减小，仅保留必要导出文件