mini-starter/docs/prd/epic-006-core-module-creation.md

Epic-006: Core Module 创建 - 从 core-module-mt 复制创建 core-module

Epic Goal

将现有的 packages/core-module-mt 复制为 packages/core-module，创建一个核心模块聚合包，用于统一导出和管理核心业务模块（用户、认证、文件、系统配置等）。复制后需要更新 package.json 和相关配置，移除 "-mt" 后缀，使其成为标准的非多租户版本。

Epic Description

Existing System Context

Current relevant functionality:

• 已存在 packages/core-module-mt 多租户版本的核心模块聚合包
• 包含 user-module-mt、auth-module-mt、file-module-mt、system-config-module-mt 四个模块
• 每个模块作为独立子目录存在，提供统一的导出接口
• 使用 TypeORM + PostgreSQL 作为数据访问层
• 采用 Hono 框架构建 RESTful API
• 已有 pnpm workspace 管理多包依赖关系

core-module-mt 当前结构:

packages/core-module-mt/
├── package.json              # 包配置，名称为 @d8d/core-module-mt
├── tsconfig.json            # TypeScript 配置
├── vitest.config.ts         # 测试配置
├── user-module-mt/          # 用户管理模块（多租户版本）
├── auth-module-mt/          # 认证管理模块（多租户版本）
├── file-module-mt/          # 文件管理模块（多租户版本）
└── system-config-module-mt/ # 系统配置模块（多租户版本）

Technology stack:

• Backend: Node.js, TypeScript, Hono, TypeORM, PostgreSQL
• Frontend: React, Taro, TanStack Query
• Authentication: JWT, Redis session management
• Package Management: pnpm workspace
• Testing: Vitest

Integration points:

• 需要创建非多租户版本的 core-module
• 需要更新 package.json 中的名称和导出配置
• 需要更新模块目录名称，移除 "-mt" 后缀
• 需要更新导出路径和类型定义

Enhancement Details

What's being added/changed:

• 复制 packages/core-module-mt 为 packages/core-module
• 更新 package.json：将名称从 @d8d/core-module-mt 改为 @d8d/core-module
• 更新 package.json 中的导出配置：将所有 -mt 后缀移除
• 重命名模块目录：将 user-module-mt 改为 user-module 等
• 更新导出路径：确保类型定义和导入路径正确
• 保持现有功能不变，仅进行名称和路径调整

Package 架构设计 (复制后):

packages/
├── core-module/               # 核心模块 (新增，非多租户版本)
│   ├── package.json          # 更新名称和导出配置
│   ├── tsconfig.json         # TypeScript 配置
│   ├── vitest.config.ts      # 测试配置
│   ├── user-module/          # 用户管理模块（重命名）
│   ├── auth-module/          # 认证管理模块（重命名）
│   ├── file-module/          # 文件管理模块（重命名）
│   └── system-config-module/ # 系统配置模块（重命名）
├── server/                    # 核心服务器 (现有)
├── user-module/               # 独立的用户管理模块 (现有)
├── auth-module/               # 独立的认证管理模块 (现有)
├── file-module/               # 独立的文件管理模块 (现有)
└── ...其他业务模块

How it integrates:

• core-module 作为聚合包，统一导出核心业务模块
• server package 可以依赖 core-module 来获取所有核心模块
• 保持与现有独立模块的兼容性
• 提供统一的导入路径和类型定义

Success criteria:

• core-module package 成功创建并可用
• package.json 配置正确更新，移除所有 "-mt" 后缀
• 模块目录重命名完成
• 导出路径和类型定义正确
• 现有功能通过测试验证
• 保持向后兼容性，现有代码无需修改

Stories

Story 1: 创建 core-module 并更新配置

任务列表:

1. 复制目录结构：执行 cp -r packages/core-module-mt packages/core-module
2. 更新 package.json 配置：
   • 将名称从 @d8d/core-module-mt 改为 @d8d/core-module
   • 更新所有导出路径中的 -mt 后缀
   • 更新 main 和 types 字段中的路径
   • 更新 files 字段中的目录名称
