178 lines
8.9 KiB
Markdown
178 lines
8.9 KiB
Markdown
# 运输管理 · 人员从业资格证拆分 — 设计文档
|
||
|
||
> **日期**: 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 矩阵。
|