Trang chủ Khám phá Trợ giúp
Đăng ký Đăng nhập
186-template-175
/
mini-starter
forked from 155-template-138/mini-starter
2
0
Fork 0
Các tập tin
Tree: a941c018de
Branches Tags
mini-starter
/
docs
/
stories
/
005.009.delivery-address-module.story.md

005.009.delivery-address-module.story.md 8.3 KB
Lịch sử Raw

Story 005.009: Delivery Address Module

Status

Draft

Story

As a 小程序开发者， I want 将配送地址管理模块从 packages/server/src 拆分到主项目的 packages 目录下作为独立 package， so that 项目可以按需引入配送地址管理功能，保持模块独立性和向后兼容性

Acceptance Criteria

  1. 创建 @d8d/delivery-address-module package，包含完整的配送地址管理功能
  2. 从 packages/server/src/modules/delivery-address 迁移配送地址服务代码
  3. 实现配送地址的完整CRUD功能，包括用户地址列表查询、默认地址设置等
  4. 提供完整的 TypeScript 类型定义和 API 文档
  5. 集成到现有的用户管理系统和地区管理系统
  6. 保持与现有认证系统的兼容性
  7. 提供单元测试和集成测试，覆盖率满足要求

Tasks / Subtasks

  • [ ] Task 1: 创建 delivery-address-module package 基础结构 (AC: 1)

    • 创建 packages/delivery-address-module 目录
    • 配置 package.json，参考广告模块的依赖版本 [Source: packages/advertisements-module/package.json#L47-L66]
    • 配置 tsconfig.json，参考广告模块配置 [Source: packages/advertisements-module/tsconfig.json#L1-L16]
    • 配置 vitest.config.ts，参考广告模块配置 [Source: packages/advertisements-module/vitest.config.ts#L1-L21]
    • 创建 src/index.ts 导出文件

  • [ ] Task 2: 迁移配送地址实体和类型定义 (AC: 2, 4)

    • 迁移 DeliveryAddress 实体到 packages/delivery-address-module/src/entities/
    • 迁移 DeliveryAddressSchema、CreateDeliveryAddressDto、UpdateDeliveryAddressDto 到 packages/delivery-address-module/src/schemas/
    • 创建类型定义文件 packages/delivery-address-module/src/types/delivery-address.types.ts
    • 更新实体导入路径，使用 workspace:* 依赖

  • [ ] Task 3: 迁移配送地址服务 (AC: 2, 3)

    • 迁移 DeliveryAddressService 到 packages/delivery-address-module/src/services/
    • 重构服务使用 shared-crud 基础设施
    • 确保 findByUser、setDefault、findDefaultByUser 方法正常工作
    • 更新服务依赖注入配置

  • [ ] Task 4: 创建配送地址路由 (AC: 3, 4)

    • 创建 packages/delivery-address-module/src/routes/index.ts
    • 实现配送地址的完整CRUD路由
    • 集成认证中间件
    • 配置用户追踪字段

  • [ ] Task 5: 集成到现有系统 (AC: 5, 6)

    • 更新 server package 依赖，添加 @d8d/delivery-address-module
    • 在 server 中注册配送地址路由
    • 验证与用户模块的集成
    • 验证与地区模块的集成

  • [ ] Task 6: 创建测试套件 (AC: 7)

    • 创建单元测试 packages/delivery-address-module/tests/unit/
    • 创建集成测试 packages/delivery-address-module/tests/integration/，参考广告模块集成测试结构 [Source: packages/advertisements-module/tests/integration/advertisements.integration.test.ts#L1-L50]
    • 配置测试数据库连接，使用 shared-test-util [Source: packages/shared-test-util/src/integration-test-db.ts#L1-L30]
    • 确保测试覆盖率满足要求

  • [ ] Task 7: 验证和文档 (AC: 4, 6)

    • 运行所有测试验证功能
    • 生成 API 文档
    • 更新 README.md 文档
    • 验证向后兼容性

Dev Notes

项目结构对齐

  • Package 位置: packages/delivery-address-module/ [Source: docs/architecture/source-tree.md#L207-L210]
  • 依赖层次: 业务模块层，依赖基础设施包 [Source: docs/architecture/source-tree.md#L249-L253]
  • 文件组织: 遵循模块化包架构模式 [Source: docs/architecture/source-tree.md#L237-L247]

技术栈要求

  • 运行时: Node.js 20.18.3 [Source: docs/architecture/tech-stack.md#L11]
  • 框架: Hono 4.8.5 [Source: docs/architecture/tech-stack.md#L12]
  • 数据库: PostgreSQL 17 + TypeORM 0.3.25 [Source: docs/architecture/tech-stack.md#L15-L16]
  • 测试框架: Vitest 3.2.4 [Source: docs/architecture/tech-stack.md#L24]

现有配送地址功能分析

  • 实体结构: DeliveryAddress 实体包含用户ID、姓名、手机号、详细地址、省市区街道ID、状态、默认地址等字段 [Source: packages/server/src/modules/delivery-address/delivery-address.entity.ts#L6-L71]
  • 服务方法:
    • findByUser(userId) - 获取用户地址列表 [Source: packages/server/src/modules/delivery-address/delivery-address.service.ts#L15-L21]
    • setDefault(id, userId) - 设置默认地址 [Source: packages/server/src/modules/delivery-address/delivery-address.service.ts#L29-L45]
    • findDefaultByUser(userId) - 获取用户默认地址 [Source: packages/server/src/modules/delivery-address/delivery-address.service.ts#L52-L57]
  • Schema 定义: 完整的 Zod Schema 验证规则 [Source: packages/server/src/modules/delivery-address/delivery-address.schema.ts#L18-L144]

依赖关系

  • 基础设施依赖:
    • @d8d/shared-types - 基础类型定义 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L269-L276]
    • @d8d/shared-utils - 工具函数 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L280-L291]
    • @d8d/shared-crud - CRUD基础设施 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L266-L278]
  • 业务模块依赖:
    • @d8d/user-module - 用户管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L321-L334]
    • @d8d/auth-module - 认证管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L337-L350]
  • 测试依赖: @d8d/shared-test-util [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L294-L306]

配置参考

  • package.json: 参考广告模块配置，统一依赖版本 [Source: packages/advertisements-module/package.json#L47-L66]
  • tsconfig.json: 参考广告模块配置 [Source: packages/advertisements-module/tsconfig.json#L1-L16]
  • vitest.config.ts: 参考广告模块配置 [Source: packages/advertisements-module/vitest.config.ts#L1-L21]
  • shared-test-util: 测试基础设施包，提供统一的测试工具 [Source: packages/shared-test-util/package.json#L1-L16]

测试要求

  • 测试位置: packages/delivery-address-module/tests/ [Source: docs/architecture/testing-strategy.md#L39-L42]
  • 测试类型: 单元测试 + 集成测试 [Source: docs/architecture/testing-strategy.md#L47-L56]
  • 覆盖率目标: 单元测试 ≥ 80%，集成测试 ≥ 60% [Source: docs/architecture/testing-strategy.md#L166-L171]
  • 测试框架: Vitest + shared-test-util [Source: docs/architecture/testing-strategy.md#L43-L44]
  • 集成测试参考: 参考广告模块集成测试结构和模式 [Source: packages/advertisements-module/tests/integration/advertisements.integration.test.ts#L1-L50]

向后兼容性

  • API 兼容: 现有配送地址API保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L101]
  • 数据库兼容: 数据库schema保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L102]
  • 认证兼容: 认证流程保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L103]

Testing

测试标准

  • 测试文件位置: packages/delivery-address-module/tests/ [Source: docs/architecture/testing-strategy.md#L39-L42]
  • 单元测试: tests/unit/**/*.test.ts [Source: docs/architecture/testing-strategy.md#L39-L42]
  • 集成测试: tests/integration/**/*.test.ts [Source: docs/architecture/testing-strategy.md#L47-L56]
  • 测试框架: Vitest 3.2.4 [Source: docs/architecture/testing-strategy.md#L43]

测试要求

  • 覆盖率目标: 单元测试 ≥ 80%，集成测试 ≥ 60% [Source: docs/architecture/testing-strategy.md#L166-L171]
  • 测试数据库: 使用专用测试数据库，事务回滚 [Source: docs/architecture/testing-strategy.md#L200-L202]
  • 测试模式: 遵循测试金字塔策略 [Source: docs/architecture/testing-strategy.md#L33-L64]

关键测试场景

  • 配送地址CRUD操作
  • 用户地址列表查询
  • 默认地址设置功能
  • 地址状态管理
  • 认证和权限验证

Change Log

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

Dev Agent Record

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

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

此部分由QA代理在质量审查后填写