Story 5.6: 乘客信息管理

Status

Approved

Story

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

Acceptance Criteria

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

Tasks / Subtasks

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

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路由]:

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

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优先级)
- 测试乘客列表页面渲染
- 验证添加乘客表单功能
- 测试编辑和删除乘客功能
页面迁移兼容性测试 (P1优先级)
- 验证迁移后的添加乘客页面功能完整性
- 测试样式保留和用户体验一致性
- 验证与后端API的集成
乘客信息验证测试 (P0优先级)
- 验证证件类型和号码格式
- 测试手机号验证规则
- 验证必填字段完整性

Change Log

Date	Version	Description	Author
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)

005.006.story.md 9.7 KB

Lịch sử Raw

Story 5.6: 乘客信息管理

Status

Story

Acceptance Criteria

Tasks / Subtasks

Dev Notes

数据模型设计

通用CRUD规范要求

权限控制要求

Taro小程序开发规范

文件位置

技术栈要求

开发规范要求

Testing

Change Log

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

005.006.story.md 9.7 KB Lịch sử Raw

Story 5.6: 乘客信息管理

Status

Story

Acceptance Criteria

Tasks / Subtasks

Dev Notes

数据模型设计

通用CRUD规范要求

权限控制要求

Taro小程序开发规范

文件位置

技术栈要求

开发规范要求

Testing

Change Log

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

005.006.story.md 9.7 KB

Lịch sử Raw