mini-starter/docs/stories/005.002.story.md

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，以下功能在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小程序开发规范
• 样式开发: 遵循 Tailwind CSS样式规范
• 迁移指导: 参考 mini-demo迁移指导规范（包含精确样式迁移）

通用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代理在审查完成后填写