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、user-core等）
3. server package 重构为使用 crud-core package 替代内部 CRUD 实现
4. 所有 CRUD 相关的通用模式迁移到 crud-core package
5. crud-core package 通过单元测试和集成测试
6. 现有 CRUD 功能通过回归测试验证无影响
7. 依赖关系层次清晰，无循环依赖
8. 提供完整的类型定义和 API 文档
9. 所有新包的依赖版本与 packages/server 保持一致

Tasks / Subtasks

• 创建 crud-core package (AC: 1)
  • 创建 package.json 配置
  • 迁移通用 CRUD 服务模式
  • 迁移 GenericCrudService 类
  • 迁移 ConcreteCrudService 类
  • 迁移相关类型定义（UserTrackingOptions、RelationFieldOptions、CrudOptions）
  • 迁移通用 CRUD 路由模式
  • 迁移 createCrudRoutes 函数
  • 迁移路由配置和验证逻辑
  • 配置 TypeScript 编译选项
  • 编写基础测试
• 配置依赖关系 (AC: 2)
  • 配置 crud-core 依赖基础设施包
  • 验证依赖解析正确
  • 确保无循环依赖
• 重构 server package (AC: 3)
  • 更新 server package.json 依赖
  • 重构代码导入路径使用 crud-core
  • 移除 server 内部的重复 CRUD 实现
  • 验证编译通过
• 迁移通用 CRUD 模式 (AC: 4)
  • 迁移基础实体服务
  • 迁移 GenericCrudService 完整实现
  • 迁移 ConcreteCrudService 完整实现
  • 迁移标准路由模式
  • 迁移 createCrudRoutes 完整实现
  • 迁移所有路由处理逻辑
  • 迁移配置和类型定义
  • 迁移 CrudOptions 类型定义
  • 迁移用户跟踪和关联字段配置
  • 迁移错误处理模式
• 编写测试 (AC: 5)
  • 编写 crud-core 单元测试（放在 tests/unit/）
  • 编写集成测试验证包间协作（放在 tests/integration/）
  • 验证所有测试通过
• 执行回归测试 (AC: 6)
  • 运行所有现有 CRUD 相关测试（tests/unit/ 和 tests/integration/）
  • 验证现有 API 功能无影响
  • 验证数据操作正确性
• 验证依赖层次 (AC: 7)
  • 检查 package 依赖关系
  • 验证无循环依赖
  • 确认依赖层次正确
• 验证依赖版本对齐 (AC: 9)
  • 检查所有新包的依赖版本与 packages/server 保持一致
  • 验证关键依赖版本（typeorm、hono、zod等）完全一致
  • 确保开发依赖版本也保持一致
• 完善文档 (AC: 8)
  • 提供类型定义文档
  • 编写使用示例
  • 更新 API 文档

Dev Notes

技术架构信息

• 项目技术栈: Node.js 20.19.2 + TypeScript + Hono + TypeORM + PostgreSQL
• 包管理: pnpm workspace
• 依赖层次: shared-types → user-core/auth-core/utils-core → crud-core → 业务模块 → server

现有代码结构参考

• 当前 CRUD 服务位置: packages/server/src/utils/
  • generic-crud.service.ts - 通用CRUD服务基类
  • concrete-crud.service.ts - 具体CRUD服务实现
  • generic-crud.routes.ts - 通用CRUD路由生成器
• 需要迁移的通用模式:
  • 通用CRUD服务基类（GenericCrudService）
  • 具体CRUD服务实现（ConcreteCrudService）
  • 通用CRUD路由生成器（createCrudRoutes）
  • CRUD配置选项和类型定义
  • 用户跟踪和关联字段处理逻辑

Package 配置要求

// crud-core package.json
{
  "name": "@d8d/crud-core",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/user-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/user-core": "workspace:*",
    "@d8d/auth-core": "workspace:*",
    "@d8d/utils-core": "workspace:*"
  }
}

需要迁移的通用 CRUD 模式

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

集成点注意事项

• 数据库连接: 使用 user-core 提供的数据库连接管理
• 类型定义: 依赖 shared-types 的基础类型
• 认证: 后续业务模块可选择性集成 auth-core
• 错误处理: 保持现有的错误处理模式
• 依赖版本对齐: 所有外部依赖版本必须与 packages/server 保持一致
• TypeScript 配置: tsconfig.json 必须设置 "composite": true
• Package 输出配置: package.json 中的 "main"、"types" 和 "exports" 必须指向 src 目录（pnpm workspace 直接引用源码）

测试标准

• 测试框架: Vitest [Source: architecture/testing-strategy.md#测试金字塔策略]
• 测试位置: crud-core 的 tests/ 目录（遵循现有测试策略）[Source: architecture/testing-strategy.md#测试金字塔策略]
  • tests/unit/ - 单元测试
  • tests/integration/ - 集成测试
• 测试要求: 单元测试覆盖核心功能，集成测试验证包间协作
• 测试执行: pnpm test 在每个 package 中运行
• 测试覆盖率目标: [Source: architecture/testing-strategy.md#测试覆盖率标准]
  • 单元测试: ≥ 80%
  • 集成测试: ≥ 60%
  • 关键模块（CRUD操作、数据库交互）: ≥ 90%
• 测试重点: CRUD 操作正确性、类型安全、错误处理
• 回归测试: 验证现有 CRUD API 功能无影响

关键依赖版本对齐要求

必须与 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/* 相关依赖版本保持一致

向后兼容性保证

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

Change Log

Date	Version	Description	Author
2025-11-10	1.0	初始创建故事文档	Bob (Scrum Master)
2025-11-10	1.1	更新依赖关系，移除 database-core 引用	Bob (Scrum Master)
2025-11-10	1.2	添加依赖版本对齐要求和测试覆盖率目标	Bob (Scrum Master)
2025-11-10	1.3	基于实际代码分析更新需要迁移的CRUD模式	Bob (Scrum Master)

Dev Agent Record

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

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

File List