Files
shanxia2.0/docs/superpowers/specs/2026-06-29-pl-carrier-attachments-design.md
T
2026-06-29 11:15:39 +08:00

229 lines
9.4 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-06-29
> **状态**: 已批准
> **前置**: `openspec/changes/transport-plan-management/specs/vehicle-driver/spec.md`、`docs/superpowers/specs/2026-06-19-pl-vehicle-personnel-cert-design.md`
> **页面**: `web-admin` `/#/pl/carrier`(承运商管理)
## 目标
在承运商档案中增加三类**必填**资质/协议附件,并基于**运输协议有效期**控制承运商车辆是否可用于运输安排:
1. **营业执照**(附件,必填)
2. **道路经营许可证**(附件,必填)
3. **运输协议**(附件,必填 + **协议有效期**必填)
协议过期时:承运商展示「协议已过期」;该承运商名下车辆**不可被选择**用于安排/调整运输。
## 已确认业务规则
| 规则 | 决策 |
|------|------|
| 协议过期展示 | 承运商详情/列表展示 `el-tag`「协议已过期」 |
| 协议过期选车 | 该承运商名下车辆不出现在安排/计划选车列表;后端 arrange 接口硬校验 |
| 合作状态 | **不自动**改为「已终止」 |
| 历史数据(无附件的旧承运商) | **B**:旧数据可保留不完整;**补全且协议有效前**不可安排运输 |
| 调整运输(协议已过期) | **B**:承运商协议过期时**禁止任何调整运输**(须先更新协议) |
| 附件数量 | 每类最多 5 个(对齐 CRM 客户证件) |
| 文件类型 | JPG / PNG / PDF,单文件 ≤ 20MB |
> 说明:用户对「历史数据」与「调整运输」均回复 **B**;若仅指其中一项,评审时更正即可。
## 非目标(本期不做)
- 营业执照、道路经营许可证的到期日与到期提醒
- 协议过期自动写入 `pl_document_reminder` / 提醒中心
- 协议过期自动变更承运商合作状态
- 复用 `pl_cert` 动态证书子表(固定三字段更简单,见方案选型)
---
## 方案选型
**采用方案 A:承运商表固定字段**(非 `pl_cert` 扩展)
| 字段 | DB 列名 | 类型 | 新建必填 | 说明 |
|------|---------|------|----------|------|
| 营业执照 | `business_license_urls` | varchar(2000) | ✅ | MinIO URL,逗号分隔 |
| 道路经营许可证 | `road_transport_license_urls` | varchar(2000) | ✅ | 同上 |
| 运输协议 | `transport_agreement_urls` | varchar(2000) | ✅ | 同上 |
| 协议有效期 | `transport_agreement_expire_date` | date | ✅ | 仅运输协议 |
**计算字段(API 返回,不落库)**
| 字段 | 逻辑 |
|------|------|
| `qualificationComplete` | 三类 URL 均非空且 `transport_agreement_expire_date` 非空 |
| `transportAgreementExpired` | `qualificationComplete` 且 `expire_date < today` |
---
## 数据模型变更
### `pl_carrier` 新增列(位于 `status` 与 `tenant_no` 之间)
```sql
ALTER TABLE `pl_carrier`
ADD COLUMN `business_license_urls` varchar(2000) DEFAULT NULL COMMENT '营业执照附件URL,逗号分隔' AFTER `status`,
ADD COLUMN `road_transport_license_urls` varchar(2000) DEFAULT NULL COMMENT '道路经营许可证附件URL,逗号分隔' AFTER `business_license_urls`,
ADD COLUMN `transport_agreement_urls` varchar(2000) DEFAULT NULL COMMENT '运输协议附件URL,逗号分隔' AFTER `road_transport_license_urls`,
ADD COLUMN `transport_agreement_expire_date` date DEFAULT NULL COMMENT '运输协议有效期' AFTER `transport_agreement_urls`;
```
同步更新:`docs/sql/pl_tables.sql`、`docs/sql/shanxia2.0.sql`。
---
## 后端设计
### Schema(`backend/app/schemas/pl/base_data.py`)
- `CarrierCreate`:四字段均必填(validator)
- `CarrierUpdate`:四字段 optional;若传入则按新建同等校验(非空、日期合法)
- `CarrierRead`:含四字段 + `qualificationComplete` + `transportAgreementExpired`(computed)
### 校验规则
**新建承运商**
- 三类 `*_urls` 去空白后非空
- `transport_agreement_expire_date` 必填、合法 date
**更新承运商(历史数据 B)**
- 允许仅更新名称/联系人等,**不强制**一次性补全附件
- 一旦传入任一附件/有效期字段,则按完整规则校验
**运输资格(安排/选车用)**
承运商同时满足方可参与运输:
```
qualificationComplete == true
AND transportAgreementExpired == false
AND status == '1'(合作中)
```
### API 变更
| 接口 | 变更 |
|------|------|
| `GET/POST/PUT /transport/carrier` | 读写新字段;Read 带计算字段 |
| `GET /transport/vehicle` | 新增 query:`excludeIneligibleCarrier`(默认 false)<br>为 true 时排除:`vehicle_type=carrier` 且所属承运商不满足运输资格 |
| `POST /transport/order/arrange/{plan_id}` | 选车后校验承运商运输资格;不通过 → 400 |
**arrange 错误文案(建议)**
- 资质不全:`该承运商资质附件不完整,无法安排运输`
- 协议过期:`该承运商运输协议已过期,无法安排运输`
- 调整运输且当前计划车辆所属承运商协议过期:`该承运商运输协议已过期,请先更新协议后再调整运输`(HTTP 400,禁止提交)
### 辅助函数
建议 `app/services/pl_carrier_service.py`:
- `carrier_qualification_complete(carrier) -> bool`
- `carrier_agreement_expired(carrier, today: date) -> bool`
- `carrier_eligible_for_transport(carrier, today: date) -> bool`
- `assert_carrier_eligible_for_transport(db, carrier_id, tenant_no)` — arrange 与 vehicle 过滤共用
---
## 前端设计
### 1. 承运商列表 / 编辑(`views/pl/carrier/index.vue`)
- 弹窗宽度:`520px` → **`720px`**
- 新增分区 **「资质附件」**(参考 CRM `CustomerFormDialog` 证件区)
- 组件:`AttachmentUploadField` × 3
- `accept="image/*,.pdf"`
- `folder="pl/carrier/license"` / `permit` / `agreement`
- `limit=5`
- 运输协议下方:`el-date-picker type="date"`,`value-format="YYYY-MM-DD"`
- **新建**:四字段 `formRules` 必填;提交前 `hasUploading()` 检查
- **编辑**:同字段展示;历史不完整时可保存基础信息,但卡片/查看态标注「资质不全」
**卡片列表增强(建议)**
- `qualificationComplete === false` → `el-tag type="warning"`「资质不全」
- `transportAgreementExpired === true` → `el-tag type="danger"`「协议已过期」
### 2. 查看弹窗(`pl-carrier-view-dialog`)
- 资质附件:可预览/下载(复用 `AttachmentUploadField` disabled 或查看态附件列表)
- 协议有效期 + 过期 Tag
### 3. 安排运输(`pl-plan-arrange-dialog`)
- `vehicleApi.list({ vehicleStatus: 'available', excludeIneligibleCarrier: true })`
- **调整运输 B**:打开弹窗时若当前计划已安排车辆,且其承运商 `transportAgreementExpired` 或 `!qualificationComplete`:
- 表单项只读或禁用提交
- 顶部 `el-alert type="warning"`:请先更新承运商资质/协议
- 提交 arrange 前无需额外前端拦截(后端兜底),但可 preempt 提示
### 4. 计划表单预选车辆(`pl-plan-form-dialog`)
- 与安排运输相同:`excludeIneligibleCarrier: true`
### 5. API 类型(`api/pl/index.ts`)
扩展 `Carrier` 接口与 `VehicleQuery`。
---
## OpenSpec 更新
更新 `openspec/changes/transport-plan-management/specs/vehicle-driver/spec.md` 中 **承运商管理**:
#### Scenario: 承运商资质附件维护
- **WHEN** 管理员新增承运商
- **THEN** 系统 SHALL 要求上传营业执照、道路经营许可证、运输协议,并填写运输协议有效期
- **AND** 附件 SHALL 使用 `AttachmentUploadField` 卡片化布局,URL 逗号分隔存库
#### Scenario: 协议过期阻断运输
- **WHEN** 承运商运输协议有效期早于当前日期
- **THEN** 系统 SHALL 展示「协议已过期」
- **AND** 该承运商名下车辆 SHALL NOT 出现在安排运输与计划预选车辆列表
- **AND** 安排/调整运输接口 SHALL 拒绝使用该承运商车辆
- **AND** 协议过期时 SHALL 禁止调整运输,直至更新协议
#### Scenario: 历史承运商兼容
- **WHEN** 存在未补全资质附件的历史承运商
- **THEN** 系统 SHALL 允许保留基础档案
- **AND** 在其资质补全且协议有效前 SHALL NOT 允许安排运输
---
## 影响范围
| 层级 | 文件 |
|------|------|
| SQL | `docs/sql/pl_tables.sql`, `docs/sql/shanxia2.0.sql`, 迁移脚本 |
| Model | `backend/app/models/pl_models.py` |
| Schema | `backend/app/schemas/pl/base_data.py` |
| Service | `backend/app/services/pl_carrier_service.py`(新建) |
| API | `backend/app/api/pl/base_data.py`, `backend/app/api/pl/transport.py` |
| 前端 | `views/pl/carrier/index.vue`, `pl-carrier-view-dialog`, `pl-plan-arrange-dialog`, `pl-plan-form-dialog`, `api/pl/index.ts` |
| OpenSpec | `vehicle-driver/spec.md` |
---
## 验收标准
1. 新建承运商:缺任一附件或协议有效期 → 前端/后端均拦截
2. 历史承运商无附件:可编辑保存基础字段;其车辆不在安排运输选车列表
3. 补全资质且协议未过期:车辆恢复可选
4. 协议过期:承运商展示「协议已过期」;车辆不可选;arrange 返回 400
5. 已安排计划 + 承运商后过期:打开「调整运输」不可提交,提示先更新协议
6. 自有车辆(`vehicle_type=self`)不受承运商规则影响
7. 查看弹窗可预览/下载三类附件
---
## 工作量估算
约 **2 人日**(含 DDL、CRUD、表单/查看、选车过滤、arrange 校验、联调)。