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

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 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优先迁移MVP核心页面：
1. **首页** (home/home) - 路线查询入口
2. **活动选择** (select-activity/select-activity) - 去程/返程活动筛选
3. **班次列表** (schedule-list/schedule-list) - 路线列表
4. **下单页面** (order/order) - 订单创建
5. **添加乘客** (add-passenger/add-passenger) - 乘客信息管理
6. **支付成功** (pay-success/pay-success) - 支付结果
7. **订单列表** (orders/orders) - 订单管理
8. **订单详情** (order-detail/order-detail) - 订单详情查看

## 用户故事

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

**验收标准**:
- [ ] 支持按出发地、目的地、日期查询路线
- [ ] 支持筛选去程活动/返程活动
- [ ] 显示路线详细信息（上车点、下车点、出发时间、车型、价格）
- [ ] 支持按价格、出发时间排序

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

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

### US005-03: 订单创建和支付
**作为** 出行用户
**我希望** 能够创建订单并完成支付
**以便** 确认出行安排

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

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

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

### US005-05: 支付集成
**作为** 系统
**我希望** 集成微信支付功能
**以便** 支持用户完成订单支付

**验收标准**:
- [ ] 实现微信支付JSAPI集成
- [ ] 处理支付回调通知
- [ ] 支付状态与订单状态同步
- [ ] 支付异常处理（超时、失败、重复支付）

## 技术实现方案

### 后端数据模型
基于架构文档设计，需要实现以下实体：
- **Order实体**: 订单管理
- **Passenger实体**: 乘客信息管理
- **Route实体**: 路线管理
- **Activity实体**: 活动管理

### API接口设计
需要新增以下API端点：
- `GET /api/v1/routes` - 路线查询
- `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` - 删除乘客

### 前端页面迁移
将mini-demo的8个核心页面迁移到Taro + React：
1. 首页迁移 - 路线查询入口
2. 活动选择页面迁移 - 活动筛选
3. 班次列表页面迁移 - 路线展示
4. 下单页面迁移 - 订单创建
5. 添加乘客页面迁移 - 乘客管理
6. 支付成功页面迁移 - 支付结果
7. 订单列表页面迁移 - 订单管理
8. 订单详情页面迁移 - 订单详情

## 依赖关系

### 前置依赖
- 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%
- [ ] 无重大安全漏洞
- [ ] 代码符合编码规范

## 下一步行动

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

---

**文档状态**: 创建完成
**最后更新**: 2025-10-15
**下次评审**: 2025-10-22