Home Esplora Aiuto
Registrati Accedi
188-template-179
/
mini-starter
forkato da 155-template-138/mini-starter
2
0
Forka 0
File
Albero (Tree): e013aa68fb
Rami (Branch) Tag
mini-starter
/
docs
/
stories
/
006.002.convert-independent-modules-to-adapter-pattern.story.md

006.002.convert-independent-modules-to-adapter-pattern.story.md 12 KB
Cronologia Originale

Story 006.002: 将现有独立模块改为适配器模式

Status

Draft

Story

As a 开发者， I want 将现有的独立模块（user-module、auth-module、file-module）改为适配器模式，重新导出 @d8d/core-module 中的代码， so that 我们可以简化依赖关系，统一代码管理到 core-module 中，提高代码维护性。

Acceptance Criteria

  1. 现有独立模块成功改为适配器模式
  2. 所有导出正确重定向到 core-module
  3. 依赖关系简化，只依赖 @d8d/core-module
  4. 功能测试通过，无回归问题
  5. TypeScript 类型检查无错误
  6. 文档更新，说明新的架构

Tasks / Subtasks

  • 备份现有独立模块的完整代码（如果需要）(AC: 1)
    • 备份 packages/user-module/src 目录
    • 备份 packages/auth-module/src 目录
    • 备份 packages/file-module/src 目录

  • [ ] 将 user-module 改为适配器模式 (AC: 1, 2, 3)

    • 清空现有 packages/user-module/src 目录中的完整代码
    • 创建适配器文件：packages/user-module/src/index.ts，重新导出 @d8d/core-module/user-module
    • 参考多租户模块写法：packages/user-module-mt/src/index.mt.ts

    • 代码示例：

      // User Module Adapter Package
// 适配器包，从核心包重新导出所有接口
export * from '@d8d/core-module/user-module'

    • [ ] 创建 packages/user-module/src/schemas/index.ts，重新导出 @d8d/core-module/user-module/schemas

    • 参考多租户模块写法：packages/user-module-mt/src/schemas/index.mt.ts

    • 代码示例：

      // User Module Schemas Adapter
// 适配器包，从核心包重新导出schemas接口
export * from '@d8d/core-module/user-module/schemas'

    • [ ] 更新 packages/user-module/package.json：简化依赖关系，只依赖 @d8d/core-module

  • [ ] 将 auth-module 改为适配器模式 (AC: 1, 2, 3)

    • 清空现有 packages/auth-module/src 目录中的完整代码
    • 创建适配器文件：packages/auth-module/src/index.ts，重新导出 @d8d/core-module/auth-module
    • 参考多租户模块写法：packages/auth-module-mt/src/index.mt.ts

    • 代码示例：

      // Auth Module Adapter Package
// 适配器包，从核心包重新导出所有接口
export * from '@d8d/core-module/auth-module'

    • [ ] 创建 packages/auth-module/src/schemas/index.ts，重新导出 @d8d/core-module/auth-module/schemas

    • 参考多租户模块写法：packages/auth-module-mt/src/schemas/index.mt.ts

    • 代码示例：

      // Auth Module Schemas Adapter
// 适配器包，从核心包重新导出schemas接口
export * from '@d8d/core-module/auth-module/schemas'

    • [ ] 更新 packages/auth-module/package.json：简化依赖关系，只依赖 @d8d/core-module

  • [ ] 将 file-module 改为适配器模式 (AC: 1, 2, 3)

    • 清空现有 packages/file-module/src 目录中的完整代码
    • 创建适配器文件：packages/file-module/src/index.ts，重新导出 @d8d/core-module/file-module
    • 参考多租户模块写法：packages/file-module-mt/src/index.ts

    • 代码示例：

      // File Module Adapter Package
// 适配器包，从核心包重新导出所有接口
export * from '@d8d/core-module/file-module'

    • [ ] 创建 packages/file-module/src/schemas/index.ts，重新导出 @d8d/core-module/file-module/schemas

    • 参考多租户模块写法：packages/file-module-mt/src/schemas/index.ts

    • 代码示例：

      // File Module Schemas Adapter
