# Story 5.6: 乘客信息管理

## Status
Approved

## Story
**As a** 出行用户
**I want** 能够管理我的乘客信息
**so that** 快速选择乘车人

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

## Tasks / Subtasks
- [x] 创建用户端乘客API路由 (AC: 1, 2, 3, 4)
  - [x] 创建 `src/server/api/passengers/index.ts` API路由文件
  - [x] 使用通用CRUD规范创建用户端乘客API
  - [x] 实现用户只能管理自己乘客的权限控制
  - [x] 支持默认乘客设置功能
- [x] 创建Taro小程序乘客管理主页面 (AC: 1, 2, 3, 4)
  - [x] 迁移 `mini-demo/pages/passenger-management/passenger-management` 页面到 `mini/src/pages/passengers/passengers.tsx`
  - [x] 遵循 [mini-demo迁移指导规范](docs/architecture/mini-demo-migration-guide.md) 进行技术栈转换
  - [x] 组件映射：原生小程序组件 → Taro组件
  - [x] 样式转换：WXSS → Tailwind CSS（精确样式保留）
  - [x] 事件处理：`bindtap` → `onClick`，`bindinput` → `onInput`
  - [x] 状态管理：小程序data → React useState
  - [x] 实现乘客列表显示（包含姓名、证件类型、手机号）
  - [x] 实现搜索功能（按姓名、手机号、证件号搜索）
  - [x] 实现模态框添加/编辑乘客功能
  - [x] 实现表单验证（姓名、证件类型、证件号码、手机号）
  - [x] 实现删除乘客功能（确认对话框）
  - [x] 实现设置默认乘客功能
  - [x] 集成真实的后端API替换模拟数据
  - [x] 保持原有样式和用户体验
  - [x] 遵循Navbar样式规范实现页面导航栏
  - [x] 遵循Dialog样式规范实现添加/编辑/删除对话框
- [ ] 创建Taro小程序独立添加乘客页面 (AC: 1, 2, 3, 4)
  - [ ] 迁移 `mini-demo/pages/add-passenger/add-passenger` 页面到 `mini/src/pages/passengers/add-passenger.tsx`
  - [ ] 遵循 [mini-demo迁移指导规范](docs/architecture/mini-demo-migration-guide.md) 进行技术栈转换
  - [ ] 组件映射：原生小程序组件 → Taro组件
  - [ ] 样式转换：WXSS → Tailwind CSS（精确样式保留）
  - [ ] 事件处理：`bindtap` → `onClick`，`bindinput` → `onInput`
  - [ ] 状态管理：小程序data → React useState
  - [ ] 实现独立添加乘客表单
  - [ ] 支持从不同来源页面跳转（订单页面、管理页面）
  - [ ] 实现表单验证（姓名、证件类型、证件号码、手机号）
  - [ ] 支持多种证件类型选择器
  - [ ] 集成真实的后端API
  - [ ] 保持原有样式和用户体验
  - [ ] 遵循Navbar样式规范实现页面导航栏
  - [ ] 遵循Dialog样式规范实现表单验证提示对话框
- [x] 集成乘客页面到小程序路由 (AC: 1)
  - [x] 在Taro小程序路由配置中添加乘客页面
  - [x] 在个人中心页面添加乘客管理入口
- [ ] 编写乘客管理测试 (AC: 1, 2, 3, 4)
  - [x] 编写用户端乘客API集成测试
  - [ ] 编写Taro小程序乘客页面组件测试
  - [ ] 编写乘客信息验证测试

## Dev Notes

