# 案例六：AI辅助前端旅客管理需求细化

> **版本说明**：本版本基于前端界面实现反向推导需求，确保需求文档与实际实现一致
> **前置文档**：案例一-AI辅助需求分析-修正版.md
> **生成日期**：2026-05-28

---

## 1. 文档目的

### 1.1 背景

在完成前端旅客管理模块开发后，我们发现原有需求文档存在以下问题：

| 问题类型 | 具体表现 |
|----------|----------|
| **字段不完整** | 原文档仅覆盖4种证件类型，实际实现支持8种 |
| **字段缺失** | 外国旅客相关字段（国籍、出生日期、性别、有效期、邮箱）未定义 |
| **交互细节缺失** | 选择器、日期控件、搜索功能等交互需求未明确 |
| **校验规则缺失** | 不同证件类型的格式校验规则未详细定义 |

### 1.2 目标

- 基于现有前端实现，反向梳理完整的旅客管理需求
- 确保需求文档与前端实现一致
- 补充遗漏的交互细节和校验规则

---

## 2. 旅客实体定义

### 2.1 旅客信息模型

```typescript
interface Passenger {
  id: number                    // 旅客ID
  name: string                  // 姓名
  idType: IdType               // 证件类型
  idCard: string               // 证件号码
  passengerType: PassengerType  // 旅客类型（成人/儿童/学生/残疾军人）
  phone: string                // 手机号
  nationality?: string          // 国籍（仅外国人永久居留身份证、外国护照）
  birthDate?: string           // 出生日期（仅复杂证件类型）
  gender?: 'male' | 'female'   // 性别（仅复杂证件类型）
  expireDate?: string          // 证件有效期截止日期（仅复杂证件类型）
  email?: string              // 电子邮箱（仅外国护照）
  isVerified: number          // 核验状态：0-待核验，1-已核验
  isDefault?: number          // 是否默认：0-否，1-是
  createTime?: string         // 创建时间
  updateTime?: string         // 更新时间
}
```

### 2.2 证件类型枚举

```typescript
enum IdType {
  ID_CARD              = 'ID_CARD',              // 中国居民身份证
  HK_MACAO_RESIDENCE   = 'HK_MACAO_RESIDENCE',   // 港澳居民居住证
  TIWAN_RESIDENCE      = 'TAIWAN_RESIDENCE',      // 台湾居民居住证
  FOREIGN_PERMANENT     = 'FOREIGN_PERMANENT',     // 外国人永久居留身份证
  HK_MACAO_PASS        = 'HK_MACAO_PASS',        // 港澳居民来往内地通行证
  TAIWAN_PASS          = 'TAIWAN_PASS',          // 台湾居民来往大陆通行证
  CHINA_PASSPORT       = 'CHINA_PASSPORT',       // 中国护照
  FOREIGN_PASSPORT      = 'FOREIGN_PASSPORT'       // 外国护照
}
```

### 2.3 证件类型与字段关系

| 证件类型 | 姓名 | 证件号 | 手机号 | 国籍 | 出生日期 | 性别 | 有效期 | 邮箱 |
|----------|------|--------|--------|------|----------|------|--------|------|
| 中国居民身份证 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 港澳居民居住证 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 台湾居民居住证 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 外国人永久居留身份证 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| 港澳居民来往内地通行证 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| 台湾居民来往大陆通行证 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| 中国护照 | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
| 外国护照 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

**注**：复杂证件类型指后5种（外国人永久居留身份证、港澳居民来往内地通行证、台湾居民来往大陆通行证、中国护照、外国护照）

### 2.4 旅客类型枚举

```typescript
enum PassengerType {
  ADULT   = 1,  // 成人
  CHILD   = 2,  // 儿童
  STUDENT = 3,  // 学生
  DISABLED = 4  // 残疾军人
}
```

---

## 3. 功能需求细化

### 3.1 旅客列表

