Files
shanxia2.0/docs/superpowers/specs/2026-07-13-pl-personnel-cert-split-design.md
T
2026-07-14 19:53:35 +08:00

178 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 运输管理 · 人员从业资格证拆分 — 设计文档
> **日期**: 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 矩阵。