### 数据模型设计
基于 [docs/architecture/data-model-schema-changes.md#乘客模型]，乘客实体已经存在，包含以下关键属性：

**乘客实体关键属性** [Source: architecture/data-model-schema-changes.md#乘客模型]:
- `id`: number - 主键标识符
- `userId`: number - 用户ID
- `name`: string - 乘客姓名
- `idType`: IdType - 证件类型（身份证、港澳通行证、台湾通行证、护照等）
- `idNumber`: string - 证件号码
- `phone`: string - 手机号
- `isDefault`: boolean - 是否默认乘客

**证件类型枚举定义** [Source: architecture/data-model-schema-changes.md#枚举定义]:
```typescript
export enum IdType {
  ID_CARD = '身份证',
  HONG_KONG_MACAO_PASS = '港澳通行证',
  TAIWAN_PASS = '台湾通行证',
  PASSPORT = '护照',
  OTHER = '其他证件'
}
```

### 通用CRUD规范要求
基于 [docs/architecture/generic-crud-standards.md#使用指南]，用户端乘客管理必须遵循通用CRUD规范：

**实体设计** [Source: architecture/generic-crud-standards.md#实体设计]:
- 所有实体必须继承 `ObjectLiteral`
- 包含 `createdAt` 和 `updatedAt` 时间戳
- 使用TypeORM装饰器定义字段

**Schema设计** [Source: architecture/generic-crud-standards.md#schema设计]:
- 创建和更新使用不同的schema
- 响应schema应包含完整字段
- 使用 `.optional()` 和 `.nullable()` 明确字段可选性

**CRUD路由注册** [Source: architecture/generic-crud-standards.md#注册crud路由]:
```typescript
export const passengerRoutes = createCrudRoutes({
  entity: Passenger,
  createSchema: PassengerCreateSchema,
  updateSchema: PassengerUpdateSchema,
  getSchema: PassengerGetSchema,
  listSchema: PassengerListSchema,
  searchFields: ['name', 'phone', 'idNumber'],
  relations: ['user'],
  middleware: [authMiddleware],
  userTracking: {
    createdByField: 'createdBy',
    updatedByField: 'updatedBy'
  }
});
```

### 权限控制要求
基于 [docs/architecture/security-integration.md#现有安全措施]，用户端乘客API需要实现权限控制：

**用户权限控制** [Source: architecture/security-integration.md#现有安全措施]:
- 用户只能查看和管理自己的乘客信息
- 使用JWT认证中间件验证用户身份
- 在查询和操作时自动过滤用户ID

### Taro小程序开发规范
基于 [docs/architecture/coding-standards.md#taro小程序开发规范]，乘客管理页面必须遵循Taro小程序开发标准：

**技术栈要求** [Source: architecture/tech-stack.md#现有技术栈维护]:
- **前端框架**: Taro + React
- **状态管理**: React Query 5.83.0
- **样式**: Tailwind CSS 4.1.11
- **路由导航**: 统一使用Taro路由API

**页面结构标准** [Source: architecture/source-tree.md#实际项目结构]:
- 页面文件位置：`mini/src/pages/passengers/passengers.tsx`
- 使用标准Taro页面组件结构
- 遵循移动端优先的响应式设计

### 文件位置
基于 [docs/architecture/source-tree.md#实际项目结构]，所有乘客相关文件必须放置在指定位置：

**后端文件位置** [Source: architecture/source-tree.md#实际项目结构]:
- **API路由**: `src/server/api/passengers/index.ts`
- **实体定义**: `src/server/modules/passengers/passenger.entity.ts` (已存在)
- **业务服务**: `src/server/modules/passengers/passenger.service.ts` (已存在)
- **Zod Schema**: `src/server/modules/passengers/passenger.schema.ts` (已存在)

**前端文件位置** [Source: architecture/source-tree.md#实际项目结构]:
- **Taro小程序页面**: `mini/src/pages/passengers/passengers.tsx`
- **迁移页面**: `mini/src/pages/passengers/add-passenger.tsx`
- **共享类型**: `src/share/passenger.types.ts` (已存在)

### 技术栈要求
基于 [docs/architecture/tech-stack.md#现有技术栈维护]，必须使用项目标准技术栈：

**后端框架** [Source: architecture/tech-stack.md#现有技术栈维护]:
- **运行时**: Node.js 20.19.2
- **框架**: Hono 4.8.5
- **数据库**: PostgreSQL 17
- **ORM**: TypeORM 0.3.25

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

### 开发规范要求
基于 [docs/architecture/coding-standards.md#通用crud开发规范]，必须遵循编码标准：

**CRUD开发** [Source: architecture/coding-standards.md#通用crud开发规范]:
- 遵循通用CRUD规范进行开发
- 所有实体必须继承 `ObjectLiteral`，包含时间戳字段
- 创建、更新、响应使用不同的Zod schema
- 使用 `createCrudRoutes` 自动生成API路由

**Taro小程序开发** [Source: architecture/coding-standards.md#taro小程序开发规范]:
- 遵循Taro小程序开发规范进行开发
- 正确处理微信小程序、H5等平台差异
- 使用React Query管理服务端状态
- 统一使用Taro路由API

**页面迁移规范** [Source: architecture/coding-standards.md#mini-demo迁移规范]:
- 遵循mini-demo迁移指导规范进行迁移
- 确保百分百样式保留，保持用户体验一致性
- 技术栈转换：原生小程序 → Taro + React + TypeScript
- 数据集成：模拟数据 → 真实后端API

**Navbar和Dialog样式规范** [Source: architecture/mini-demo-migration-guide.md#navbar-导航栏样式规范]:
- 遵循Navbar导航栏样式规范进行导航栏开发
- 使用预设样式变体（默认、深色、透明、主色调）
- 正确处理微信小程序和H5平台的适配差异
- 遵循Dialog对话框样式规范进行弹窗开发
- 使用标准对话框组件结构（Content、Header、Title、Footer）
- 实现确认对话框、表单对话框、警告对话框等预设变体

### Testing

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

**具体测试要求** [Source: architecture/testing-strategy.md#测试金字塔策略]:
- **用户端乘客API集成测试** (P1优先级)
  - 测试乘客列表API端点
  - 验证用户权限控制
  - 测试默认乘客设置功能
- **Taro小程序乘客页面组件测试** (P1优先级)
  - 测试乘客列表页面渲染
  - 验证添加乘客表单功能
  - 测试编辑和删除乘客功能
  - 验证Navbar组件样式和交互
  - 验证Dialog组件样式和交互
- **页面迁移兼容性测试** (P1优先级)
  - 验证迁移后的添加乘客页面功能完整性
  - 测试样式保留和用户体验一致性
  - 验证与后端API的集成
  - 验证Navbar和Dialog样式规范遵循情况
- **乘客信息验证测试** (P0优先级)
  - 验证证件类型和号码格式
  - 测试手机号验证规则
  - 验证必填字段完整性

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-10-22 | 1.5 | 实现完整的表单验证功能，使用react-hook-form和zod | James (Developer) |
| 2025-10-22 | 1.4 | 乘客管理主页面任务完成，状态更新 | James (Developer) |
| 2025-10-22 | 1.3 | 添加Navbar和Dialog样式规范要求 | Winston (Architect) |
| 2025-10-21 | 1.2 | 故事验证通过，状态更新为Approved | Sarah (Product Owner) |
| 2025-10-21 | 1.1 | 添加页面迁移任务和测试要求 | Bob (Scrum Master) |
| 2025-10-21 | 1.0 | 初始故事创建，基于史诗005 US005-06需求 | Bob (Scrum Master) |

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

### Agent Model Used
- Claude Sonnet 4.5 (2025-09-29)

### Debug Log References
- 乘客API集成测试执行：2025-10-21 07:18:56
- 测试文件：[tests/integration/server/passengers.integration.test.ts](tests/integration/server/passengers.integration.test.ts)
- 乘客管理主页面迁移完成：2025-10-22 14:30:00
- 页面文件：[mini/src/pages/passengers/passengers.tsx](mini/src/pages/passengers/passengers.tsx)
- 路由集成完成：2025-10-22 14:35:00
- 个人中心入口添加：2025-10-22 14:40:00
- 表单验证功能实现完成：2025-10-22 15:20:00
- 验证文件：[mini/src/pages/passengers/passengers.tsx](mini/src/pages/passengers/passengers.tsx)
- 使用react-hook-form和zod进行现代化表单验证

### Completion Notes List
- ✅ 用户端乘客API路由已创建并完整实现
- ✅ 使用通用CRUD规范创建了完整的乘客API
- ✅ 实现了用户只能管理自己乘客的权限控制
- ✅ 支持默认乘客设置功能，包括设置新默认时取消原默认状态
- ✅ 用户端乘客API集成测试已完成并全部通过
- ✅ 24个测试用例覆盖乘客CRUD操作、权限控制、搜索功能和性能要求
- ✅ 测试验证了用户数据隔离、认证授权、默认乘客逻辑等关键功能
- ✅ 所有测试在42.93秒内完成，性能符合要求
- ✅ Taro小程序乘客管理主页面已完整迁移并实现
- ✅ 成功从原生小程序迁移到Taro + React技术栈
- ✅ 实现了乘客列表显示、搜索、添加、编辑、删除、设置默认等完整功能
- ✅ 集成真实后端API，使用React Query进行状态管理
- ✅ 遵循Navbar和Dialog样式规范，保持用户体验一致性
- ✅ 乘客页面已集成到小程序路由和个人中心菜单
- ✅ 实现了完整的表单验证功能，使用react-hook-form和zod进行现代化验证
- ✅ 姓名验证：必填、长度限制（2-50字符）
- ✅ 证件类型验证：必填、有效枚举值
- ✅ 证件号码验证：必填、根据证件类型进行格式验证
- ✅ 手机号验证：必填、中国手机号格式验证
- ✅ 实时错误提示和表单状态管理

### File List
- [src/server/api/passengers/index.ts](src/server/api/passengers/index.ts) - 用户端乘客API路由文件
- [tests/integration/server/passengers.integration.test.ts](tests/integration/server/passengers.integration.test.ts) - 乘客API集成测试文件
- [mini/src/pages/passengers/passengers.tsx](mini/src/pages/passengers/passengers.tsx) - Taro小程序乘客管理主页面
- [mini/src/pages/passengers/add-passenger.tsx](mini/src/pages/passengers/add-passenger.tsx) - Taro小程序独立添加乘客页面
- [mini/src/pages/passengers/add-passenger.config.ts](mini/src/pages/passengers/add-passenger.config.ts) - 添加乘客页面配置文件
- [mini/src/app.config.ts](mini/src/app.config.ts) - 小程序路由配置（已包含乘客页面）
- [mini/src/pages/profile/index.tsx](mini/src/pages/profile/index.tsx) - 个人中心页面（已添加乘客管理入口）

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