#### F01: 查看旅客列表

**用户故事**：
- 作为已登录用户，我希望查看我的所有常用旅客信息，以便快速选择乘车人

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 用户访问旅客管理页面 | 显示旅客列表，包含：姓名、证件类型（中文名称）、证件号（脱敏）、旅客类型标签、手机号（脱敏） |
| AC2 | 旅客类型展示 | 不同类型显示不同颜色标签：成人-绿色、儿童-橙色、学生-蓝色、残疾军人-红色 |
| AC3 | 证件号脱敏规则 | 显示前4位 + `********` + 后4位，如：`1101********1234` |
| AC4 | 手机号脱敏规则 | 显示前3位 + `****` + 后4位，如：`138****8001` |
| AC5 | 空状态 | 无旅客时显示空状态引导，提示"暂无乘车人，添加常用联系人购票更便捷" |
| AC6 | 旅客数量上限 | 最多添加30名旅客（12306规则），前端可配置上限提示 |

#### F02: 移动端旅客分组展示

**用户故事**：
- 作为移动端用户，我希望旅客按姓名首字母分组展示，以便快速查找

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 分组规则 | 按姓名首字母拼音分组，字母作为分组标题 |
| AC2 | 排序规则 | 组内按姓名升序排列 |
| AC3 | 当前用户标识 | 当前登录用户单独展示，显示"当前用户"标签 |

#### F03: 设置默认旅客

**用户故事**：
- 作为已登录用户，我希望设置一名默认旅客，以便购票时自动填充

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 默认标记 | 默认旅客显示"默认"标签或特殊标识 |
| AC2 | 切换默认 | 点击设为默认后，替换原默认旅客 |
| AC3 | 默认旅客排序 | 默认旅客排在列表最前面 |

---

### 3.2 添加旅客

#### F04: 添加旅客（基础流程）

**用户故事**：
- 作为已登录用户，我希望添加常用旅客，以便购票时快速选择

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 进入添加流程 | 点击"添加旅客"按钮，打开添加对话框 |
| AC2 | 扫描证件入口 | 显示"扫描/上传证件快速填写"入口（推荐功能占位） |
| AC3 | 选择证件类型 | 提供8种证件类型选择，选择后动态显示相关字段 |
| AC4 | 动态字段展示 | 根据证件类型显示对应字段（见2.3节表格） |
| AC5 | 姓名规则 | 2-50个字符，外国护照需填写英文姓名 |
| AC6 | 姓名占位符提示 | 根据证件类型显示不同占位符 |
| AC7 | 提交校验 | 所有必填字段验证通过后保存 |
| AC8 | 数量限制 | 达到上限时提示"每个账号最多允许添加30个乘客" |

#### F05: 证件类型选择

**用户故事**：
- 作为用户，我希望方便地选择证件类型，以便正确填写旅客信息

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 证件类型列表 | 显示8种证件类型中文名称 |
| AC2 | 选择交互 | 点击选项后关闭选择器，更新表单 |
| AC3 | 已选标识 | 当前选中项显示选中状态 |

#### F06: 国籍选择（仅复杂证件类型）

**用户故事**：
- 作为用户，我希望选择国籍以便完成外国旅客信息登记

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 显示条件 | 证件类型为"外国人永久居留身份证"或"外国护照"时显示 |
| AC2 | 国籍列表 | 提供195个国家/地区选择，含中文名和英文名 |
| AC3 | 搜索功能 | 支持按国家名称或拼音搜索 |
| AC4 | 选中回显 | 选中后显示国家中文名称 |

#### F07: 出生日期选择

**用户故事**：
- 作为用户，我希望选择出生日期以便完成旅客信息登记

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 显示条件 | 证件类型为复杂证件类型时显示 |
| AC2 | 日期范围 | 出生日期不能晚于当前日期 |
| AC3 | 选择器类型 | 滚轮式日期选择器（年/月/日三列） |
| AC4 | 闰年处理 | 2月份天数根据年份自动调整 |

