shanxia2.0/docs/superpowers/specs/2026-07-13-pl-personnel-cert-split-design.md

运输管理 · 人员从业资格证拆分 — 设计文档

日期: 2026-07-13
状态: 已批准
前置: docs/superpowers/specs/2026-07-12-pl-required-cert-slots-design.md（D5/D6 需废止并替换）
界面: /#/pl/base-info/personnel（驾押人员信息）

背景

2026-07-12 实现将「从业资格证」视为驾押共用的一种证，并通过 matchRequiredCertName 模糊匹配（含「危化品从业资格证」、名称含「从业资格证」）。业务上这是错误建模：

• 驾驶员从业资格证 与 押运员从业资格证 是两张不同的证
• 驾驶员兼押运员 须同时持有上述两种从业资格证（共 4 项必备，非 3 项）

已确认决策

#	决策	说明
D1	拆分必备证种	不再使用泛称「从业资格证」作为必备槽名称
D2	兼岗 4 证	both = 身份证 + 驾驶证 + 驾驶员从业资格证 + 押运员从业资格证
D3	徽章 shortLabel	驾驶员从业资格证 → 业；押运员从业资格证 → 押
D4	押运员证别名	历史/录入名称「押运员证」等价于「押运员从业资格证」（匹配与迁移均认可）
D5	严格匹配从业证	取消「名称含从业资格证」的宽泛规则；两类从业证分别精确匹配（押运员侧含 D4 别名）
D6	保存一律阻断	沿用 2026-07-12 D7：缺必备证时任何保存均 400 / 前端 warning
D7	前后端双校验	规则以 util + service 两处硬编码保持一致
D8	历史数据迁移	上线前执行 SQL/脚本，见 §三

一、修订后必备证书矩阵

personnel_type	展示文案	必备证书	列表徽章顺序
driver	驾驶员	身份证、驾驶证、驾驶员从业资格证	身、驾、业
escort	押运员	身份证、押运员从业资格证	身、押
both	驾驶员兼押运员	身份证、驾驶证、驾驶员从业资格证、押运员从业资格证	身、驾、业、押

每项必备仍要求：证号 + 有效期 + 附件 均非空（与 2026-07-12 §1.4 一致）。

1.1 证书名称匹配规则

必备槽目标名称	可接受的 cert_name
身份证	精确：身份证
驾驶证	精确：驾驶证
驾驶员从业资格证	精确：驾驶员从业资格证
押运员从业资格证	精确：押运员从业资格证；别名：押运员证（D4）

不再接受作为任一从业必备槽的匹配：

• 泛称 从业资格证
• 危化品从业资格证（除非业务后续单独确认可映射到驾驶员侧，本期不自动映射）
• name.includes('从业资格证') 类模糊规则

1.2 与 2026-07-12 的差异

项	2026-07-12	本变更
driver 必备	身份证、驾驶证、从业资格证	身份证、驾驶证、驾驶员从业资格证
escort 必备	身份证、从业资格证	身份证、押运员从业资格证
both 必备	同 driver（3 项）	4 项（驾+押从业证均有）
从业证匹配	模糊共用	分类型精确匹配 + 押运员证别名

二、实现范围

2.1 前端

文件: web-admin/src/utils/pl-personnel-cert.ts

• 常数：
  • PL_PERSONNEL_DRIVER_REQUIRED_CERT_NAMES → ('身份证', '驾驶证', '驾驶员从业资格证')
  • PL_PERSONNEL_ESCORT_REQUIRED_CERT_NAMES → ('身份证', '押运员从业资格证')
• getRequiredPersonnelCertNamesByType：
  • escort → escort 列表
  • driver → driver 列表
  • both → 合并去重 driver ∪ escort（顺序：身份证、驾驶证、驾驶员从业资格证、押运员从业资格证）
• matchRequiredCertName：
  • 删除对泛称「从业资格证」的模糊分支
  • 新增：押运员从业资格证 可匹配 押运员证
  • 驾驶员从业资格证 仅精确匹配
• PL_PERSONNEL_CERT_SHORT_LABELS：
  • 驾驶员从业资格证: '业'
  • 押运员从业资格证: '押'
  • 移除泛称 从业资格证: '业'

文件: web-admin/src/views/pl/personnel/index.vue

• certNameOptions：必备相关选项改为 驾驶员从业资格证、押运员从业资格证；保留 押运员证 于「其他证书」可选（或标注为别名，非必备槽名）
• 移除泛称 从业资格证 作为必备槽预置名（可选是否保留于自由添加下拉）

