Epic 005: 出行服务核心功能 (MVP优先)

版本信息

版本	日期	描述	作者
2.1	2025-10-20	添加车型和路线配置增强故事US005-04，顺延原有故事编号	John (PM)
2.0	2025-10-19	添加样式迁移合规性修复故事US005-03，顺延原有故事编号	John (PM)
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)
1.5	2025-10-16	为乘客、订单、用户添加管理后台查看故事	John (PM)
1.4	2025-10-16	修正数据模型，移除班次实体，与架构文档保持一致	Bob (Scrum Master)
1.3	2025-10-16	添加管理后台故事US005-01，确保故事闭环	John (PM)
1.2	2025-10-15	添加我的页面到MVP迁移范围	John (PM)
1.1	2025-10-15	重构页面迁移为用户故事任务	John (PM)
1.0	2025-10-15	基于实际项目状态创建Epic 005	John (PM)

Epic概述

Epic目标

实现出行服务的核心功能，包括路线查询、活动筛选、订单管理、乘客管理、支付集成等，将mini-demo的核心页面功能迁移到真实的后端系统。

成功标准

用户能够完成从查询路线到支付完成的完整出行流程
订单数据正确存储到PostgreSQL数据库
核心业务逻辑完整实现
MVP相关页面功能正常

当前项目状态分析

现有基础

✅ 后端框架: Hono + TypeORM + PostgreSQL 已就绪
✅ 用户管理: 完整的用户认证和权限系统已实现
✅ 文件管理: MinIO对象存储集成已完成
✅ 前端基础: Taro + React 框架已搭建
⚠️ 业务数据: 缺少出行服务相关数据模型
⚠️ 前端页面: 只有基础页面，缺少出行服务页面

mini-demo页面分析

mini-demo包含14个页面，Epic 005将页面迁移作为用户故事的具体任务进行拆分：

核心流程页面 (9个): 首页、活动选择、班次列表、下单页面、添加乘客、支付成功、订单列表、订单详情、我的页面
辅助功能页面 (5个): 积分商城、积分历史、优惠券管理等（MVP阶段暂不迁移）

用户故事

US005-01: 基础数据管理（管理后台）

作为系统管理员 我希望 能够配置活动、路线等基础数据以便用户能够查询和使用出行服务

验收标准:

支持创建和管理活动信息（活动名称、描述、举办地点、时间范围）
支持配置路线信息（出发地、目的地、上车点、下车点、出发时间、车型、价格、座位数）
支持设置活动关联的路线
支持启用/禁用活动、路线
路线自动识别为去程或返程（目的地=活动地点为去程，出发地=活动地点为返程）

管理后台页面任务:

活动管理页面 - 活动类型配置和管理
路线管理页面 - 路线信息配置和管理

US005-02: 路线查询和活动筛选

作为出行用户 我希望 能够查询出行路线和筛选活动类型以便快速找到适合的出行方案

验收标准:

支持按出发地、目的地、日期查询路线
支持筛选去程路线/返程路线
显示路线详细信息（上车点、下车点、出发时间、车型、价格）
支持按价格、出发时间排序
路线类型自动识别（去程：目的地=活动地点，返程：出发地=活动地点）
支持通过路线查询关联的活动信息

页面迁移任务:

迁移首页 (home/home) - 路线查询入口页面
迁移活动选择页面 (select-activity/select-activity) - 活动筛选页面
迁移班次列表页面 (schedule-list/schedule-list) - 路线列表展示

US005-03: 样式迁移合规性修复

作为产品经理 我希望 确保所有迁移页面严格遵守样式迁移规范以便保持用户体验一致性和设计系统完整性

验收标准:

更新Tailwind配置，添加迁移指导规范中定义的设计系统
修复首页样式，使用正确的设计系统类名
实现包车主题，为不同出行方式提供不同的视觉主题
验证活动选择页面和班次列表页面的样式合规性
确保所有样式转换符合精确迁移要求

技术实现任务:

扩展Tailwind配置（颜色系统、圆角系统、阴影系统）
修复首页样式合规性（轮播图、出行方式选择器、出行选择区域）
验证活动选择页面样式（头部信息区域、行程区域、活动卡片）
验证班次列表页面样式（包车卡片、预订按钮、排序工具栏）
编写样式合规性测试