#### F08: 性别选择

**用户故事**：
- 作为用户，我希望选择性别以便完成旅客信息登记

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 显示条件 | 证件类型为复杂证件类型时显示 |
| AC2 | 选项 | 男/女两个选项 |
| AC3 | 单选交互 | 点击切换选中状态 |

#### F09: 有效期截止日期选择

**用户故事**：
- 作为用户，我希望选择证件有效期以便完成旅客信息登记

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 显示条件 | 证件类型为复杂证件类型时显示 |
| AC2 | 日期范围 | 有效期必须不早于当前日期 |
| AC3 | 选择器类型 | 滚轮式日期选择器（年/月/日三列） |

#### F10: 联系方式填写

**用户故事**：
- 作为用户，我希望填写联系方式以便接收铁路服务通知

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 手机号格式 | +86前缀，11位数字 |
| AC2 | 邮箱字段条件 | 仅外国护照显示邮箱字段 |
| AC3 | 联系方式提示 | 外国护照提示"请在手机号和电子邮箱中任选一个进行核验" |
| AC4 | 温馨提示 | 显示：请您填写乘车人真实有效的联系方式... |

#### F11: 优惠（待）类型选择

**用户故事**：
- 作为用户，我希望选择旅客的优惠类型以便购买相应车票

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 选项列表 | 成人、儿童、学生、残疾军人 |
| AC2 | 默认值 | 新增时默认为"成人" |
| AC3 | 类型标签颜色 | 成人-绿色、儿童-橙色、学生-蓝色、残疾军人-红色 |

---

### 3.3 编辑旅客

#### F12: 编辑旅客信息

**用户故事**：
- 作为已登录用户，我希望编辑旅客信息以便更正错误或更新信息

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 进入编辑 | 点击旅客卡片/行，打开编辑对话框 |
| AC2 | 不可编辑字段 | 证件类型、证件号码不可编辑（显示但禁用） |
| AC3 | 可编辑字段 | 姓名、旅客类型、手机号可编辑 |
| AC4 | 删除入口 | 编辑模式下提供删除按钮 |
| AC5 | 保存提交 | 验证通过后更新旅客信息 |

---

### 3.4 删除旅客

#### F13: 删除旅客

**用户故事**：
- 作为已登录用户，我希望删除不需要的旅客以便管理常用联系人列表

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 删除确认 | 弹出确认对话框："确定要删除乘车人[姓名]吗？" |
| AC2 | 取消操作 | 用户取消时关闭对话框，不删除 |
| AC3 | 删除后回显 | 列表移除该旅客，显示"删除成功"提示 |
| AC4 | 删除限制 | 提示：乘车人在添加后30天内不允许删除 |

---

### 3.5 旅客核验

#### F14: 旅客核验状态

**用户故事**：
- 作为已登录用户，我希望了解旅客的核验状态以便确认是否可以购票

**验收标准**：

| AC编号 | 场景 | 预期结果 |
|--------|------|----------|
| AC1 | 核验状态标签 | 已核验-绿色标签，待核验-橙色标签 |
| AC2 | 未核验提示 | 添加后24小时内未通过核验，提示到车站办理身份核验 |

---

## 4. 交互细节规范

### 4.1 选择器组件规范

#### 证件类型/优惠类型选择器

| 规范项 | 要求 |
|--------|------|
| 触发方式 | 点击表单项行 |
| 弹出位置 | 屏幕底部 |
| 动画 | 从底部滑入，300ms ease |
| 遮罩 | 半透明黑色遮罩 |
| 关闭 | 点击遮罩或关闭按钮 |
| 选项样式 | 左侧选项文字，右侧单选图标 |
| 选中状态 | 浅蓝色背景高亮 |

#### 日期选择器

