# 案例一（续）：需求与实现差异分析报告

> **版本说明**：对比原始需求文档与前端实现(Passengers-Mobile.vue)的差异
> **原始文档**：案例一-AI辅助需求分析与UserStory生成.md
> **前端实现**：Passengers-Mobile.vue（最完整的移动端实现）
> **生成日期**：2026-05-28

---

## 1. 差异概览

| 差异类别 | 差异项 | 原始需求 | 前端实现 | 处理建议 |
|----------|--------|----------|----------|----------|
| **证件类型** | 数量 | 4种 | 8种 | ✏️ 需求补充 |
| **证件类型** | 详细定义 | 模糊 | 完整枚举 | ✏️ 需求细化 |
| **旅客上限** | 数量 | 8人 | 30人 | ✏️ 需求修正 |
| **旅客字段** | 国籍 | 未定义 | 新增 | ✏️ 需求补充 |
| **旅客字段** | 出生日期 | 未定义 | 新增 | ✏️ 需求补充 |
| **旅客字段** | 性别 | 未定义 | 新增 | ✏️ 需求补充 |
| **旅客字段** | 有效期 | 未定义 | 新增 | ✏️ 需求补充 |
| **旅客字段** | 邮箱 | 未定义 | 新增 | ✏️ 需求补充 |
| **学生字段** | 学校/学号等 | 定义了4个字段 | 未实现 | ⚠️ 待确认 |
| **残军字段** | 残疾证号等 | 定义了2个字段 | 未实现 | ⚠️ 待确认 |
| **API接口** | 请求字段 | 简化版 | 完整版 | ✏️ 接口细化 |
| **交互细节** | 选择器组件 | 未定义 | 完整实现 | ✏️ 需求补充 |

---

## 2. 证件类型差异

### 2.1 原始需求（4种）

```
- 身份证
- 护照
- 港澳通行证
- 台湾通行证
```

### 2.2 前端实现（8种）

| 证件类型 | 枚举值 | 说明 |
|----------|--------|------|
| 中国居民身份证 | `ID_CARD` | - |
| 港澳居民居住证 | `HK_MACAO_RESIDENCE` | 新增 |
| 台湾居民居住证 | `TAIWAN_RESIDENCE` | 新增 |
| 外国人永久居留身份证 | `FOREIGN_PERMANENT` | 新增 |
| 港澳居民来往内地通行证 | `HK_MACAO_PASS` | 补充"来往内地" |
| 台湾居民来往大陆通行证 | `TAIWAN_PASS` | 补充"来往大陆" |
| 中国护照 | `CHINA_PASSPORT` | 新增明确定义 |
| 外国护照 | `FOREIGN_PASSPORT` | 新增明确定义 |

### 2.3 差异分析

```
原始需求问题：
1. "护照"定义模糊，未区分中国护照和外国护照
2. "港澳通行证"未区分证件类型（通行证vs居住证）
3. 缺少台湾居民相关证件类型
4. 缺少外国人永久居留身份证
```

### 2.4 更新后的证件类型定义

```typescript
enum IdType {
  ID_CARD              = 'ID_CARD',              // 中国居民身份证
  HK_MACAO_RESIDENCE   = 'HK_MACAO_RESIDENCE',   // 港澳居民居住证
  TAIWAN_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'      // 外国护照
}
```

---

## 3. 数据字段差异

### 3.1 旅客实体对比

