# Story 005.001: Infrastructure Packages Split

## Status
Draft

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

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

## Tasks / Subtasks

### 第一阶段：共享基础设施包
- [x] 创建 shared-types package (AC: 1)
  - [x] 创建 package.json 配置
  - [x] 迁移通用类型定义（GlobalConfig、AuthContextType、EnableStatus、DeleteStatus、DisabledStatus等）
  - [x] 配置 TypeScript 编译选项（包含 `"composite": true`）
  - [x] 编写基础测试（放在 tests/unit/）

- [x] 创建 shared-utils package (AC: 2)
  - [x] 创建 package.json 配置
  - [x] 迁移通用工具函数（jwt.util.ts、errorHandler.ts、parseWithAwait.ts等）
  - [x] 迁移数据库连接配置（data-source.ts）
  - [x] 配置 TypeScript 编译选项（包含 `"composite": true`）
  - [x] 编写单元测试（放在 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 直接引用源码）

### 依赖关系设计
```json
// 共享基础设施层
// 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 完全一致