📝 docs(requirements): update travel service core requirements and design

- add new acceptance criteria: route type dynamic judgment, area three-level linkage, multi-dimensional query
- update data entity design with detailed field definitions for Area and Location entities
- enhance route query logic with round trip identification and area-based filtering
- add user-side route search API design and implementation details
- update task lists to include new features and corresponding test cases
- expand test strategy with new P0/P1/P2 test items for new functionality
- add business logic implementation details for route type judgment
- update API filter configurations to support route type filtering

docs/stories/005.001.story.md

@@ -14,18 +14,25 @@ Approve
 3. 支持设置活动关联的路线
 4. 支持启用/禁用活动、路线
 5. 支持创建和管理地点信息（名称、省份、城市、区县、详细地址、经纬度）
+6. 支持去程/返程路线动态判断：目的地=活动地点为去程，出发地=活动地点为返程
+7. 支持省市区三级联动查询和选择
+8. 支持按省市区多维度查询地点和路线
 
 ## Tasks / Subtasks
 - [x] 创建基础数据实体 (AC: 1, 2, 3)
   - [x] 在 `src/server/modules/routes/` 创建 `route.entity.ts`
   - [x] 在 `src/server/modules/activities/` 创建 `activity.entity.ts`
   - [x] 在 `src/share/` 创建相关类型定义
-- [ ] 创建省市区实体和关联关系 (AC: 5)
+- [ ] 创建省市区实体和关联关系 (AC: 5, 7, 8)
   - [ ] 在 `src/server/modules/areas/` 创建 `area.entity.ts`
   - [ ] 在 `src/server/modules/locations/` 创建 `location.entity.ts`
   - [ ] 更新ActivityEntity，添加venueLocation字段关联LocationEntity
   - [ ] 更新RouteEntity，添加startLocation和endLocation字段关联LocationEntity
   - [ ] 在 `src/share/` 创建省市区和地点相关类型定义
+  - [ ] 在 `src/server/modules/routes/route.service.ts` 中实现去程/返程动态判断逻辑
+  - [ ] 在Route实体中添加 `routeType` 计算字段，根据活动地点关系自动判断类型
+  - [ ] 在路线查询API中集成去程/返程筛选功能
+  - [ ] 在管理后台路线列表页面显示路线类型（去程/返程）
 - [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)
@@ -51,18 +58,31 @@ Approve
   - [x] 在 `src/server/api/admin/routes/index.ts` 使用 `createCrudRoutes` 创建路线管理API
   - [x] 配置搜索字段、关联关系、筛选条件
   - [x] 实现启用/禁用功能
-- [ ] 实现省市区管理API (AC: 5)
+- [ ] 实现省市区管理API (AC: 5, 7, 8)
   - [ ] 在 `src/server/api/admin/areas/index.ts` 使用 `createCrudRoutes` 创建省市区管理API
   - [ ] 配置搜索字段、筛选条件（层级、父级ID）
   - [ ] 实现省市区层级查询API（省份列表、城市列表、区县列表）
   - [ ] 配置省市区树形结构查询API
   - [ ] 实现省市区三级联动查询API（根据省份获取城市，根据城市获取区县）
   - [ ] 实现省市区完整层级路径查询API（根据区县ID获取完整省市区路径）
-- [ ] 实现地点管理API (AC: 5)
+  - [ ] 实现省市区查询端点：
+    - `GET /api/v1/areas/provinces` - 获取省份列表
+    - `GET /api/v1/areas/cities?provinceId=1` - 获取城市列表
+    - `GET /api/v1/areas/districts?cityId=34` - 获取区县列表
+- [ ] 实现地点管理API (AC: 5, 8)
   - [ ] 在 `src/server/api/admin/locations/index.ts` 使用 `createCrudRoutes` 创建地点管理API
   - [ ] 配置搜索字段、关联关系、筛选条件
   - [ ] 更新活动和路线API，支持地点关联查询
   - [ ] 支持按省市区筛选地点