| 字段名 | 原始需求 | 前端实现 | 差异说明 |
|--------|----------|----------|----------|
| `id` | ✅ | ✅ | 一致 |
| `name` | ✅ 姓名 | ✅ 姓名 | 一致 |
| `idType` | ❌ 未定义 | ✅ 证件类型 | **新增** |
| `idCard` | ✅ 证件号 | ✅ 证件号 | 一致 |
| `passengerType` | ✅ 旅客类型 | ✅ 旅客类型 | 一致 |
| `phone` | ✅ 手机号 | ✅ 手机号 | 一致 |
| `nationality` | ❌ 未定义 | ✅ 国籍 | **新增** |
| `birthDate` | ❌ 未定义 | ✅ 出生日期 | **新增** |
| `gender` | ❌ 未定义 | ✅ 性别 | **新增** |
| `expireDate` | ❌ 未定义 | ✅ 有效期 | **新增** |
| `email` | ❌ 未定义 | ✅ 邮箱 | **新增** |
| `isVerified` | ✅ 核验状态 | ✅ 核验状态 | 一致 |
| `isDefault` | ✅ 默认标识 | ✅ 默认标识 | 一致 |
| `createTime` | ❌ 未定义 | ✅ 创建时间 | **新增** |
| `updateTime` | ❌ 未定义 | ✅ 更新时间 | **新增** |

### 3.2 证件类型与字段关联

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

### 3.3 复杂证件类型定义

以下证件类型需要额外字段，称为"复杂证件类型"：
- 外国人永久居留身份证
- 港澳居民来往内地通行证
- 台湾居民来往大陆通行证
- 中国护照
- 外国护照

---

## 4. 旅客数量上限差异

### 4.1 对比

| 来源 | 数量 |
|------|------|
| 原始需求文档 | 8人 |
| 前端实现 | 30人 |
| 12306实际规则 | 30人 |

### 4.2 差异原因

原始需求文档参考了早期12306规则（最多8人），但实际12306规则已更新为30人。

### 4.3 更新建议

```
将原文档中：
"旅客上限：每个用户最多添加8名常用旅客"

更新为：
"旅客上限：每个账号最多允许添加30个乘客"
```

---

## 5. 学生/残军字段差异

### 5.1 学生旅客字段对比

| 字段 | 原始需求 | 前端实现 | 状态 |
|------|----------|----------|------|
| 学校名称 | ✅ 必填 | ❌ 未实现 | ⚠️ 待确认 |
| 学号 | ✅ 必填 | ❌ 未实现 | ⚠️ 待确认 |
| 优惠区间 | ✅ 必填 | ❌ 未实现 | ⚠️ 待确认 |
| 有效期 | ✅ 必填 | ❌ 未实现 | ⚠️ 待确认 |

**分析**：前端Passengers-Mobile.vue的学生旅客仅包含基础字段，未包含学生资质相关字段。这可能是：
1. 学生资质功能尚未开发
2. 学生资质在购票时单独处理，而非存储在旅客信息中

### 5.2 残军旅客字段对比

| 字段 | 原始需求 | 前端实现 | 状态 |
|------|----------|----------|------|
| 残疾证号 | ✅ 必填 | ❌ 未实现 | ⚠️ 待确认 |
| 有效期 | ✅ 必填 | ❌ 未实现 | ⚠️ 待确认 |

### 5.3 待确认事项

```
❓ 待确认1：学生/残军的资质字段是否需要存储在旅客信息中？
   - 如果是：需要补充后端API和数据库字段
   - 如果否：则仅在购票时需要提供资质证明

❓ 待确认2：学生优惠区间如何选择？
   - 方案A：从车站列表选择（类似原需求）
   - 方案B：简化处理，不存储此字段
```

---

## 6. API接口差异

### 6.1 原始需求接口定义

```typescript
// 添加旅客
add(data: {
  name: string
  idCard: string
  passengerType?: number
  phone?: string
  gender?: number  // 注意：这里的gender是数字类型
})
```

### 6.2 前端实现对应的接口调用

```typescript
// 实际上传字段（Passengers-Mobile.vue）
{
  name: string
  idType: string        // 新增：证件类型
  idCard: string
  passengerType: number
  phone: string
  nationality: string   // 新增：国籍
  birthDate: string     // 新增：出生日期
  gender: string        // 变更：字符串类型 ('male'/'female')
  expireDate: string    // 新增：有效期
  email: string         // 新增：邮箱
}
```

