Strona główna Odkrywaj Pomoc
Zarejestruj się Zaloguj się
176-template-162
/
mini-starter
sklonowany z 155-template-138/mini-starter
2
0
Forkuj 0
Pliki
Drzewo: 0243752a47
Gałęzie Tagi
mini-starter
/
docs
/
stories
/
005.001.story.md

005.001.story.md 12 KB
Historia Czysty

Story 5.1: 路线查询和活动筛选

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

  • 创建路线实体和活动实体 (AC: 1, 2, 3)
    • 在 src/server/modules/routes/ 创建 route.entity.ts
    • 在 src/server/modules/activities/ 创建 activity.entity.ts
    • 在 src/share/ 创建相关类型定义
  • 数据库迁移和种子数据 (AC: 1, 2, 3, 4)
    • 创建数据库迁移文件，添加活动、路线相关表结构
    • 创建种子数据，添加示例活动和路线数据
    • 验证数据库迁移和种子数据正确性
  • 实现路线查询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 在 src/client/home/pages/ 创建 HomePage.tsx
    • 迁移活动选择页面 - 基于 mini-demo/pages/select-activity/select-activity 在 src/client/home/pages/ 创建 ActivitySelectPage.tsx
    • 迁移班次列表页面 - 基于 mini-demo/pages/schedule-list/schedule-list 在 src/client/home/pages/ 创建 ScheduleListPage.tsx
    • 集成查询表单和结果展示
    • 使用React Query调用通用CRUD API
  • 实现前端活动筛选组件 (AC: 2)
    • 在 src/client/home/components/ 创建 ActivityFilter.tsx 组件
    • 支持活动类型筛选
  • 编写单元测试、集成测试和E2E测试 (AC: 1, 2, 3, 4)
    • 为所有新实体编写单元测试 (tests/unit/server/)
    • 为通用CRUD路由编写集成测试 (tests/integration/server/)
    • 为前端组件编写单元测试 (tests/unit/client/)
    • 为查询功能编写集成测试 (tests/integration/client/)
    • 编写完整出行流程的E2E测试 (tests/e2e/travel-flow/)

Dev Notes

MVP限制说明

根据 docs/mvp.md，以下功能在MVP阶段暂时不要实现：

  • 没有途径点 - 路线只包含出发地和目的地
  • 没有热门路线 - 首页不展示热门路线推荐
  • 没有司机当前位置 - 班次列表不显示司机实时位置
  • 没有优惠券和积分商城 - 不实现优惠券和积分功能
  • 没有会员等级 - 不实现会员体系
  • 首页焦点图使用固定静态图 - 轮播图组件保留，但数据使用固定的一张静态图片（不从API获取轮播图数组）

数据模型

  • Route实体: 包含上车点、下车点、出发时间、车型、价格等字段 [Source: architecture/data-model-schema-changes.md#路线模型]
  • Activity实体: 包含活动名称、描述、类型（去程/返程）、开始日期、结束日期等字段 [Source: architecture/data-model-schema-changes.md#活动模型]
  • 关系: 一个活动关联多条路线 [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]

文件位置

  • 后端实体: src/server/modules/routes/route.entity.ts, src/server/modules/activities/activity.entity.ts [Source: architecture/source-tree.md#实际项目结构]
  • API路由: src/server/api/routes/index.ts, src/server/api/activities/index.ts [Source: architecture/source-tree.md#实际项目结构]
  • 前端页面:
    • src/client/home/pages/HomePage.tsx (首页)
    • src/client/home/pages/ActivitySelectPage.tsx (活动选择页面)
    • src/client/home/pages/ScheduleListPage.tsx (班次列表页面) [Source: architecture/source-tree.md#实际项目结构]
  • 前端组件: src/client/home/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#现有技术栈维护]

通用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/ 目录 [Source: architecture/testing-strategy.md#单元测试]
  • 集成测试位置: tests/integration/ 目录 [Source: architecture/testing-strategy.md#集成测试]
  • E2E测试位置: tests/e2e/ 目录 [Source: architecture/testing-strategy.md#e2e测试]
  • 测试框架: Vitest + Testing Library + hono/testing + Playwright [Source: architecture/testing-strategy.md#测试框架]
  • 覆盖率目标: 核心业务逻辑 > 80% [Source: architecture/testing-strategy.md#覆盖率目标]

具体测试要求:

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

Change Log

Date Version Description Author
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代理在审查完成后填写