mini-starter/docs/stories/005.002.geo-areas-module.md

Story 005.002: Geo Areas Module

Status

Ready for Review

Story

As a 系统架构师, I want 从 mini-auth-demo/packages/server/src 拆分反哺省市区三级联动数据管理和API, so that 实现独立的地区模块包，为项目提供完整的中国行政区划管理功能

Acceptance Criteria

1. 创建 geo-areas package 包配置和目录结构
2. 迁移地区实体类 (AreaEntity) 和枚举定义 (AreaLevel)
3. 迁移地区服务类 (AreaService) 和业务逻辑
4. 迁移地区 Schema 定义和验证规则
5. 迁移地区 API 路由 (公共接口和管理接口)
6. 配置 TypeScript 编译选项 (包含 "composite": true)
7. 编写单元测试和集成测试
8. 配置 pnpm workspace 依赖关系
9. 验证依赖版本与 packages/server 保持一致
10. 所有测试通过，覆盖率满足要求

Tasks / Subtasks

第一阶段：包基础设施创建

• 创建 geo-areas package 目录结构 (AC: 1)
  • 创建 packages/geo-areas/package.json 配置
  • 创建 packages/geo-areas/tsconfig.json TypeScript 配置
  • 创建 packages/geo-areas/vitest.config.ts 测试配置
  • 创建 packages/geo-areas/src/index.ts 包入口

第二阶段：实体和服务迁移

• 迁移地区实体类 (AC: 2)
  • 迁移 AreaEntity 实体类
  • 迁移 AreaLevel 枚举定义
  • 更新导入路径和依赖
• 迁移地区服务类 (AC: 3)
  • 迁移 AreaService 服务类
  • 重构数据库连接使用 shared-utils
  • 更新服务依赖关系

第三阶段：Schema 和验证迁移

• 迁移地区 Schema 定义 (AC: 4)
  • 迁移所有 Zod Schema 定义
  • 迁移输入/输出类型定义
  • 更新 Schema 导入路径

第四阶段：API 路由迁移

• 迁移公共地区 API 路由 (AC: 5)
  • 迁移 /api/areas 路由 (省份、城市、区县查询)
  • 更新路由导入和服务依赖
• 迁移管理地区 API 路由 (AC: 5)
  • 迁移 /api/admin/areas 路由 (CRUD 操作)
  • 迁移树形结构查询路由
  • 更新认证中间件依赖

第五阶段：测试和验证

• 迁移现有集成测试 (AC: 7)
  • 迁移 mini-auth-demo/web/tests/integration/server/api/areas/index.test.ts
  • 使用 shared-test-util 测试工具
  • 更新测试导入路径和依赖
  • 验证迁移后的测试通过
• 创建管理地区 API 集成测试 (AC: 7)
  • 创建 tests/integration/admin-areas.integration.test.ts
  • 参考用户模块测试结构
  • 包含认证测试、CRUD操作测试、树形结构查询测试
  • 验证管理 API 完整功能
• 验证依赖版本对齐 (AC: 9)
  • 检查所有外部依赖版本与 packages/server 保持一致
  • 验证关键依赖版本完全一致

第六阶段：集成和验证

• 配置 pnpm workspace 依赖关系 (AC: 8)
  • 更新根目录 package.json workspace 配置
  • 配置 geo-areas package 依赖关系
  • 验证依赖解析正确
• 执行回归测试 (AC: 10)
  • 运行所有单元测试
  • 运行集成测试
  • 验证现有功能无回归

Dev Notes

技术架构信息

