mini-starter/docs/stories/005.001.infrastructure-core-packages.md

Story 005.001: Infrastructure Core Packages

Status

Draft

Story

As a 系统架构师, I want 将共享类型、数据库核心、认证核心、工具核心从 packages/server/src 拆分为独立的基础设施包, so that 为后续的业务模块提供标准化的基础设施支持，并实现清晰的依赖层次结构

Acceptance Criteria

1. shared-types package 创建完成，包含所有通用类型定义
2. auth-core package 创建完成，提供认证相关的核心服务
3. utils-core package 创建完成，提供通用的工具函数
4. user-core package 创建完成，提供用户管理相关的核心服务
5. 所有基础设施包通过 pnpm workspace 正确配置依赖关系
6. 现有 server package 重构为使用新的基础设施包
7. 所有基础设施包通过单元测试和集成测试
8. 现有功能通过回归测试验证无影响
9. 所有新包的依赖版本与 packages/server 保持一致

Tasks / Subtasks

• 创建 shared-types package (AC: 1)
  • 创建 package.json 配置
  • 迁移通用类型定义（ApiResponse、Pagination、QueryParams等）
  • 配置 TypeScript 编译选项（包含 "composite": true）
  • 编写基础测试（放在 tests/unit/）
• 创建 auth-core package (AC: 2)
  • 创建 package.json 配置
  • 迁移认证相关的核心服务
  • 提供 JWT 令牌管理
  • 配置 TypeScript 编译选项（包含 "composite": true）
  • 编写单元测试（放在 tests/unit/）
• 创建 utils-core package (AC: 3)
  • 创建 package.json 配置
  • 迁移通用工具函数
  • 提供常用工具类
  • 配置 TypeScript 编译选项（包含 "composite": true）
  • 编写单元测试（放在 tests/unit/）
• 创建 user-core package (AC: 4)
  • 创建 package.json 配置
  • 迁移用户管理相关的核心服务
  • 提供用户 CRUD 操作
  • 配置 TypeScript 编译选项（包含 "composite": true）
  • 编写单元测试（放在 tests/unit/）
• 配置 pnpm workspace 依赖关系 (AC: 5)
  • 更新根目录 package.json workspace 配置
  • 配置各 package 间的依赖关系
  • 验证依赖解析正确
• 重构 server package 依赖 (AC: 6)
  • 更新 server package.json 依赖
  • 重构代码导入路径
  • 验证编译通过
• 执行回归测试 (AC: 7, 8)
  • 运行所有单元测试（tests/unit/）
  • 运行集成测试（tests/integration/）
  • 验证现有功能无回归
• 验证依赖版本对齐 (AC: 9)
  • 检查所有新包的依赖版本与 packages/server 保持一致
  • 验证关键依赖版本（typeorm、hono、zod等）完全一致
  • 确保开发依赖版本也保持一致

Dev Notes

技术架构信息

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

现有代码结构参考

• 当前共享类型位置: packages/server/src/types/
• 当前认证核心: packages/server/src/auth/
• 当前工具函数: packages/server/src/utils/
• 当前用户管理: packages/server/src/modules/users/

Package 配置要求

• 所有 package 使用 TypeScript 编译
• 遵循现有的代码风格和命名规范
• 提供完整的类型定义导出
• 配置适当的构建脚本
• 依赖版本对齐: 所有外部依赖版本必须与 packages/server 保持一致
• TypeScript 配置: 所有 package 的 tsconfig.json 必须设置 "composite": true
• Package 输出配置: package.json 中的 "main"、"types" 和 "exports" 必须指向 src 目录（pnpm workspace 直接引用源码）

依赖关系设计

// shared-types package.json
{
  "name": "@d8d/shared-types",
  "dependencies": {}
}

// auth-core package.json
{
  "name": "@d8d/auth-core",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "jsonwebtoken": "^9.0.2",
    "bcrypt": "^6.0.0"
  }
}

// utils-core package.json
{
  "name": "@d8d/utils-core",
  "dependencies": {
    "@d8d/shared-types": "workspace:*"
  }
}

// user-core package.json
{
  "name": "@d8d/user-core",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "typeorm": "^0.3.20",
    "pg": "^8.16.3"
  }
}

关键依赖版本对齐要求

必须与 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%
  • 关键模块（认证授权、数据库操作）: ≥ 90%

Change Log

Date	Version	Description	Author
2025-11-10	1.0	初始创建故事文档	Bob (Scrum Master)
2025-11-10	1.1	添加依赖版本对齐要求	Bob (Scrum Master)
2025-11-10	1.2	添加 TypeScript composite 配置要求	Bob (Scrum Master)
2025-11-10	1.3	修正 Package 输出配置指向 src 目录	Bob (Scrum Master)
2025-11-10	1.4	移除 database-core package，简化架构	James (Developer)
2025-11-10	1.5	添加 user-core package 需求	James (Developer)

Dev Agent Record

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

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

File List