This commit is contained in:
zlwu committed 2026-06-29 11:15:39 +08:00
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/`