Story 005.009: Delivery Address Module

Status

Draft

Story

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

Acceptance Criteria

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

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, 8)
- 迁移 DeliveryAddress 实体到 packages/delivery-address-module/src/entities/
- 将省市区字段从 City 实体关联更新为 AreaEntity 关联
- 更新实体字段映射，使用 AreaEntity 的 level 枚举
- 迁移 DeliveryAddressSchema、CreateDeliveryAddressDto、UpdateDeliveryAddressDto 到 packages/delivery-address-module/src/schemas/
- 创建类型定义文件 packages/delivery-address-module/src/types/delivery-address.types.ts
- 更新实体导入路径，使用 workspace:* 依赖
- 添加 @d8d/geo-areas 包依赖
[ ] Task 3: 迁移配送地址服务 (AC: 2, 3, 8)
- 迁移 DeliveryAddressService 到 packages/delivery-address-module/src/services/
- 重构服务使用 shared-crud 基础设施
- 集成 AreaService 用于省市区数据验证和查询
- 更新地址验证逻辑，使用 AreaEntity 的层级枚举
- 确保 findByUser、setDefault、findDefaultByUser 方法正常工作
- 更新服务依赖注入配置
[x] Task 4: 创建配送地址路由 (AC: 3, 4)
- 创建 packages/delivery-address-module/src/routes/index.ts
- 迁移配送地址的完整CRUD路由，使用 shared-crud 基础设施, 原文件 packages/server/src/api/delivery-address/index.ts
- 集成认证中间件
- 配置用户追踪字段
[x] Task 5: 创建当前用户权限API路由文件 (AC: 3, 4)
- 创建 packages/delivery-address-module/src/schemas/user-delivery-address.schema.ts - 用户专用schema
- 移除userId字段，自动使用当前登录用户ID
- 创建 packages/delivery-address-module/src/schemas/admin-delivery-address.schema.ts - 管理员专用schema
- 保留userId字段，允许管理员指定用户
- 创建 packages/delivery-address-module/src/routes/user-routes.ts - 仅限当前用户使用的路由
- 配置数据权限控制，使用 shared-crud 的 dataPermission 配置
- 设置 userIdField: 'userId'，确保用户只能操作自己的数据
- 使用用户专用schema
- 创建 packages/delivery-address-module/src/routes/admin-routes.ts - 管理员使用的完整权限路由
- 配置管理员路由不使用数据权限控制，保持完整CRUD功能
- 使用管理员专用schema
- 更新 packages/delivery-address-module/src/routes/index.ts 导出两个路由集合
- 验证用户路由只能访问和操作当前用户的数据
- 验证管理员路由可以访问所有用户的数据
[x] Task 6: 创建测试套件 (AC: 7, 8)
- 创建用户路由集成测试 packages/delivery-address-module/tests/integration/user-routes.integration.test.ts
- 测试用户路由只能访问和操作当前用户的数据
- 验证用户创建地址时自动使用当前用户ID
- 验证用户无法访问其他用户的数据
- 创建管理员路由集成测试 packages/delivery-address-module/tests/integration/admin-routes.integration.test.ts
- 测试管理员路由可以访问所有用户的数据
- 验证管理员可以为其他用户创建地址
- 验证管理员可以更新和删除任何用户的地址
- 配置测试数据库连接，使用 shared-test-util [Source: packages/shared-test-util/src/integration-test-db.ts#L1-L30]
- 添加省市区关联测试场景
- 测试地址创建时的地区验证逻辑
- 测试地址查询时的地区数据关联
- 确保测试覆盖率满足要求
[ ] Task 7: 集成到现有系统 (AC: 5, 6, 8)
- 更新 server package 依赖，添加 @d8d/delivery-address-module
- 在 server 中注册配送地址路由
- 验证与用户模块的集成
- 验证与 @d8d/geo-areas 包的集成
- 确保省市区数据关联正常工作
- 验证地址创建和更新时的地区验证
[ ] Task 8: 验证和文档 (AC: 4, 6)
- 运行所有测试验证功能
- 更新 docs/architecture/source-tree.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]

省市区迁移说明

