📝 docs(prd): add area entity design and update version history

- add version 1.9 record with area entity design changes
- add detailed area entity design scheme including problem identification, optimization plan, entity structure, and API design
- add advantages of standardized area data management

📝 docs(story): update story 5.1 with area management tasks

- update task list to include area entity creation and management
- add area management API implementation tasks
- add area management page implementation tasks
- add area-related test tasks
- update change log with area entity design changes
- add area entity related file list

docs/prd/epic-005-travel-service-core.md

@@ -3,6 +3,7 @@
 ## 版本信息
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
+| 1.9 | 2025-10-17 | 添加省市区实体设计方案，支持标准化行政区划数据管理 | John (PM) |
 | 1.8 | 2025-10-17 | 采用地点实体方案，统一管理地点信息，支持省市区查询 | John (PM) |
 | 1.7 | 2025-10-17 | 优化查询逻辑，明确通过路线查询活动的实现方式 | John (PM) |
 | 1.6 | 2025-10-17 | 优化活动实体设计，添加举办地点字段，去程/返程动态判断 | John (PM) |
@@ -229,6 +230,79 @@ mini-demo包含14个页面，Epic 005将页面迁移作为用户故事的具体
 └── 其他信息...
 ```
 
+### 省市区实体设计方案
+基于发现的省市区数据文件，需要实现标准化的省市区数据管理：
+
+**问题识别**:
+- 当前地点实体中的省市区字段为自由文本，缺乏标准化
+- 无法支持省市区三级联动选择
+- 地点查询时无法按标准行政区划进行精确筛选
+- 缺乏完整的省市区数据支持
+
+**优化方案**:
+- **创建省市区实体(AreaEntity)**: 标准化管理省市区三级数据
+- **Location实体关联Area**: 通过province、city、district字段关联AreaEntity
+- **预置完整数据**: 使用现有的省市区CSV文件初始化数据
+- **支持三级联动**: 前端组件支持省市区联动选择
+
+**省市区实体设计**:
+```
+省市区 (Area)
+├── ID (id) - 主键
+├── 父级ID (parentId) - 关联父级区域，0表示顶级（省/直辖市）
+├── 名称 (name) - 区域名称
+├── 层级 (level) - 1:省/直辖市, 2:市, 3:区/县
+├── 代码 (code) - 行政区划代码
+├── 创建时间 (createdAt)
+└── 更新时间 (updatedAt)
+```
+
+**数据来源和使用**:
+- **数据文件**: `scripts/省市区.csv` (包含3282条完整记录)
+- **生成脚本**: `scripts/generate-area-sql.mjs` (CSV转SQL导入脚本)
+- **初始化**: 通过数据库迁移预置完整的省市区数据
+- **更新机制**: 支持后续行政区划变更的增量更新
+
+**地点实体优化**:
+```
+地点 (Location)
+├── 名称 (name)
+├── 省份 (province) → 关联AreaEntity (level=1)
+├── 城市 (city) → 关联AreaEntity (level=2)
+├── 区县 (district) → 关联AreaEntity (level=3)
+├── 详细地址 (address)
+├── 纬度 (latitude)
+└── 经度 (longitude)
+```
+
+**省市区查询逻辑设计**:
+- **获取省份列表**: 查询level=1的区域
+- **获取城市列表**: 根据省份ID查询level=2的子区域
+- **获取区县列表**: 根据城市ID查询level=3的子区域
+- **地点关联查询**: 通过省市区ID精确关联地点
+
+**API设计示例**:
+```typescript
+// 获取省份列表
+GET /api/v1/areas/provinces
+
+// 获取城市列表
+GET /api/v1/areas/cities?provinceId=1
+
+// 获取区县列表
+GET /api/v1/areas/districts?cityId=34
+
+// 地点查询（支持省市区筛选）
+GET /api/v1/locations?provinceId=1&cityId=34&districtId=36
+```
+
+**优势**:
+- **数据标准化**: 统一的省市区数据源，避免数据不一致
+- **查询优化**: 支持精确的省市区筛选和关联查询
+- **用户体验**: 前端组件支持省市区三级联动选择
+- **扩展性**: 支持行政区划变更和新增区域
+- **维护性**: 集中管理省市区数据，便于更新和维护
+
 ### 查询逻辑设计
 基于优化的数据模型，查询逻辑需要相应调整：
 

docs/stories/005.001.story.md

@@ -20,37 +20,83 @@ Approve
   - [x] 在 `src/server/modules/routes/` 创建 `route.entity.ts`
   - [x] 在 `src/server/modules/activities/` 创建 `activity.entity.ts`
   - [x] 在 `src/share/` 创建相关类型定义
-- [ ] 创建地点实体和关联关系 (AC: 5)
+- [ ] 创建省市区实体和关联关系 (AC: 5)
+  - [ ] 在 `src/server/modules/areas/` 创建 `area.entity.ts`
   - [ ] 在 `src/server/modules/locations/` 创建 `location.entity.ts`
   - [ ] 更新ActivityEntity，添加venueLocation字段关联LocationEntity
   - [ ] 更新RouteEntity，添加startLocation和endLocation字段关联LocationEntity
-  - [ ] 在 `src/share/` 创建地点相关类型定义
+  - [ ] 在 `src/share/` 创建省市区和地点相关类型定义
 - [x] 创建Zod Schema (AC: 1, 2, 3, 4)
   - [x] 在 `src/server/modules/routes/` 创建 `route.schema.ts` (创建、更新、获取、列表Schema)
   - [x] 在 `src/server/modules/activities/` 创建 `activity.schema.ts` (创建、更新、获取、列表Schema)
   - [x] 验证Schema符合业务逻辑约束
-- [ ] 创建地点Zod Schema (AC: 5)
+- [ ] 创建省市区Zod Schema (AC: 5)
+  - [ ] 在 `src/server/modules/areas/` 创建 `area.schema.ts` (创建、更新、获取、列表Schema)
   - [ ] 在 `src/server/modules/locations/` 创建 `location.schema.ts` (创建、更新、获取、列表Schema)
   - [ ] 更新Activity和Route的Schema，支持地点关联
-  - [ ] 验证地点Schema符合业务逻辑约束
+  - [ ] 验证省市区和地点Schema符合业务逻辑约束
 - [x] 数据库迁移和种子数据 (AC: 1, 2, 3, 4)
   - [x] 创建数据库迁移文件，添加活动、路线相关表结构
   - [x] 创建种子数据，添加示例活动和路线数据
   - [x] 验证数据库迁移和种子数据正确性
-- [ ] 地点数据库迁移和种子数据 (AC: 5)
+- [ ] 省市区数据库迁移和种子数据 (AC: 5)
+  - [ ] 创建数据库迁移文件，添加省市区表结构
   - [ ] 创建数据库迁移文件，添加地点表结构
   - [ ] 更新活动和路线表，添加地点关联字段
+  - [ ] 使用 `scripts/generate-area-sql.mjs` 生成省市区种子数据
   - [ ] 创建种子数据，添加示例地点数据
-  - [ ] 验证地点数据库迁移和种子数据正确性
+  - [ ] 验证省市区和地点数据库迁移和种子数据正确性
 - [x] 实现管理后台API (AC: 1, 2, 3, 4)
   - [x] 在 `src/server/api/admin/activities/index.ts` 使用 `createCrudRoutes` 创建活动管理API
   - [x] 在 `src/server/api/admin/routes/index.ts` 使用 `createCrudRoutes` 创建路线管理API
   - [x] 配置搜索字段、关联关系、筛选条件
   - [x] 实现启用/禁用功能
+- [ ] 实现省市区管理API (AC: 5)
+  - [ ] 在 `src/server/api/admin/areas/index.ts` 使用 `createCrudRoutes` 创建省市区管理API
+  - [ ] 配置搜索字段、筛选条件（层级、父级ID）
+  - [ ] 实现省市区层级查询API（省份列表、城市列表、区县列表）
+  - [ ] 配置省市区树形结构查询API
+  - [ ] 实现省市区三级联动查询API（根据省份获取城市，根据城市获取区县）
+  - [ ] 实现省市区完整层级路径查询API（根据区县ID获取完整省市区路径）
 - [ ] 实现地点管理API (AC: 5)
   - [ ] 在 `src/server/api/admin/locations/index.ts` 使用 `createCrudRoutes` 创建地点管理API
   - [ ] 配置搜索字段、关联关系、筛选条件
   - [ ] 更新活动和路线API，支持地点关联查询
+  - [ ] 支持按省市区筛选地点
+
+- [ ] 实现省市区管理页面 (AC: 5)
+  - [ ] 创建省市区管理页面 - 省市区数据配置和管理
+  - [ ] 实现省市区管理页面的搜索和筛选功能
+  - [ ] 实现省市区创建和编辑表单
+  - [ ] 支持省市区层级展示和树形结构
+  - [ ] 实现省市区三级联动选择组件
+
+- [ ] 实现地点管理页面 (AC: 5)
+  - [ ] 创建地点管理页面 - 地点信息配置和管理
+  - [ ] 实现地点管理页面的搜索和筛选功能
+  - [ ] 实现地点创建和编辑表单
+  - [ ] 更新活动和路线表单，支持地点选择组件
+  - [ ] 支持按省市区筛选地点列表
+
+- [ ] 编写地点管理测试 (AC: 5)
+  - [ ] 管理后台API集成测试 (`tests/integration/server/`)
+    - [ ] 地点管理API CRUD操作测试 (P0)
+    - [ ] 地点搜索和筛选功能测试 (P1)
+    - [ ] 地点关联关系测试 (P1)
+  - [ ] 管理后台页面组件测试 (`tests/integration/client/`)
+    - [ ] LocationManagementPage组件测试 (P1)
+    - [ ] LocationForm组件测试 (P1)
+    - [ ] LocationSelect组件测试 (P1)
+  - [ ] E2E测试 (`tests/e2e/specs/admin/`)
+    - [ ] 地点管理E2E测试 (P1)
+
+- [ ] 实现地点选择组件 (AC: 5)
+  - [ ] 创建LocationSelect组件，支持地点搜索和选择
+  - [ ] 在ActivityForm中集成LocationSelect组件，选择举办地点
+  - [ ] 在RouteForm中集成LocationSelect组件，选择出发地和目的地
+  - [ ] 实现地点搜索功能，支持按名称、省份、城市搜索
+  - [ ] 实现地点列表展示，显示地点名称和完整地址
+  - [ ] 添加地点选择验证
 - [x] 实现管理后台页面 (AC: 1, 2, 3, 4)
   - [x] 创建活动管理页面 - 活动类型配置和管理
   - [x] 创建路线管理页面 - 路线信息配置和管理
@@ -59,11 +105,18 @@ Approve
   - [x] 实现活动创建和编辑表单
   - [x] 实现路线创建和编辑表单
   - [x] 实现启用/禁用功能
+- [ ] 实现省市区管理页面 (AC: 5)
+  - [ ] 创建省市区管理页面 - 省市区数据配置和管理
+  - [ ] 实现省市区管理页面的搜索和筛选功能
+  - [ ] 实现省市区创建和编辑表单
+  - [ ] 支持省市区层级展示和树形结构
+  - [ ] 实现省市区三级联动选择组件
 - [ ] 实现地点管理页面 (AC: 5)
   - [ ] 创建地点管理页面 - 地点信息配置和管理
   - [ ] 实现地点管理页面的搜索和筛选功能
   - [ ] 实现地点创建和编辑表单
   - [ ] 更新活动和路线表单，支持地点选择组件
+  - [ ] 支持按省市区筛选地点列表
 - [x] 编写测试 (AC: 1, 2, 3, 4)
   - [x] 管理后台API集成测试 (`tests/integration/server/`)
     - [x] 活动管理API CRUD操作测试 (P0)
@@ -432,6 +485,7 @@ const debouncedSearch = useCallback(
 ## Change Log
 | Date | Version | Description | Author |
 |------|---------|-------------|--------|
+| 2025-10-17 | 4.0 | 添加省市区实体设计方案，支持省市区三级联动数据管理，完善地点管理任务 | James (Dev Agent) |
 | 2025-10-17 | 3.0 | 添加地点实体设计方案，支持省市区结构化地址管理，优化活动实体设计 | John (PM) |
 | 2025-10-16 | 2.0 | 修复TypeScript类型错误，提升代码质量：修复Schema定义、枚举类型、filters参数格式，移除所有any类型使用 | James (Dev Agent) |
 | 2025-10-16 | 1.9 | 完成活动管理和路线管理E2E测试，实现完整的测试覆盖 | James (Dev Agent) |
@@ -462,6 +516,11 @@ Claude Sonnet 4.5 (2025-09-29)
 - 优化活动实体设计，添加venueLocation字段关联LocationEntity
 - 优化路线实体设计，添加startLocation和endLocation字段关联LocationEntity
 - 设计去程/返程动态判断逻辑：目的地=活动地点为去程，出发地=活动地点为返程
+- 发现省市区数据文件（scripts/省市区.csv），确认需要省市区实体（AreaEntity）
+- 设计省市区实体方案，支持省市区三级联动数据管理
+- 更新PRD文档，添加完整的省市区实体设计方案
+- 更新故事5.1，添加完整的省市区管理任务结构
+- 设计省市区API，支持三级联动查询和完整层级路径查询
 
 ### Completion Notes List
 ✅ **已完成的任务:**
@@ -572,6 +631,18 @@ Claude Sonnet 4.5 (2025-09-29)
 - [tests/integration/server/admin/activities.integration.test.ts](tests/integration/server/admin/activities.integration.test.ts) - 修复类型错误，移除any类型使用
 - [tests/integration/server/admin/routes.integration.test.ts](tests/integration/server/admin/routes.integration.test.ts) - 修复类型错误，移除any类型使用
 
+**省市区实体设计相关文件:**
+- [docs/prd/epic-005-travel-service-core.md](docs/prd/epic-005-travel-service-core.md) - 添加省市区实体设计方案
+- [scripts/省市区.csv](scripts/省市区.csv) - 完整的省市区数据文件（3282条记录）
+- [scripts/generate-area-sql.mjs](scripts/generate-area-sql.mjs) - 省市区SQL生成脚本
+- [src/server/modules/areas/area.entity.ts](src/server/modules/areas/area.entity.ts) - 省市区实体定义（待创建）
+- [src/server/modules/locations/location.entity.ts](src/server/modules/locations/location.entity.ts) - 地点实体定义（待创建）
+- [src/server/modules/areas/area.schema.ts](src/server/modules/areas/area.schema.ts) - 省市区Zod Schema（待创建）
+- [src/server/modules/locations/location.schema.ts](src/server/modules/locations/location.schema.ts) - 地点Zod Schema（待创建）
+- [src/server/api/admin/areas/index.ts](src/server/api/admin/areas/index.ts) - 省市区管理API（待创建）
+- [src/share/area.types.ts](src/share/area.types.ts) - 省市区相关类型定义（待创建）
+- [src/share/location.types.ts](src/share/location.types.ts) - 地点相关类型定义（待创建）
+
 ## QA Results
 
 ### 测试设计审查 (2025-10-16)