# Story 005.002: CRUD Infrastructure Package

## Status
Draft

## Story
**As a** 系统架构师,
**I want** 将 CRUD 核心基础设施从 packages/server/src 拆分为独立的 crud-core package 并重构 server 依赖关系,
**so that** 为业务模块提供标准化的 CRUD 操作支持，并建立清晰的依赖层次结构

## Acceptance Criteria
1. crud-core package 创建完成，包含通用的 CRUD 服务、控制器和路由模式
2. crud-core package 正确依赖基础设施包（shared-types、database-core等）
3. server package 重构为使用 crud-core package 替代内部 CRUD 实现
4. 所有 CRUD 相关的通用模式迁移到 crud-core package
5. crud-core package 通过单元测试和集成测试
6. 现有 CRUD 功能通过回归测试验证无影响
7. 依赖关系层次清晰，无循环依赖
8. 提供完整的类型定义和 API 文档

## Tasks / Subtasks
- [ ] 创建 crud-core package (AC: 1)
  - [ ] 创建 package.json 配置
  - [ ] 迁移通用 CRUD 服务模式
  - [ ] 迁移通用 CRUD 控制器模式
  - [ ] 迁移通用 CRUD 路由模式
  - [ ] 配置 TypeScript 编译选项
  - [ ] 编写基础测试
- [ ] 配置依赖关系 (AC: 2)
  - [ ] 配置 crud-core 依赖基础设施包
  - [ ] 验证依赖解析正确
  - [ ] 确保无循环依赖
- [ ] 重构 server package (AC: 3)
  - [ ] 更新 server package.json 依赖
  - [ ] 重构代码导入路径使用 crud-core
  - [ ] 移除 server 内部的重复 CRUD 实现
  - [ ] 验证编译通过
- [ ] 迁移通用 CRUD 模式 (AC: 4)
  - [ ] 迁移基础实体服务
  - [ ] 迁移通用控制器逻辑
  - [ ] 迁移标准路由模式
  - [ ] 迁移错误处理模式
- [ ] 编写测试 (AC: 5)
  - [ ] 编写 crud-core 单元测试（放在 tests/unit/）
  - [ ] 编写集成测试验证包间协作（放在 tests/integration/）
  - [ ] 验证所有测试通过
- [ ] 执行回归测试 (AC: 6)
  - [ ] 运行所有现有 CRUD 相关测试（tests/unit/ 和 tests/integration/）
  - [ ] 验证现有 API 功能无影响
  - [ ] 验证数据操作正确性
- [ ] 验证依赖层次 (AC: 7)
  - [ ] 检查 package 依赖关系
  - [ ] 验证无循环依赖
  - [ ] 确认依赖层次正确
- [ ] 完善文档 (AC: 8)
  - [ ] 提供类型定义文档
  - [ ] 编写使用示例
  - [ ] 更新 API 文档

## Dev Notes

### 技术架构信息
- **项目技术栈**: Node.js 20.19.2 + TypeScript + Hono + TypeORM + PostgreSQL
- **包管理**: pnpm workspace
- **依赖层次**: shared-types → database-core → crud-core → 业务模块 → server

### 现有代码结构参考
- **当前 CRUD 服务位置**: packages/server/src/services/
- **当前 CRUD 控制器**: packages/server/src/controllers/
- **当前 CRUD 路由**: packages/server/src/routes/
- **需要迁移的通用模式**: 基础实体服务、通用控制器逻辑、标准路由模式

### Package 配置要求
```json
// crud-core package.json
{
  "name": "@d8d/crud-core",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/database-core": "workspace:*",
    "typeorm": "^0.3.20",
    "@hono/zod-openapi": "1.0.2",
    "zod": "^4.1.12"
  }
}

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

### 需要迁移的通用 CRUD 模式
- **基础服务模式**: 提供通用的 CRUD 操作方法
- **控制器模式**: 标准化的控制器结构和错误处理
- **路由模式**: 统一的 API 路由定义和验证
- **DTO 模式**: 通用的数据转换和验证
- **查询模式**: 标准化的查询参数处理和分页

### 集成点注意事项
- **数据库连接**: 使用 database-core 提供的连接管理
- **类型定义**: 依赖 shared-types 的基础类型
- **认证**: 后续业务模块可选择性集成 auth-core
- **错误处理**: 保持现有的错误处理模式

### 测试标准
- **测试框架**: Vitest
- **测试位置**: crud-core 的 `tests/` 目录（遵循现有测试策略）
  - `tests/unit/` - 单元测试
  - `tests/integration/` - 集成测试
- **测试类型**: 单元测试 + 集成测试
- **测试重点**: CRUD 操作正确性、类型安全、错误处理
- **回归测试**: 验证现有 CRUD API 功能无影响

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

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-11-10 | 1.0 | 初始创建故事文档 | Bob (Scrum Master) |

## Dev Agent Record
*此部分由开发代理在实现过程中填写*

### Agent Model Used
{{agent_model_name_version}}

### Debug Log References

### Completion Notes List

### File List