Story 005.001: Infrastructure Packages Split

Status

Draft

Story

As a 系统架构师, I want 按照模块化架构将 packages/server/src 拆分为独立的模块包, so that 实现清晰的模块边界、可复用的基础设施组件，并为后续的业务模块提供标准化的模块化支持

Acceptance Criteria

shared-types package 创建完成，包含所有通用类型定义
shared-utils package 创建完成，提供通用的工具函数和数据库连接
shared-crud package 创建完成，包含通用的 CRUD 服务、控制器和路由模式
user-module package 创建完成，提供完整的用户管理模块（实体、服务、路由）
auth-module package 创建完成，提供完整的认证管理模块（实体、服务、路由）
file-module package 创建完成，提供完整的文件管理模块（实体、服务、路由）
所有模块包通过 pnpm workspace 正确配置依赖关系
现有 server package 重构为使用新的模块包
所有模块包通过单元测试和集成测试
现有功能通过回归测试验证无影响
所有新包的依赖版本与 packages/server 保持一致
依赖关系层次清晰，无循环依赖
提供完整的类型定义和 API 文档

Tasks / Subtasks

第一阶段：共享基础设施包

[x] 创建 shared-types package (AC: 1)
- 创建 package.json 配置
- 迁移通用类型定义（GlobalConfig、AuthContextType、EnableStatus、DeleteStatus、DisabledStatus等）
- 配置 TypeScript 编译选项（包含 "composite": true）
- 编写基础测试（放在 tests/unit/）
[x] 创建 shared-utils package (AC: 2)
- 创建 package.json 配置
- 迁移通用工具函数（jwt.util.ts、errorHandler.ts、parseWithAwait.ts等）
- 迁移数据库连接配置（data-source.ts）
- 配置 TypeScript 编译选项（包含 "composite": true）
- 编写单元测试（放在 tests/unit/）
[ ] 创建 shared-crud package (AC: 3)
- 创建 package.json 配置
- 迁移通用 CRUD 服务模式
- 迁移 GenericCrudService 类
- 迁移 ConcreteCrudService 类
- 迁移相关类型定义（UserTrackingOptions、RelationFieldOptions、CrudOptions）
- 迁移通用 CRUD 路由模式
- 迁移 createCrudRoutes 函数
- 迁移路由配置和验证逻辑
- 配置 TypeScript 编译选项
- 编写基础测试

第二阶段：业务模块包

[ ] 创建 user-module package (AC: 4)
- 创建 package.json 配置
- 迁移用户实体类（UserEntity、Role）
- 迁移用户服务类（UserService、RoleService）
- 迁移用户相关 Schema 定义
- 迁移用户 API 路由
- 配置 TypeScript 编译选项（包含 "composite": true）
- 编写单元测试和集成测试
[ ] 创建 auth-module package (AC: 5)
- 创建 package.json 配置
- 迁移认证服务类（AuthService、MiniAuthService）
- 迁移认证相关 Schema 定义
- 迁移认证 API 路由
- 配置 TypeScript 编译选项（包含 "composite": true）
- 编写单元测试和集成测试
[ ] 创建 file-module package (AC: 6)
- 创建 package.json 配置
- 迁移文件实体类（File）
- 迁移文件服务类（FileService、MinioService）
- 迁移文件相关 Schema 定义
- 迁移文件 API 路由
- 配置 TypeScript 编译选项（包含 "composite": true）
- 编写单元测试和集成测试
[ ] 配置 pnpm workspace 依赖关系 (AC: 6)
- 更新根目录 package.json workspace 配置
- 配置各 package 间的依赖关系
- 验证依赖解析正确
[ ] 重构 server package 依赖 (AC: 7)
- 更新 server package.json 依赖
- 重构代码导入路径
- 移除 server 内部的重复 CRUD 实现
- 验证编译通过
[ ] 执行回归测试 (AC: 8, 9)
- 运行所有单元测试（tests/unit/）
- 运行集成测试（tests/integration/）
- 验证现有功能无回归
[ ] 验证依赖版本对齐 (AC: 10)
- 检查所有新包的依赖版本与 packages/server 保持一致
- 验证关键依赖版本（typeorm、hono、zod等）完全一致
- 确保开发依赖版本也保持一致
[ ] 验证依赖层次 (AC: 11)
- 检查 package 依赖关系
- 验证无循环依赖
- 确认依赖层次正确
[ ] 完善文档 (AC: 12)
- 提供类型定义文档
- 编写使用示例
- 更新 API 文档