3. 重命名模块目录：
   • user-module-mt → user-module
   • auth-module-mt → auth-module
   • file-module-mt → file-module
   • system-config-module-mt → system-config-module
4. 检查并更新导出文件：
   • 检查各模块中的 index.mt.ts 文件，确保导出路径正确
   • 根据需要重命名文件（如 index.mt.ts → index.ts）
5. 验证步骤：
   • 运行 pnpm typecheck 检查类型错误
   • 运行 pnpm test 确保测试通过
   • 检查 server package 能否正确导入

验收标准:

• packages/core-module 目录成功创建
• package.json 配置正确更新，名称和导出路径无误
• 所有模块目录重命名完成（移除 "-mt" 后缀）
• 类型定义和导出路径正确
• 现有测试通过，功能正常
• TypeScript 类型检查无错误

Story 2: 将现有独立模块改为适配器模式

背景分析: 当前架构：

1. 多租户版本：

   • 完整代码在 core-module-mt 中
   • user-module-mt、auth-module-mt、file-module-mt 只是适配器，重新导出 @d8d/core-module-mt 中的代码

2. 非多租户版本（当前）：

   • user-module、auth-module、file-module 包含完整代码
   • 依赖多个基础设施包

3. 目标架构：

   • 完整代码移到 core-module 中（通过 Story 1 创建）
   • 现有独立模块改为适配器模式，重新导出 @d8d/core-module 中的代码
   • 简化依赖关系，统一代码管理

任务列表:

1. 备份现有独立模块的完整代码（如果需要）
2. 将 user-module 改为适配器模式：
   • 清空现有 src 目录中的完整代码
   • 创建适配器文件：src/index.ts，重新导出 @d8d/core-module/user-module
   • 创建 src/schemas/index.ts，重新导出 @d8d/core-module/user-module/schemas
   • 更新 package.json：简化依赖关系，只依赖 @d8d/core-module
3. 同样处理 auth-module 和 file-module
4. 验证适配器模式功能正常：
   • 确保所有导出都正确重定向到 core-module
   • 运行测试验证功能
   • 检查类型定义正确
5. 更新文档：
   • 说明新的架构模式
   • 提供导入示例

验收标准:

• 现有独立模块成功改为适配器模式
• 所有导出正确重定向到 core-module
• 依赖关系简化，只依赖 @d8d/core-module
• 功能测试通过，无回归问题
• TypeScript 类型检查无错误
• 文档更新，说明新的架构

Compatibility Requirements

• 现有功能保持不变，仅进行名称和路径调整
• 数据库 schema 保持不变，不影响现有数据
• 现有独立模块（user-module、auth-module、file-module）不受影响
• 性能无影响，仅进行文件复制和重命名
• 依赖关系清晰，core-module 作为聚合包使用
• 支持按需导入，可以从 core-module 统一导入或从独立模块导入

Risk Mitigation

Primary Risk: 重命名过程中可能遗漏某些文件或路径 Mitigation: 使用脚本批量重命名，并进行全面检查 Rollback Plan: 保留原始 core-module-mt 目录，可以快速回滚

Primary Risk: package.json 导出配置更新错误 Mitigation: 仔细检查每个导出路径，确保正确移除 "-mt" 后缀 Rollback Plan: 备份原始 package.json，可以恢复

Primary Risk: 类型定义路径不正确 Mitigation: 运行 TypeScript 类型检查，确保所有导入路径正确 Rollback Plan: 保留原始类型定义文件

Primary Risk: 测试失败 Mitigation: 复制后立即运行测试，确保功能正常 Rollback Plan: 如果测试失败，回滚到原始状态

Definition of Done

• Story 1 完成且所有验收标准满足
• Story 2 完成且所有验收标准满足
• core-module 成功创建并包含完整代码
• 现有独立模块成功改为适配器模式
• 所有导出正确重定向到 core-module
• 依赖关系简化完成
• 功能验证通过，无回归问题

