mini-starter/docs/stories/005.002.crud-infrastructure-package.md

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 配置要求

// 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