# Prototype Review

- 审查目标：`src/prototypes/vehicle-management`（入口：`index.tsx`，含列表页与详情页）
- 用户资料/参考资料：
  - `.spec/requirements-prd-list.md`、`.spec/requirements-prd-detail.md`
  - `annotation-source.json` 及 `scripts/build-annotation-source.mjs` 中的原型实现补充
  - 源码：`index.tsx`、`pages/DetailPage.tsx`、`components/*`、`utils/*`、`data/*.json`
  - 关联只读参考：`src/prototypes/lease-contract-management` 中对「已备车」车辆的消费口径
  - 本轮用户未提供额外 PRD/会议纪要；`src/resources/` 下无车辆管理专属资源文档
- 生成时间：2026-06-25

## 总体点评

车辆管理原型在业务主链路上完成度较高：**筛选（含 KPI 叠加）→ 宽表浏览 → 详情下钻 → 行内/弹窗维护 → Toast 演示跨模块跳转**，与两份 `.spec` PRD 描述的核心任务基本一致。列表页对证照/保险异常、交还车可点、运营城市来源区分（车机/GPS/人工）、所属项目按运营状态显隐等关键业务规则，在 `VehicleTable.tsx` 与 `utils/vehicle.ts` 中均有对应实现；详情页 11 个 Tab 与多类业务记录（事故、故障、违章、异动、调拨、年审）均已接通种子数据与筛选/分页模式。

当前主要风险不在「能不能演示」，而在 **角色权限不可验证**、**文档口径分叉** 与 **原型边界未对用户显式交代** 三类问题：权限常量写死为管理员/运维主管，导致 PRD 中的条件操作无法做负向验收；详情页 PRD 正文仍写弹窗改运营城市/运维负责人，而 annotation 补充与代码已改为内联面板；批量导入、外链跳转、内存台账等「演示态」能力需要在评审与交付时与真实系统能力明确区分，避免被误读为已闭环业务。

作为 ONE-OS 多原型中的车辆主数据模块，与租赁合同管理在「已备车车牌/品牌型号」上的引用关系清晰，但跨模块仍停留在 Toast，尚不能验证端到端数据一致性。

## P0-P3 优先级问题

### P1 - 权限与角色矩阵无法做负向验收

- 证据：`index.tsx` 中 `CAN_EDIT_OPS_MANAGER = true`、`IS_ADMIN = true` 写死；`VehicleTable` / `DetailPage` 仅据此控制「更多」菜单、运维负责人、编辑入口。PRD 列表 §2 明确 ADMIN / 运维主管不同取值下的可见性与可操作性。
- 影响：无法验证非管理员是否隐藏「编辑」、非运维主管是否禁用负责人维护等业务前置条件；后续研发若直接复用该常量，会掩盖权限漏洞。
- 修复方向：在原型中增加可切换的演示角色（或 dev 开关），至少覆盖「仅查看」「运维主管」「管理员」三态，并在 annotation/PRD 中标注验收用例。

### P1 - 详情统计条交互：PRD 正文与最新实现补充不一致（待确认）

- 证据：`requirements-prd-detail.md` §2.3 写运营城市/运维负责人为「弹窗」；`annotation-source.json` 的 `vm-detail-stats` / `vm-ops-modal` 补充写「详情页改用内联编辑面板」；`DetailPage.tsx` 实际使用 `DetailOperateCityInlineEdit`、`DetailOpsManagerInlineEdit`，列表页仍用 `OperateCityEditModal` / `OpsManagerModal`。
- 影响：产品、测试若仍按 PRD 正文验收，会判为缺陷；业务培训材料也会出现「详情弹窗 vs 内联」双口径。
- 修复方向：以 annotation 补充为准时，回写 `requirements-prd-detail.md` §2.3，并说明列表/详情双端交互差异的设计理由；若应统一为弹窗，则改回详情实现。

### P2 - 批量导入承诺与真实能力不匹配

- 证据：`ImportModal.tsx` 文案为「点击或拖拽文件到此处上传」，但上传区仅为 `button` + 隐藏 `input`，无 `onDrop`；`onImport` 仅 Toast「导入校验为原型演示」，不做字段校验、错误行反馈或台账合并。PRD 列表 §6.1 描述「下载模板 → 上传 → 校验」两步流程。
- 影响：业务方可能认为导入链路已可评审字段规则与失败恢复；实际只能验证入口与模板下载，无法讨论必填项、重复车牌、格式错误等边界。
- 修复方向：二选一并在 PRD 标注——（a）补齐拖拽与最小校验反馈（成功/失败条数示意）；（b）收敛文案为「仅演示点击上传」，并在 annotation 标明非目标。

### P2 - 详情多 Tab 内筛选/分页状态不保留

- 证据：`DetailPage.tsx` 使用单一 `tab` state，各 `Detail*RecordsTab` 在切换 Tab 时重新挂载；`requirements-prd-detail.md` §16 已写明「切换 Tab 不保留筛选/分页」。
- 影响：核对同一车辆「租赁记录 + 事故 + 保险」时需重复筛选，增加业务演示与 UAT 摩擦；不影响单 Tab 内逻辑正确性。
- 修复方向：若需支撑联合核查场景，为各 Tab 提升独立 filter/page 状态到 `DetailPage` 或 URL 查询参数；否则在详情 PRD 验收项中明确「不保留」为已知限制。