### 6.3 API字段差异汇总

| 字段 | 原API定义 | 实际需要 | 差异 |
|------|-----------|----------|------|
| idType | ❌ 无 | ✅ 必填 | **新增** |
| nationality | ❌ 无 | ✅ 条件必填 | **新增** |
| birthDate | ❌ 无 | ✅ 条件必填 | **新增** |
| gender | 数字类型 | 字符串类型 | **类型变更** |
| expireDate | ❌ 无 | ✅ 条件必填 | **新增** |
| email | ❌ 无 | ✅ 条件必填 | **新增** |

---

## 7. 交互细节差异

### 7.1 原始需求交互描述

```
原始需求中关于交互的描述：
- "添加旅客" → 无具体交互说明
- "编辑旅客" → 无具体交互说明
- "选择证件类型" → 无具体交互说明
```

### 7.2 前端实现的交互组件

| 组件 | 原始需求 | 前端实现 | 说明 |
|------|----------|----------|------|
| 证件类型选择器 | ❌ 未定义 | ✅ 底部弹窗式 | 支持8种证件类型 |
| 优惠类型选择器 | ❌ 未定义 | ✅ 底部弹窗式 | 成人/儿童/学生/残军 |
| 国籍选择器 | ❌ 未定义 | ✅ 底部弹窗+搜索 | 195个国家/地区 |
| 日期选择器 | ❌ 未定义 | ✅ 滚轮式年/月/日 | 出生日期、有效期 |
| 性别选择器 | ❌ 未定义 | ✅ 单选按钮组 | 男/女 |
| 删除确认 | ✅ 有描述 | ✅ 对话框确认 | 一致 |

### 7.3 交互细节补充

```markdown
## 证件类型选择器
- 弹出位置：屏幕底部
- 动画：从底部滑入，300ms ease
- 遮罩：半透明黑色遮罩
- 关闭：点击遮罩或关闭按钮
- 选中状态：浅蓝色背景高亮

## 日期选择器（滚轮式）
- 三列选择：年/月/日
- 触摸滚动，支持惯性
- 选中项居中高亮
- 闰年2月自动处理
- 顶部确认/取消按钮

## 国籍选择器
- 顶部搜索框
- 支持中文名、英文名、拼音搜索
- 选中项浅蓝色背景
```

---

## 8. 校验规则差异

### 8.1 姓名校验

| 证件类型 | 原始需求 | 前端实现 | 占位符提示 |
|----------|----------|----------|------------|
| 中国居民身份证 | 2-20字符 | 一致 | "请填写真实姓名" |
| 港澳居民居住证 | - | 2-20字符 | "请填写真实姓名" |
| 台湾居民居住证 | - | 2-20字符 | "请填写真实姓名" |
| 外国人永久居留身份证 | - | 2-20字符 | "请填写真实姓名" |
| 港澳居民来往内地通行证 | - | 2-20字符 | "请输入真实姓名，以便购票" |
| 台湾居民来往大陆通行证 | - | 2-20字符 | "请输入真实姓名，以便购票" |
| 中国护照 | - | 2-20字符 | "中国护照用户请填写中文姓名" |
| 外国护照 | - | 2-50字符 | "外国护照按姓名顺序填写英文姓名" |

### 8.2 证件号校验

| 证件类型 | 原始需求 | 前端实现 | 说明 |
|----------|----------|----------|------|
| 中国居民身份证 | 18位 | 一致 | 支持末位X |
| 港澳居民居住证 | - | 待定 | - |
| 台湾居民居住证 | - | 待定 | - |
| 外国人永久居留身份证 | - | 字母+数字 | - |
| 港澳居民来往内地通行证 | - | H/T+8位数字 | - |
| 台湾居民来往大陆通行证 | - | W+8位数字 | - |
| 中国护照 | - | E+8位数字 | - |
| 外国护照 | - | 字母+数字 | - |