具体更新步骤

1. 复制目录

cp -r packages/core-module-mt packages/core-module

2. 更新 package.json

需要更新的关键字段：

• name: @d8d/core-module-mt → @d8d/core-module
• exports: 所有导出路径中的 -mt 后缀需要移除
• main 和 types: 更新路径中的 -mt 后缀
• files: 更新目录名称，移除 -mt 后缀

3. 重命名模块目录

cd packages/core-module
mv user-module-mt user-module
mv auth-module-mt auth-module
mv file-module-mt file-module
mv system-config-module-mt system-config-module

4. 检查并更新导出文件

检查以下文件，确保导出路径正确：

• user-module/src/index.mt.ts → 可能需要重命名为 index.ts
• auth-module/src/index.mt.ts → 可能需要重命名为 index.ts
• file-module/src/index.ts → 保持原样
• system-config-module/src/index.mt.ts → 可能需要重命名为 index.ts

5. 验证步骤

1. 运行 pnpm typecheck 检查类型错误
2. 运行 pnpm test 确保测试通过
3. 检查 server package 能否正确导入

预期的 package.json 更新示例

更新前 (core-module-mt):

{
  "name": "@d8d/core-module-mt",
  "exports": {
    "./user-module-mt": {
      "import": "./user-module-mt/src/index.mt.ts"
    },
    "./auth-module-mt": {
      "import": "./auth-module-mt/src/index.mt.ts"
    }
  },
  "files": [
    "user-module-mt/src",
    "auth-module-mt/src"
  ]
}

更新后 (core-module):

{
  "name": "@d8d/core-module",
  "exports": {
    "./user-module": {
      "import": "./user-module/src/index.ts"
    },
    "./auth-module": {
      "import": "./auth-module/src/index.ts"
    }
  },
  "files": [
    "user-module/src",
    "auth-module/src"
  ]
}

使用方式

从 core-module 导入:

import { UserService } from '@d8d/core-module/user-module';
import { AuthService } from '@d8d/core-module/auth-module';

从独立模块导入 (仍然可用):

import { UserService } from '@d8d/user-module';
import { AuthService } from '@d8d/auth-module';

---

当前进展总结

待完成 🔄

• Story 1: 创建 core-module 并更新配置 - 待实现

  • 复制目录结构
  • 更新 package.json 配置
  • 重命名模块目录
  • 检查并更新导出文件
  • 验证功能正常

• Story 2: 将现有独立模块改为适配器模式 - 待实现

  • 备份现有完整代码（如果需要）
  • 清空独立模块的 src 目录
  • 创建适配器文件，重新导出 core-module
  • 更新 package.json 依赖
  • 验证功能正常

Story Manager Handoff

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

• Story 1: 这是一个简单的目录复制和重命名任务，不需要复杂的架构设计

  • 需要从 packages/core-module-mt 复制到 packages/core-module
  • 需要更新 package.json 中的名称和所有导出路径，移除 '-mt' 后缀
  • 需要重命名模块目录：user-module-mt → user-module, auth-module-mt → auth-module 等
  • 需要检查并更新导出文件（如 index.mt.ts 文件）
  • 关键兼容性要求：现有功能保持不变，仅进行名称和路径调整
  • 包含验证步骤：类型检查、测试运行、导入验证

• Story 2: 将现有独立模块改为适配器模式

  • 当前架构：完整代码在独立模块中（user-module、auth-module、file-module）
  • 目标架构：完整代码移到 core-module 中，独立模块改为适配器
  • 需要将现有独立模块的完整代码清空，改为重新导出 @d8d/core-module 中的代码
  • 需要简化 package.json 依赖关系，只依赖 @d8d/core-module
  • 需要验证适配器模式功能正常，无回归问题

该 epic 的目标是：

1. 创建一个非多租户版本的 core-module，包含完整的核心模块代码
2. 将现有独立模块改为适配器模式，统一代码管理到 core-module 中
3. 简化依赖关系，提高代码维护性"