# 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. 提供单元测试和集成测试，覆盖率满足要求
8. 将省市区字段从旧的 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)
  - [x] 创建 packages/delivery-address-module/src/routes/index.ts
  - [x] 迁移配送地址的完整CRUD路由，使用 shared-crud 基础设施, 原文件 packages/server/src/api/delivery-address/index.ts
  - [x] 集成认证中间件
  - [x] 配置用户追踪字段

- [x] Task 5: 创建当前用户权限API路由文件 (AC: 3, 4)
  - [x] 创建 packages/delivery-address-module/src/schemas/user-delivery-address.schema.ts - 用户专用schema
  - [x] 移除userId字段，自动使用当前登录用户ID
  - [x] 创建 packages/delivery-address-module/src/schemas/admin-delivery-address.schema.ts - 管理员专用schema
  - [x] 保留userId字段，允许管理员指定用户
  - [x] 创建 packages/delivery-address-module/src/routes/user-routes.ts - 仅限当前用户使用的路由
  - [x] 配置数据权限控制，使用 shared-crud 的 dataPermission 配置
  - [x] 设置 userIdField: 'userId'，确保用户只能操作自己的数据
  - [x] 使用用户专用schema
  - [x] 创建 packages/delivery-address-module/src/routes/admin-routes.ts - 管理员使用的完整权限路由
  - [x] 配置管理员路由不使用数据权限控制，保持完整CRUD功能
  - [x] 使用管理员专用schema
  - [x] 更新 packages/delivery-address-module/src/routes/index.ts 导出两个路由集合
  - [x] 验证用户路由只能访问和操作当前用户的数据
  - [x] 验证管理员路由可以访问所有用户的数据

- [x] Task 6: 创建测试套件 (AC: 7, 8)
  - [x] 创建用户路由集成测试 packages/delivery-address-module/tests/integration/user-routes.integration.test.ts
  - [x] 测试用户路由只能访问和操作当前用户的数据
  - [x] 验证用户创建地址时自动使用当前用户ID
  - [x] 验证用户无法访问其他用户的数据
  - [x] 创建管理员路由集成测试 packages/delivery-address-module/tests/integration/admin-routes.integration.test.ts
  - [x] 测试管理员路由可以访问所有用户的数据
  - [x] 验证管理员可以为其他用户创建地址
  - [x] 验证管理员可以更新和删除任何用户的地址
  - [x] 配置测试数据库连接，使用 shared-test-util [Source: packages/shared-test-util/src/integration-test-db.ts#L1-L30]
  - [x] 添加省市区关联测试场景
  - [x] 测试地址创建时的地区验证逻辑
  - [x] 测试地址查询时的地区数据关联
  - [x] 确保测试覆盖率满足要求

- [ ] 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代理在质量审查后填写*