📝 docs(architecture): add infrastructure packages split story

- create detailed story for splitting server into modular packages
- define acceptance criteria for 3 shared infrastructure packages and 3 business modules
- outline two-phase implementation plan with specific tasks
- document technical architecture, dependency relationships and package configurations
- specify critical requirements for type definitions, testing and dependency version alignment

docs/stories/005.001.infrastructure-packages-split.md

@@ -0,0 +1,313 @@
+# 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/）
+
+- [ ] 创建 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 直接引用源码）
+
+### 依赖关系设计
+```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
+{{agent_model_name_version}}
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List