|
|
@@ -1,205 +0,0 @@
|
|
|
-# 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 配置要求
|
|
|
-```json
|
|
|
-// 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
|