从 City 实体迁移到 AreaEntity:
- 当前使用 City 实体管理省市区数据 [Source: packages/server/src/modules/system/city.entity.ts#L1-L34]
- 迁移到 @d8d/geo-areas 包的 AreaEntity [Source: packages/geo-areas/src/modules/areas/area.entity.ts#L1-L62]
- AreaEntity 提供更清晰的层级枚举：PROVINCE(1), CITY(2), DISTRICT(3) [Source: packages/geo-areas/src/modules/areas/area.entity.ts#L4-L8]
字段映射关系:
- receiver_province → 关联 AreaEntity.level = PROVINCE
- receiver_city → 关联 AreaEntity.level = CITY
- receiver_district → 关联 AreaEntity.level = DISTRICT
- receiver_town → 保留现有逻辑，可考虑扩展 AreaEntity.level = TOWN(4)
服务集成:
- 使用 AreaService 进行地区数据验证和查询 [Source: packages/geo-areas/src/modules/areas/area.service.ts#L1-L163]
- 支持树形结构查询和地区路径获取 [Source: packages/geo-areas/src/modules/areas/area.service.ts#L126-L145]

依赖关系

基础设施依赖:
- @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/geo-areas - 省市区管理 [Source: packages/geo-areas/package.json#L1-L71]
测试依赖: @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路由设计

用户路由: packages/delivery-address-module/src/routes/user-routes.ts - 仅限当前用户使用 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
管理员路由: packages/delivery-address-module/src/routes/admin-routes.ts - 管理员使用的完整权限路由 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
用户专用Schema: packages/delivery-address-module/src/schemas/user-delivery-address.schema.ts - 移除userId字段，自动使用当前登录用户ID
管理员专用Schema: packages/delivery-address-module/src/schemas/admin-delivery-address.schema.ts - 保留userId字段，允许管理员指定用户
数据权限配置: 使用 shared-crud 的 dataPermission 配置 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L22-L25]
权限字段: 设置 userIdField: 'userId' 确保用户只能操作自己的数据 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L26-L33]
权限验证: 查询、创建、更新、删除操作都会验证用户权限 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L26-L41]

向后兼容性

API 兼容: 现有配送地址API保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L101]
数据库兼容: 数据库schema保持不变 [Source: docs/prd/epic-005-minim-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操作
用户地址列表查询
默认地址设置功能
地址状态管理
认证和权限验证
省市区数据关联验证
地区层级关系验证
地址创建时的地区验证逻辑
用户路由权限测试:
- 验证用户只能访问和操作自己的数据
- 验证用户创建地址时自动使用当前用户ID
- 验证用户无法访问其他用户的数据
- 验证用户无法更新其他用户的地址
- 验证用户无法删除其他用户的地址
管理员路由权限测试:
- 验证管理员可以访问所有用户的数据
- 验证管理员可以为其他用户创建地址
- 验证管理员可以更新任何用户的地址
- 验证管理员可以删除任何用户的地址
数据权限配置测试: 验证 dataPermission 配置正确工作

Change Log

Date	Version	Description	Author
2025-11-11	1.0	初始故事创建	Bob (Scrum Master)
2025-11-11	1.1	更新省市区关联，集成 @d8d/geo-areas 包	Bob (Scrum Master)
2025-11-11	1.2	添加当前用户权限API路由文件任务，支持admin/user分离路由和schema	Bob (Scrum Master)
2025-11-11	1.3	完成测试套件创建，修复路由和地区验证问题	Claude Code

Dev Agent Record

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

Agent Model Used

James (Developer Agent)

Debug Log References

修复了geo-areas包中AreaSchema导入问题，改为getAreaSchema

Completion Notes List

Task 4 已完成：成功创建配送地址路由，使用shared-crud基础设施
路由文件已正确配置认证中间件和用户追踪字段
类型检查通过，所有依赖导入正确
Task 5 已完成：成功创建用户权限API路由文件
用户专用schema移除userId字段，自动使用当前登录用户ID
管理员专用schema保留userId字段，允许管理员指定用户
用户路由配置数据权限控制，确保用户只能操作自己的数据
管理员路由不使用数据权限控制，保持完整CRUD功能
路由导出文件已更新，支持两个路由集合导出
Task 6 已完成：成功创建完整的测试套件
修复了用户路由集成测试中的schema字段不匹配问题
修复了管理员路由集成测试中的userId字段覆盖问题
创建了自定义管理员路由（admin-custom.routes.ts）集成地区验证
增强了地区验证逻辑，支持地区层级关系验证
所有集成测试通过，覆盖了用户权限、管理员权限、地区验证等关键场景

File List

packages/delivery-address-module/src/routes/index.ts (新建)
packages/delivery-address-module/src/schemas/user-delivery-address.schema.ts (新建)
packages/delivery-address-module/src/schemas/admin-delivery-address.schema.ts (新建)
packages/delivery-address-module/src/routes/user-routes.ts (新建)
packages/delivery-address-module/src/routes/admin-routes.ts (新建)
packages/delivery-address-module/src/routes/admin-custom.routes.ts (新建)
packages/delivery-address-module/tests/integration/user-routes.integration.test.ts (新建)
packages/delivery-address-module/tests/integration/admin-routes.integration.test.ts (新建)

QA Results

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

005.009.delivery-address-module.story.md 16 KB Cronologia Originale

Story 005.009: Delivery Address Module

Status

Story

Acceptance Criteria

Tasks / Subtasks

Dev Notes

项目结构对齐

技术栈要求

现有配送地址功能分析

省市区迁移说明

依赖关系

配置参考

测试要求

当前用户权限API路由设计

向后兼容性

Testing

测试标准

测试要求

关键测试场景

Change Log

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

005.009.delivery-address-module.story.md 16 KB

Cronologia Originale