US005-04: 车型和出行方式配置增强

作为系统管理员 我希望 能够配置完整的车型枚举和独立的出行方式字段以便支持更灵活的出行服务组合查询

组合查询逻辑:

大巴拼车 → 大巴 + 拼车
商务车 → 商务车 + 拼车/包车
包车 → 大巴/商务车 + 包车

具体实现要求:

首页：保持现有三种查询选项，但查询逻辑需要调整为组合查询
活动选择页面：根据组合查询条件筛选相关活动
班次列表页面：根据组合查询条件显示匹配的路线
API查询：支持根据车型和出行方式的组合条件进行筛选

组合查询API参数映射:

大巴拼车：vehicleType=bus&travelMode=carpool
商务车：vehicleType=business&travelMode=carpool,charter（支持两种出行方式）
包车：vehicleType=bus,business&travelMode=charter（支持两种车型）

验收标准:

车型枚举包含完整选项：大巴、中巴、小车、商务车
路线配置支持独立的出行方式选择（拼车/包车）
支持组合查询逻辑：大巴拼车、商务车、包车三种查询方式
不同组合支持不同的价格策略和座位配置
前端页面正确显示组合查询选项
小程序和管理后台界面支持组合查询方式
查询API支持组合查询逻辑
活动选择页面支持组合查询逻辑
班次列表页面正确显示组合查询结果

技术实现任务:

更新VehicleType枚举，添加商务车选项
创建TravelMode枚举，定义拼车和包车出行方式
在路线实体中添加travelMode字段
更新管理后台路线配置页面，支持车型和出行方式独立选择
更新小程序首页出行方式选择器的查询逻辑，支持组合查询
更新活动选择页面查询逻辑，支持组合查询
更新班次列表页面查询逻辑，支持组合查询
更新班次列表页面显示逻辑，正确显示车型和出行方式的组合信息
更新路线查询API，支持组合查询逻辑
更新订单详情页面，显示完整的车型和出行方式信息
验证前端页面正确显示组合查询选项

查询逻辑实现细节:

首页查询逻辑：将三种组合选项映射为对应的API查询参数
活动选择页面查询逻辑：根据组合条件查询关联的活动，支持多条件筛选
班次列表页面查询逻辑：根据组合条件查询匹配的路线，支持车型和出行方式的组合筛选
API查询逻辑：支持多值参数查询，如vehicleType=bus,business和travelMode=carpool,charter

界面修改任务:

管理后台路线配置页面：添加出行方式选择器，与车型选择器并列
小程序首页：保持现有组合查询选项显示，更新查询逻辑
班次列表页面：更新路线卡片，同时显示车型和出行方式
订单详情页面：更新订单信息显示，包含车型和出行方式

API修改任务:

更新路线创建和更新API，支持travelMode字段
更新路线查询API，支持组合查询逻辑
更新路线列表API响应，包含travelMode字段
更新活动查询API，支持组合查询逻辑
更新订单相关API，确保travelMode信息正确传递
更新管理后台路线管理API，支持车型和出行方式筛选

API查询参数设计:

路线查询API：支持多值参数
- vehicleType: 支持逗号分隔的多个车型（如bus,business）
- travelMode: 支持逗号分隔的多个出行方式（如carpool,charter）
- 组合查询逻辑：vehicleType和travelMode参数同时存在时进行组合筛选
活动查询API：根据路线组合条件查询关联的活动
- 支持通过路线查询参数间接筛选活动
- 返回去重后的活动列表

US005-05: 乘客信息查看（管理后台）

作为系统管理员 我希望 能够查看所有用户的乘客信息以便了解用户乘车人情况和进行数据统计

验收标准:

支持查看所有乘客信息列表
支持按用户筛选乘客信息
显示乘客基本信息（姓名、证件类型、证件号码、手机号）
支持导出乘客数据

管理后台页面任务:

乘客信息管理页面 - 查看所有乘客信息

US005-06: 乘客信息管理

作为出行用户 我希望 能够管理我的乘客信息以便快速选择乘车人