### P3 - 跨模块与异常态仅停留在 Toast/空态

- 证据：`index.tsx` 中合同、交还车、证照、保险、事故等跳转均为 `showToast`；无加载中、接口失败、权限不足、会话过期等状态；数据为 `vehicles.json` 内存态，刷新即丢失编辑（PRD 列表 §12、详情 §16 已说明）。
- 影响：适合流程走查与字段对照，不足以验证跨系统编号、状态回写、失败重试；对生产排期需单独标注为非本期。
- 修复方向：维持原型边界时，在 PRD「原型局限」增加「跨模块一致性未验证」清单；若进入联调阶段，至少选 1 条主链路（如租赁合同详情）做真实路由或 mock 接口。

## 完整性与项目对齐

| 维度 | 结论 |
|---|---|
| 核心用户 | 运营、业务、运维、管理员 — 与 PRD 一致 |
| 主流程 | 列表筛选/KPI → 表格 → 详情 Tab → 维护字段/负责人/城市 — 已覆盖 |
| 入口/出口 | 车牌/查看进详情，返回列表保留 `pendingFilters`/`appliedFilters`/`kpiTab`/`page` 内存态 — 符合 PRD §9 |
| 范围边界 | 导入/导出/外链为演示；地图依赖外网 — PRD 已声明 |
| 项目对齐 | 模块位于 `src/prototypes/vehicle-management`，与 `lease-contract-management` 通过车辆台账、`READY_VEHICLE_STATUS` 等口径衔接；`src/resources/` 无独立车辆 PRD 副本，以 `.spec` 两份 Markdown 为准 |
| 资料冲突/待确认 | ① 详情统计条「弹窗 vs 内联」见 P1；② 列表 PRD 未写「区域」筛选项，但 `FilterPanel` 与 annotation `vm-filter` 补充已实现华东/华南等映射 — 建议回写列表 PRD §4.1 |

**已对齐且表达较好的能力（节选）**：KPI 与筛选叠加（`applyFilters`）；车牌多行精确匹配；运营城市省-市多选（`OperateCityField`）；证照/保险异常与「禁止交车」；人工运营城市可改、车机/GPS 不可改；详情 11 Tab 与年审记录字段；`PageDocToolbar` + `@axhub/annotation` 需求说明与测试用例导出。

## 业务逻辑连贯性

- **流程顺序**：筛选需点「查询」才生效、重置清空待应用与已应用条件，与 PRD §4.2 一致；KPI 切换重置页码，逻辑自洽。
- **状态迁移**：运营城市保存后 `operateCitySource` 置「人工」；运维负责人、车辆编辑写回 `records` 并 Toast 反馈，列表与详情通过 `activeDetail` 查找最新记录保持同步。
- **角色权限**：正向路径完整，负向路径缺失（见 P1）。
- **数据生命周期**：保险到期展示取自 `insurance-purchases.json` 最新采购（`buildInsuranceExpireMap`），与 PRD §3 一致；台账编辑不落盘，符合原型声明。
- **跨页面一致性**：列表弹窗改城市 vs 详情内联改城市，业务结果一致但交互路径不同，需在文档中统一叙述以免误解为 bug。

## 状态、异常、边界与恢复

| 类别 | 检查结论 |
|---|---|
| 输入校验 | 车牌归一化、多车牌解析、运维候选人按区域过滤已实现；车辆编辑弹窗对运营状态/车辆状态有空值禁用保存 |
| 边界条件 | 筛选无结果时 `VehicleTable` 展示 `vm-empty`；分页在 `total=0` 时仍保底 1 页；各详情 Tab 表内「暂无数据」单元格齐全 |
| 空/加载/成功 | 无网络加载态（本地 JSON）；成功以 Toast 为主，3 秒消失 |
| 失败/权限 | 无 API 失败、权限不足、会话过期演示 |
| 并发/重复 | 单用户内存编辑，无并发冲突处理 |
| 集成失败 | 地图、OpenStreetMap 外网不可用无降级说明（PRD §12 仅提依赖外网） |
| 恢复路径 | 筛选可重置；弹窗可取消（列表运维/城市）；详情内联编辑失焦自动提交（无显式取消，误操作风险需在 UI Review 单独处理） |

## 证据与评估说明

- **用户资料优先级**：本轮无用户附加文档；以 `.spec` 两份 PRD + annotation 补充 + 源码为基线。
- **读取范围**：`requirements-prd-list.md`、`requirements-prd-detail.md`、`ui-review.md`（仅作交叉参考，非本次业务结论来源）、`index.tsx` 及主要 components/utils、`annotation-source.json`、部分 `data/*.json`。
- **独立评估**：`degraded` — 未拆分「业务完整性子代理」与「原型证据子代理」并行互盲评估；业务基线笔记与源码走查在同一轮完成。
- **Impeccable critique 方法运用**：采用其「先证据后结论、优先级 ruthlessly、 persona/边界追问」思路，但输出结构、优先级定义与「不评视觉」边界以 `rules/prototype-review-guide.md` 为准；未生成 `.impeccable/critique` 产物。
