# Story 5.2: 路线查询和活动筛选

## Status
Draft

## Story
**As a** 出行用户
**I want** 能够查询出行路线和筛选活动类型
**so that** 快速找到适合的出行方案

## Acceptance Criteria
1. 支持按出发地、目的地、日期查询路线
2. 支持筛选去程活动/返程活动
3. 显示路线详细信息（上车点、下车点、出发时间、车型、价格）
4. 支持按价格、出发时间排序

## 页面迁移任务 (从mini-demo迁移)
- [ ] 迁移首页 (mini-demo/pages/home/home) - 路线查询入口页面
  - [ ] 轮播海报展示（MVP阶段使用固定的一张静态图片，不从API获取轮播图数组）
  - [ ] 出行方式选择（大巴拼车、商务车、包车）
  - [ ] 出发地/目的地选择器（省市区三级联动）
  - [ ] 日期选择
  - [ ] **注意：MVP阶段不实现热门路线展示**
- [ ] 迁移活动选择页面 (mini-demo/pages/select-activity/select-activity) - 活动筛选页面
  - [ ] 去程活动筛选（前往目的地观看活动）
  - [ ] 返程活动筛选（从出发地观看活动后返回）
  - [ ] 活动卡片展示（图片、名称、时间、地点、匹配点）
- [ ] 迁移班次列表页面 (mini-demo/pages/schedule-list/schedule-list) - 路线列表展示
  - [ ] 路线列表展示（上车点、下车点、出发时间、车型、价格）
  - [ ] 排序功能（价格、出发时间）
  - [ ] 筛选功能
  - [ ] **注意：MVP阶段不实现司机当前位置显示**

## Tasks / Subtasks
- [ ] 实现路线查询API使用通用CRUD (AC: 1, 3, 4)
  - [ ] 在 `src/server/api/routes/index.ts` 使用 `createCrudRoutes` 创建通用CRUD路由
  - [ ] 配置搜索字段：startPoint, endPoint, vehicleType
  - [ ] 配置排序字段：price, departureTime
  - [ ] 使用filters参数支持日期范围查询
- [ ] 实现活动查询API使用通用CRUD (AC: 2)
  - [ ] 在 `src/server/api/activities/index.ts` 使用 `createCrudRoutes` 创建通用CRUD路由
  - [ ] 配置搜索字段：name, description
  - [ ] 配置筛选字段：type (去程活动/返程活动)
- [ ] 实现前端页面迁移 (从mini-demo迁移) (AC: 1, 2, 3, 4)
  - [ ] 迁移首页 - 基于 `mini-demo/pages/home/home` 在 `mini/src/pages/home/` 创建 `HomePage.tsx`
  - [ ] 迁移活动选择页面 - 基于 `mini-demo/pages/select-activity/select-activity` 在 `mini/src/pages/select-activity/` 创建 `ActivitySelectPage.tsx`
  - [ ] 迁移班次列表页面 - 基于 `mini-demo/pages/schedule-list/schedule-list` 在 `mini/src/pages/schedule-list/` 创建 `ScheduleListPage.tsx`
  - [ ] 集成查询表单和结果展示
  - [ ] 使用React Query调用通用CRUD API
- [ ] 实现前端活动筛选组件 (AC: 2)
  - [ ] 在 `mini/src/components/` 创建 `ActivityFilter.tsx` 组件
  - [ ] 支持活动类型筛选
- [ ] 编写单元测试、集成测试和E2E测试 (AC: 1, 2, 3, 4)
  - [ ] 为通用CRUD路由编写集成测试 (`tests/integration/server/`)
  - [ ] 为前端组件编写单元测试 (`tests/unit/client/`)
  - [ ] 为查询功能编写集成测试 (`tests/integration/client/`)
  - [ ] 编写完整出行流程的E2E测试 (`tests/e2e/travel-flow/`)

## Dev Notes

### MVP限制说明
根据 [docs/mvp.md](docs/mvp.md)，以下功能在MVP阶段暂时不要实现：
- **没有途径点** - 路线只包含出发地和目的地
- **没有热门路线** - 首页不展示热门路线推荐
- **没有司机当前位置** - 班次列表不显示司机实时位置
- **没有优惠券和积分商城** - 不实现优惠券和积分功能
- **没有会员等级** - 不实现会员体系
- **首页焦点图使用固定静态图** - 轮播图组件保留，但数据使用固定的一张静态图片（不从API获取轮播图数组）

