# 车辆管理 · 列表页产品需求说明（PRD）

> 本页为车辆台账列表。标注「原型演示」的跳转、导入、导出仅 Toast 提示，不做真实页面跳转。

---

## 1. 模块定位

| 项 | 说明 |
|---|---|
| 模块名称 | 车辆管理 — 列表页 |
| 目标用户 | 运营、业务、运维、管理员 |
| 核心任务 | 按多维度筛选车辆台账，查看证照/保险/交还车状态，维护运维负责人，进入车辆详情 |
| 页面结构 | 右上角工具栏：「查看需求说明」「PRD文档MD文件下载」「下载测试用例」；筛选区 + KPI + 表格 + 分页 |

---

## 2. 权限与角色（原型常量）

| 常量 | 原型取值 | 影响 |
|---|---|---|
| ADMIN | `true` | 操作列「更多」菜单显示「编辑」 |
| 运维主管 | `true` | 可点击运维负责人、操作列「修改运维负责人」 |

生产环境应由登录用户权限接口下发，原型写死便于演示。

---

## 3. 数据来源总览

| 数据 | 来源文件/规则 | 用途 |
|---|---|---|
| 车辆台账 | `data/vehicles.json`（100 条样例） | 列表、筛选选项、详情、编辑回写 |
| 保险采购 | `data/insurance-purchases.json` | 按车辆 + 险种取**最新一条**采购记录的到期日 |
| 停车场→区域 | `PARKING_REGION_MAP` 常量 | 运维负责人候选区域、运营城市辅助 |
| 运维人员 | `OPS_STAFF` 常量 | 按车辆区域过滤可选运维负责人 |
| 运营城市种子 | `OPERATE_CITY_SEED` + 台账 `location` | 运营城市筛选/修改选项 |
| GPS 坐标 | 优先 `gpsLat/gpsLng`；否则按 `location` 城市基准点 + 车辆 id 偏移模拟 | 地图弹窗 |
| GPS 详细地址 | `locationAddress` 优先，否则 `location` 省市区 | 当前位置列 |
| 所属项目三元组 | `projectName` / `contractNo` / `customer` | 仅运营状态为「租赁」「自营」时展示 |
| 三方租赁公司 | `leaseCompany` | 仅 `vehicleSource === '外租'` 时展示 |
| 交还车记录 | `lastDelivery*` / `lastReturn*` 字段 | 上次交车/还车情况列 |

**空值约定**：台账中 `-`、空字符串视为无数据；列表列默认显示空白（非「—」）。

---

## 4. 筛选区

### 4.1 字段清单

默认展示前 4 项，点击「展开更多筛选项」显示全部。

| 字段 | 控件 | 选项来源 | 匹配规则 |
|---|---|---|---|
| 车牌号 | 多行弹层输入 | 用户输入 | 确认后精确匹配（归一化：去空格、大写） |
| 运营城市 | 省-市级联多选 | 种子 + 停车场映射 + 台账 location | 与车辆运营城市（省-市格式）包含关系 |
| 品牌/型号/客户/部门/项目/合同/所有权/运营公司/租赁公司/停车场 | 可搜索单选 | 当前台账去重排序 | 精确相等 |
| 项目类型 | 可搜索单选 | 租赁、自营 | 与创建合同时合同类型相等 |
| 运营状态 | 可搜索单选 | 租赁、自营、可运营、待运营、退出运营 | 精确相等 |
| 车辆来源 | 可搜索单选 | 自有、外租、挂靠 | 精确相等 |

### 4.2 操作逻辑

| 操作 | 行为 |
|---|---|
| **查询** | 将当前筛选项写入「已应用条件」，列表与 KPI 计数基于全量台账；页码重置为 1 |
| **重置** | 清空待应用与已应用条件，页码重置为 1 |
| 修改筛选项未点查询 | 不影响当前列表 |

筛选与 KPI Tab **叠加**：先按 KPI 分类过滤，再按筛选条件过滤。

---

## 5. KPI 分类卡片

点击卡片切换列表分类，并回到第 1 页。卡片右上角「?」展示口径说明。

| KPI | 统计口径 |
|---|---|
| 所有营运车辆 | 非「非运营车辆」且非「退出运营」 |
| 租赁车辆 | `operateStatus === '租赁'` |
| 自营车辆 | `operateStatus === '自营'` |
| 库存车辆 | `operateStatus` 为「可运营」或「待运营」 |
| 非运营车辆 | `vehicleLedgerType === '非运营车辆'` |
| 退出运营车辆 | `operateStatus === '退出运营'` |
| 证照异常车辆 | 检验有效期已过期（`inspectExpire` 早于今天） |
| 保险异常车辆 | `insuranceStatus === '异常'` |

---

## 6. 列表工具栏

| 按钮 | 行为 |
|---|---|
| 导出 | Toast：`导出功能（原型演示）：当前列表共 N 条` |
| 批量导入 | 打开导入弹窗 |

### 6.1 批量导入弹窗

1. 下载 CSV 模板（含必填字段说明行）
2. 上传文件 → Toast：`已接收文件 {文件名}，导入校验为原型演示`

原型不做真实校验与落库。

---

## 7. 列表字段说明

### 7.1 车辆信息（冻结列）

- 车牌：链接色，点击进入**车辆详情页**
- VIN、品牌·型号：只读展示

### 7.2 运营城市

