提交
This commit is contained in:
1 parent
493f8d6756
commit
d84f4b944c
406 files changed
+58954
-10376
No files matched your search
@@ -0,0 +1,316 @@
|
||||
# 操作审计与业务语义日志 — 设计文档
|
||||
|
||||
> **日期**: 2026-06-29
|
||||
> **状态**: 已批准(待实现)
|
||||
> **OpenSpec**: `openspec/changes/operation-audit-enhancement/`
|
||||
> **前置**: 现有 `ApiRequestLogMiddleware`、`sys_api_request_log`、`operlog/list` API
|
||||
> **界面模式**: P01 标准列表(操作日志管理页)
|
||||
|
||||
## 目标
|
||||
|
||||
满足客户对「用户操作可追溯」的要求,在**不重建**审计体系的前提下:
|
||||
|
||||
1. **继续全量 API 采集** — 接口地址、入参、出参、时间、操作人
|
||||
2. **补齐请求人姓名与租户** — `create_name`(nick_name)、`tenant_no`
|
||||
3. **增加业务语义字段** — 模块、操作类型、业务主键、可读摘要
|
||||
4. **提供全局管理页** — 筛选、分页、详情
|
||||
5. **CRM 详情 Tab** — 按 `business_id` 精确查日志
|
||||
|
||||
## 已确认业务规则
|
||||
|
||||
| # | 规则 | 决策 |
|
||||
|---|------|------|
|
||||
| D1 | 总体方案 | **方案 A + 语义字段**;不新建 `sys_oper_log` 表 |
|
||||
| D2 | 采集范围 | 默认**全 API**(含 GET 列表);跳过 health/docs/OPTIONS |
|
||||
| D3 | 写操作语义 | `@oper_log` 装饰器声明;只读走路径推断 |
|
||||
| D4 | 请求人展示 | 列表/详情 **姓名优先**(`create_name`),账号为 `username` |
|
||||
| D5 | 入参出参 | 已在中间件记录;详情完整展示(受截断限制) |
|
||||
| D6 | 文件上传 | multipart **不记文件体** |
|
||||
| D7 | 权限 | operlog API 与菜单:**admin / super_admin** + 数据权限 |
|
||||
| D8 | 归档 | 本期只做表结构扩展;定时归档为后续项 |
|
||||
| D9 | business_type | 对齐 `sys_oper_type`:0/1/2/3/5/6 |
|
||||
| D10 | oper_summary 模板 | `{动词}{对象}【{名或编号}】` |
|
||||
|
||||
## 非目标(本期不做)
|
||||
|
||||
- 前端 UI 埋点(不发 API 的行为)
|
||||
- MQ/ES 独立审计平台
|
||||
- 与 CRM Java 仓 `sys_oper_log` 数据合并
|
||||
- 全模块写接口 `@oper_log` 一次性覆盖
|
||||
- multipart 文件内容入库
|
||||
- 响应体手机号/身份证扩展脱敏(待客户确认)
|
||||
|
||||
---
|
||||
|
||||
## 现状与差距
|
||||
|
||||
### 已实现
|
||||
|
||||
| 能力 | 实现位置 |
|
||||
|------|----------|
|
||||
| 中间件采集 | `backend/app/core/api_request_log_middleware.py` |
|
||||
| 落库表 | `sys_api_request_log`、`sys_api_request_log_his` |
|
||||
| 查询 API | `POST /api/web/monitor/operlog/list`、`/detail` |
|
||||
| CRM 嵌入 | `CustomerDetailDialog`、`contract/detail` Tab |
|
||||
| 默认开关 | `API_REQUEST_LOG_ENABLED=true` |
|
||||
|
||||
### 字段映射(客户需求 → 现状)
|
||||
|
||||
| 客户项 | 表字段 | OperLog 字段 | 现状 |
|
||||
|--------|--------|--------------|------|
|
||||
| 接口地址 | `path` | `operUrl` | ✅ |
|
||||
| 入参 | `query_string` + `request_body` | `operParam` | ✅(有例外) |
|
||||
| 出参 | `response_body` | `jsonResult` | ✅(有截断) |
|
||||
| 时间 | `create_at` | `operTime` | ✅ |
|
||||
| 账号 | `username` | `operName` 兜底 | ✅ |
|
||||
| 姓名 | `create_name` | `operName` 优先 | ⚠️ 未写入 |
|
||||
| 模块/类型/单据 | — | `title`、`businessType` | ⚠️ 仅读时推断 |
|
||||
| 可读摘要 | — | — | ❌ |
|
||||
| 租户 | — | — | ❌ |
|
||||
|
||||
### 采集限制(保持)
|
||||
|
||||
| 场景 | 处理 |
|
||||
|------|------|
|
||||
| body > 10MB | `[body omitted: N bytes]` |
|
||||
| 文本截断 | `API_REQUEST_LOG_MAX_BODY` 65536 字符 |
|
||||
| 原始读取 | `API_REQUEST_LOG_MAX_BODY_BYTES` 131072 |
|
||||
| 敏感键 | password/token 等 → `***` |
|
||||
| multipart | `[multipart/form-data body omitted]` |
|
||||
|
||||
---
|
||||
|
||||
## 数据模型扩展
|
||||
|
||||
### `sys_api_request_log` / `sys_api_request_log_his` 新增列
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `tenant_no` | varchar(64) | 租户编号,JWT 写入 |
|
||||
| `business_title` | varchar(100) | 模块标题,如 `CRM客户管理` |
|
||||
| `business_type` | tinyint | 0其他 1新增 2修改 3删除 5导出 6导入 |
|
||||
| `business_id` | varchar(64) NULL | 业务主键 |
|
||||
| `oper_summary` | varchar(500) NULL | 人读摘要 |
|
||||
|
||||
**建议索引**:
|
||||
|
||||
- `idx_arl_tenant_createat` (`tenant_no`, `create_at`)
|
||||
- `idx_arl_business` (`business_id`, `business_title`, `create_at`)
|
||||
|
||||
### business_type 枚举
|
||||
|
||||
| 值 | 含义 | 典型场景 |
|
||||
|----|------|----------|
|
||||
| 0 | 其他 | 登录、只读查询 |
|
||||
| 1 | 新增 | create/add |
|
||||
| 2 | 修改 | update/edit/审批/转移 |
|
||||
| 3 | 删除 | delete/remove |
|
||||
| 5 | 导出 | export |
|
||||
| 6 | 导入 | import |
|
||||
|
||||
### 存储样式示例
|
||||
|
||||
**修改客户(有 @oper_log)**
|
||||
|
||||
```
|
||||
tenant_no = shanxia2.0
|
||||
business_title = CRM客户管理
|
||||
business_type = 2
|
||||
business_id = SXCU0000000000000123
|
||||
oper_summary = 修改客户【杭州某某化工有限公司】
|
||||
path = /api/web/crm/customer/update
|
||||
http_method = POST
|
||||
request_body = {"id":"SXCU...","customerName":"杭州某某化工有限公司",...}
|
||||
response_body = {"code":200,"message":"success",...}
|
||||
user_id = d3000000000000000000000000000001
|
||||
username = liming
|
||||
create_name = 李明
|
||||
create_at = 2026-06-29 14:32:05
|
||||
ip_address = 192.168.1.10
|
||||
duration_ms = 45
|
||||
status_code = 200
|
||||
```
|
||||
|
||||
**客户列表(无装饰器,推断兜底)**
|
||||
|
||||
```
|
||||
business_title = CRM客户管理
|
||||
business_type = 0
|
||||
business_id = NULL
|
||||
oper_summary = NULL
|
||||
path = /api/web/crm/customer/list
|
||||
request_body = {"page":1,"pageSize":10}
|
||||
response_body = {"code":200,"data":{...}}
|
||||
```
|
||||
|
||||
**导出(business_id 可空)**
|
||||
|
||||
```
|
||||
business_title = CRM客户管理
|
||||
business_type = 5
|
||||
business_id = NULL
|
||||
oper_summary = 导出客户列表
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 架构与数据流
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Client[Web / 小程序] --> Crypto[ApiCryptoMiddleware]
|
||||
Crypto --> LogMW[ApiRequestLogMiddleware]
|
||||
LogMW --> Route[FastAPI Route]
|
||||
Route --> Decorator["@oper_log → ContextVar"]
|
||||
Decorator --> Service[Service / CRUD]
|
||||
Service --> Route
|
||||
Route --> LogMW
|
||||
LogMW --> DB[(sys_api_request_log)]
|
||||
DB --> OperAPI[operlog/list detail]
|
||||
OperAPI --> AdminPage[操作日志管理页]
|
||||
OperAPI --> CRMTab[CRM 详情 Tab]
|
||||
```
|
||||
|
||||
### 中间件与加解密顺序
|
||||
|
||||
`main.py` 注册顺序:先 `ApiRequestLogMiddleware`,后 `ApiCryptoMiddleware` → Crypto 为外层。RequestLog 在解密后的明文上记录 JSON。
|
||||
|
||||
### ContextVar 与装饰器
|
||||
|
||||
**`app/core/context.py` 扩展**:
|
||||
|
||||
```python
|
||||
oper_log_meta: ContextVar[dict] = ContextVar("oper_log_meta", default=None)
|
||||
```
|
||||
|
||||
**`@oper_log` 参数(建议)**:
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `title` | `business_title` |
|
||||
| `business_type` | int |
|
||||
| `business_id_param` | 从 path/query/body 取 id 的键名 |
|
||||
| `summary` | 固定摘要或带占位符 |
|
||||
| `summary_from` | 从 body 字段组装摘要的可选映射 |
|
||||
|
||||
装饰器在 handler 入口解析参数并 `oper_log_meta.set(...)`;中间件 `finally` 读取后落库。
|
||||
|
||||
**子线程注意**: `_persist_log` 经 `asyncio.to_thread` 执行时,须在主线程先把 ContextVar 值拷贝进 `kwargs`,避免线程内丢失。
|
||||
|
||||
### 路径推断兜底(无装饰器)
|
||||
|
||||
沿用 `oper_log.py` 中 `_MODULE_TITLE_RULES`、`_ACTION_TYPE_MAP`;中间件落库时若 ContextVar 为空则写入推断结果。
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
### 现有(增强)
|
||||
|
||||
| 方法 | 路径 | 变更 |
|
||||
|------|------|------|
|
||||
| POST | `/api/web/monitor/operlog/list` | 增加 `businessId`、`businessTitle`、`tenant_no` DB 筛选;`title`/`businessType` 读落库列 |
|
||||
| POST | `/api/web/monitor/operlog/detail` | `operName` = `create_name` 优先 |
|
||||
|
||||
### OperLogListBody 扩展字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `businessId` | string? | 业务主键 |
|
||||
| `businessTitle` | string? | 模块模糊 |
|
||||
| `beginTime` / `endTime` | string? | 时间范围(可选本期) |
|
||||
|
||||
---
|
||||
|
||||
## 前端
|
||||
|
||||
### 操作日志管理页
|
||||
|
||||
| 项 | 值 |
|
||||
|----|-----|
|
||||
| 路径建议 | `web-admin/src/views/system/operlog/index.vue` |
|
||||
| Hash | `/#/system/operlog`(以菜单 SQL 为准) |
|
||||
| 模式 | P01,参考 `views/system/unit/index.vue` |
|
||||
| 权限 | `system:operlog:list`、`system:operlog:query` |
|
||||
|
||||
**列表列**: 模块、操作类型(Tag)、操作人、操作时间、摘要、状态、耗时、操作(详情)
|
||||
|
||||
**筛选**: 模块、操作类型、操作人、状态、时间范围
|
||||
|
||||
**详情弹窗**: 接口地址、IP、入参(`operParam`)、出参(`jsonResult`)、错误信息
|
||||
|
||||
### CRM Tab 改造
|
||||
|
||||
| 页面 | 变更 |
|
||||
|------|------|
|
||||
| `CustomerDetailDialog` | `listOperLog({ businessId: customerId, pageSize: ... })` |
|
||||
| `contract/detail` | `listOperLog({ businessId: contractId, ... })` |
|
||||
|
||||
移除「拉全量 + 前端 filter path/body」逻辑。
|
||||
|
||||
### 菜单 SQL
|
||||
|
||||
挂于「系统管理」下,`order_num` 在字典/岗位等之后;`menuCode` 示例 `system:operlog:list`。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
| 环境变量 | 默认 | 说明 |
|
||||
|----------|------|------|
|
||||
| `API_REQUEST_LOG_ENABLED` | `true` | 生产必须为 true |
|
||||
| `API_REQUEST_LOG_MAX_BODY` | `65536` | 文本字符截断 |
|
||||
| `API_REQUEST_LOG_MAX_BODY_BYTES` | `131072` | 读取字节上限 |
|
||||
| `API_REQUEST_LOG_EXCLUDE_PATHS` | 空(本期新增) | 逗号分隔 path 前缀排除 |
|
||||
|
||||
---
|
||||
|
||||
## 迁移
|
||||
|
||||
**脚本**: `docs/sql/migrations/2026-06-29-operation-audit.sql`
|
||||
|
||||
1. `ALTER TABLE sys_api_request_log` 增加五列 + 索引
|
||||
2. 同步 `ALTER` `sys_api_request_log_his`
|
||||
3. 插入菜单与 `super_admin` 角色菜单(确定性 id)
|
||||
4. 同步 `docs/sql/shanxia2.0.sql`
|
||||
|
||||
---
|
||||
|
||||
## 实施阶段
|
||||
|
||||
| 阶段 | 内容 | 估时 |
|
||||
|------|------|------|
|
||||
| 1 | SQL + ORM + 中间件姓名/租户/语义 | 1 天 |
|
||||
| 2 | ContextVar + `@oper_log` + CRM 写接口样例 | 1 天 |
|
||||
| 3 | operlog API + 管理页 + CRM Tab | 1~2 天 |
|
||||
| 4 | 验收 + graphify | 0.5 天 |
|
||||
|
||||
---
|
||||
|
||||
## 验收清单
|
||||
|
||||
- [ ] 修改客户后 `sys_api_request_log` 含 `create_name`、path、request_body、response_body
|
||||
- [ ] 有 `@oper_log` 的记录含 `business_title`、`business_type`、`business_id`、`oper_summary`
|
||||
- [ ] 管理页可筛选、详情可看入参出参
|
||||
- [ ] 客户详情 Tab 仅显示该 `business_id` 日志
|
||||
- [ ] 非 admin 无法访问 operlog API
|
||||
- [ ] 租户 A 看不到租户 B 日志
|
||||
- [ ] multipart 上传不产生文件二进制日志
|
||||
|
||||
---
|
||||
|
||||
## 待客户确认
|
||||
|
||||
1. **「所有操作」范围** — 当前默认全 API;若仅写操作需配置排除规则
|
||||
2. **日志保留天数** — 建议 90 天热数据 + 归档
|
||||
3. **响应体 PII** — 是否扩展脱敏手机号/身份证
|
||||
|
||||
---
|
||||
|
||||
## 参考
|
||||
|
||||
- `backend/app/core/api_request_log_middleware.py`
|
||||
- `backend/app/crud/monitor/oper_log.py`
|
||||
- `backend/app/api/monitor.py`
|
||||
- `docs/sql/sx.sql` → `sys_oper_log`(RuoYi 对照)
|
||||
- `openspec/changes/operation-audit-enhancement/`
|
||||
@@ -0,0 +1,228 @@
|
||||
# 运输计划 · 承运商资质附件 — 设计文档
|
||||
|
||||
> **日期**: 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 校验、联调)。
|
||||
@@ -0,0 +1,382 @@
|
||||
# 运输计划 · 车辆 ETC/加油充值申请与发放 — 设计文档
|
||||
|
||||
> **日期**: 2026-06-29
|
||||
> **状态**: 已批准
|
||||
> **前置**: `docs/sql/pl_tables.sql`(`pl_vehicle`)、`docs/superpowers/specs/2026-06-25-pl-freight-settlement-design.md`(申请→登记两阶段参考)
|
||||
> **界面模式**: P01 标准列表 CRUD(双菜单)+ P13 财务登记式表单(发放页)
|
||||
|
||||
## 目标
|
||||
|
||||
在运输管理模块新增 **ETC/加油充值** 管理能力,支持:
|
||||
|
||||
1. **【ETC加油申请】**:业务人员提交充值申请(车牌、类型、申请日期、期初公里数、附件、申请人)。
|
||||
2. **【ETC加油发放登记】**:财务/行政登记实际充值结果(订单号、充值日期、卡号、加油站、金额、附件、关联申请单)。
|
||||
|
||||
两菜单独立,职责分离;**本期不做审批流**——申请提交后直接进入「待发放」,由登记人在发放页关联并完成登记。
|
||||
|
||||
## 已确认业务规则
|
||||
|
||||
| # | 规则 | 决策 |
|
||||
|---|------|------|
|
||||
| D1 | 审批 | **A:无需审批**;申请提交即「待发放」 |
|
||||
| D2 | 菜单结构 | **两个独立菜单**:ETC加油申请 / ETC加油发放登记 |
|
||||
| D3 | 申请与发放关联 | **1 申请 : 0~1 发放**;已发放的申请不可再关联 |
|
||||
| D4 | 无申请补录 | **允许**直接新建发放登记(历史数据补录),`apply_id` 可空 |
|
||||
| D5 | 车牌范围 | 下拉取自 **`pl_vehicle` 全量**(自有 + 承运商车辆) |
|
||||
| D6 | 类型一致性 | 发放关联申请时,**自动带出**车牌号、充值类型且只读 |
|
||||
| D7 | 申请人/创建人 | 默认当前登录用户,表单只读展示;落库 `applicant_id` / `create_by` |
|
||||
| D8 | 附件 | JPG/PNG/PDF,单文件 ≤ 20MB,每单最多 5 个;MinIO 逗号分隔 URL |
|
||||
| D9 | 充值订单号 | 后端自动生成:`SXCL` + `YYYYMMDD` + 6 位序号,例 `SXCL20260628000001` |
|
||||
| D10 | 申请单号 | 后端自动生成:`SXSQ` + `YYYYMMDD` + 6 位序号(便于列表检索与关联) |
|
||||
| D11 | 加油站 | 下拉预设 + 自由填写(`el-select` + `allow-create`);预设:中石化、线上etc-app、百链 |
|
||||
| D12 | 删除 | 软删除;**已关联发放记录的申请不可删除**;已有 `apply_id` 关联的发放记录删除时释放申请状态 |
|
||||
|
||||
## 非目标(本期不做)
|
||||
|
||||
- 接入通用工作流 / 主管审批
|
||||
- ETC 卡、油卡主数据维护(卡号每次手填)
|
||||
- 充值报表导出、统计看板
|
||||
- 与运输单 / 地磅 / 计划自动联动
|
||||
- 小程序端申请
|
||||
- 一次申请多次分批发放
|
||||
|
||||
---
|
||||
|
||||
## 方案选型
|
||||
|
||||
**采用方案 A:两个独立菜单**(非单 Tab、非单表状态机)
|
||||
|
||||
| 方案 | 说明 | 结论 |
|
||||
|------|------|------|
|
||||
| A 双菜单 | 申请与发放分页面、分权限 | ✅ 采用 |
|
||||
| B 单菜单 Tab | 申请 \| 待发放 \| 已发放 | 权限边界模糊 |
|
||||
| C 单表状态 | 一张表混放申请/发放字段 | 扩展性差 |
|
||||
|
||||
---
|
||||
|
||||
## 页面与路由
|
||||
|
||||
| 菜单名 | Hash | 组件 | menuCode |
|
||||
|--------|------|------|----------|
|
||||
| ETC加油申请 | `/#/pl/vehicle-recharge-apply` | `web-admin/src/views/pl/vehicle-recharge-apply/index.vue` | `pl:vehicle-recharge-apply:list` |
|
||||
| ETC加油发放登记 | `/#/pl/vehicle-recharge-record` | `web-admin/src/views/pl/vehicle-recharge-record/index.vue` | `pl:vehicle-recharge-record:list` |
|
||||
|
||||
**侧栏位置**:运输管理 → 与「车辆列表」「山峡自有车辆」「运费结算」并列。
|
||||
|
||||
### 权限编码
|
||||
|
||||
| 模块 | 权限 |
|
||||
|------|------|
|
||||
| 申请 | `pl:vehicle-recharge-apply:list` `query` `add` `edit` `remove` |
|
||||
| 发放 | `pl:vehicle-recharge-record:list` `query` `add` `edit` `remove` |
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### 1. 申请单 `pl_vehicle_recharge_apply`
|
||||
|
||||
```sql
|
||||
CREATE TABLE `pl_vehicle_recharge_apply` (
|
||||
`id` varchar(64) NOT NULL COMMENT '主键ID',
|
||||
`apply_no` varchar(32) NOT NULL COMMENT '申请单号 SXSQ+YYYYMMDD+6位',
|
||||
`license_plate` varchar(20) NOT NULL COMMENT '车牌号',
|
||||
`recharge_type` varchar(20) NOT NULL COMMENT '充值类型 etc-ETC fuel-加油',
|
||||
`apply_date` date NOT NULL COMMENT '申请日期',
|
||||
`odometer_km` decimal(10,1) DEFAULT NULL COMMENT '期初公里数',
|
||||
`attachment_urls` varchar(2000) DEFAULT NULL COMMENT '附件URL,逗号分隔',
|
||||
`applicant_id` varchar(64) NOT NULL COMMENT '申请人用户ID',
|
||||
`status` varchar(20) NOT NULL DEFAULT 'pending' COMMENT 'pending-待发放 disbursed-已发放 cancelled-已作废',
|
||||
`tenant_no` varchar(64) NOT NULL DEFAULT 'shanxia2.0' COMMENT '租户编号',
|
||||
`order_num` int(11) DEFAULT NULL COMMENT '排序号',
|
||||
`remark` varchar(512) DEFAULT NULL COMMENT '备注',
|
||||
`create_by` varchar(64) DEFAULT NULL COMMENT '创建人id',
|
||||
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID',
|
||||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
`update_by` varchar(64) DEFAULT NULL COMMENT '更新人id',
|
||||
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||||
`del_flag` smallint(6) NOT NULL DEFAULT 0 COMMENT '删除标记:0-正常 1-已删除',
|
||||
PRIMARY KEY (`id`),
|
||||
UNIQUE KEY `uk_apply_no` (`apply_no`),
|
||||
KEY `idx_tenant` (`tenant_no`),
|
||||
KEY `idx_license_plate` (`license_plate`),
|
||||
KEY `idx_status` (`status`),
|
||||
KEY `idx_apply_date` (`apply_date`)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆ETC/加油充值申请';
|
||||
```
|
||||
|
||||
### 2. 发放登记 `pl_vehicle_recharge_record`
|
||||
|
||||
```sql
|
||||
CREATE TABLE `pl_vehicle_recharge_record` (
|
||||
`id` varchar(64) NOT NULL COMMENT '主键ID',
|
||||
`recharge_order_no` varchar(32) NOT NULL COMMENT '充值订单号 SXCL+YYYYMMDD+6位',
|
||||
`recharge_date` date NOT NULL COMMENT '充值日期',
|
||||
`recharge_type` varchar(20) NOT NULL COMMENT '充值类型 etc-ETC fuel-加油',
|
||||
`card_no` varchar(64) DEFAULT NULL COMMENT '卡号',
|
||||
`gas_station` varchar(200) DEFAULT NULL COMMENT '加油站/充值渠道',
|
||||
`amount` decimal(10,2) NOT NULL COMMENT '充值金额(元)',
|
||||
`attachment_urls` varchar(2000) DEFAULT NULL COMMENT '附件URL,逗号分隔',
|
||||
`apply_id` varchar(64) DEFAULT NULL COMMENT '关联申请单ID',
|
||||
`license_plate` varchar(20) DEFAULT NULL COMMENT '车牌号(冗余,便于无关联申请时列表展示)',
|
||||
`tenant_no` varchar(64) NOT NULL DEFAULT 'shanxia2.0' COMMENT '租户编号',
|
||||
`order_num` int(11) DEFAULT NULL COMMENT '排序号',
|
||||
`remark` varchar(512) DEFAULT NULL COMMENT '备注',
|
||||
`create_by` varchar(64) DEFAULT NULL COMMENT '创建人id',
|
||||
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID',
|
||||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
`update_by` varchar(64) DEFAULT NULL COMMENT '更新人id',
|
||||
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||||
`del_flag` smallint(6) NOT NULL DEFAULT 0 COMMENT '删除标记:0-正常 1-已删除',
|
||||
PRIMARY KEY (`id`),
|
||||
UNIQUE KEY `uk_recharge_order_no` (`recharge_order_no`),
|
||||
UNIQUE KEY `uk_apply_id` (`apply_id`),
|
||||
KEY `idx_tenant` (`tenant_no`),
|
||||
KEY `idx_recharge_date` (`recharge_date`),
|
||||
KEY `idx_license_plate` (`license_plate`)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆ETC/加油充值发放登记';
|
||||
```
|
||||
|
||||
> `uk_apply_id`:保证同一申请最多一条有效发放记录(MySQL 允许多个 NULL)。
|
||||
|
||||
**DDL 同步**:`docs/sql/pl_tables.sql`、`docs/sql/shanxia2.0.sql`、迁移脚本 `docs/sql/migrations/2026-06-29-pl-vehicle-recharge.sql`。
|
||||
|
||||
### 3. 字典
|
||||
|
||||
| dict_type | 标签 | 值 | Tag 色 |
|
||||
|-----------|------|-----|--------|
|
||||
| `pl_recharge_type` | ETC | `etc` | primary |
|
||||
| `pl_recharge_type` | 加油 | `fuel` | success |
|
||||
| `pl_recharge_apply_status` | 待发放 | `pending` | warning |
|
||||
| `pl_recharge_apply_status` | 已发放 | `disbursed` | success |
|
||||
| `pl_recharge_apply_status` | 已作废 | `cancelled` | info |
|
||||
|
||||
加油站预设写入前端常量 + 可选 dict `pl_gas_station`(中石化 / 线上etc-app / 百链);自由填写值仅存 `gas_station` 字段,本期不入字典。
|
||||
|
||||
---
|
||||
|
||||
## 状态机
|
||||
|
||||
```
|
||||
申请创建 ──→ pending(待发放)
|
||||
├── 关联发放登记成功 ──→ disbursed(已发放)
|
||||
└── 手动作废 ──→ cancelled(已作废)
|
||||
|
||||
发放登记创建(含 apply_id)──→ 申请 status 更新为 disbursed
|
||||
发放登记删除(软删)──→ 若曾关联申请,申请回退为 pending
|
||||
```
|
||||
|
||||
| 操作 | 规则 |
|
||||
|------|------|
|
||||
| 编辑申请 | 仅 `pending` 可编辑 |
|
||||
| 作废申请 | 仅 `pending`;手动作废,不物理删除 |
|
||||
| 删除申请 | 仅 `pending` 且无关联发放 |
|
||||
| 新建发放 | 选关联申请时,申请须为 `pending` |
|
||||
| 编辑发放 | 允许;若改 `apply_id` 须重新校验 |
|
||||
| 删除发放 | 软删;释放原申请为 `pending` |
|
||||
|
||||
---
|
||||
|
||||
## 单号生成
|
||||
|
||||
对齐 `backend/app/api/pl/plan.py` `_generate_plan_no`:
|
||||
|
||||
```python
|
||||
def _generate_apply_no(db: Session) -> str:
|
||||
prefix = f"SXSQ{date.today():%Y%m%d}"
|
||||
# 查最大序号(uk 含软删,不过滤 del_flag)
|
||||
...
|
||||
|
||||
def _generate_recharge_order_no(db: Session) -> str:
|
||||
prefix = f"SXCL{date.today():%Y%m%d}"
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 后端设计
|
||||
|
||||
### 模块位置
|
||||
|
||||
| 层 | 路径 |
|
||||
|----|------|
|
||||
| Model | `backend/app/models/pl_models.py` |
|
||||
| Schema | `backend/app/schemas/pl/vehicle_recharge.py`(新建) |
|
||||
| CRUD | `backend/app/crud/pl/vehicle_recharge_apply.py`、`vehicle_recharge_record.py` |
|
||||
| API | `backend/app/api/pl/vehicle_recharge.py` |
|
||||
| 注册 | `app/api/__init__.py`、`app/main.py` |
|
||||
|
||||
### API 清单
|
||||
|
||||
**申请** `/api/admin/pl/vehicle-recharge-apply`
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/list` | 分页列表;筛选:q(单号/车牌)、rechargeType、status、applyDateFrom/To、applicantId |
|
||||
| GET | `/{id}` | 详情 |
|
||||
| POST | `/` | 新建;生成 apply_no;status=pending |
|
||||
| PUT | `/{id}` | 更新;仅 pending |
|
||||
| DELETE | `/{ids}` | 软删;仅 pending |
|
||||
| POST | `/{id}/cancel` | 作废 → cancelled |
|
||||
| GET | `/pending-options` | 待发放申请下拉(供发放页关联;返回 id、applyNo、licensePlate、rechargeType) |
|
||||
|
||||
**发放** `/api/admin/pl/vehicle-recharge-record`
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/list` | 分页;筛选:q(订单号/车牌/卡号)、rechargeType、rechargeDateFrom/To、gasStation、applyNo |
|
||||
| GET | `/{id}` | 详情(含关联申请摘要) |
|
||||
| POST | `/` | 新建;生成 recharge_order_no;若带 apply_id 则更新申请为 disbursed |
|
||||
| PUT | `/{id}` | 更新 |
|
||||
| DELETE | `/{ids}` | 软删;释放关联申请 |
|
||||
|
||||
### 校验要点
|
||||
|
||||
- `license_plate` 须存在于当前租户 `pl_vehicle`(del_flag=0)
|
||||
- `recharge_type` ∈ `{etc, fuel}`
|
||||
- `odometer_km` ≥ 0,最多 1 位小数
|
||||
- `amount` > 0,最多 2 位小数
|
||||
- 新建/更新发放时:若 `apply_id` 非空,申请须 `pending`,且类型一致;自动写入 `license_plate`
|
||||
- 无 `apply_id` 时:`license_plate` 表单必填(补录场景)
|
||||
- 租户隔离 + 数据权限(沿用 PL 模块惯例)
|
||||
|
||||
### `_row_to_dict` 可读字段(申请)
|
||||
|
||||
`id`, `applyNo`, `licensePlate`, `rechargeType`, `applyDate`, `odometerKm`, `attachmentUrls`, `applicantId`, `applicantName`(computed), `status`, `remark`, `createTime`, `updateTime`
|
||||
|
||||
### `_row_to_dict` 可读字段(发放)
|
||||
|
||||
`id`, `rechargeOrderNo`, `rechargeDate`, `rechargeType`, `cardNo`, `gasStation`, `amount`, `attachmentUrls`, `applyId`, `applyNo`(computed), `licensePlate`, `remark`, `createBy`, `createByName`(computed), `createTime`, `updateTime`
|
||||
|
||||
---
|
||||
|
||||
## 前端设计
|
||||
|
||||
### 1. ETC加油申请(P01)
|
||||
|
||||
**参考**:`views/system/unit/index.vue` + `views/pl/carrier/index.vue`(附件)
|
||||
|
||||
**筛选**:关键词(申请单号/车牌)、充值类型、状态、申请日期范围、申请人
|
||||
|
||||
**列表列**:申请单号、车牌、充值类型(Tag)、申请日期、期初公里数、申请人、状态(Tag)、创建时间、操作(查看/编辑/作废/删除)
|
||||
|
||||
**工具栏**:已选 N 项 → 新增申请(primary)
|
||||
|
||||
**新增/编辑弹窗**(`dialog-form-layout`,720px,`form-grid-2`):
|
||||
|
||||
| 字段 | 控件 |
|
||||
|------|------|
|
||||
| 申请单号 | 编辑/查看只读;新建保存后展示 |
|
||||
| 车牌号 | `el-select` filterable,选项来自 `vehicleApi.list` |
|
||||
| 充值类型 | `el-select` + dict |
|
||||
| 申请日期 | `el-date-picker` `YYYY-MM-DD` |
|
||||
| 期初公里数 | `el-input-number` min=0 precision=1 |
|
||||
| 附件 | `AttachmentUploadField` folder=`pl/vehicle-recharge/apply` limit=5 |
|
||||
| 申请人 | 只读,当前用户姓名 |
|
||||
| 备注 | textarea 跨列 |
|
||||
|
||||
**查看弹窗**:`SystemViewDialog` 或专用 view dialog,附件可预览/下载。
|
||||
|
||||
**行操作**:
|
||||
|
||||
- `pending`:查看、编辑、作废、删除
|
||||
- `disbursed`:仅查看
|
||||
- `cancelled`:仅查看、删除(可选,默认保留只读)
|
||||
|
||||
### 2. ETC加油发放登记(P01 + P13)
|
||||
|
||||
**参考**:`views/pl/freight-disburse` 登记思路、`AttachmentUploadField`
|
||||
|
||||
**筛选**:关键词(订单号/车牌/卡号)、充值类型、充值日期范围、加油站、关联申请单号
|
||||
|
||||
**列表列**:充值订单号、充值日期、充值类型(Tag)、车牌、卡号、加油站、金额、关联申请单号、创建人、操作
|
||||
|
||||
**新增/编辑弹窗**(720px):
|
||||
|
||||
| 字段 | 控件 |
|
||||
|------|------|
|
||||
| 充值订单号 | 只读(新建提示「保存后自动生成」) |
|
||||
| 关联申请单 | `el-select` clearable,remote/本地加载 `pending-options`;选中后带出车牌、类型只读 |
|
||||
| 车牌号 | 有关联时只读;无关联时必选 |
|
||||
| 充值类型 | 有关联时只读;无关联必选 |
|
||||
| 充值日期 | date picker |
|
||||
| 卡号 | text input |
|
||||
| 加油站 | `el-select` allow-create filterable,预设三项 |
|
||||
| 充值金额 | input-number precision=2 min=0.01 |
|
||||
| 附件 | `AttachmentUploadField` folder=`pl/vehicle-recharge/record` |
|
||||
| 备注 | textarea |
|
||||
| 创建人 | 只读 |
|
||||
|
||||
**快捷入口(可选增强)**:申请列表行操作增加「去登记」→ 打开发放新建弹窗并预填 `applyId`(二期可做,本期发放页选手动关联即可)。
|
||||
|
||||
### 3. API 类型(`web-admin/src/api/pl/index.ts`)
|
||||
|
||||
新增 `VehicleRechargeApply`、`VehicleRechargeRecord` 接口与 CRUD 方法。
|
||||
|
||||
### 4. UI 规范
|
||||
|
||||
- 状态/类型字段用 `el-tag` + dict Store
|
||||
- 按钮带 `@element-plus/icons-vue` 图标
|
||||
- 弹窗 `align-center`,无 backdrop blur
|
||||
- 操作列 `fixed="right"` min-width ≥ 260px
|
||||
- 列宽用 `min-width`
|
||||
|
||||
---
|
||||
|
||||
## OpenSpec 更新(建议)
|
||||
|
||||
在 `openspec/changes/transport-plan-management/` 下新增 capability `vehicle-recharge/spec.md`,或扩展 `vehicle-driver/spec.md`:
|
||||
|
||||
#### Scenario: ETC加油申请提交
|
||||
|
||||
- **WHEN** 用户提交充值申请
|
||||
- **THEN** 系统 SHALL 生成申请单号并置状态为待发放
|
||||
- **AND** 申请人 SHALL 默认为当前登录用户
|
||||
|
||||
#### Scenario: 发放登记关联申请
|
||||
|
||||
- **WHEN** 财务创建发放登记并关联待发放申请
|
||||
- **THEN** 系统 SHALL 自动生成充值订单号 `SXCL+日期+序号`
|
||||
- **AND** 申请状态 SHALL 更新为已发放
|
||||
- **AND** 同一申请 SHALL NOT 被重复关联
|
||||
|
||||
#### Scenario: 无申请补录
|
||||
|
||||
- **WHEN** 用户创建发放登记且不关联申请
|
||||
- **THEN** 系统 SHALL 允许保存并要求手动填写车牌与充值类型
|
||||
|
||||
---
|
||||
|
||||
## 影响范围
|
||||
|
||||
| 层级 | 文件 |
|
||||
|------|------|
|
||||
| SQL | `pl_tables.sql`, `shanxia2.0.sql`, migration |
|
||||
| Backend | `pl_models.py`, schemas, crud, api, `__init__.py`, `main.py` |
|
||||
| Frontend | 两页面 vue、api/pl、dict 注册 |
|
||||
| 菜单 | 迁移 SQL 或菜单管理脚本 |
|
||||
| OpenSpec | transport-plan-management spec(可选) |
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. 新建申请:必填校验通过 → 生成 `SXSQ…` 单号,状态「待发放」,申请人为当前用户
|
||||
2. 待发放申请可在发放页关联;关联后申请变「已发放」,不可再选
|
||||
3. 新建发放:生成 `SXCL…` 订单号;金额、日期、类型校验生效
|
||||
4. 无关联申请的发放:可手填车牌、类型并保存
|
||||
5. 删除发放:关联申请回退「待发放」
|
||||
6. 已发放申请不可编辑/删除;待发放可编辑
|
||||
7. 附件上传/预览/下载正常;列表筛选、分页、权限按钮生效
|
||||
8. 租户隔离:跨租户数据不可见
|
||||
|
||||
---
|
||||
|
||||
## 工作量估算
|
||||
|
||||
| 项 | 估时 |
|
||||
|----|------|
|
||||
| DDL + Model + CRUD + API + 单号/状态联动 | 1~1.5 人日 |
|
||||
| 前端双页 + API + 字典 + 附件 | 1.5~2 人日 |
|
||||
| 菜单权限 + 联调 + field consistency 脚本 | 0.5 人日 |
|
||||
| **合计** | **约 3~4 人日** |
|
||||
@@ -0,0 +1,167 @@
|
||||
# 运输计划 · 车辆维保申请与处理登记 — 设计文档
|
||||
|
||||
> **日期**: 2026-06-29
|
||||
> **状态**: 已批准
|
||||
> **前置**: `docs/superpowers/specs/2026-06-29-pl-vehicle-recharge-design.md`(申请→登记两阶段参考)、`docs/sql/pl_tables.sql`(`pl_vehicle`)
|
||||
> **界面模式**: P01 标准列表 CRUD(双菜单);处理登记页参考 ETC 发放看板(申请 + 处理合并列表)
|
||||
|
||||
## 目标
|
||||
|
||||
在运输管理模块新增 **车辆维保** 管理能力,支持:
|
||||
|
||||
1. **【车辆维保申请】**:提交维保申请(车牌、申请人、申请时间、维保类型、开始/取车时间、内容、店铺地址、附件、备注)。
|
||||
2. **【车辆维保处理登记】**:登记处理结果(金额、处理人、处理时间、附件;可关联申请或无申请补录)。
|
||||
|
||||
两菜单独立;**本期不做审批流**——申请提交后进入「待处理」,登记处理完成后变为「已处理」。
|
||||
|
||||
## 已确认业务规则
|
||||
|
||||
| # | 规则 | 决策 |
|
||||
|---|------|------|
|
||||
| D1 | 审批 | **无需审批**;申请提交即「待处理」 |
|
||||
| D2 | 菜单结构 | **车辆维保申请** / **车辆维保处理登记** |
|
||||
| D3 | 申请与处理关联 | **1 申请 : 0~1 处理**;已处理的申请不可再关联 |
|
||||
| D4 | 无申请补录 | **允许**;`apply_id` 可空 |
|
||||
| D5 | 处理完成语义 | 提交处理登记即 **已处理**;不设独立「是否已处理」字段 |
|
||||
| D6 | 金额 | **非必填**;有值须 > 0;可后补编辑 |
|
||||
| D7 | 申请人/处理人 | 下拉选择用户(`fetchUserOptions`);默认当前登录人 |
|
||||
| D8 | 维保类型 | 下拉预设(保养、维修、年检)+ **allow-create 自定义**;存 varchar 自由文本 |
|
||||
| D9 | 车辆状态联动 | **V1 不自动**改 `pl_vehicle.vehicle_status` |
|
||||
| D10 | 选车提醒 | 见 §选车维保提醒 |
|
||||
| D11 | 申请单号 | `SXWB` + `YYYYMMDD` + 6 位序号 |
|
||||
| D12 | 处理单号 | `SXWC` + `YYYYMMDD` + 6 位序号 |
|
||||
| D13 | 附件 | JPG/PNG/PDF,单文件 ≤ 20MB,每单最多 5 个;MinIO 逗号分隔 URL |
|
||||
| D14 | 删除 | 软删除;已关联处理记录的申请不可删;删处理记录时释放申请为待处理 |
|
||||
|
||||
## 非目标(本期不做)
|
||||
|
||||
- 接入通用工作流 / 主管审批
|
||||
- 维保店铺主数据维护
|
||||
- 申请后自动将车辆设为「维修中」
|
||||
- 维保费用统计报表、导出
|
||||
- 小程序端申请
|
||||
- 一次申请多次分批处理
|
||||
|
||||
---
|
||||
|
||||
## 选车维保提醒
|
||||
|
||||
在申请页(及处理页补录选车牌时)选择车牌后:
|
||||
|
||||
**触发条件**(同时满足):
|
||||
|
||||
1. 存在该车牌 **待处理**(`status=pending`)的维保申请;
|
||||
2. `expected_pickup_date IS NULL` **或** `today <= expected_pickup_date`。
|
||||
|
||||
**不提醒**:`today > expected_pickup_date`(即使仍为待处理)。
|
||||
|
||||
**展示**:`ElMessageBox.alert` 或等价弹窗,展示维保类型、开始时间、预计取车、内容、店铺地址、申请单号等;多条时合并展示或取最近一条(实现取 **全部待提醒** 列表)。
|
||||
|
||||
**API**:`GET /api/transport/vehicle-maintenance-apply/reminders?licensePlate=xxx`
|
||||
|
||||
---
|
||||
|
||||
## 页面与路由
|
||||
|
||||
| 菜单名 | Hash | 组件 | menuCode |
|
||||
|--------|------|------|----------|
|
||||
| 车辆维保申请 | `/#/pl/vehicle-maintenance-apply` | `web-admin/src/views/pl/vehicle-maintenance-apply/index.vue` | `pl:vehicle-maintenance-apply:list` |
|
||||
| 车辆维保处理登记 | `/#/pl/vehicle-maintenance-process` | `web-admin/src/views/pl/vehicle-maintenance-process/index.vue` | `pl:vehicle-maintenance-process:list` |
|
||||
|
||||
**侧栏位置**:运输管理 → 与 ETC/加油 菜单并列(`order_num` 33 / 34)。
|
||||
|
||||
### 权限编码
|
||||
|
||||
| 模块 | 权限 |
|
||||
|------|------|
|
||||
| 申请 | `pl:vehicle-maintenance-apply:list` `query` `add` `edit` `remove` `cancel` |
|
||||
| 处理 | `pl:vehicle-maintenance-process:list` `query` `add` `edit` `remove` |
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### 1. 申请单 `pl_vehicle_maintenance_apply`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | varchar(64) | UUID 主键 |
|
||||
| apply_no | varchar(32) | SXWB+日期+6位,唯一 |
|
||||
| license_plate | varchar(20) | 车牌,校验 pl_vehicle |
|
||||
| applicant_id | varchar(64) | 申请人 |
|
||||
| apply_date | date | 申请时间 |
|
||||
| maintenance_type | varchar(64) | 维保类型(可自定义文本) |
|
||||
| start_date | date | 维保开始时间 |
|
||||
| expected_pickup_date | date NULL | 预计取车时间 |
|
||||
| maintenance_content | varchar(1000) | 维保内容 |
|
||||
| shop_address | varchar(500) | 维保店铺地址 |
|
||||
| attachment_urls | varchar(2000) | 申请附件 |
|
||||
| status | varchar(20) | pending / processed / cancelled |
|
||||
| + 公共字段 | | tenant_no … del_flag |
|
||||
|
||||
**日期校验**:`apply_date <= start_date`;若 `expected_pickup_date` 有值则 `start_date <= expected_pickup_date`。
|
||||
|
||||
### 2. 处理登记 `pl_vehicle_maintenance_process`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | varchar(64) | UUID 主键 |
|
||||
| process_no | varchar(32) | SXWC+日期+6位,唯一 |
|
||||
| apply_id | varchar(64) NULL | 关联申请,唯一索引(允许多 NULL) |
|
||||
| license_plate | varchar(20) | 车牌冗余 |
|
||||
| amount | decimal(10,2) NULL | 金额(元) |
|
||||
| handler_id | varchar(64) | 处理人 |
|
||||
| process_date | date | 处理时间 |
|
||||
| attachment_urls | varchar(2000) | 处理附件 |
|
||||
| + 公共字段 | | |
|
||||
|
||||
### 字典
|
||||
|
||||
| dict_type | 预设 |
|
||||
|-----------|------|
|
||||
| pl_maintenance_type | 保养、维修、年检 |
|
||||
| pl_maintenance_apply_status | 待处理、已处理、已作废 |
|
||||
|
||||
---
|
||||
|
||||
## 状态流转
|
||||
|
||||
```
|
||||
创建申请 → pending
|
||||
pending + 登记处理(有 apply_id)→ processed
|
||||
pending → cancelled(作废)
|
||||
删除处理记录 → 关联申请回 pending
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 概要
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/transport/vehicle-maintenance-apply/` | 申请分页列表 |
|
||||
| POST | `/transport/vehicle-maintenance-apply/` | 新建申请 |
|
||||
| PUT | `/transport/vehicle-maintenance-apply/{id}` | 编辑(仅 pending) |
|
||||
| POST | `/transport/vehicle-maintenance-apply/{id}/cancel` | 作废 |
|
||||
| DELETE | `/transport/vehicle-maintenance-apply/{id}` | 软删 |
|
||||
| GET | `/transport/vehicle-maintenance-apply/reminders` | 选车提醒 |
|
||||
| GET | `/transport/vehicle-maintenance-process/process-board` | 处理看板(申请 LEFT JOIN 处理) |
|
||||
| POST | `/transport/vehicle-maintenance-process/` | 新建处理(含补录) |
|
||||
| PUT | `/transport/vehicle-maintenance-process/{id}` | 编辑处理 |
|
||||
| DELETE | `/transport/vehicle-maintenance-process/{id}` | 软删处理 |
|
||||
|
||||
---
|
||||
|
||||
## 实现参考
|
||||
|
||||
复制并改造 ETC/加油 模块:
|
||||
|
||||
- 后端:`pl_vehicle_recharge_service.py` → `pl_vehicle_maintenance_service.py`
|
||||
- 前端:`vehicle-recharge-apply` / `vehicle-recharge-record` → 维保对应页面
|
||||
- 静态路由:`web-admin/src/router/modules/pl.ts`
|
||||
|
||||
---
|
||||
|
||||
## OpenSpec
|
||||
|
||||
变更目录:`openspec/changes/vehicle-maintenance-management/`
|
||||
@@ -0,0 +1,115 @@
|
||||
# 运输计划 · 车辆尿素申请与发放登记 — 设计文档
|
||||
|
||||
> **日期**: 2026-06-29
|
||||
> **状态**: 已批准
|
||||
> **前置**: `docs/superpowers/specs/2026-06-29-pl-vehicle-recharge-design.md`、`docs/superpowers/specs/2026-06-29-vehicle-maintenance-design.md`
|
||||
> **界面模式**: P01 标准列表 CRUD(双菜单);发放页参考 ETC 发放看板
|
||||
|
||||
## 目标
|
||||
|
||||
在运输管理模块新增 **车辆尿素** 管理能力:
|
||||
|
||||
1. **【车辆尿素申请】**:提交入库/采购类申请(车牌、申请人、申请时间、入库时间、单位、入库数、申请金额、附件、备注)。
|
||||
2. **【车辆尿素发放登记】**:登记实际发放(发放金额、处理人、发放时间、附件;可关联申请或无申请补录)。
|
||||
|
||||
无审批流;申请提交后 **待发放**,发放登记后 **已发放**。
|
||||
|
||||
## 已确认业务规则
|
||||
|
||||
| # | 规则 | 决策 |
|
||||
|---|------|------|
|
||||
| D1 | 审批 | **无需审批** |
|
||||
| D2 | 菜单 | **车辆尿素申请** / **车辆尿素发放登记** |
|
||||
| D3 | 关联 | **1 申请 : 0~1 发放** |
|
||||
| D4 | 无申请补录 | **允许** |
|
||||
| D5 | 申请 vs 发放金额 | **计划 vs 实付**;发放默认带出申请金额,可修改 |
|
||||
| D6 | 申请金额 | **必填** > 0 |
|
||||
| D7 | 发放金额 | **必填** > 0 |
|
||||
| D8 | 入库数 | **必填**,支持小数 |
|
||||
| D9 | 单位 | 默认「吨桶」+ **allow-create** |
|
||||
| D10 | 是否已处理 | **不设字段**;发放提交 → `disbursed` |
|
||||
| D11 | 申请人/处理人 | 用户下拉,默认当前登录人 |
|
||||
| D12 | 单号 | 申请 `SXNS*` / 发放 `SXUF*` |
|
||||
| D13 | 日期 | `apply_date ≤ warehouse_in_date` |
|
||||
| D14 | 附件 | JPG/PNG/PDF,≤20MB,最多 5 个 |
|
||||
| D15 | 删除 | 软删除;有关联发放的申请不可删;删发放释放申请为待发放 |
|
||||
|
||||
## 非目标(V1)
|
||||
|
||||
- 审批流、库存台账联动、报表导出、小程序、车辆状态联动、选车提醒
|
||||
|
||||
---
|
||||
|
||||
## 页面与路由
|
||||
|
||||
| 菜单 | Hash | menuCode |
|
||||
|------|------|----------|
|
||||
| 车辆尿素申请 | `/#/pl/vehicle-urea-apply` | `pl:vehicle-urea-apply:list` |
|
||||
| 车辆尿素发放登记 | `/#/pl/vehicle-urea-disburse` | `pl:vehicle-urea-disburse:list` |
|
||||
|
||||
侧栏 `order_num`: 35 / 36(运输管理下,维保之后)。
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### `pl_vehicle_urea_apply`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| apply_no | varchar(32) | SXNS+日期+6位 |
|
||||
| license_plate | varchar(20) | 车牌 |
|
||||
| applicant_id | varchar(64) | 申请人 |
|
||||
| apply_date | date | 申请时间 |
|
||||
| warehouse_in_date | date | 入库时间 |
|
||||
| unit | varchar(32) | 单位 |
|
||||
| quantity | decimal(10,2) | 入库数 |
|
||||
| apply_amount | decimal(10,2) | 申请金额 |
|
||||
| attachment_urls | varchar(2000) | 附件 |
|
||||
| status | varchar(20) | pending / disbursed / cancelled |
|
||||
|
||||
### `pl_vehicle_urea_disburse`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| disburse_no | varchar(32) | SXUF+日期+6位 |
|
||||
| apply_id | varchar(64) NULL | 关联申请,唯一 |
|
||||
| license_plate | varchar(20) | 冗余 |
|
||||
| amount | decimal(10,2) | 发放金额(实付) |
|
||||
| handler_id | varchar(64) | 处理人 |
|
||||
| disburse_date | date | 发放时间 |
|
||||
| attachment_urls | varchar(2000) | 附件 |
|
||||
|
||||
### 字典
|
||||
|
||||
- `pl_urea_unit`:吨桶(UI 预设 + allow-create,库内可存自由文本)
|
||||
- `pl_urea_apply_status`:待发放 / 已发放 / 已作废
|
||||
|
||||
---
|
||||
|
||||
## API 概要
|
||||
|
||||
| 路径 | 说明 |
|
||||
|------|------|
|
||||
| `/transport/vehicle-urea-apply/*` | 申请 CRUD + 作废 |
|
||||
| `/transport/vehicle-urea-disburse/disburse-board` | 发放看板 |
|
||||
| `/transport/vehicle-urea-disburse/*` | 发放 CRUD |
|
||||
|
||||
---
|
||||
|
||||
## 发放弹窗交互
|
||||
|
||||
- 只读展示:车牌、入库时间、单位、入库数、**申请金额**
|
||||
- **发放金额**:默认 = 申请金额,可编辑(实付可与计划不同)
|
||||
- **处理人**:下拉,默认当前用户
|
||||
- **发放时间**:默认今天
|
||||
|
||||
---
|
||||
|
||||
## 实现参考
|
||||
|
||||
- 后端/页面:复制 `pl_vehicle_recharge_*` / `vehicle-recharge-*`
|
||||
- 申请扩展字段:入库时间、单位、数量、申请金额
|
||||
- `sys_role_menu`:**固定 id / MD5**,禁止单语句多行 `UUID()`
|
||||
|
||||
OpenSpec:`openspec/changes/vehicle-urea-management/`
|
||||
Reference in new issue
Block a user