shanxia2.0/openspec/changes/vehicle-maintenance-management/design.md

Context

山峡化工 web-admin 运输管理（PL）已有 ETC/加油充值申请与发放（pl_vehicle_recharge_apply / pl_vehicle_recharge_record），采用双菜单、无审批、1:0~1 关联、发放看板 UX。客户新增 车辆维保 需求，业务形态相似但申请字段更丰富，且需在选车时提醒未过预计取车日的待处理维保。

工程约束：租户隔离、数据权限、软删除、Fresh Mint UI、静态路由（VITE_ACCESS_MODE=frontend）。

Goals / Non-Goals

Goals:

• 交付维保申请页 + 处理登记页，业务规则与客户确认一致
• 复用 ETC 模块架构，降低回归与工期
• 选车维保提醒 API + 前端弹窗

Non-Goals:

• 审批流、车辆状态自动联动、报表、小程序

Decisions

D1 双菜单平行模块（非抽象框架）

决策：新建 pl_vehicle_maintenance_* 表与独立 Service/API/页面，复制 ETC 模式。
理由：仅第二个类似场景，抽象成本高；独立模块便于维保特有规则（提醒、日期校验）演进。
备选：通用 ApplyDisburse 基类 — 拒绝（过度设计）。

D2 处理完成 = 申请 status processed

决策：不设 is_processed 字段；创建/更新处理记录且关联申请时，申请置 processed。
理由：客户选 A，与 ETC「发放即完成」一致。
备选：独立布尔 — 拒绝。

D3 金额可选

决策：amount NULL 允许；非 NULL 时 > 0。
理由：客户选 B，可先登记处理人与时间。

D4 维保类型 varchar + UI allow-create

决策：库存自由文本；字典仅作下拉预设（保养/维修/年检）。
理由：客户要求可手填；避免每次自定义类型写 dict 表。

D5 选车提醒

决策：查询 pending 且 (expected_pickup_date IS NULL OR today <= expected_pickup_date) 的申请；today > expected_pickup_date 不提醒；取车时间为空仍提醒。
理由：客户明确规则；不依赖 vehicle_status。

D6 单号前缀

决策：申请 SXWB，处理 SXWC。
理由：与 SXSQ/SXCL 命名风格一致，WB=维保，WC=维保处理。

D7 处理看板 API

决策：GET .../process-board，申请 LEFT JOIN 处理（同 ETC disburse-board）。
理由：UX 已验证；行内处理/编辑。

Risks / Trade-offs

风险	缓解
与 ETC 代码重复	接受；后续若第三模块再抽公共层
多条 pending 提醒信息过多	弹窗列表展示全部待提醒项
预计取车日为空长期 pending 持续提醒	符合客户确认；业务侧应填取车日或作废
静态路由遗漏导致菜单不可见	同步 pl.ts + DB 菜单

Migration Plan

1. 执行 docs/sql/migrations/2026-06-29-pl-vehicle-maintenance.sql
2. 部署后端 + 前端
3. 为相关角色授权菜单（脚本含 super_admin + 拥有 PL_VEHICLE 的角色）
4. 回滚：隐藏菜单；表保留（软删即可）

Open Questions

• （无 — 客户已确认 V1 范围）