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. database-core package 创建完成，提供数据库连接和基础实体管理
3. auth-core package 创建完成，提供认证相关的核心服务
4. utils-core package 创建完成，提供通用的工具函数
5. 所有基础设施包通过 pnpm workspace 正确配置依赖关系
6. 现有 server package 重构为使用新的基础设施包
7. 所有基础设施包通过单元测试和集成测试
8. 现有功能通过回归测试验证无影响

Tasks / Subtasks

• 创建 shared-types package (AC: 1)
  • 创建 package.json 配置
  • 迁移通用类型定义（ApiResponse、Pagination、QueryParams等）
  • 配置 TypeScript 编译选项
  • 编写基础测试（放在 tests/unit/）
• 创建 database-core package (AC: 2)
  • 创建 package.json 配置
  • 迁移数据库连接配置和基础实体
  • 提供数据库连接管理服务
  • 配置 TypeScript 编译选项
  • 编写单元测试（放在 tests/unit/）
• 创建 auth-core package (AC: 3)
  • 创建 package.json 配置
  • 迁移认证相关的核心服务
  • 提供 JWT 令牌管理
  • 配置 TypeScript 编译选项
  • 编写单元测试（放在 tests/unit/）
• 创建 utils-core package (AC: 4)
  • 创建 package.json 配置
  • 迁移通用工具函数
  • 提供常用工具类
  • 配置 TypeScript 编译选项
  • 编写单元测试（放在 tests/unit/）
• 配置 pnpm workspace 依赖关系 (AC: 5)
  • 更新根目录 package.json workspace 配置
  • 配置各 package 间的依赖关系
  • 验证依赖解析正确
• 重构 server package 依赖 (AC: 6)
  • 更新 server package.json 依赖
  • 重构代码导入路径
  • 验证编译通过
• 执行回归测试 (AC: 7, 8)
  • 运行所有单元测试（tests/unit/）
  • 运行集成测试（tests/integration/）
  • 验证现有功能无回归

Dev Notes

技术架构信息

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

现有代码结构参考

• 当前共享类型位置: packages/server/src/types/
• 当前数据库核心: packages/server/src/database/
• 当前认证核心: packages/server/src/auth/
• 当前工具函数: packages/server/src/utils/

Package 配置要求

• 所有 package 使用 TypeScript 编译
• 遵循现有的代码风格和命名规范
• 提供完整的类型定义导出
• 配置适当的构建脚本

依赖关系设计

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

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

// 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:*"
  }
}

测试标准

• 测试框架: Vitest
• 测试位置: 每个 package 的 tests/ 目录（遵循现有测试策略）
  • tests/unit/ - 单元测试
  • tests/integration/ - 集成测试
• 测试要求: 单元测试覆盖核心功能，集成测试验证包间协作
• 测试执行: pnpm test 在每个 package 中运行

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