- 展示：省-市（由 `location` 解析）
- 标签：车机 / GPS / 人工（来源 `operateCitySource` 或推导）
- **可编辑**：仅来源为「人工」时可点击修改 → 运营城市修改弹窗
- 车机/GPS 来源：不可改，hover 提示原因

### 7.3 所属项目

仅**租赁/自营**车辆展示项目名称、合同编码、客户名称；否则三行均为空。

- 项目名称、合同编码：有值时可点击 → Toast 跳转合同详情（原型演示）

### 7.4 里程数

- 在线车辆：显示里程 + 「车机」标签，里程按车机数据格式化
- 离线：仅里程或空

### 7.5 证照 / 保险

| 列 | 有数据 | 无数据/异常 |
|---|---|---|
| 检验有效期 | 到期日 + 剩余/已过期天数标签 | 「未上传」可点击 + 「禁止交车」标签 |
| 保险状态 | 正常/异常 Tag；异常时 hover 展示具体到期险种 | — |
| 交强险/商业险到期 | 到期日 + 剩余天数 | 「未购买」可点击 + 「禁止交车」 |

未上传/未购买点击 → Toast 跳转证照管理或保险采购（原型演示）。

### 7.6 上次交车 / 还车情况

三行纯数值（无行内标题）：里程(km)、人员、时间(至分钟)。**有数据时**可点击。

| 列 | 点击行为 |
|---|---|
| 上次交车情况 | Toast：`即将跳转至交车管理（原型演示）：{车牌}` |
| 上次还车情况 | Toast：`即将跳转至还车管理（原型演示）：{车牌}` |

### 7.7 三方租赁公司

仅外租车辆显示 `leaseCompany`，否则空白。

### 7.8 当前位置

- 在线状态圆点 + 文案
- 详细地址：有 GPS 坐标时可点击 → 地图弹窗（OpenStreetMap 嵌入）
- GPS 时间：精确到秒

### 7.9 运维负责人

可编辑时显示为链接；无负责人显示「设置负责人」→ 运维负责人弹窗。

### 7.10 操作列（冻结）

| 操作 | 条件 | 行为 |
|---|---|---|
| 查看 | 始终 | 进入车辆详情页 |
| 更多 | 管理员或有运维权限 | 下拉：编辑（管理员）、修改运维负责人 |

---

## 8. 弹窗交互

### 8.1 设置运维负责人

- 标题下胶囊：车牌 | 运维区域（省-市）
- 多选搜索选择器，候选人按车辆区域过滤
- **保存**：写回 `opsManagers`，Toast「运维负责人已更新」
- **取消**：不保存

### 8.2 修改运营城市

- 省-市选择，保存后 `location` 更新且 `operateCitySource` 置为「人工」
- Toast「运营城市已更新」

### 8.3 编辑车辆（管理员）

- 可搜索选择器字段与筛选区一致规范
- 保存时运营状态、车辆状态仍为必填（按钮禁用），但标签无红色 *
- Toast「车辆信息已更新」

### 8.4 地图

展示坐标点与 GPS 时间；关闭不保存。

---

## 9. 进入详情页

- 入口：列表车牌链接或操作列「查看」
- 详情页右上角同样有「查看需求说明」，展示**详情页 PRD**（与本文档分离）
- 从详情返回列表时，保留筛选/KPI/分页状态（内存态）

---

## 10. 提示信息汇总（Toast）

| 触发场景 | 文案模板 |
|---|---|
| 导出 | 导出功能（原型演示）：当前列表共 {n} 条 |
| 导入成功 | 已接收文件 {name}，导入校验为原型演示 |
| 运维负责人保存 | 运维负责人已更新 |
| 运营城市保存 | 运营城市已更新 |
| 车辆编辑保存 | 车辆信息已更新 |
| 合同跳转 | 即将跳转至合同详情（原型演示）：{合同编码} |
| 证照跳转 | 即将跳转至证照管理编辑页（原型演示）：{车牌} |
| 保险跳转 | 即将跳转至保险采购编辑页（原型演示）：{车牌} · {险种} |
| 交车跳转 | 即将跳转至交车管理（原型演示）：{车牌} |
| 还车跳转 | 即将跳转至还车管理（原型演示）：{车牌} |

Toast 约 3 秒后自动消失。

---

## 11. 分页

- 默认每页 10 条，可选 10 / 20 / 50 / 100
- 切换每页条数回到第 1 页
- 总条数为筛选后的数量

---

## 12. 原型局限

1. 数据为前端 JSON，刷新页面后编辑结果丢失（内存态）。
2. 导入、导出、外链跳转均为演示提示。
3. 地图依赖外网 OpenStreetMap。

---

## 13. 验收要点

- [ ] 筛选查询/重置与 KPI 叠加正确
- [ ] 空值列显示空白
- [ ] 人工运营城市可改，车机/GPS 不可改
- [ ] 未上传/未购买可点击并提示跳转
- [ ] 交还车有数据可点击、无数据不可点
- [ ] 运维负责人、编辑弹窗保存后列表即时更新
- [ ] 管理员「更多」菜单与权限开关联动
- [ ] 右上角「查看需求说明」展示本文档（列表页 PRD）
- [ ] 「PRD文档MD文件下载」可下载列表页、详情页两份 .md
- [ ] 「下载测试用例」可下载含列表页/详情页 Sheet 的 Excel