Dev Notes

技术架构信息

项目技术栈: Node.js 20.19.2 + TypeScript + Hono + TypeORM + PostgreSQL
包管理: pnpm workspace
模块化架构:
- 共享基础设施层: shared-types → shared-utils → shared-crud
- 业务模块层: user-module → auth-module → file-module
- 应用层: server
模块边界: 每个模块包包含完整的业务功能（实体、服务、路由）

现有代码结构参考

当前共享基础设施位置:
- packages/server/src/share/types.ts - 共享类型定义
- packages/server/src/data-source.ts - 数据库连接
- packages/server/src/utils/ - 工具函数
- jwt.util.ts - JWT工具类
- errorHandler.ts - 错误处理
- parseWithAwait.ts - 异步解析工具
- packages/server/src/utils/ - CRUD工具
- generic-crud.service.ts - 通用CRUD服务基类
- concrete-crud.service.ts - 具体CRUD服务实现
- generic-crud.routes.ts - 通用CRUD路由生成器
当前用户模块位置: packages/server/src/modules/users/
- user.entity.ts - 用户实体
- role.entity.ts - 角色实体
- user.service.ts - 用户服务
- role.service.ts - 角色服务
- user.schema.ts - 用户Schema
- role.schema.ts - 角色Schema
- packages/server/src/api/users/ - 用户API路由
当前认证模块位置: packages/server/src/modules/auth/
- auth.service.ts - 认证服务
- mini-auth.service.ts - 小型认证服务
- packages/server/src/api/auth/ - 认证API路由
当前文件模块位置: packages/server/src/modules/files/
- file.entity.ts - 文件实体
- file.service.ts - 文件服务
- minio.service.ts - MinIO服务
- file.schema.ts - 文件Schema
- packages/server/src/api/files/ - 文件API路由

Package 配置要求

所有 package 使用 TypeScript 编译
遵循现有的代码风格和命名规范
提供完整的类型定义导出
配置适当的构建脚本
依赖版本对齐: 所有外部依赖版本必须与 packages/server 保持一致
TypeScript 配置: 所有 package 的 tsconfig.json 必须设置 "composite": true
Package 输出配置: package.json 中的 "main"、"types" 和 "exports" 必须指向 src 目录（pnpm workspace 直接引用源码）

依赖关系设计

// 共享基础设施层
// shared-types package.json
{
  "name": "@d8d/shared-types",
  "dependencies": {}
}

// shared-utils package.json
{
  "name": "@d8d/shared-utils",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "jsonwebtoken": "^9.0.2",
    "bcrypt": "^6.0.0",
    "typeorm": "^0.3.20",
    "pg": "^8.16.3"
  }
}

// shared-crud package.json
{
  "name": "@d8d/shared-crud",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "typeorm": "^0.3.20",
    "@hono/zod-openapi": "1.0.2",
    "zod": "^4.1.12"
  }
}

// 业务模块层
// user-module package.json
{
  "name": "@d8d/user-module",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/shared-crud": "workspace:*",
    "typeorm": "^0.3.20"
  }
}

// auth-module package.json
{
  "name": "@d8d/auth-module",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/user-module": "workspace:*",
    "typeorm": "^0.3.20"
  }
}

// file-module package.json
{
  "name": "@d8d/file-module",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/shared-crud": "workspace:*",
    "typeorm": "^0.3.20"
  }
}

// 重构后的 server package.json
{
  "name": "@d8d/server",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/shared-crud": "workspace:*",
    "@d8d/user-module": "workspace:*",
    "@d8d/auth-module": "workspace:*",
    "@d8d/file-module": "workspace:*"
  }
}

需要迁移的通用 CRUD 模式