• 项目技术栈: Node.js 20.19.2 + TypeScript + Hono + TypeORM + PostgreSQL [Source: architecture/tech-stack.md#现有技术栈维护]
• 包管理: pnpm workspace [Source: architecture/source-tree.md#包管理]
• 模块化架构: 遵循现有的基础设施包结构 [Source: architecture/source-tree.md#项目结构]

现有代码结构参考

• 当前地区模块位置: mini-auth-demo/packages/server/src/modules/areas/
  • area.entity.ts - 地区实体 (省市区三级树形结构)
  • area.service.ts - 地区服务 (树形查询、路径查询、层级查询)
  • area.schema.ts - 地区 Schema 定义和验证规则
• 当前 API 路由位置:
  • mini-auth-demo/packages/server/src/api/areas/index.ts - 公共地区 API
  • mini-auth-demo/packages/server/src/api/admin/areas/index.ts - 管理地区 API
  • mini-auth-demo/packages/server/src/api/admin/areas/tree.ts - 树形结构 API
• 当前集成测试位置:
  • mini-auth-demo/web/tests/integration/server/api/areas/index.test.ts - 公共地区 API 集成测试
  • 测试省份查询 API (/areas/provinces)
  • 测试城市查询 API (/areas/cities)
  • 测试区县查询 API (/areas/districts)
  • 包含禁用状态过滤验证

Package 配置要求

• 所有 package 使用 TypeScript 编译 [Source: architecture/coding-standards.md#现有标准合规性]
• 遵循现有的代码风格和命名规范 [Source: architecture/coding-standards.md#现有标准合规性]
• 提供完整的类型定义导出
• 配置适当的构建脚本
• 依赖版本对齐: 所有外部依赖版本必须与 packages/server 保持一致
• TypeScript 配置: tsconfig.json 必须设置 "composite": true
• Package 输出配置: package.json 中的 "main"、"types" 和 "exports" 必须指向 src 目录

依赖关系设计

// geo-areas package.json 依赖关系
{
  "name": "@d8d/geo-areas",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/shared-crud": "workspace:*",
    "typeorm": "^0.3.20"
  },
  "devDependencies": {
    "@d8d/shared-test-util": "workspace:*"
  }
}

关键依赖版本对齐要求

必须与 packages/server 完全一致的依赖版本： [Source: architecture/tech-stack.md#现有技术栈维护]

• typeorm: ^0.3.20
• hono: ^4.8.5
• zod: ^4.1.12
• @hono/zod-openapi: 1.0.2

测试标准

• 测试框架: Vitest [Source: architecture/testing-strategy.md#测试金字塔策略]
• 测试位置: packages/geo-areas/tests/ 目录 [Source: architecture/testing-strategy.md#测试位置]
  • tests/unit/ - 单元测试
  • tests/integration/ - 集成测试
• 测试要求: 单元测试覆盖核心功能，集成测试验证包间协作 [Source: architecture/testing-strategy.md#测试金字塔策略]
• 测试执行: pnpm test 在 geo-areas package 中运行
• 测试覆盖率目标: [Source: architecture/testing-strategy.md#测试覆盖率标准]
  • 单元测试: ≥ 80%
  • 集成测试: ≥ 60%
  • 关键模块 (地区服务、API路由): ≥ 90%

向后兼容性保证

• 现有 API 接口保持不变
• 数据库操作逻辑保持一致
• 错误响应格式保持不变
• 仅重构内部实现，不改变外部行为

Testing

测试框架和位置 [Source: architecture/testing-strategy.md#测试金字塔策略]

• 测试框架: Vitest + hono/testing
• 测试位置: packages/geo-areas/tests/
  • tests/unit/ - 单元测试
  • tests/integration/ - 集成测试

测试标准和覆盖率要求 [Source: architecture/testing-strategy.md#测试覆盖率标准]

• 单元测试覆盖率: ≥ 80%
• 集成测试覆盖率: ≥ 60%
• 关键模块覆盖率: ≥ 90%

测试数据管理 [Source: architecture/testing-strategy.md#测试数据管理]

• 使用测试数据工厂模式
• 集成测试使用专用测试数据库，事务回滚
• 单元测试使用内存数据库或完全 mock

API 测试要求 [Source: architecture/testing-strategy.md#安全测试策略]

• 所有 API 端点必须测试输入验证
• 测试认证和权限控制
• 测试错误处理场景

Change Log

Date	Version	Description	Author
2025-11-10	1.0	创建地区模块包故事草稿	Bob (Scrum Master)

Dev Agent Record

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

Agent Model Used

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

Debug Log References

• 成功创建 geo-areas 包完整结构
• 验证所有依赖版本与 packages/server 完全一致
• 集成测试全部通过 (9/9)
• 重构 AreaService 使用依赖注入模式

Completion Notes List

1. ✅ 创建完整的 geo-areas 包目录结构
2. ✅ 迁移 AreaEntity 和 AreaLevel 枚举定义
3. ✅ 迁移 AreaService 服务类，使用依赖注入
4. ✅ 迁移所有 Zod Schema 定义和验证规则
5. ✅ 迁移公共地区 API 路由 (/api/areas)
6. ✅ 迁移管理地区 API 路由 (/api/admin/areas)
7. ✅ 配置 TypeScript 编译选项 (包含 "composite": true)
8. ✅ 迁移集成测试文件，使用 shared-test-util 包
9. ✅ 验证依赖版本完全对齐
10. ✅ 所有测试通过，功能验证完整

File List

• packages/geo-areas/package.json - 包配置
• packages/geo-areas/tsconfig.json - TypeScript 配置
• packages/geo-areas/vitest.config.ts - 测试配置
• packages/geo-areas/src/index.ts - 包入口
• packages/geo-areas/src/modules/areas/area.entity.ts - 地区实体
• packages/geo-areas/src/modules/areas/area.service.ts - 地区服务
• packages/geo-areas/src/modules/areas/area.schema.ts - 地区 Schema
• packages/geo-areas/src/api/areas/index.ts - 公共地区 API
• packages/geo-areas/src/api/admin/areas/index.ts - 管理地区 API
• packages/geo-areas/tests/integration/areas.integration.test.ts - 集成测试
• packages/geo-areas/tests/integration/admin-areas.integration.test.ts - 集成测试
• packages/geo-areas/tests/utils/test-data-factory.ts - 测试数据工厂
• packages/geo-areas/tests/utils/integration-test-utils.ts - 测试工具

QA Results

此部分由 QA 代理在完成故事实现后填写