验收标准:

支持添加、编辑、删除乘客信息
支持设置默认乘客
验证乘客信息完整性（姓名、证件类型、证件号码、手机号）
支持多种证件类型（身份证、港澳通行证、护照等）

页面迁移任务:

迁移添加乘客页面 (add-passenger/add-passenger) - 乘客信息管理页面

US005-07: 订单信息查看（管理后台）

作为系统管理员 我希望 能够查看所有订单信息和状态以便监控订单流程和处理异常订单

验收标准:

支持查看所有订单列表
支持按订单状态筛选（待支付、待出发、行程中、已完成、已取消）
显示订单详细信息（用户信息、路线信息、乘客信息、金额、状态）
支持订单状态统计和报表

管理后台页面任务:

订单管理页面 - 查看所有订单信息

US005-08: 订单创建和支付

作为出行用户 我希望 能够创建订单并完成支付以便确认出行安排

验收标准:

选择路线和乘客后创建订单
计算订单总金额
集成微信支付完成支付流程
支付成功后更新订单状态
保存订单快照信息（路线快照、乘客快照）

页面迁移任务:

迁移下单页面 (order/order) - 订单创建页面
迁移支付成功页面 (pay-success/pay-success) - 支付结果页面

US005-09: 订单状态管理

作为出行用户 我希望 能够查看和管理我的订单状态以便了解出行安排进度

验收标准:

查看订单列表（待支付、待出发、行程中、已完成、已取消）
查看订单详情信息
支持取消订单（在允许的时间范围内）
订单状态自动更新（待出发→行程中→已完成）

页面迁移任务:

迁移订单列表页面 (orders/orders) - 订单管理页面
迁移订单详情页面 (order-detail/order-detail) - 订单详情查看页面

US005-10: 个人中心管理

作为出行用户 我希望 能够查看和管理我的个人信息和出行记录以便方便地管理我的出行服务

验收标准:

查看个人基本信息
查看出行统计和订单概览
快速访问常用功能（订单管理、乘客管理等）
支持用户设置和偏好管理

页面迁移任务:

迁移我的页面 (mine/mine) - 个人中心入口页面

US005-11: 支付集成

作为系统 我希望 集成微信支付功能以便支持用户完成订单支付

验收标准:

实现微信支付JSAPI集成
处理支付回调通知
支付状态与订单状态同步
支付异常处理（超时、失败、重复支付）

技术实现方案

后端数据模型

基于架构文档设计，需要实现以下实体：

Order实体: 订单管理
Passenger实体: 乘客信息管理
Route实体: 路线管理（包含出发时间、车型、价格、座位数等）
Activity实体: 活动管理（包含举办地点信息，去程/返程通过路线与活动地点的关系动态判断）

活动实体设计优化

基于对现有设计的分析，活动实体需要进行以下优化：

问题识别:

当前活动实体缺少举办地点字段
去程/返程逻辑不够清晰，存在数据冗余
每个活动都需要创建对应的去程和返程活动，导致重复数据
地点信息缺乏结构化，无法支持省市区查询和地理功能

优化方案:

创建独立的地点实体(LocationEntity): 统一管理所有地点信息，包含省市区、经纬度等
Activity实体关联地点: 通过venueLocation字段关联活动举办地点
Route实体关联地点: 通过startLocation和endLocation字段关联路线起止地点
去程/返程动态判断:
- 去程路线: 目的地 = 活动举办地点
- 返程路线: 出发地 = 活动举办地点
简化数据模型: 每个活动只需创建一次，路线根据与活动地点的关系自动识别类型

数据模型示例:

地点 (Location)
├── 名称 (name)
├── 省份 (province)
├── 城市 (city)
├── 区县 (district)
├── 详细地址 (address)
├── 纬度 (latitude)
└── 经度 (longitude)

活动 (Activity)
├── 名称 (name)
├── 描述 (description)
├── 举办地点 (venueLocation) → 关联Location
├── 开始时间 (startDate)
└── 结束时间 (endDate)