### 数据模型依赖
- **Route实体**: 已在Story 5.1中创建，包含上车点、下车点、出发时间、车型、价格等字段
- **Activity实体**: 已在Story 5.1中创建，包含活动名称、描述、类型（去程/返程）、开始日期、结束日期等字段
- **关系**: 一个活动关联多条路线 [Source: architecture/data-model-schema-changes.md#数据关系]

### API规范
- **通用CRUD路由**: 使用 `createCrudRoutes` 创建标准CRUD API [Source: src/server/utils/generic-crud.routes.ts]
- **路线查询端点**: `GET /api/v1/routes` 支持查询参数：page, pageSize, keyword, sortBy, sortOrder, filters [Source: src/server/utils/generic-crud.routes.ts#L23]
- **活动查询端点**: `GET /api/v1/activities` 支持查询参数：page, pageSize, keyword, sortBy, sortOrder, filters [Source: src/server/utils/generic-crud.routes.ts#L23]
- **分页响应**: 使用标准分页格式 [Source: architecture/data-model-schema-changes.md#分页响应接口]
- **通用CRUD服务**: 使用 `ConcreteCrudService` 作为基础服务类 [Source: src/server/utils/concrete-crud.service.ts]

### 文件位置
- **API路由**: `src/server/api/routes/index.ts`, `src/server/api/activities/index.ts` [Source: architecture/source-tree.md#实际项目结构]
- **前端页面**:
  - `mini/src/pages/home/HomePage.tsx` (首页)
  - `mini/src/pages/select-activity/ActivitySelectPage.tsx` (活动选择页面)
  - `mini/src/pages/schedule-list/ScheduleListPage.tsx` (班次列表页面) [Source: architecture/source-tree.md#实际项目结构]
- **前端组件**: `mini/src/components/ActivityFilter.tsx` [Source: architecture/source-tree.md#实际项目结构]
- **共享类型**: `src/share/route.types.ts`, `src/share/activity.types.ts` [Source: architecture/source-tree.md#实际项目结构]

### 技术栈要求
- **后端框架**: Hono + TypeORM [Source: architecture/tech-stack.md#现有技术栈维护]
- **前端框架**: Taro + React [Source: architecture/tech-stack.md#现有技术栈维护]
- **状态管理**: React Query [Source: architecture/tech-stack.md#现有技术栈维护]
- **样式**: Tailwind CSS [Source: architecture/tech-stack.md#现有技术栈维护]

### 开发规范要求
- **Taro开发**: 遵循 [Taro小程序开发规范](../architecture/taro-mini-program-standards.md)
- **样式开发**: 遵循 [Tailwind CSS样式规范](../architecture/tailwind-css-standards.md)
- **迁移指导**: 参考 [mini-demo迁移指导规范](../architecture/mini-demo-migration-guide.md)（包含精确样式迁移）

### 通用CRUD使用模式
- **路由创建**: 使用 `createCrudRoutes` 函数创建标准CRUD路由 [Source: src/server/api/users/index.ts#L9]
- **搜索配置**: 配置 `searchFields` 支持关键词搜索 [Source: src/server/api/users/index.ts#L15]
- **关联关系**: 配置 `relations` 字段加载关联数据 [Source: src/server/api/users/index.ts#L16]
- **认证中间件**: 使用 `authMiddleware` 保护路由 [Source: src/server/api/users/index.ts#L17]
- **前端调用**: 使用React Query调用通用CRUD API，支持分页、搜索、排序

### 安全要求
- **API认证**: 所有路线和活动查询API必须使用 `authMiddleware` 进行认证保护
- **数据验证**: 所有输入数据必须通过Zod schema验证 [Source: architecture.md#后端安全]
- **敏感信息处理**: 司机电话等敏感信息在响应中应适当脱敏
- **权限控制**: 确保用户只能访问授权的数据 [Source: architecture.md#认证授权]
- **输入清理**: 防止SQL注入和XSS攻击 [Source: architecture.md#后端安全]

### mini-demo迁移指导
- **迁移来源**: 所有页面迁移基于 `mini-demo/pages/` 目录下的对应页面 [Source: docs/prd/epic-005-travel-service-core.md#mini-demo页面分析]
- **技术栈转换**: 将mini-demo原生小程序代码转换为Taro + React技术栈
- **数据集成**: 将模拟数据替换为真实的后端API调用
- **组件重构**: 保持原有UI体验，但使用项目标准的shadcn/ui组件库

### mini-demo页面结构分析
**首页 (home/home)**:
- 轮播海报展示 [Source: mini-demo/pages/home/home.wxml#L4] - **MVP限制：使用固定的一张静态图片，不从API获取轮播图数组**
- 出行方式选择（大巴拼车、商务车、包车） [Source: mini-demo/pages/home/home.wxml#L26]
- 出发地/目的地选择器（省市区三级联动） [Source: mini-demo/pages/home/home.wxml#L37]
- 日期选择 [Source: mini-demo/pages/home/home.wxml#L66]
- 热门路线展示 [Source: mini-demo/pages/home/home.wxml#L78] - **MVP限制：不实现**

**活动选择页面 (select-activity/select-activity)**:
- 去程活动筛选（前往目的地观看活动） [Source: mini-demo/pages/select-activity/select-activity.wxml#L12]
- 返程活动筛选（从出发地观看活动后返回） [Source: mini-demo/pages/select-activity/select-activity.wxml#L43]
- 活动卡片展示（图片、名称、时间、地点、匹配点） [Source: mini-demo/pages/select-activity/select-activity.wxml#L22]

**班次列表页面 (schedule-list/schedule-list)**:
- 路线列表展示（上车点、下车点、出发时间、车型、价格）
- 排序功能（价格、出发时间）
- 筛选功能
- **MVP限制：不显示司机当前位置**

### Testing
**测试要求**:
- **主项目测试位置**: `tests/unit/`, `tests/integration/`, `tests/e2e/` 目录 [Source: architecture/testing-strategy.md#主项目测试体系]
- **Taro项目测试位置**: `mini/tests/` 目录 [Source: architecture/testing-strategy.md#taro小程序测试体系]
- **主项目测试框架**: Vitest + Testing Library + hono/testing + Playwright [Source: architecture/testing-strategy.md#测试框架]
- **Taro项目测试框架**: Jest + @tarojs/test-utils-react [Source: architecture/testing-strategy.md#taro小程序测试体系]
- **覆盖率目标**: 核心业务逻辑 > 80% [Source: architecture/testing-strategy.md#覆盖率目标]

**具体测试要求**:
- 路线查询API的单元测试 (`tests/unit/server/routes/`) 和集成测试 (`tests/integration/server/routes/`)
  - 正常查询场景：按出发地、目的地、日期查询
  - 边界条件：空查询结果、日期范围查询、分页查询
  - 排序功能：按价格、出发时间排序
  - 错误场景：无效参数、认证失败、权限不足
- 活动查询API的单元测试 (`tests/unit/server/activities/`) 和集成测试 (`tests/integration/server/activities/`)
  - 正常筛选场景：按活动类型（去程/返程）筛选
  - 边界条件：无活动数据、活动状态筛选
  - 关联查询：活动关联的路线数据
  - 错误场景：无效类型参数、认证失败
- 前端组件的单元测试 (`mini/tests/components/`)
  - 组件渲染：首页、活动选择、班次列表页面
  - 用户交互：查询表单提交、筛选条件变更
  - 状态管理：查询结果展示、加载状态处理
- 查询功能的集成测试 (`mini/tests/pages/`)
  - 完整查询流程：首页查询 → 活动筛选 → 班次列表
  - 数据一致性：前端展示与后端数据一致
  - 错误处理：网络错误、API错误处理
- 完整出行流程的E2E测试 (`tests/e2e/travel-flow/`)
  - 用户登录 → 路线查询 → 活动筛选 → 查看班次列表
  - 边界场景：无数据、大量数据、并发查询

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-10-16 | 1.8 | 移除基础数据实体任务，迁移到Story 5.1 | Bob (Scrum Master) |
| 2025-10-15 | 1.7 | 修正Taro测试位置，统一使用mini/tests/目录 | Winston (Architect) |
| 2025-10-15 | 1.6 | 修正前端页面路径从src/client到mini/src目录 | Bob (Scrum Master) |
| 2025-10-15 | 1.5 | 修复测试位置与测试策略文档不一致问题，添加安全要求和数据库迁移任务 | Bob (Scrum Master) |
| 2025-10-15 | 1.4 | 补充MVP文档中标识为暂时不要的页面元素 | Bob (Scrum Master) |
| 2025-10-15 | 1.3 | 明确迁移来源为mini-demo并添加页面结构分析 | Bob (Scrum Master) |
| 2025-10-15 | 1.2 | 添加页面迁移任务和具体页面实现 | Bob (Scrum Master) |
| 2025-10-15 | 1.1 | 更新为使用通用CRUD服务 | Bob (Scrum Master) |
| 2025-10-15 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Dev Agent Record
*此部分由开发代理在实施过程中填写*

### Agent Model Used

### Debug Log References

### Completion Notes List

### File List

## QA Results
*此部分由QA代理在审查完成后填写*