连带组件（逻辑随 util 自动生效，需回归）：

• pl-personnel-cert-badges
• pl-cert-form-list / pl-cert-slots
• pl-vehicle-personnel-view-list / PersonnelViewPanel（车辆关联查看态缺失 suffix）
• pl/self-vehicle、pl/vehicle（关联人员证书校验提示）

2.2 后端

文件: backend/app/services/pl_cert_required_service.py

• PERSONNEL_DRIVER_REQUIRED、PERSONNEL_ESCORT_REQUIRED 与前端对齐
• get_required_personnel_cert_names：both 返回 4 项合并列表
• match_required_cert_name：与前端 D4/D5 一致
• validate_vehicle_personnel_cert_links：按 role 使用 driver/escort 必备列表（escort 侧含押运员从业资格证 + 押运员证别名）

2.3 字典（可选同步）

sys_dict_data / pl_cert_name：

• 新增：驾驶员从业资格证、押运员从业资格证
• 押运员证 保留（作为别名来源，非必备槽展示名）
• 泛称 从业资格证、危化品从业资格证：可保留于字典供历史/other 证书，不参与必备匹配

三、历史数据迁移

3.1 证书名称重命名

原 cert_name	迁移后 cert_name	条件
押运员证	押运员从业资格证	全部 personnel owner
从业资格证	驾驶员从业资格证	该人员 personnel_type IN ('driver', 'both')
从业资格证	押运员从业资格证	该人员 personnel_type = 'escort'
从业资格证	不自动迁移	personnel_type = 'both' 且仅有一条 → 导出人工清单；或按业务规则复制为两条（若证号相同则拆两条记录，需运营确认，默认不自动复制）

both + 单条泛称「从业资格证」：迁移脚本应 输出待人工处理清单（personnel_id、姓名、原 cert_name），不静默映射，避免一张证冒充两种从业证。

危化品从业资格证：本期 不自动映射；进入缺证清单，由运营按实际类型补录或重命名。

3.2 迁移脚本

• 路径建议：backend/scripts/migration_20260713_pl_personnel_cert_split.sql
• 要求：可重复执行（UPDATE 仅作用于未迁移行）；执行后附 SELECT 验证 both 人员是否仍缺押运/驾从业证

3.3 上线顺序

1. 执行迁移脚本 + 人工处理 both ambiguous 清单
2. 部署前后端新规则
3. 运营抽查列表徽章（身驾业押）与保存阻断

四、业务规则（保持不变部分）

• 人员主数据：按 personnel_type 校验必备（both 为 4 项）
• 山峡自有车关联人员：按关联行 role 校验 driver/escort 必备子集
• both 类型人员主数据仍须驾驶证，即使仅关联为 escort（沿用 2026-07-12 §3.2 说明）
• 承运商车辆不强制车辆证；人员主数据始终强制

五、验收标准

1. 新增驾驶员：预置 3 必备槽（身份证、驾驶证、驾驶员从业资格证）；缺任一项无法保存。
2. 新增押运员：预置 2 必备槽（身份证、押运员从业资格证）；列表徽章 身、押。
3. 新增兼岗：预置 4 必备槽；列表徽章 身、驾、业、押；缺押运员从业资格证无法保存。
4. 录入证书名称为「押运员证」时，满足押运员从业资格证必备槽（D4）。
5. 泛称「从业资格证」不能满足任一从业必备槽（迁移后）。
6. 车辆关联 escort role：校验身份证 + 押运员从业资格证（含押运员证别名）。
7. 前后端错误文案一致，含缺失字段（证号/有效期/附件）。
8. 迁移脚本执行后，押运员证 行已更名为 押运员从业资格证。

六、工作量估算

模块	预估
前后端 util/service 规则对齐	0.5 天
人员页下拉/槽位 + 徽章回归	0.25 天
迁移脚本 + both 人工清单	0.25 天
车辆页关联校验回归 + 自测	0.25 天
合计	约 1~1.25 人天

七、风险

风险	缓解
both 人员仅有一条泛称从业证	迁移输出人工清单，不上线前不部署新规则
兼岗人员大量缺「押运员从业资格证」	迁移押运员证 + 运营补录
危化品从业资格证无法自动归类	本期不映射，运营手动改为驾驶员/押运员从业资格证

八、OpenSpec

建议在 transport-plan-management 或新 change 中增补 Scenario，废止 2026-07-12 的 D5/D6 表述，引用本设计 §1 矩阵。