+  - [ ] 支持地点名称模糊搜索
+  - [ ] 支持按省市区多维度查询地点
+- [ ] 实现用户端路线查询API (AC: 6, 7, 8)
+  - [ ] 在 `src/server/api/routes/index.ts` 中实现路线搜索API
+  - [ ] 支持按出发地、目的地、日期查询路线
+  - [ ] 支持按路线类型（去程/返程）筛选
+  - [ ] 支持按价格、出发时间排序
+  - [ ] 返回包含关联活动信息的路线列表
+  - [ ] 实现去重后的活动列表展示
 
 - [ ] 实现省市区管理页面 (AC: 5)
   - [ ] 创建省市区管理页面 - 省市区数据配置和管理
@@ -78,17 +98,26 @@ Approve
   - [ ] 更新活动和路线表单，支持地点选择组件
   - [ ] 支持按省市区筛选地点列表
 
-- [ ] 编写地点管理测试 (AC: 5)
+- [ ] 编写地点管理测试 (AC: 5, 6, 7, 8)
   - [ ] 管理后台API集成测试 (`tests/integration/server/`)
     - [ ] 地点管理API CRUD操作测试 (P0)
     - [ ] 地点搜索和筛选功能测试 (P1)
     - [ ] 地点关联关系测试 (P1)
+    - [ ] 省市区三级联动API测试 (P1)
+    - [ ] 去程/返程动态判断逻辑测试 (P0)
+    - [ ] 省市区多维度查询测试 (P1)
+    - [ ] 用户端路线查询API测试 (P0)
+    - [ ] 路线活动关联查询测试 (P1)
   - [ ] 管理后台页面组件测试 (`tests/integration/client/`)
     - [ ] LocationManagementPage组件测试 (P1)
     - [ ] LocationForm组件测试 (P1)
     - [ ] LocationSelect组件测试 (P1)
+    - [ ] 省市区三级联动组件测试 (P1)
   - [ ] E2E测试 (`tests/e2e/specs/admin/`)
     - [ ] 地点管理E2E测试 (P1)
+    - [ ] 省市区三级联动E2E测试 (P1)
+    - [ ] 去程/返程路线识别E2E测试 (P0)
+    - [ ] 用户端路线查询E2E测试 (P0)
 
 - [ ] 实现地点选择组件 (AC: 5)
   - [ ] 创建LocationSelect组件，支持地点搜索和选择
@@ -135,17 +164,26 @@ Approve
     - [x] 路线管理E2E测试 (P1)
     - [ ] 搜索筛选E2E测试 (P2)
     - [x] 启用禁用操作E2E测试 (P1)
-- [ ] 编写地点管理测试 (AC: 5)
+- [ ] 编写地点管理测试 (AC: 5, 6, 7, 8)
   - [ ] 管理后台API集成测试 (`tests/integration/server/`)
     - [ ] 地点管理API CRUD操作测试 (P0)
     - [ ] 地点搜索和筛选功能测试 (P1)
     - [ ] 地点关联关系测试 (P1)
+    - [ ] 省市区三级联动API测试 (P1)
+    - [ ] 去程/返程动态判断逻辑测试 (P0)
+    - [ ] 省市区多维度查询测试 (P1)
+    - [ ] 用户端路线查询API测试 (P0)
+    - [ ] 路线活动关联查询测试 (P1)
   - [ ] 管理后台页面组件测试 (`tests/integration/client/`)
     - [ ] LocationManagementPage组件测试 (P1)
     - [ ] LocationForm组件测试 (P1)
     - [ ] LocationSelect组件测试 (P1)
+    - [ ] 省市区三级联动组件测试 (P1)
   - [ ] E2E测试 (`tests/e2e/specs/admin/`)
     - [ ] 地点管理E2E测试 (P1)