---

## 9. 儿童旅客年龄校验

### 9.1 原始需求

```
If 年龄 >= 14周岁 Then 显示提示："14周岁以上请选择成人"
If 年龄 < 0 Then 显示提示："出生日期不能晚于今天"
```

### 9.2 前端实现

```typescript
// 前端根据旅客类型展示提示，但未实现年龄自动计算
// 移动端实现了出生日期选择器，但校验逻辑需要确认
```

### 9.3 差异说明

```
差异点：
- 原始需求定义了儿童年龄校验规则
- 前端实现了出生日期选择器（复杂证件类型必需）
- 但儿童年龄的自动校验逻辑未在Passengers-Mobile.vue中实现

建议补充：
- 当旅客类型为"儿童"时，出生日期应为必填
- 根据出生日期自动计算年龄
- 年龄 >= 14周岁时提示建议选择成人
```

---

## 10. 差异汇总与处理建议

### 10.1 需要更新的需求内容

| 序号 | 差异项 | 更新内容 | 优先级 |
|------|--------|----------|--------|
| 1 | 证件类型 | 从4种扩展到8种 | P0 |
| 2 | 旅客上限 | 从8人修正为30人 | P0 |
| 3 | 新增字段 | 国籍、出生日期、性别、有效期、邮箱 | P0 |
| 4 | 字段关联 | 定义8种证件类型与字段的关联关系 | P0 |
| 5 | 交互细节 | 补充选择器、日期控件规范 | P1 |
| 6 | 校验规则 | 补充各证件类型的校验规则 | P1 |

### 10.2 待确认事项

| 序号 | 待确认项 | 影响范围 | 负责人 |
|------|----------|----------|--------|
| 1 | 学生资质字段是否存储 | API设计、数据库设计 | 后端 |
| 2 | 残军资质字段是否存储 | API设计、数据库设计 | 后端 |
| 3 | 儿童年龄自动校验 | 前端交互 | 前端 |

### 10.3 不需要更改的内容

| 内容 | 说明 |
|------|------|
| 旅客类型枚举 | 成人/儿童/学生/残军保持一致 |
| 核验状态 | 已核验/待核验保持一致 |
| 默认旅客设置 | 功能保持一致 |
| 删除确认交互 | 功能保持一致 |

---

## 11. 更新建议汇总

### 11.1 数据模型更新建议

```typescript
// 更新旅客实体定义
interface Passenger {
  id: number
  name: string
  idType: IdType           // 新增：证件类型
  idCard: string
  passengerType: PassengerType
  phone: string
  nationality?: string      // 新增：国籍
  birthDate?: string       // 新增：出生日期
  gender?: 'male' | 'female'  // 新增：性别
  expireDate?: string       // 新增：有效期
  email?: string           // 新增：邮箱
  isVerified: number
  isDefault?: number
  // 以下为12306扩展字段（如需）
  // schoolName?: string     // 学校名称（学生）
  // studentNo?: string      // 学号（学生）
  // discountStation?: string // 优惠区间（学生）
  // credentialNo?: string   // 残疾证号（残军）
  createTime?: string
  updateTime?: string
}
```

### 11.2 API接口更新建议

```typescript
// 更新添加旅客接口
add(data: {
  name: string
  idType: string           // 新增
  idCard: string
  passengerType: number
  phone: string
  nationality?: string      // 新增
  birthDate?: string       // 新增
  gender?: string          // 变更类型
  expireDate?: string      // 新增
  email?: string           // 新增
})
```

### 11.3 需求文档更新建议

| 原始内容 | 更新为 |
|----------|--------|
| 4种证件类型 | 8种证件类型 |
| 8人上限 | 30人上限 |
| 缺少的5个字段 | 新增字段定义 |
| 模糊的校验规则 | 具体的校验规则 |

---

*差异分析完成时间：2026-05-28*
*前端实现版本：Passengers-Mobile.vue（完整版）*