| 规范项 | 要求 |
|--------|------|
| 组件类型 | 滚轮式三列选择器（年/月/日） |
| 视觉指示 | 选中项居中，上下有半透明边框指示 |
| 滚动方式 | 触摸滚动，支持惯性滚动 |
| 确认/取消 | 顶部取消/确定按钮 |
| 日期联动 | 切换年/月时自动调整日选项（闰年2月处理） |

#### 国籍选择器

| 规范项 | 要求 |
|--------|------|
| 搜索框 | 顶部搜索输入框 |
| 搜索方式 | 支持中文名、英文名、拼音搜索 |
| 列表展示 | 左侧国家名，右侧英文名 |
| 选中状态 | 浅蓝色背景高亮 |

### 4.2 表单规范

#### 必填标识

| 规范项 | 要求 |
|--------|------|
| 必填标记 | 姓名右侧显示蓝色问号图标 |
| 选填标记 | 手机号/邮箱等选填字段不标记 |

#### 输入框状态

| 状态 | 样式 |
|------|------|
| 默认 | 灰色边框 |
| 聚焦 | 蓝色边框 |
| 错误 | 红色边框 + 错误提示 |
| 禁用 | 灰色背景 |

### 4.3 提示文案规范

#### 温馨提示内容

```
1. 请提供乘车人真实有效的联系方式。对于未成年人、老年人等重点旅客以及无手机的旅客，可提供监护人或能及时联系的亲友手机号码。
2. 互联网售票实行实名制，请准确填写乘车人基本信息。
3. 如旅客身份信息未能在添加后的24小时内通过核验，请乘车人持有效身份证件原件到车站办理身份核验。
4. 乘车人在添加后30天内不允许删除，每个账号最多允许添加30个乘客。
```

---

## 5. 数据校验规则

### 5.1 姓名校验

| 证件类型 | 规则 | 错误提示 |
|----------|------|----------|
| 中国居民身份证 | 2-20个字符 | 姓名长度为2-20个字符 |
| 港澳居民居住证 | 2-20个字符 | 姓名长度为2-20个字符 |
| 台湾居民居住证 | 2-20个字符 | 姓名长度为2-20个字符 |
| 外国人永久居留身份证 | 2-20个字符 | 姓名长度为2-20个字符 |
| 港澳居民来往内地通行证 | 2-20个字符 | 请输入真实姓名，以便购票 |
| 台湾居民来往大陆通行证 | 2-20个字符 | 请输入真实姓名，以便购票 |
| 中国护照 | 2-20个字符 | 中国护照用户请填写中文姓名 |
| 外国护照 | 2-50个字符（英文） | 外国护照按姓名顺序填写英文姓名 |

### 5.2 证件号校验

| 证件类型 | 规则 | 错误提示 |
|----------|------|----------|
| 中国居民身份证 | 18位，最后一位可为X | 身份证号格式不正确 |
| 港澳居民居住证 | 格式待定 | 请输入正确的证件号 |
| 台湾居民居住证 | 格式待定 | 请输入正确的证件号 |
| 外国人永久居留身份证 | 字母+数字组合 | 请输入正确的证件号 |
| 港澳居民来往内地通行证 | H/T + 8位数字 | 请输入正确的证件号 |
| 台湾居民来往大陆通行证 | W + 8位数字 | 请输入正确的证件号 |
| 中国护照 | E + 8位数字 | 请输入正确的证件号 |
| 外国护照 | 字母+数字组合 | 请输入正确的证件号 |

### 5.3 手机号校验

| 规则 | 错误提示 |
|------|----------|
| 11位数字 | 请输入11位手机号 |
| 以86开头或纯数字 | 手机号格式不正确 |

### 5.4 邮箱校验（仅外国护照）

| 规则 | 错误提示 |
|------|----------|
| 有效的邮箱格式 | 邮箱格式不正确 |

---

## 6. 页面布局规范

### 6.1 桌面端布局

