# 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

### 第一阶段：包基础设施创建
- [x] 创建 geo-areas package 目录结构 (AC: 1)
  - [x] 创建 `packages/geo-areas/package.json` 配置
  - [x] 创建 `packages/geo-areas/tsconfig.json` TypeScript 配置
  - [x] 创建 `packages/geo-areas/vitest.config.ts` 测试配置
  - [x] 创建 `packages/geo-areas/src/index.ts` 包入口

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

### 第三阶段：Schema 和验证迁移
- [x] 迁移地区 Schema 定义 (AC: 4)
  - [x] 迁移所有 Zod Schema 定义
  - [x] 迁移输入/输出类型定义
  - [x] 更新 Schema 导入路径

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

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

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

## 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` 目录

### 依赖关系设计
```json
// 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 代理在完成故事实现后填写*