+    - [ ] 省市区三级联动E2E测试 (P1)
+    - [ ] 去程/返程路线识别E2E测试 (P0)
+    - [ ] 用户端路线查询E2E测试 (P0)
 - [x] 实现活动选择组件 (AC: 3)
   - [x] 创建ActivitySelect组件，支持活动搜索和选择
   - [x] 在RouteForm中集成ActivitySelect组件，替换原有的数字输入框
@@ -171,25 +209,47 @@ Approve
 ### 数据模型设计
 基于 [docs/prd/epic-005-travel-service-core.md#后端数据模型] 和 [docs/architecture/data-model-schema-changes.md]，需要实现以下实体：
 
+**Area实体** (遵循 [通用CRUD实体设计规范](../architecture/generic-crud-standards.md#实体设计)):
+- `id` - 主键
+- `parentId` - 关联父级区域，0表示顶级（省/直辖市）
+- `name` - 区域名称
+- `level` - 层级: 1:省/直辖市, 2:市, 3:区/县
+- `code` - 行政区划代码
+- `createdAt` 和 `updatedAt` 时间戳
+- 使用TypeORM装饰器定义字段
+
 **Location实体** (遵循 [通用CRUD实体设计规范](../architecture/generic-crud-standards.md#实体设计)):
-- 包含地点名称、省份、城市、区县、详细地址、经纬度等字段
+- `name` - 地点名称
+- `province` - 关联AreaEntity (level=1)
+- `city` - 关联AreaEntity (level=2)
+- `district` - 关联AreaEntity (level=3)
+- `address` - 详细地址
+- `latitude` - 纬度
+- `longitude` - 经度
 - 支持状态管理（启用/禁用）
 - 包含 `createdAt` 和 `updatedAt` 时间戳
 - 使用TypeORM装饰器定义字段
 
 **Activity实体** (遵循 [通用CRUD实体设计规范](../architecture/generic-crud-standards.md#实体设计)):
-- 包含活动名称、描述、类型（去程/返程）、开始日期、结束日期等字段
-- 关联举办地点实体（LocationEntity）
-- 关联路线实体
+- `name` - 活动名称
+- `description` - 活动描述
+- `venueLocation` - 关联LocationEntity（举办地点）
+- `startDate` - 开始时间
+- `endDate` - 结束时间
 - 支持状态管理（启用/禁用）
 - 包含 `createdAt` 和 `updatedAt` 时间戳
 - 使用TypeORM装饰器定义字段
 
 **Route实体** (遵循 [通用CRUD实体设计规范](../architecture/generic-crud-standards.md#实体设计)):
-- 包含上车点、下车点、出发时间、车型、价格、座位数等字段
-- 关联出发地点实体（LocationEntity）
-- 关联目的地点实体（LocationEntity）
-- 关联活动实体
+- `startLocation` - 关联LocationEntity（出发地）
+- `endLocation` - 关联LocationEntity（目的地）
+- `pickupPoint` - 上车点
+- `dropoffPoint` - 下车点
+- `departureTime` - 出发时间
+- `vehicleType` - 车型
+- `price` - 价格
+- `seatCount` - 座位数
+- `activity` - 关联ActivityEntity
 - 支持状态管理（启用/禁用）
 - 包含 `createdAt` 和 `updatedAt` 时间戳
 - 使用TypeORM装饰器定义字段
@@ -201,6 +261,43 @@ Approve
 - 创建关联关系表（如需要）
 - 添加适当的约束和索引优化查询性能
 
+### 查询逻辑业务流程
+基于优化的数据模型，查询逻辑需要相应调整：
+
+**地点查询流程**:
+- 支持按省份、城市、区县多维度查询地点
+- 支持地点名称模糊搜索
+- 支持按省市区筛选地点
+
+**路线查询流程**:
+- 通过地点关联查询路线
+- 路线类型动态判断：目的地=活动地点为去程，出发地=活动地点为返程
+- 支持按省市区范围查询路线
+
+**用户端路线和活动查询流程**:
+- 用户输入出发地、目的地、日期时，系统：
+  1. 查询匹配的出发地点和目的地点
+  2. 通过地点ID查询符合条件的路线（出发地、目的地、日期）
+  3. 根据路线找到关联的活动
+  4. 展示去重后的活动列表，每个活动显示可用的路线信息
+
+**查询API设计**:
+- `GET /api/v1/routes/search?startLocationId=123&endLocationId=456&date=2025-10-15`
+- 响应包含：路线列表 + 关联的活动信息
+- 支持按路线类型（去程/返程）筛选
+- 支持按价格、出发时间排序
+
+**去程/返程动态判断逻辑**:
+- 去程路线: 目的地 = 活动举办地点
+- 返程路线: 出发地 = 活动举办地点
+- 简化数据模型: 每个活动只需创建一次，路线根据与活动地点的关系自动识别类型
+
+**业务逻辑实现位置**:
+- 在 `src/server/modules/routes/route.service.ts` 中实现 `getRouteType` 方法
+- 在Route实体中添加计算字段 `routeType`，基于活动地点关系自动判断
+- 在路线查询API中支持按路线类型筛选
+- 在管理后台路线列表页面显示路线类型
+
 ### 管理后台API设计
 基于 [docs/prd/epic-005-travel-service-core.md#管理后台API]，使用 [通用CRUD规范](../architecture/generic-crud-standards.md) 实现以下API端点：
 
@@ -242,10 +339,11 @@ Approve
 **路线管理API配置**:
 - **搜索字段**: `['vehicleType']`
 - **关联关系**: `['activity', 'startLocation', 'endLocation']`
-- **筛选字段**: `vehicleType`, `price` (范围查询)
+- **筛选字段**: `vehicleType`, `price` (范围查询), `routeType` (去程/返程)
 - **排序字段**: `price`, `departureTime`
 - **中间件**: `[authMiddleware]`
 - **Zod Schema**: 创建、更新、获取、列表Schema
+- **自定义查询**: 支持按路线类型（去程/返程）筛选
 
 ### 地点选择组件设计
 基于地点实体设计方案，需要实现地点选择组件来提升用户体验：
@@ -393,6 +491,8 @@ const debouncedSearch = useCallback(
 - 支持创建、编辑、删除路线
 - 支持启用/禁用路线
 - 配置出发地、目的地、上车点、下车点、出发时间、车型、价格、座位数
+- 显示路线类型（去程/返程），基于活动地点关系自动判断
+- 支持按路线类型筛选
 - 遵循 [管理后台页面结构标准](../architecture/admin-dashboard-standards.md#页面结构标准)
 - 使用 [数据表格规范](../architecture/admin-dashboard-standards.md#数据表格规范) 显示路线列表
 - 实现 [搜索和筛选功能](../architecture/admin-dashboard-standards.md#搜索和筛选规范)
@@ -466,16 +566,24 @@ const debouncedSearch = useCallback(
 - 路线字段格式验证
 - 数据库CRUD操作测试
 - 启用/禁用状态切换测试
+- 去程/返程动态判断逻辑测试
+- 省市区三级联动API测试
+- 用户端路线查询API测试
 
 **P1 其次实施** (重要功能):
 - 搜索和筛选功能测试
 - 活动路线关联测试
 - 管理后台页面组件测试
 - 关键E2E用户旅程测试
+- 省市区多维度查询测试
+- 地点关联关系测试
+- 路线活动关联查询测试
 
 **P2 最后实施** (辅助功能):
 - 高级搜索筛选E2E测试
 - 管理后台页面导航测试
+- 省市区三级联动E2E测试
+- 用户端路线查询E2E测试
 
 **测试文件位置参考**:
 - 集成测试: `tests/integration/server/admin/`