| 区域 | 说明 |
|------|------|
| 顶部导航 | Logo + 主导航菜单 + 用户信息 |
| 内容区 | 最大宽度1200px，居中显示 |
| 列表形式 | 表格形式展示旅客信息 |
| 操作区 | 列表内编辑/删除按钮 |

### 6.2 移动端布局

| 区域 | 说明 |
|------|------|
| 顶部导航 | 返回按钮 + 标题 + 添加按钮 |
| 刷新提示 | 黄色提示条："下拉刷新可获取12306乘车人最新状态" |
| 内容区 | 按首字母分组的旅客列表 |
| 弹窗形式 | 全屏弹窗展示添加/编辑表单 |

---

## 7. 与原需求文档的差异

### 7.1 新增内容

| 差异项 | 原文档 | 本文档 |
|--------|--------|--------|
| 证件类型数量 | 4种（身份证/护照/港澳通行证/台湾通行证） | 8种（含居住证、外国人永久居留证等） |
| 国籍字段 | 未定义 | 仅外国人永久居留身份证、外国护照需要 |
| 出生日期 | 未定义 | 仅复杂证件类型需要 |
| 性别字段 | 未定义 | 仅复杂证件类型需要 |
| 有效期至 | 未定义 | 仅复杂证件类型需要 |
| 电子邮箱 | 未定义 | 仅外国护照需要 |
| 国家选择器 | 未定义 | 含195个国家/地区的搜索选择器 |
| 日期选择器 | 未定义 | 滚轮式年/月/日选择器 |
| 旅客分组展示 | 未定义 | 按姓名首字母分组（移动端） |
| 当前用户标识 | 未定义 | 单独展示当前用户 |

### 7.2 需求冲突说明

| 项目 | 原文档描述 | 实际实现 | 说明 |
|------|------------|----------|------|
| 旅客数量上限 | 8人 | 30人 | 按12306实际规则调整为30人 |
| 旅客类型 | 成人/儿童/学生/残军 | 一致 | - |
| 核验状态 | 已核验/待核验 | 一致 | - |

---

## 8. API接口对照

### 8.1 旅客相关接口

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 获取旅客列表 | GET | /passengers | 返回当前用户的所有旅客 |
| 添加旅客 | POST | /passengers | 添加新旅客 |
| 更新旅客 | PUT | /passengers/{id} | 更新旅客信息 |
| 删除旅客 | DELETE | /passengers/{id} | 删除旅客 |
| 获取旅客详情 | GET | /passengers/{id} | 获取单个旅客详细信息 |

### 8.2 请求/响应字段对照

**添加旅客请求**：
```json
{
  "name": "张三",
  "idType": "ID_CARD",
  "idCard": "110101199001011234",
  "passengerType": 1,
  "phone": "13800138001",
  "nationality": "",
  "birthDate": "",
  "gender": "",
  "expireDate": "",
  "email": ""
}
```

**旅客响应**：
```json
{
  "id": 1,
  "name": "张三",
  "idType": "ID_CARD",
  "idCard": "110101199001011234",
  "passengerType": 1,
  "phone": "13800138001",
  "nationality": "",
  "birthDate": "",
  "gender": "",
  "expireDate": "",
  "email": "",
  "isVerified": 1,
  "isDefault": 1,
  "createTime": "2026-05-28 10:00:00",
  "updateTime": "2026-05-28 10:00:00"
}
```

---

## 9. 前端实现文件清单

| 文件 | 说明 |
|------|------|
| `views/Passengers.vue` | 基础桌面版（表格形式） |
| `views/Passengers-Normal.vue` | 普通桌面版 |
| `views/Passengers-Designer.vue` | 设计师版（卡片形式） |
| `views/Passengers-Mobile.vue` | 移动版（完整功能） |
| `api/passenger.ts` | 旅客API定义 |

---

*本文档生成时间：2026-05-28*
*基于前端实现反向推导*
