Files
shanxia2.0/docs/superpowers/specs/2026-07-04-pl-hazard-cert-ready-design.md
T
2026-07-05 10:07:24 +08:00

254 lines
11 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-04
> **状态**: 已实现(2026-07-04)
> **前置**: 现有 `pl_plan_product.purchase_cert_url` / `transport_cert_url` 双证校验逻辑;`/#/pl/plan-cert` 危化品证上传页
> **界面模式**: P06 复杂业务列表 + 弹窗表单(延续危化品证上传页)
## 背景与问题
### 现状
| 环节 | 行为 |
|------|------|
| 危化品识别 | 以 CRM 产品主数据 `isToxic` / `isExplosive` 为准 |
| 证书存储 | 计划产品行 `pl_plan_product.purchase_cert_url`(购买证)、`transport_cert_url`(合法使用证明) |
| 上传页校验 | 上传弹窗保存时 **强制** 每个危化品产品两个 URL 均非空 |
| 安排运输校验 | 前端 `buildMissingHazardCertMessage` + 后端 `transport.py` / `_validate_toxic_products` 均要求 **双证齐全** |
### 客户反馈
实际业务中,是否需要购买证、合法使用证明,以及是否两个都要,**取决于多种现场条件**(产品类型、单据类型、客户资质、运输方式等),规则复杂且频繁变化,**难以在系统中穷举**。
当前「双证强制」导致:
- 只需上传一种证的业务场景无法保存、无法标记完成;
- 操作员被迫上传占位文件或反复与开发沟通改规则;
- 系统规则与客户实际合规判断脱节。
### 目标
1. **危化品证上传页**增加「证书齐备」人工确认能力;
2. **运输计划安排运输**改为校验「证书齐备状态」,**不再**校验两个 URL 是否同时存在;
3. 证书文件仍可在上传页按需上传(0~2 个均可),供存档与查看。
---
## 方案对比
### 方案 A:计划级「证书齐备」标志(推荐)
在 `pl_plan` 增加 `hazard_cert_ready`(0/1)及可选审计字段(`hazard_cert_ready_by`、`hazard_cert_ready_time`)。
| 优点 | 缺点 |
|------|------|
| 与「安排运输按整单校验」一致,改动面小 | 一单多危化品时无法逐行独立确认 |
| 列表可加一列 Tag,一眼可见 | 计划产品变更后需定义是否自动撤销齐备 |
| 后端一处字段即可 gate 安排运输 | 依赖人工责任心,需审计字段 |
### 方案 B:产品级「证书齐备」标志
在 `pl_plan_product` 每行增加 `cert_ready`。
| 优点 | 缺点 |
|------|------|
| 多产品粒度更细 | 安排运输需「所有危化品行齐备」聚合逻辑 |
| 与现有证书 URL 同表,语义近 | UI 更复杂(每行按钮或弹窗内逐行确认) |
### 方案 C:配置化规则引擎(按产品/单据类型判定要几个证)
| 优点 | 缺点 |
|------|------|
| 理论上可自动化 | 客户已明确规则复杂、难维护,与诉求相反 |
| | 开发成本高、持续运维 |
**推荐:方案 A(计划级标志)**,配合审计字段与产品变更自动撤销。若后续确需逐产品确认,可演进为方案 B,API 可预留。
---
## 已确认设计(其余待拍板项见 §七)
| # | 决策 | 说明 |
|---|------|------|
| D1 | **齐备粒度:计划级** | `pl_plan.hazard_cert_ready`,仅对「含至少一个危化品产品」的计划有意义 |
| D2 | **无危化品计划免校验** | 计划不含易制毒/易制爆产品时,安排运输不检查齐备标志 |
| D3 | **上传不再强制双证** | 上传弹窗保存时允许购买证/合法使用证明 **0~2 个任意组合**;至少保留「有危化品产品行」才允许保存附件 |
| D4 | **安排运输只查齐备标志** | 替换现有 `purchase_cert_url && transport_cert_url` 校验(前后端一致) |
| D5 | **齐备为人工显式操作** | 【危化品证上传】列表工具栏 + 查看弹窗 hero 提供「证书齐备」;需二次确认 |
| D6 | **可撤销齐备** | 提供「取消齐备」;已归档/已作废计划不可操作 |
| D7 | **产品变更自动撤销** | 计划编辑导致危化品产品集合变化(增删改 productId 或危化品行)时,自动 `hazard_cert_ready=0` |
| D8 | **上传证书不自动齐备** | 保存附件 ≠ 证书齐备;须单独点击「证书齐备」 |
| D9 | **运输计划页无上传入口** | 维持已移除「上传证书」;仅提示「请至危化品证上传页确认证书齐备」 |
| D10 | **零附件可确认齐备** ✅ 2026-07-04 | 不要求任何附件即可点击「证书齐备」;人工确认即视为通过(证在客户处、纯备案等场景) |
| D11 | **齐备后可继续补传附件** ✅ 2026-07-04 | `hazard_cert_ready=1` **不阻断** 后续在危化品证上传页打开上传弹窗、补充/更新购买证或合法使用证明;齐备状态保持,除非 D7 触发撤销 |
---
## 一、数据模型
### 1.1 `pl_plan` 新增字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `hazard_cert_ready` | tinyint, default 0 | 危化品证书是否已人工确认齐备:0-否 1-是 |
| `hazard_cert_ready_by` | varchar(64), nullable | 确认人 user id |
| `hazard_cert_ready_time` | datetime, nullable | 确认时间 |
DDL 写入 `docs/sql/shanxia2.0.sql`(及迁移片段如项目惯例)。
### 1.2 既有字段保留
- `pl_plan_product.purchase_cert_url` / `transport_cert_url` **保留**,继续用于存档与列表「有/无」展示;
- **不再**作为安排运输的硬性条件。
---
## 二、后端 API
### 2.1 标记 / 取消齐备
```
PATCH /api/transport/plan/{id}/hazard-cert-ready
Body: { "ready": true | false }
```
规则:
- 计划存在且未归档、未作废;
- `ready=true`:计划须含至少一个危化品产品(CRM 标识),否则 400;**不校验** 是否已上传任何附件(D10);
- `ready=false`:清空 `hazard_cert_ready_by/time`;
- 写 `update_by`;可选写操作日志。
权限:`pl:plan-cert:edit` 或与上传证书同权限 `pl:plan-cert:list` + 编辑(与菜单权限对齐,实现时查现有 plan-cert 权限码)。
### 2.2 安排运输校验(替换)
`_validate_toxic_products` 与 `transport.py` 内联校验改为:
```python
# 伪代码
if plan_has_hazard_products(plan):
if not plan.hazard_cert_ready:
raise HTTPException(400, "该计划危化品证书尚未确认齐备,请至危化品证上传页操作")
```
删除对 `purchase_cert_url` / `transport_cert_url` 的非空检查。
### 2.3 计划更新时撤销齐备
在 `update_plan`(或产品明细 diff 逻辑)中:若危化品产品集合或危化品行 id 集合变化 → `hazard_cert_ready=0`,清空 by/time。
### 2.4 列表 / 详情返回
`_row_to_dict` / Plan schema 增加:
- `hazardCertReady` (bool/int)
- `hazardCertReadyBy` / `hazardCertReadyTime`(详情与危化品证上传列表展示)
---
## 三、前端
### 3.1 危化品证上传页 `plan-cert/index.vue`
**列表**
- 新增列「证书齐备」:`el-tag`,success=已齐备 / warning=待确认 / info=无需(无危化品);
- 工具栏(选中单行且含危化品、未归档、未作废):
- 未齐备 → 主按钮「证书齐备」(`CircleCheck` 图标),确认框后调 API;
- 已齐备 → 描边「取消齐备」(`CircleClose`),确认框后调 API。
**上传弹窗** `PlPlanCertUploadDialog`
- 去掉保存时对双证非空的 `ElMessage.warning` 拦截;
- **已齐备计划仍可打开上传弹窗**并保存附件(D11);不因 `hazardCertReady=1` 禁用「上传证书」;
- 提示文案改为:「请按实际业务上传所需证书;可先点击『证书齐备』放行运输,之后再补充附件。」
**查看弹窗 hero-actions**
- 与工具栏同样的齐备 / 取消齐备按钮。
### 3.2 运输计划 `plan/index.vue` + `PlPlanArrangeDialog`
- 提交前:若计划含危化品且 `!hazardCertReady`,`ElMessageBox.alert`:
「该计划危化品证书尚未确认齐备,请至【危化品证上传】页面操作。」
- 移除 `buildMissingHazardCertMessage` 对 URL 的检查(可保留 composable 供列表展示「有/无」,或重命名用途)。
### 3.3 列表证书展示
- `PlPlanListCertCell` / `PlPlanListProductCell` 继续展示各证「有/无」,**不作为**运输门槛;
- 可选:计划级齐备 Tag 与产品级有/无并存,便于操作员自查。
---
## 四、状态流转
```
[计划含危化品]
│
├──(可选) 零附件──► 点击「证书齐备」+ 确认 ──► hazard_cert_ready=1 ──► 可安排运输
│
└──(可选) 先传部分附件 ──► 同上
│
└── 已齐备后仍可「上传证书」补传/更新附件(齐备状态不变,D11)
│
编辑计划(危化品行变化) ──► 自动撤销齐备 (hazard_cert_ready=0)
点击「取消齐备」 ──► hazard_cert_ready=0
```
无危化品计划:`hazard_cert_ready` 保持 0,安排运输跳过校验。
---
## 五、影响范围(实现清单)
| 层 | 文件/模块 |
|----|-----------|
| SQL | `docs/sql/shanxia2.0.sql` |
| Model | `backend/app/models/pl_models.py` |
| Schema | `backend/app/schemas/pl/plan.py` |
| Service | `pl_plan_service.py`:`_validate_toxic_products`、`update_plan` 撤销逻辑、新增 `set_hazard_cert_ready` |
| API | `plan.py`:PATCH hazard-cert-ready;`transport.py`:校验替换 |
| FE API | `web-admin/src/api/pl/index.ts` |
| FE 页 | `plan-cert/index.vue` |
| FE 组件 | `pl-plan-cert-upload-dialog`、`pl-plan-arrange-dialog` |
| FE 类型 | `Plan` interface、`usePlToxicProductCertCheck.ts`(调整或拆分) |
**非目标**:不改 CRM 产品危化品标识;不改司机/车辆危化品证(`hazmat_cert_no`)逻辑。
---
## 六、风险与缓解
| 风险 | 缓解 |
|------|------|
| 人工误点齐备导致无证运输 | 二次确认文案强调合规责任;记录确认人/时间;列表保留附件有/无 |
| 计划变更后仍显示已齐备 | D7 自动撤销 |
| 历史已双证齐全的计划 | 迁移:`含危化品且双证 historically 齐全` 可批量 `hazard_cert_ready=1`(可选脚本,非必须) |
| 后端被绕过 | 安排运输 API 服务端强制校验齐备标志 |
---
## 七、待产品确认(实现前需答复)
| # | 问题 | 状态 |
|---|------|------|
| 1 | **齐备粒度**:计划级还是产品级? | 默认 **计划级**(D1),若无异议按此实现 |
| 2 | **零附件是否允许齐备** | ✅ **已确认:允许**(D10);人工点确认即通过 |
| 3 | **齐备后是否可补传附件** | ✅ **已确认:可以**(D11);齐备不锁死上传入口 |
| 4 | **权限**:「证书齐备」是否与「上传证书」同一角色即可? | 待确认(默认:是,沿用 `pl:plan-cert:list` 菜单权限) |
| 5 | **历史数据**:是否对已有双证齐全的计划批量标记已齐备? | 待确认(默认:否,由操作员按需点确认) |
---
## 八、验收标准
- [ ] 危化品证上传页可对含危化品的计划执行「证书齐备 / 取消齐备」,列表 Tag 正确
- [ ] 上传弹窗可只传 0/1/2 个证并保存成功
- [ ] **零附件**也可点击「证书齐备」并成功;安排运输可通过
- [ ] **已齐备后**仍可打开上传弹窗补充/更新附件,齐备状态不被上传动作清除
- [ ] 未齐备时,运输计划「安排运输」前后端均拦截,提示去危化品证上传页
- [ ] 已齐备且无其他阻塞时可正常安排运输
- [ ] 编辑计划变更危化品产品后,齐备状态自动清除
- [ ] 无危化品计划安排运输不受本功能影响