基础服务模式: 提供通用的 CRUD 操作方法
- GenericCrudService - 通用CRUD服务基类
- ConcreteCrudService - 具体CRUD服务实现
- 用户跟踪功能（UserTrackingOptions）
- 关联字段处理（RelationFieldOptions）
路由模式: 统一的 API 路由定义和验证
- createCrudRoutes - 通用CRUD路由生成器
- 标准化的CRUD操作路由（列表、创建、获取、更新、删除）
- 只读模式支持
配置模式: 标准化的CRUD配置
- CrudOptions - CRUD配置选项类型
- 搜索字段配置
- 关联关系配置
- 中间件配置
查询模式: 标准化的查询参数处理和分页
- 分页查询
- 关键词搜索
- 复杂筛选条件
- 排序支持

关键依赖版本对齐要求

必须与 packages/server 完全一致的依赖版本：

typeorm: ^0.3.20
hono: ^4.8.5
zod: ^4.1.12
@hono/zod-openapi: 1.0.2
jsonwebtoken: ^9.0.2
bcrypt: ^6.0.0
pg: ^8.16.3
axios: ^1.12.2

开发依赖版本对齐：

typescript: ^5.8.3
vitest: ^3.2.4
@types/* 相关依赖版本保持一致

测试标准

测试框架: Vitest [Source: architecture/testing-strategy.md#测试金字塔策略]
测试位置: 每个 package 的 tests/ 目录（遵循现有测试策略）[Source: architecture/testing-strategy.md#测试金字塔策略]
- tests/unit/ - 单元测试
- tests/integration/ - 集成测试
测试要求: 单元测试覆盖核心功能，集成测试验证包间协作
测试执行: pnpm test 在每个 package 中运行
测试覆盖率目标: [Source: architecture/testing-strategy.md#测试覆盖率标准]
- 单元测试: ≥ 80%
- 集成测试: ≥ 60%
- 关键模块（认证授权、数据库操作、CRUD操作）: ≥ 90%

向后兼容性保证

现有 API 接口保持不变
数据库操作逻辑保持一致
错误响应格式保持不变
仅重构内部实现，不改变外部行为

Change Log

Date	Version	Description	Author
2025-11-10	1.0	合并 005.001 和 005.002 故事，创建统一的基础设施包拆分故事	Bob (Scrum Master)
2025-11-10	1.1	基于实际代码依赖分析调整任务顺序和依赖关系	Bob (Scrum Master)
2025-11-10	2.0	重大架构调整：从功能分包改为模块分包架构，按照 users/auth/files 模块组织	Bob (Scrum Master)

Dev Agent Record

此部分由开发代理在实现过程中填写

Agent Model Used

Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

Debug Log References

修复了数据源测试中的环境变量计算时机问题
修复了 JWT 测试中的时间计算问题
添加了缺失的依赖（reflect-metadata, @hono/zod-openapi）

Completion Notes List

✅ shared-utils package 创建完成
✅ 所有通用工具函数已迁移
✅ 数据库连接配置已迁移并重构为通用函数
✅ TypeScript 配置完成（包含 composite: true）
✅ 单元测试编写完成并通过
✅ 依赖版本与 packages/server 保持一致

File List

新增文件：

packages/shared-utils/package.json - 包配置
packages/shared-utils/tsconfig.json - TypeScript 配置
packages/shared-utils/vitest.config.ts - 测试配置
packages/shared-utils/src/index.ts - 包入口
packages/shared-utils/src/utils/jwt.util.ts - JWT 工具函数
packages/shared-utils/src/utils/errorHandler.ts - 错误处理
packages/shared-utils/src/utils/parseWithAwait.ts - 异步解析工具
packages/shared-utils/src/utils/logger.ts - 日志工具
packages/shared-utils/src/data-source.ts - 数据库连接配置
packages/shared-utils/tests/unit/jwt.util.test.ts - JWT 测试
packages/shared-utils/tests/unit/parseWithAwait.test.ts - 异步解析测试
packages/shared-utils/tests/unit/data-source.test.ts - 数据源测试

修改文件：

packages/shared-types/src/index.ts - 添加 JWTPayload 类型定义
tsconfig.json - 创建根目录 TypeScript 配置

依赖关系：

shared-utils 依赖 shared-types
所有外部依赖版本与 packages/server 完全一致

005.001.infrastructure-packages-split.md 13 KB History Raw