路线 (Route)
├── 出发地 (startLocation) → 关联Location
├── 目的地 (endLocation) → 关联Location
├── 上车点 (pickupPoint)
├── 下车点 (dropoffPoint)
├── 车型 (vehicleType) → VehicleType枚举（大巴/中巴/小车/商务车）
├── 出行方式 (travelMode) → TravelMode枚举（拼车/包车）
├── 关联活动 (activity)
└── 其他信息...

省市区实体设计方案

基于发现的省市区数据文件，需要实现标准化的省市区数据管理：

问题识别:

当前地点实体中的省市区字段为自由文本，缺乏标准化
无法支持省市区三级联动选择
地点查询时无法按标准行政区划进行精确筛选
缺乏完整的省市区数据支持

优化方案:

创建省市区实体(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设计示例:

// 获取省份列表
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

优势:

数据标准化: 统一的省市区数据源，避免数据不一致
查询优化: 支持精确的省市区筛选和关联查询
用户体验: 前端组件支持省市区三级联动选择
扩展性: 支持行政区划变更和新增区域
维护性: 集中管理省市区数据，便于更新和维护

查询逻辑设计

基于优化的数据模型，查询逻辑需要相应调整：

地点查询:

支持按省份、城市、区县多维度查询地点
支持地点名称模糊搜索
支持按地点类型筛选（场馆、车站、地标等）

路线查询:

通过地点关联查询路线
路线类型动态判断：目的地=活动地点为去程，出发地=活动地点为返程
支持按省市区范围查询路线
组合查询支持：支持车型和出行方式的组合筛选
- 大巴拼车：vehicleType=bus&travelMode=carpool
- 商务车：vehicleType=business&travelMode=carpool,charter
- 包车：vehicleType=bus,business&travelMode=charter

活动查询:

通过路线间接查询关联的活动
用户选择出发地、目的地、日期时，系统：
1. 查询匹配的地点
2. 通过地点找到关联的路线（支持组合查询条件）
3. 根据路线找到关联的活动
4. 展示去重后的活动列表
组合查询支持：活动查询基于路线组合条件进行筛选

API设计示例:

// 查询地点（支持省市区筛选）
GET /api/v1/locations?province=北京市&city=北京市&name=工人体育场

// 查询路线（支持组合查询）
GET /api/v1/routes?startLocationId=123&endLocationId=456&date=2025-10-15&type=departure&vehicleType=bus,business&travelMode=carpool,charter

// 响应：路线列表，包含完整的地点信息和活动信息
{
  routes: [
    {
      id: 1,
      startLocation: {
        id: 123,
        name: "中关村",
        province: "北京市",
        city: "北京市",
        district: "海淀区"
      },
      endLocation: {
        id: 456,
        name: "工人体育场",
        province: "北京市",
        city: "北京市",
        district: "朝阳区"
      },
      vehicleType: "bus",
      travelMode: "carpool",
      activity: {
        id: 1,
        name: "中超联赛北京国安主场赛事",
        venueLocation: {
          id: 456,
          name: "工人体育场",
          province: "北京市",
          city: "北京市",
          district: "朝阳区"
        }
      }
    }
  ]
}

API接口设计

需要新增以下API端点：

管理后台API:

GET /api/v1/admin/locations - 地点管理列表
POST /api/v1/admin/locations - 创建地点
PUT /api/v1/admin/locations/:id - 更新地点
DELETE /api/v1/admin/locations/:id - 删除地点
GET /api/v1/admin/activities - 活动管理列表
POST /api/v1/admin/activities - 创建活动
PUT /api/v1/admin/activities/:id - 更新活动
DELETE /api/v1/admin/activities/:id - 删除活动
GET /api/v1/admin/routes - 路线管理列表
POST /api/v1/admin/routes - 创建路线
PUT /api/v1/admin/routes/:id - 更新路线
DELETE /api/v1/admin/routes/:id - 删除路线

用户端API:

GET /api/v1/locations - 地点查询（支持省份、城市、区县、名称等参数）
GET /api/v1/routes - 路线查询（支持出发地、目的地、日期、类型等参数，返回包含活动信息的路线列表）
- 组合查询参数：
- vehicleType：车型筛选，支持多值（如bus,business）
- travelMode：出行方式筛选，支持多值（如carpool,charter）
- 支持三种组合查询模式：大巴拼车、商务车、包车
GET /api/v1/activities - 活动列表查询（基础信息查询）
POST /api/v1/orders - 创建订单
GET /api/v1/orders - 订单列表
GET /api/v1/orders/:id - 订单详情
PUT /api/v1/orders/:id/cancel - 取消订单
POST /api/v1/passengers - 添加乘客
GET /api/v1/passengers - 乘客列表
PUT /api/v1/passengers/:id - 更新乘客
DELETE /api/v1/passengers/:id - 删除乘客

前端页面迁移策略

页面迁移任务已分配到各个用户故事中，确保每个页面迁移与对应的业务功能同步开发：

US005-01: 活动管理页面、路线管理页面、班次管理页面（管理后台）
US005-02: 首页、活动选择、班次列表页面
US005-03: 样式迁移合规性修复（所有迁移页面）
US005-04: 车型和出行方式配置增强（管理后台路线配置页面、小程序首页、班次列表页面、订单详情页面）
US005-05: 乘客信息管理页面（管理后台）
US005-06: 添加乘客页面
US005-07: 订单管理页面（管理后台）
US005-08: 下单页面、支付成功页面
US005-09: 订单列表、订单详情页面
US005-10: 我的页面

依赖关系

前置依赖

Epic 001: 测试基础设施 ✅
Epic 002: 用户管理增强 ✅
Epic 003: Lint配置 ✅
Epic 004: API实际请求测试 ✅

后续依赖

Epic 006: 前端页面迁移和基础框架
Epic 007: 用户认证和基础管理
Epic 008: 管理后台系统

风险评估

技术风险

微信支付集成: 需要申请微信支付商户号和配置证书
数据迁移: mini-demo模拟数据需要转换为真实数据
性能优化: 订单状态自动更新需要定时任务支持

业务风险

支付流程: 需要确保支付流程的稳定性和安全性
用户体验: 页面迁移可能影响原有用户体验
数据一致性: 订单快照机制需要确保数据完整性

测试策略

单元测试

订单业务逻辑测试
支付状态流转测试
乘客信息验证测试

集成测试

API端点集成测试
微信支付集成测试
数据库操作测试

E2E测试

完整出行流程测试（查询→下单→支付→完成）
异常场景测试（支付失败、取消订单等）

验收标准

功能验收

用户能够完成完整的出行服务流程
订单数据正确存储和展示
支付功能正常集成
乘客信息管理功能完整

性能验收

页面加载时间 < 2秒
API响应时间 < 500ms
支付成功率 > 98%

质量验收

核心业务逻辑测试覆盖率 > 80%
无重大安全漏洞
代码符合编码规范

下一步行动

立即开始: 创建出行服务数据模型实体
并行开发: 后端API开发和前端页面迁移
集成测试: 微信支付集成和端到端测试
用户验收: MVP功能演示和用户反馈收集

文档状态: 已更新 最后更新: 2025-10-20 下次评审: 2025-10-27

epic-005-travel-service-core.md 23 KB Verlauf Originalformat

Epic 005: 出行服务核心功能 (MVP优先)

版本信息

Epic概述

Epic目标

成功标准

当前项目状态分析

现有基础

mini-demo页面分析

用户故事

US005-01: 基础数据管理（管理后台）

US005-02: 路线查询和活动筛选

US005-03: 样式迁移合规性修复

US005-04: 车型和出行方式配置增强

US005-05: 乘客信息查看（管理后台）

US005-06: 乘客信息管理

US005-07: 订单信息查看（管理后台）

US005-08: 订单创建和支付

US005-09: 订单状态管理

US005-10: 个人中心管理

US005-11: 支付集成

技术实现方案

后端数据模型

活动实体设计优化

省市区实体设计方案

查询逻辑设计

API接口设计

前端页面迁移策略

依赖关系

前置依赖

后续依赖

风险评估

技术风险

业务风险

测试策略

单元测试

集成测试

E2E测试

验收标准

功能验收

性能验收

质量验收

下一步行动

epic-005-travel-service-core.md 23 KB

Verlauf Originalformat