// 适配器包，从核心包重新导出schemas接口
export * from '@d8d/core-module/file-module/schemas'

    • [ ] 更新 packages/file-module/package.json：简化依赖关系，只依赖 @d8d/core-module

  • [ ] 验证适配器模式功能正常 (AC: 4, 5)

    • 确保所有导出都正确重定向到 core-module
    • 运行测试验证功能：cd packages/user-module && pnpm test
    • 运行测试验证功能：cd packages/auth-module && pnpm test
    • 运行测试验证功能：cd packages/file-module && pnpm test
    • 检查类型定义正确：cd packages/user-module && pnpm typecheck
    • 检查类型定义正确：cd packages/auth-module && pnpm typecheck
    • 检查类型定义正确：cd packages/file-module && pnpm typecheck

  • [ ] 更新文档 (AC: 6)

    • 说明新的架构模式
    • 提供导入示例
    • 更新 README 文件

Dev Notes

项目结构信息 [Source: architecture/source-tree.md#实际项目结构]

  • 项目采用 monorepo 结构，包含小程序(mini)、Web应用(web)和模块化包架构
  • 包管理使用 pnpm workspace 管理多包依赖关系
  • 包架构层次：
    • 基础设施层: shared-types → shared-utils → shared-crud
    • 测试基础设施: shared-test-util
    • 业务模块层: user-module → auth-module → file-module → geo-areas
    • 应用层: server (重构后)
  • 当前独立模块位置：
    • packages/user-module/ - 用户管理模块 (@d8d/user-module)
    • packages/auth-module/ - 认证管理模块 (@d8d/auth-module)
    • packages/file-module/ - 文件管理模块 (@d8d/file-module)
  • 新创建的 core-module 位置：
    • packages/core-module/ - 核心模块聚合包 (@d8d/core-module)
    • 包含：user-module/, auth-module/, file-module/, system-config-module/

技术栈信息 [Source: architecture/tech-stack.md]

  • 运行时：Node.js 20.18.3
  • 框架：Hono 4.8.5 (Web框架和API路由，RPC类型安全)
  • 数据库：PostgreSQL 17 (通过TypeORM)
  • ORM：TypeORM 0.3.25 (数据库操作抽象，实体管理)
  • 包管理：pnpm workspace

编码标准 [Source: architecture/coding-standards.md]

  • 代码风格：TypeScript严格模式，一致的缩进和命名
  • linting规则：已配置ESLint，支持TypeScript和React
  • 测试模式：完整的测试框架已配置（Vitest + Testing Library + Playwright）

测试策略 [Source: architecture/testing-strategy.md]

  • 测试框架: Vitest + Testing Library + hono/testing + Playwright
  • 测试位置: tests/ 目录在包根目录下 [Source: architecture/testing-strategy.md#单元测试]
  • 覆盖率目标: 核心业务逻辑 > 80%
  • 测试类型: 单元测试、集成测试、E2E测试
  • 业务模块包测试位置:
    • 单元测试：packages/*-module/tests/unit/**/*.test.ts [Source: architecture/testing-strategy.md#单元测试]
    • 集成测试：packages/*-module/tests/integration/**/*.test.ts [Source: architecture/testing-strategy.md#集成测试]
  • 测试执行命令:
    • 运行所有测试：cd packages/user-module && pnpm test
    • 运行单元测试：cd packages/user-module && pnpm test:unit
    • 运行集成测试：cd packages/auth-module && pnpm test:integration
    • 生成覆盖率报告：cd packages/user-module && pnpm test:coverage

适配器模式设计

当前架构：

  1. 多租户版本：

    • 完整代码在 core-module-mt 中
    • user-module-mt、auth-module-mt、file-module-mt 只是适配器，重新导出 @d8d/core-module-mt 中的代码

  2. 非多租户版本（当前）：

    • user-module、auth-module、file-module 包含完整代码
    • 依赖多个基础设施包

  3. 目标架构：

    • 完整代码移到 core-module 中（通过 Story 1 创建）
    • 现有独立模块改为适配器模式，重新导出 @d8d/core-module 中的代码
    • 简化依赖关系，统一代码管理

文件路径参考

Core-module 中的模块路径

  • packages/core-module/user-module/src/index.ts - core-module 中的用户模块入口
  • packages/core-module/auth-module/src/index.ts - core-module 中的认证模块入口
  • packages/core-module/file-module/src/index.ts - core-module 中的文件模块入口
  • packages/core-module/user-module/src/schemas/index.ts - core-module 中的用户模式
  • packages/core-module/auth-module/src/schemas/index.ts - core-module 中的认证模式
  • packages/core-module/file-module/src/schemas/index.ts - core-module 中的文件模式

多租户模块适配器写法参考

  • packages/user-module-mt/src/index.mt.ts - 用户模块适配器入口（参考写法）

    // User Module MT Adapter Package
// 适配器包，从核心包重新导出所有接口
export * from '@d8d/core-module-mt/user-module-mt'

  • packages/user-module-mt/src/schemas/index.mt.ts - 用户模式适配器（参考写法）

    // User Module MT Schemas Adapter
// 适配器包，从核心包重新导出schemas接口
export * from '@d8d/core-module-mt/user-module-mt/schemas'

  • packages/auth-module-mt/src/index.mt.ts - 认证模块适配器入口（参考写法）

    // Auth Module MT Adapter Package
// 适配器包，从核心包重新导出所有接口
export * from '@d8d/core-module-mt/auth-module-mt'

  • packages/auth-module-mt/src/schemas/index.mt.ts - 认证模式适配器（参考写法）

    // Auth Module MT Schemas Adapter
// 适配器包，从核心包重新导出schemas接口
export * from '@d8d/core-module-mt/auth-module-mt/schemas'

  • packages/file-module-mt/src/index.ts - 文件模块适配器入口（参考写法）

    // File Module MT Adapter Package
// 适配器包，从核心包重新导出所有接口
export * from '@d8d/core-module-mt/file-module-mt'

  • packages/file-module-mt/src/schemas/index.ts - 文件模式适配器（参考写法）

    // File Module MT Schemas Adapter
// 适配器包，从核心包重新导出schemas接口
export * from '@d8d/core-module-mt/file-module-mt/schemas'

依赖关系简化

当前独立模块依赖多个包：

  • @d8d/shared-types
  • @d8d/shared-utils
  • @d8d/shared-crud
  • 其他业务模块

改为适配器模式后，只需依赖：

  • @d8d/core-module

测试要求

  • 确保所有现有测试通过
  • 验证适配器正确重定向到 core-module
  • 检查类型定义兼容性
  • 确保无回归问题

兼容性要求

  • 现有功能保持不变
  • 现有导入路径保持不变：import { UserService } from '@d8d/user-module';
  • 数据库 schema 保持不变，不影响现有数据
  • 性能无影响

Testing

测试标准 [Source: architecture/testing-strategy.md]

  • 测试框架: Vitest
  • 测试位置: tests/ 目录在包根目录下 [Source: architecture/testing-strategy.md#单元测试]
  • 覆盖率目标: 核心业务逻辑 > 80%
  • 测试类型: 单元测试、集成测试

适配器模式特定测试要求

  1. 导出验证测试: 验证适配器正确重新导出所有 core-module 的导出
  2. 类型兼容性测试: 确保类型定义与 core-module 完全兼容
  3. 功能回归测试: 确保所有现有功能测试通过
  4. 依赖关系测试: 验证 package.json 依赖关系正确简化

测试执行流程

  1. 运行单元测试：cd packages/user-module && pnpm test:unit
  2. 运行集成测试：cd packages/auth-module && pnpm test:integration
  3. 运行所有测试：cd packages/file-module && pnpm test
  4. 类型检查：cd packages/user-module && pnpm typecheck

Change Log

Date Version Description Author
2025-12-02 1.0 初始故事创建 Bob (Scrum Master)

Dev Agent Record

This section is populated by the development agent during implementation

Agent Model Used

Record the specific AI agent model and version used for development

Debug Log References

Reference any debug logs or traces generated during development

Completion Notes List

Notes about the completion of tasks and any issues encountered

File List

List all files created, modified, or affected during story implementation

QA Results

Results from QA Agent QA review of the completed story implementation