diff --git a/docs/superpowers/specs/2026-07-25-pl-tripartite-vehicle-personnel-design.md b/docs/superpowers/specs/2026-07-25-pl-tripartite-vehicle-personnel-design.md new file mode 100644 index 000000000..464155814 --- /dev/null +++ b/docs/superpowers/specs/2026-07-25-pl-tripartite-vehicle-personnel-design.md @@ -0,0 +1,310 @@ +# 运输管理 · 三方/山峡分册与粘贴建档 — 设计文档 + +> **日期**: 2026-07-25 +> **状态**: 已批准(待实现) +> **界面模式**: P01 标准列表 + 弹窗表单 +> **前置**: +> - `docs/superpowers/specs/2026-06-19-pl-vehicle-personnel-cert-design.md` +> - `docs/superpowers/specs/2026-07-12-pl-required-cert-slots-design.md` +> - `docs/superpowers/specs/2026-07-13-pl-personnel-cert-split-design.md` +> - 承运商资质/审核相关现网实现(`pl/carrier`、`pl-plan-arrange-dialog`) + +## 背景与问题 + +### 业务诉求 + +1. **分册管理**:山峡自有与三方(承运商)的车辆、驾押人员分开维护,避免混在「全部」列表中操作规则不一致。 +2. **证书差异**:山峡自有车辆/人员必须登记证书;三方车辆/人员无法约束对方是否提供证书,**有则可选登记、无则不阻断**。 +3. **快速建档**:客户常以一段固定格式文本提供三方车与驾押信息,需粘贴识别后自动生成三方车辆与人员。 +4. **承运商准入取消**:承运商管理不再使用审核状态;其他界面选择承运商时不校验审核、资质完整性、协议过期,列表内均可选。 + +### 示例客户文本 + +``` +皖LB1405 皖LP359 +核载:34 吨 +驾驶员:徐孝军 +手机号:18956652137 +身份证:342921198602020031 +押运员:汪海明 +电话:13955522828 +身份证:342829197009084019 +``` + +- 首行:前为**主车号**,后为**挂车号**。 +- 其后为核载、驾驶员、押运员及联系方式/身份证。 + +### 与现网差距 + +| 项 | 现网 | 目标 | +|----|------|------| +| 车辆菜单 | 「全部车辆信息」(self+carrier)+「山峡自有车辆」 | 「三方车辆」+「山峡自有车辆」 | +| 人员菜单 | 「驾押人员信息」(self+carrier 混在一起) | 「三方驾押人员」+「山峡驾押人员」 | +| 承运商车辆证书 | 仍强制主车/挂车部分证书,且关联人员证书校验 | 三方完全不强制证书 | +| 人员证书 | 不区分归属,保存均校验必备证 | 仅山峡人员强制;三方人员不强制 | +| 粘贴建档 | 无 | 三方车辆 / 三方人员双入口 | +| 承运商审核 | 有审核状态;安排运输校验审核/资质/协议 | 去审核 UI/流程;选择不校验上述项 | + +--- + +## 已确认决策 + +| # | 决策 | 说明 | +|---|------|------| +| D1 | **四菜单分册** | 三方车辆、三方驾押人员、山峡自有车辆、山峡驾押人员 | +| D2 | **实现路径 A** | 列表页变体 + 共享粘贴弹窗;后端沿用现有 API,按归属过滤并放宽三方证书校验 | +| D3 | **三方证书不强制** | 表单结构保持;证书/附件类不设必填、不阻断保存 | +| D4 | **三方身份字段仍必填** | 车牌、姓名、人员类型、承运商(车辆)等身份项保持现表单必填 | +| D5 | **山峡侧不变** | 车辆/人员必备证书与现网一致 | +| D6 | **粘贴双入口** | 车辆页整车套装;人员页以人为主,识别到车牌可勾选建车并关联(默认勾选) | +| D7 | **冲突三选一** | 车牌或身份证已存在 → 复用 / 覆盖更新 / 取消 | +| D8 | **粘贴建车必选承运商** | 识别预览中未选承运商不可确认生成车辆 | +| D9 | **承运商去准入** | 去掉审核 UI/流程;选择时不校验审核、资质完整性、协议过期 | +| D10 | **归属匹配保留** | 三方车仅关联三方人,山峡车仅关联山峡人 | + +--- + +## 一、菜单与数据范围 + +**基础信息库**下四个菜单(建议顺序): + +| 菜单名 | 策略 | 列表固定过滤 | 表单锁定 | +|--------|------|--------------|----------| +| 三方车辆 | 现「全部车辆信息」改名改造 | `vehicleType=carrier` | 车辆类型固定承运商,隐藏类型切换 | +| 三方驾押人员 | **新建**页(人员页变体) | `personnelAffiliation=carrier` | 归属固定非山峡/承运商 | +| 山峡自有车辆 | 保持 | `vehicleType=self` | 保持现状 | +| 山峡驾押人员 | 现「驾押人员信息」改名 | `personnelAffiliation=self` | 归属固定山峡 | + +要点: + +- 不再保留「全部车辆 / 全部人员」混合列表。 +- 同步调整 `sys_menu` 文案、路由 `meta.title`、权限码;旧名称退役。 +- 车辆↔人员关联仍校验归属匹配(D10)。 + +界面参考: + +- 车辆列表/弹窗:`web-admin/src/views/pl/vehicle/index.vue`、`self-vehicle/index.vue` +- 人员列表/弹窗:`web-admin/src/views/pl/personnel/index.vue` + +--- + +## 二、证书与必填规则 + +### 2.1 三方车辆 / 三方驾押人员 + +- 表单结构保持现状(证书区仍可录入)。 +- **不做证书强制**:不预置必备槽位阻断;前后端保存不校验必备证齐全。 +- 关联人员时也不因缺证拦截。 +- **身份字段仍必填**:车牌、承运商、姓名、人员类型、人员归属(锁定)等,与现表单身份项一致。 + +### 2.2 山峡自有车辆 / 山峡驾押人员 + +- 表单与必备证书规则**全部保持现状**(主车/挂车必备、人员按类型必备、前后端双校验、保存阻断)。 +- 权威清单见 `2026-07-12` / `2026-07-13` 设计文档。 + +### 2.3 相对现网的校验调整 + +| 场景 | 现网 | 目标 | +|------|------|------| +| `vehicleType=carrier` 车辆保存 | `validate_carrier_vehicle_required_certs` | **跳过**车辆证书必备校验 | +| 承运商车关联人员证书 | `validate_vehicle_personnel_cert_links` | **跳过**(三方) | +| 人员保存 | 一律 `validate_personnel_required_certs` | 仅 `personnelAffiliation=self` 校验;`carrier` 跳过 | +| 归属匹配 | 已有 | **保留** | + +前端对应关闭:`enforceCarrierVehicleRequired`、三方人员页的必备槽位注入与校验。 + +--- + +## 三、粘贴识别(快速录入) + +### 3.1 入口 + +| 页面 | 工具栏按钮 | 模式 | +|------|------------|------| +| 三方车辆 | 粘贴识别 | `vehicle-bundle`(整车套装) | +| 三方驾押人员 | 粘贴识别 | `personnel-first`(以人为主) | + +共享同一「识别预览」弹窗组件,仅默认模式与勾选项不同。 + +### 3.2 解析映射 + +| 原文 | 落库 | +|------|------| +| 首行前牌 | 主车 `licensePlate` | +| 首行后牌 | 挂车 `trailerNo` | +| 核载 | `loadCapacity` | +| 驾驶员块(姓名/手机/身份证) | 人员 `personnelType=driver`,`personnelAffiliation=carrier`;车关联 `role=driver`(默认司机) | +| 押运员块 | 人员 `personnelType=escort`,`personnelAffiliation=carrier`;车关联 `role=escort` | + +解析策略: + +- 前端规则解析(车牌行、键值行);预览可手工改。 +- 确认后调用现有 create/update API,或一个**薄封装批量接口**(推荐批量 + 单事务,见 §五)。 + +### 3.3 预览与确认 + +1. 展示解析结果(车 / 驾 / 押),可编辑。 +2. **承运商必选**;未选不可确认生成车辆。 +3. `vehicle-bundle`:始终创建/更新车辆,并创建/关联驾、押。 +4. `personnel-first`:默认创建/更新人员;若识别到车牌,**默认勾选**「一并创建三方车辆并关联」,可取消;勾选时同样必选承运商。 + +### 3.4 冲突处理 + +当车牌或身份证已存在时,对每个冲突主体提示,用户选择: + +| 选项 | 行为 | +|------|------| +| 复用 | 使用已有 ID;可补车辆-人员关联 | +| 覆盖更新 | 用本次识别/预览字段更新已有记录 | +| 取消 | 中止本次确认(整单取消) | + +未处理完冲突前禁止确认。 + +--- + +## 四、承运商准入取消 + +### 4.1 承运商管理页 `/#/pl/base-info/carrier` + +- 去掉审核状态:筛选、列表列、查看弹窗字段、「审核通过」等操作入口。 +- 后端:停用审核通过/驳回业务门禁;新建不再依赖 `pending→approved` 准入语义。 +- `audit_status` 等列**可保留在库表**兼容历史数据,业务不再使用。 +- 资质附件、运输协议等**档案字段可保留**展示与维护,不作准入条件。 + +### 4.2 其他界面选择承运商 + +- 下拉/选择**不再**过滤或拦截: + - `auditStatus` + - `qualificationComplete` + - `transportAgreementExpired` +- 明确覆盖:三方车辆表单、粘贴识别预览、安排运输/调整运输(如 `pl-plan-arrange-dialog`)等所有选承运商处。 +- 列表返回的承运商均可选;本期不新增「已终止」等额外拦截(若某处历史上仅拉 `status=1`,保持该列表查询习惯即可,不把审核/资质/协议当作门禁)。 + +### 4.3 非目标 + +- 不删除库表审核列(避免大迁移)。 +- 不改承运商资质上传能力本身。 + +--- + +## 五、架构与数据流 + +### 5.1 前端 + +``` +pl/vehicle (三方) ──┐ + ├── PlPasteRecognizeDialog (shared) +pl/personnel-carrier ┘ │ + ▼ + parse → preview → conflict resolve + │ + ▼ + carrierApi / vehicleApi / personnelApi + (或 POST /pl/paste-recognize/commit) +``` + +- 三方/山峡人员页尽量复用同一套表单逻辑(props:`affiliationMode: 'self' | 'carrier'`)。 +- 证书组件:三方 `enforce*Required=false`;山峡保持现网。 + +### 5.2 后端 + +- 列表 API:支持/沿用 `vehicleType`、`personnelAffiliation` 过滤。 +- `validate_vehicle_save_certs` / `validate_personnel_required_certs`:按 D3/D5 分支。 +- 安排运输等:删除对承运商审核/资质/协议过期的硬拦截。 +- 粘贴提交(推荐):新增批量提交接口,事务内处理车+人+关联+冲突策略,失败整单回滚。 + +### 5.3 数据模型 + +- **不新增**车辆/人员主表字段(沿用 `vehicle_type`、`personnel_affiliation`、`pl_cert`、`pl_vehicle_personnel`)。 +- 承运商审核列保留但不驱动业务。 + +--- + +## 六、错误处理 + +| 场景 | 行为 | +|------|------| +| `vehicle-bundle` 无法解析出车牌 | 预览标红,禁止确认 | +| 无法解析出姓名(对应人员主体) | 预览标红,禁止确认该主体 | +| 未选承运商却要建车 | 禁止确认并提示 | +| 冲突未处理完 | 禁止确认 | +| 批量提交失败 | 明确错误提示;推荐整单回滚 | +| 三方保存缺证 | **不**报证书错误 | +| 山峡保存缺证 | 维持现网阻断文案 | + +--- + +## 七、验收标准 + +1. 基础信息库可见四个菜单:三方车辆、三方驾押人员、山峡自有车辆、山峡驾押人员;数据按归属隔离。 +2. 三方车辆/人员:无证书可保存;身份必填项缺失不可保存。 +3. 山峡车辆/人员:缺必备证书不可保存(与现网一致)。 +4. 三方车辆「粘贴识别」可从示例文本生成车+驾+押+关联;承运商未选不可确认。 +5. 三方人员「粘贴识别」默认建人;识别到车牌时默认勾选建车,可取消;冲突可选复用/覆盖/取消。 +6. 承运商页无审核筛选/列/通过按钮;查看弹窗无审核状态作为业务字段展示(或不再作为准入信息)。 +7. 安排运输等选择承运商:不因未审核、资质不全、协议过期而拦截。 +8. 三方车不可关联山峡人(及反向),归属匹配仍生效。 + +--- + +## 八、风险与缓解 + +| 风险 | 缓解 | +|------|------| +| 现网已对 carrier 强制证书,历史三方车可能「看起来缺证」 | 放开校验后即可编辑保存;列表可保留「证书缺失」提示但不阻断 | +| 粘贴格式多样导致解析失败 | 预览可改 + 明确支持的键名;失败不自动落库 | +| 覆盖更新误伤已有档案 | 冲突必须显式选择;覆盖前展示将写入字段摘要 | +| 去掉承运商准入后合规风险 | 产品已确认;档案字段仍可维护备查 | +| 四页模板重复 | 人员页用 affiliationMode 变体;粘贴弹窗共享 | + +--- + +## 九、工作量估算 + +| 模块 | 预估 | +|------|------| +| 菜单/路由/权限文案与三方人员页 | 0.5 天 | +| 前后端三方证书校验放宽 | 0.5 天 | +| 粘贴解析 + 预览弹窗 + 冲突处理 | 1~1.5 天 | +| 粘贴批量提交 API(若做) | 0.5 天 | +| 承运商去审核 UI + 选择门禁拆除 | 0.5 天 | +| 联调与回归(分册/证书/安排运输) | 0.5~1 天 | +| **合计** | **约 3.5~4.5 人天** | + +--- + +## 十、实施任务清单(概要) + +1. 菜单与路由:改名「三方车辆」「山峡驾押人员」;新增「三方驾押人员」;权限码对齐 +2. 车辆三方页:固定 `carrier`;关闭承运商证书强制 +3. 人员山峡/三方页:固定归属;仅山峡跑必备证书校验 +4. 后端:`pl_cert_required_service` / personnel & vehicle API 按归属分支 +5. 共享 `PlPasteRecognizeDialog` + 解析工具;两页入口 +6. (推荐)批量提交 API + 冲突策略 +7. 承运商:去审核 UI/API 门禁;安排运输等去掉审核/资质/协议拦截 +8. 验收 §七 + 相关回归 + +--- + +## 附录 A · 与既有设计关系 + +- `2026-07-12` 原文写「承运商车辆不强制」;现网实现已部分强制 carrier 证书——**本设计显式纠正为三方完全不强制**,并与分册菜单对齐。 +- 山峡必备证书清单仍以 `2026-07-12` / `2026-07-13` 为准,本设计不改清单内容。 +- 承运商附件能力见 `2026-06-29-pl-carrier-attachments-design.md`;本设计仅取消其作为选择准入条件。 + +## 附录 B · 解析示例期望结果 + +输入见文首示例,期望预览: + +| 字段 | 值 | +|------|-----| +| licensePlate | 皖LB1405 | +| trailerNo | 皖LP359 | +| loadCapacity | 34 | +| driver.name | 徐孝军 | +| driver.phone | 18956652137 | +| driver.idCardNo | 342921198602020031 | +| escort.name | 汪海明 | +| escort.phone | 13955522828 | +| escort.idCardNo | 342829197009084019 | +| carrierId | (用户必选) |