升鲜宝生鲜配送供应链系统 vs_车辆管理模块开发文档 PRD（一）---升鲜宝生鲜配送供应链管理系统

车辆档案 · 司机档案 · 证照保险 · 维保费用 · 可用状态 · 配送调度联动

|--------|------------------------------------------------------------------|
| 项目 | 内容 |
| 文档版本 | V1.0 研发落地版 |
| 适用范围 | 升鲜宝供应链后台车辆管理、配送调度前置资源管理、司机/车辆资料维护 |
| 技术口径 | Spring Boot 4.x + MyBatis-Plus + MySQL 8.0 + Vue3 + Element Plus |
| 数据库前缀 | vs_，表示 Vehicle Service / Vehicle System 车辆管理域 |
| 生成日期 | 2026-05-17 |
| 文档用途 | 产品评审、数据库设计、后端接口开发、前端页面开发、测试验收、实施培训 |

文档目标与模块定位
业务边界与系统关系
角色与权限范围
功能架构与后台菜单
核心业务流程
页面级 PRD 设计
数据库表结构与数据字典
后端 API 与 Service 设计
前端页面与交互规范
状态枚举与业务规则
与配送/OMS/WMS/财务的集成
非功能要求
开发优先级与验收标准
附录：建议目录结构与命名规范

1. 文档目标与模块定位

本文档用于规范升鲜宝供应链系统中 vs_ 车辆管理模块的功能范围、页面结构、数据库表设计、后端接口、前端交互和测试验收标准。车辆管理模块是配送调度、线路计划、司机任务和物流成本核算的基础资源模块。

模块定位：车辆管理模块负责维护车辆、司机、证照、保险、年检、维保、维修、加油、里程、费用、违章事故、GPS设备和车辆可用状态。车辆管理不直接替代配送调度模块，不负责订单分配和路线优化，但要为配送调度提供车辆容量、车辆状态、司机绑定、证照有效性和可派车校验能力。

车辆资源可视化：统一维护车辆档案、装载能力、所属仓库、使用状态。
合规风险前置：保险、年检、驾驶证、道路运输证、冷链资质等到期预警。
运营成本沉淀：加油、维修、保养、保险、违章、事故等费用归集到车辆维度。
调度可用性支撑：配送排车前校验车辆启用、司机有效、证照有效、保养状态和占用状态。
物流分析基础：按车辆、司机、线路、仓库统计出车次数、里程、油耗、费用和异常。

2. 业务边界与系统关系

vs_车辆管理属于物流资源域。它维护车辆和司机基础能力，和 OMS 订单、WMS 出库、配送调度、财务费用形成协作关系。

|-----------|--------------------|------------------------------|
| 系统/模块 | 与车辆管理的关系 | 边界说明 |
| OMS订单中心 | 提供待配送订单、配送任务来源 | 车辆管理不生成客户订单，不修改订单金额。 |
| WMS仓库出库 | 提供出库单、装车确认、发车前复核 | 车辆管理不处理库存扣减，只记录车辆与任务关联。 |
| 配送调度/TMS | 读取车辆容量、状态、司机、可派车校验 | 路线规划、任务分配、到达签收由配送调度负责。 |
| FIN财务 | 接收车辆费用、油费、维修费等成本数据 | 财务凭证、付款核销由财务模块处理。 |
| SYS权限系统 | 提供菜单、按钮、数据权限 | 车辆管理只提供权限编码和操作日志。 |
| IoT/GPS平台 | 同步定位、轨迹、温度 | 车辆管理存设备绑定和轨迹摘要，原始高频轨迹可走外部平台。 |

3. 角色与权限范围

|--------|-----------------------|----------------------|----------------|
| 角色 | 职责 | 可使用功能 | 关键权限 |
| 物流主管 | 维护车辆、司机、可用状态，查看成本报表 | 全部车辆档案、司机、维保、费用、可用状态 | 新增/修改/启停/导出/审核 |
| 调度员 | 查看可派车辆，绑定配送任务，登记出车/回车 | 车辆可用看板、车辆任务关联、里程登记 | 查询/绑定/出车/回车 |
| 司机 | 查看本人车辆与任务，登记里程/异常 | 移动端车辆状态、出车检查、异常上报 | 本人数据查询/上报 |
| 财务人员 | 查看费用，核对油费、维修费、保险费 | 车辆费用、费用报表 | 查询/导出/费用审核 |
| 系统管理员 | 维护字典、权限、菜单 | 车辆类型、状态字典、权限菜单 | 菜单/按钮授权 |

4. 功能架构与后台菜单

建议将车辆管理作为"物流配送"或"基础资料"下的二级模块，也可独立为"车辆管理"一级菜单。对于升鲜宝后台，推荐采用三级菜单结构：一级模块 / 二级分组 / 三级功能菜单。

|----------|----------|------------|-----------------------------|
| 一级模块 | 二级分组 | 三级功能菜单 | 功能说明 |
| 车辆管理 | 基础资料 | 车辆类型 | 维护冷藏车、厢式车、面包车、货车等车型及容量模板。 |
| 车辆管理 | 基础资料 | 车辆档案 | 维护车牌、车型、载重、体积、所属仓库、状态、证照信息。 |
| 车辆管理 | 基础资料 | 司机档案 | 维护司机证件、联系方式、驾驶证类型、有效期和状态。 |
| 车辆管理 | 基础资料 | 司机车辆绑定 | 维护司机与车辆的主驾/副驾/临时绑定关系。 |
| 车辆管理 | 证照合规 | 车辆证照 | 行驶证、道路运输证、营运证、冷链资质等证照管理。 |
| 车辆管理 | 证照合规 | 保险管理 | 交强险、商业险、货运险、冷链险等保单和到期预警。 |
| 车辆管理 | 证照合规 | 年检管理 | 车辆年检、环保检、冷链设备校验记录。 |
| 车辆管理 | 维保费用 | 保养计划 | 按时间或里程自动生成保养提醒。 |
| 车辆管理 | 维保费用 | 保养记录 | 登记保养项目、费用、里程、供应商、附件。 |
| 车辆管理 | 维保费用 | 维修记录 | 登记维修原因、维修项目、费用、停运天数。 |
| 车辆管理 | 维保费用 | 加油/充电记录 | 油量、电量、单价、金额、里程、油耗统计。 |
| 车辆管理 | 维保费用 | 车辆费用 | 保险、维保、油费、罚款、停车、过路费等汇总。 |
| 车辆管理 | 调度状态 | 车辆可用状态 | 展示可用、占用、维修、停用、证照到期等状态。 |
| 车辆管理 | 调度状态 | 出车/回车记录 | 记录任务、司机、车辆、出车里程、回车里程。 |
| 车辆管理 | 异常安全 | 违章记录 | 登记违章、扣分、罚款、处理状态。 |
| 车辆管理 | 异常安全 | 事故记录 | 登记事故时间、地点、责任、损失、保险理赔。 |
| 车辆管理 | 设备冷链 | GPS设备绑定 | 车辆与GPS/温度设备绑定。 |
| 车辆管理 | 设备冷链 | 温度记录 | 冷链温度上报、超温告警、任务关联。 |
| 车辆管理 | 报表中心 | 车辆运营报表 | 车辆里程、油耗、费用、出车次数、异常分析。 |
| 车辆管理 | 系统设置 | 操作日志 | 记录车辆模块关键操作。 |

5. 核心业务流程

5.1 车辆建档流程

新增车辆 → 选择车型 → 填写车牌/VIN/载重/体积/所属仓库 → 上传行驶证/证照 → 设置启用状态 → 进入可派车池。

5.2 司机建档与绑定流程

新增司机 → 填写驾驶证/准驾车型/手机号 → 校验驾驶证有效期 → 绑定车辆 → 设置主驾/副驾/临时司机 → 调度时参与可派车校验。

5.3 证照到期预警流程

定时任务扫描保险、年检、营运证、驾驶证到期日期 → 生成预警 → 推送物流主管/调度员 → 到期未处理时车辆状态置为"限制派车"。

5.4 调度可用性校验流程

配送调度选择车辆 → 校验车辆启用、未删除、未维修、未停用、未被占用 → 校验证照未过期 → 校验司机驾驶证有效 → 校验载重/体积是否满足任务 → 返回可派/不可派原因。

5.5 出车与回车流程

调度绑定车辆任务 → 司机出车确认 → 记录出车时间/起始里程/油量/照片 → 任务完成 → 回车确认 → 记录回车时间/结束里程/异常/费用 → 更新车辆里程与可用状态。

6. 页面级 PRD 设计

|---------|-----------------------------------|----------------------------------|
| 页面 | 主要操作 | 核心字段 |
| 车辆类型 | 查询车型名称/温控类型/状态；新增、修改、启停、删除、导出 | 车型名称、温控类型、默认载重、默认体积、尺寸、状态、排序、备注 |
| 车辆档案 | 查询车牌/车型/仓库/状态/证照到期；新增、修改、启停、详情、导出 | 车牌、车型、载重、体积、仓库、司机、使用状态、年检到期、保险到期 |
| 司机档案 | 查询司机姓名/手机号/驾驶证状态；新增、修改、启停、导出 | 姓名、手机号、准驾车型、驾驶证号、到期日、状态、绑定车辆 |
| 司机车辆绑定 | 按车辆或司机查询绑定关系；新增绑定、解绑、设置主驾 | 车牌、司机、绑定类型、生效时间、失效时间、状态 |
| 车辆证照 | 维护证照类型、证照编号、有效期、附件、到期提醒 | 车牌、证照类型、编号、有效期、附件、提醒状态 |
| 保险管理 | 维护保单、保险公司、保额、费用、到期日期 | 车牌、险种、保单号、保险公司、费用、有效期 |
| 年检管理 | 登记年检/环保检/冷链校验记录 | 车牌、检测类型、检测日期、下次检测日期、结果、附件 |
| 保养计划 | 按里程或时间生成保养计划 | 车牌、计划类型、计划里程、计划日期、提醒状态 |
| 保养记录 | 登记保养项目、费用、里程、供应商 | 车牌、保养日期、里程、项目、费用、供应商、附件 |
| 维修记录 | 登记故障、维修项目、费用、停运时间 | 车牌、故障说明、维修日期、费用、维修厂、停运天数 |
| 加油/充电记录 | 登记油量/电量、单价、金额、里程 | 车牌、日期、油量/电量、单价、金额、当前里程 |
| 车辆费用 | 汇总车辆费用，可按类型、车辆、日期查询 | 车牌、费用类型、金额、来源单据、审核状态 |
| 车辆可用状态 | 展示可用/占用/维修/停用/证照到期 | 车牌、当前状态、占用任务、司机、原因、更新时间 |
| 出车/回车记录 | 记录车辆任务、出车里程、回车里程、异常 | 任务号、车牌、司机、出车时间、回车时间、里程差 |
| 违章记录 | 登记违章、扣分、罚款、处理状态 | 车牌、司机、违章时间、地点、扣分、罚款、处理状态 |
| 事故记录 | 登记事故信息、损失、保险理赔 | 车牌、司机、事故时间、责任、损失金额、理赔状态 |
| GPS设备绑定 | 绑定GPS设备、SIM卡、设备状态 | 车牌、设备号、SIM卡、平台、状态、绑定时间 |
| 温度记录 | 冷链车温度记录与超温告警 | 车牌、任务号、温度、采集时间、是否超温 |
| 车辆运营报表 | 按车辆/司机/线路/仓库统计 | 出车次数、里程、油耗、费用、异常、利用率 |

7. 数据库表结构与数据字典

本章给出 vs_ 车辆管理模块建议表。字段采用升鲜宝常用口径：主键 BIGINT；启停字段使用 enabled；逻辑删除使用 del_flag；排序使用 sort_code；时间字段按项目现有口径可使用 BIGINT 时间戳或 DATETIME，本文以 BIGINT 时间戳表达。

|-------------|--------------|--------------|--------|
| 通用字段 | 类型 | 说明 | 索引 |
| id | BIGINT | 主键ID | PK |
| enabled | TINYINT | 启用状态：0停用 1启用 | IDX |
| del_flag | TINYINT | 删除标记：0正常 1删除 | IDX |
| sort_code | INT | 排序码 | |
| creator | BIGINT | 创建人ID | |
| create_date | BIGINT | 创建时间 | IDX |
| updater | BIGINT | 修改人ID | |
| update_date | BIGINT | 修改时间 | |
| remark | VARCHAR(255) | 备注 | |

7.1 vs_vehicle_type - 车辆类型表

表职责：维护车型、温控类型、默认载重体积和尺寸模板。

|---------------------|---------------|-----------------------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| type_code | VARCHAR(64) | 车型编码 | UK |
| type_name | VARCHAR(100) | 车型名称 | |
| temperature_type | TINYINT | 温控类型：0常温 1冷藏 2冷冻 3多温区 | IDX |
| default_load_weight | DECIMAL(12,3) | 默认载重kg | |
| default_load_volume | DECIMAL(12,3) | 默认体积m³ | |
| default_length | DECIMAL(10,3) | 默认车厢长m | |
| default_width | DECIMAL(10,3) | 默认车厢宽m | |
| default_height | DECIMAL(10,3) | 默认车厢高m | |

7.2 vs_vehicle - 车辆档案表

表职责：车辆管理主表，供调度、费用、证照、维保关联。

|------------------------|---------------|----------------------------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_code | VARCHAR(64) | 车辆编码 | UK |
| plate_no | VARCHAR(32) | 车牌号 | UK |
| vehicle_type_id | BIGINT | 车型ID=vs_vehicle_type.id | IDX |
| vehicle_name | VARCHAR(100) | 车辆名称/简称 | |
| vin | VARCHAR(64) | 车架号VIN | IDX |
| engine_no | VARCHAR(64) | 发动机号 | |
| brand | VARCHAR(100) | 品牌 | |
| model | VARCHAR(100) | 型号 | |
| load_weight | DECIMAL(12,3) | 核定载重kg | |
| load_volume | DECIMAL(12,3) | 核定体积m³ | |
| vehicle_length | DECIMAL(10,3) | 车厢长m | |
| vehicle_width | DECIMAL(10,3) | 车厢宽m | |
| vehicle_height | DECIMAL(10,3) | 车厢高m | |
| temperature_type | TINYINT | 温控类型 | IDX |
| belong_company_id | BIGINT | 所属公司/组织 | IDX |
| workhouse_id | BIGINT | 默认所属仓库 | IDX |
| current_mileage | DECIMAL(12,2) | 当前里程 | |
| use_status | TINYINT | 使用状态：1可用 2占用 3维修 4停用 5限制派车 | IDX |
| inspection_expire_date | BIGINT | 年检到期时间 | IDX |
| insurance_expire_date | BIGINT | 保险到期时间 | IDX |

7.3 vs_driver - 司机档案表

表职责：维护司机资料、准驾车型、证件有效期与启用状态。

|-------------------------|--------------|------------------------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| driver_code | VARCHAR(64) | 司机编码 | UK |
| driver_name | VARCHAR(100) | 司机姓名 | IDX |
| mobile | VARCHAR(32) | 手机号 | IDX |
| id_card_no | VARCHAR(64) | 身份证号，可加密/脱敏 | |
| driver_license_no | VARCHAR(64) | 驾驶证号 | IDX |
| license_class | VARCHAR(20) | 准驾车型 | |
| license_expire_date | BIGINT | 驾驶证到期时间 | IDX |
| health_cert_no | VARCHAR(64) | 健康证/从业证编号 | |
| health_cert_expire_date | BIGINT | 健康证/从业证到期时间 | IDX |
| driver_status | TINYINT | 司机状态：1可用 2请假 3停用 4限制派车 | IDX |

7.4 vs_driver_vehicle - 司机车辆绑定表

表职责：维护司机与车辆的主驾、副驾、临时绑定关系。

|-------------|---------|------------------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| driver_id | BIGINT | 司机ID | IDX |
| bind_type | TINYINT | 绑定类型：1主驾 2副驾 3临时 | IDX |
| start_time | BIGINT | 生效时间 | |
| end_time | BIGINT | 失效时间 | |
| bind_status | TINYINT | 绑定状态：1有效 2失效 | IDX |

7.5 vs_vehicle_certificate - 车辆证照表

表职责：维护行驶证、道路运输证、营运证、冷链资质等证照。

|------------------|--------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| certificate_type | TINYINT | 证照类型 | IDX |
| certificate_no | VARCHAR(100) | 证照编号 | |
| issue_org | VARCHAR(100) | 发证机构 | |
| start_date | BIGINT | 生效时间 | |
| expire_date | BIGINT | 到期时间 | IDX |
| file_url | VARCHAR(500) | 附件地址 | |
| warn_days | INT | 提前预警天数 | |
| warn_status | TINYINT | 预警状态 | IDX |

7.6 vs_vehicle_insurance - 车辆保险表

表职责：维护交强险、商业险、货运险、冷链险等保单。

|-------------------|---------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| insurance_type | TINYINT | 保险类型 | IDX |
| policy_no | VARCHAR(100) | 保单号 | UK |
| insurance_company | VARCHAR(100) | 保险公司 | |
| insured_amount | DECIMAL(12,2) | 保额 | |
| premium_amount | DECIMAL(12,2) | 保费 | |
| start_date | BIGINT | 生效时间 | |
| expire_date | BIGINT | 到期时间 | IDX |
| file_url | VARCHAR(500) | 保单附件 | |

7.7 vs_vehicle_annual_inspection - 车辆年检表

表职责：维护年检、环保检测、冷链设备校验记录。

|----------------------|---------------|-------------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| inspection_type | TINYINT | 检测类型 | IDX |
| inspection_date | BIGINT | 检测时间 | |
| next_inspection_date | BIGINT | 下次检测时间 | IDX |
| inspection_result | TINYINT | 结果：1通过 2不通过 | IDX |
| inspection_org | VARCHAR(100) | 检测机构 | |
| fee_amount | DECIMAL(12,2) | 检测费用 | |
| file_url | VARCHAR(500) | 附件 | |

7.8 vs_vehicle_maintenance_plan - 车辆保养计划表

表职责：按时间/里程生成保养提醒。

|--------------|---------------|-----------------------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| plan_name | VARCHAR(100) | 计划名称 | |
| plan_type | TINYINT | 计划类型：1按日期 2按里程 | IDX |
| plan_date | BIGINT | 计划保养日期 | IDX |
| plan_mileage | DECIMAL(12,2) | 计划保养里程 | |
| warn_days | INT | 提前预警天数 | |
| plan_status | TINYINT | 状态：0待提醒 1已提醒 2已完成 3取消 | IDX |

7.9 vs_vehicle_maintenance_record - 车辆保养记录表

表职责：登记保养项目、费用、里程、供应商。

|-------------------|---------------|-----------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| maintenance_date | BIGINT | 保养日期 | IDX |
| mileage | DECIMAL(12,2) | 保养时里程 | |
| maintenance_items | VARCHAR(500) | 保养项目 | |
| supplier_id | BIGINT | 供应商/维修厂ID | |
| fee_amount | DECIMAL(12,2) | 保养费用 | |
| next_mileage | DECIMAL(12,2) | 下次保养里程 | |
| next_date | BIGINT | 下次保养日期 | IDX |
| file_url | VARCHAR(500) | 附件 | |

7.10 vs_vehicle_repair_record - 车辆维修记录表

表职责：登记故障、维修项目、费用、停运信息。

|---------------|---------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| repair_no | VARCHAR(64) | 维修单号 | UK |
| fault_desc | VARCHAR(500) | 故障描述 | |
| repair_date | BIGINT | 维修日期 | IDX |
| repair_org | VARCHAR(100) | 维修机构 | |
| fee_amount | DECIMAL(12,2) | 维修费用 | |
| stop_days | DECIMAL(8,2) | 停运天数 | |
| repair_status | TINYINT | 维修状态 | IDX |
| file_url | VARCHAR(500) | 附件 | |

7.11 vs_vehicle_fuel_record - 车辆加油/充电记录表

表职责：记录油量/电量、单价、金额、里程，支持油耗统计。

|--------------|---------------|---------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| driver_id | BIGINT | 司机ID | IDX |
| record_type | TINYINT | 1加油 2充电 | IDX |
| fuel_date | BIGINT | 加油/充电时间 | IDX |
| quantity | DECIMAL(12,3) | 数量：升/度 | |
| unit_price | DECIMAL(12,3) | 单价 | |
| amount | DECIMAL(12,2) | 金额 | |
| mileage | DECIMAL(12,2) | 当前里程 | |
| station_name | VARCHAR(100) | 油站/充电站 | |

7.12 vs_vehicle_mileage_record - 车辆里程记录表

表职责：记录出车、回车、人工调整里程。

|----------------|---------------|---------------------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| driver_id | BIGINT | 司机ID | IDX |
| source_type | TINYINT | 来源：1出车 2回车 3手工 4GPS | IDX |
| source_no | VARCHAR(100) | 来源单号 | IDX |
| before_mileage | DECIMAL(12,2) | 变更前里程 | |
| after_mileage | DECIMAL(12,2) | 变更后里程 | |
| change_mileage | DECIMAL(12,2) | 本次里程 | |
| record_time | BIGINT | 记录时间 | IDX |

7.13 vs_vehicle_expense - 车辆费用表

表职责：统一归集油费、维修、保养、保险、停车、过路、违章等费用。

|--------------|---------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| driver_id | BIGINT | 司机ID | IDX |
| expense_type | TINYINT | 费用类型 | IDX |
| source_type | TINYINT | 来源类型 | IDX |
| source_no | VARCHAR(100) | 来源单号 | IDX |
| expense_date | BIGINT | 费用日期 | IDX |
| amount | DECIMAL(12,2) | 费用金额 | |
| audit_status | TINYINT | 审核状态 | IDX |

7.14 vs_vehicle_violation - 车辆违章记录表

表职责：登记违章、扣分、罚款及处理状态。

|-----------------|---------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| driver_id | BIGINT | 司机ID | IDX |
| violation_time | BIGINT | 违章时间 | IDX |
| violation_place | VARCHAR(200) | 违章地点 | |
| violation_desc | VARCHAR(500) | 违章说明 | |
| deduct_points | DECIMAL(6,2) | 扣分 | |
| fine_amount | DECIMAL(12,2) | 罚款金额 | |
| handle_status | TINYINT | 处理状态 | IDX |

7.15 vs_vehicle_accident - 车辆事故记录表

表职责：登记事故责任、损失、理赔及处理进度。

|---------------------|---------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| driver_id | BIGINT | 司机ID | IDX |
| accident_time | BIGINT | 事故时间 | IDX |
| accident_place | VARCHAR(200) | 事故地点 | |
| responsibility_type | TINYINT | 责任类型 | |
| loss_amount | DECIMAL(12,2) | 损失金额 | |
| claim_amount | DECIMAL(12,2) | 理赔金额 | |
| handle_status | TINYINT | 处理状态 | IDX |
| file_url | VARCHAR(500) | 附件 | |

7.16 vs_vehicle_gps_device - 车辆GPS设备表

表职责：维护GPS设备/SIM卡/平台绑定信息。

|---------------|--------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| device_no | VARCHAR(100) | 设备编号 | UK |
| sim_no | VARCHAR(100) | SIM卡号 | |
| platform_name | VARCHAR(100) | 平台名称 | |
| bind_time | BIGINT | 绑定时间 | |
| device_status | TINYINT | 设备状态 | IDX |

7.17 vs_vehicle_track_log - 车辆轨迹日志表

表职责：保存任务相关轨迹摘要或低频轨迹点。

|--------------|---------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| task_no | VARCHAR(100) | 配送任务号 | IDX |
| longitude | DECIMAL(12,6) | 经度 | |
| latitude | DECIMAL(12,6) | 纬度 | |
| speed | DECIMAL(10,2) | 速度 | |
| direction | VARCHAR(50) | 方向 | |
| collect_time | BIGINT | 采集时间 | IDX |

7.18 vs_vehicle_temperature_log - 冷链温度日志表

表职责：记录冷链车辆温度上报和超温状态。

|--------------|--------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | IDX |
| task_no | VARCHAR(100) | 配送任务号 | IDX |
| temperature | DECIMAL(8,2) | 温度 | |
| zone_no | VARCHAR(50) | 温区编号 | |
| alarm_flag | TINYINT | 是否超温 | IDX |
| collect_time | BIGINT | 采集时间 | IDX |

7.19 vs_vehicle_availability - 车辆可用状态表

表职责：维护车辆当前可派、占用、维修、停用、限制派车等状态。

|-------------------|--------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| vehicle_id | BIGINT | 车辆ID | UK |
| current_status | TINYINT | 当前状态 | IDX |
| occupied_task_no | VARCHAR(100) | 占用任务号 | IDX |
| status_reason | VARCHAR(255) | 状态原因 | |
| start_time | BIGINT | 状态开始时间 | |
| end_time | BIGINT | 预计结束时间 | |
| last_refresh_time | BIGINT | 最后刷新时间 | |

7.20 vs_vehicle_dispatch_ref - 车辆配送任务关联表

表职责：记录车辆与配送任务的关联、出车、回车和任务结果。

|-----------------|---------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| dispatch_no | VARCHAR(100) | 配送任务号 | IDX |
| vehicle_id | BIGINT | 车辆ID | IDX |
| driver_id | BIGINT | 司机ID | IDX |
| route_id | BIGINT | 线路ID | IDX |
| start_time | BIGINT | 出车时间 | |
| return_time | BIGINT | 回车时间 | |
| start_mileage | DECIMAL(12,2) | 出车里程 | |
| return_mileage | DECIMAL(12,2) | 回车里程 | |
| dispatch_status | TINYINT | 任务状态 | IDX |

7.21 vs_vehicle_operate_log - 车辆操作日志表

表职责：记录关键操作：新增、修改、启停、派车、回车、证照更新等。

|---------------|--------------|--------|----------|
| 字段名 | 类型 | 说明 | 键/索引 |
| biz_type | VARCHAR(64) | 业务类型 | IDX |
| biz_id | BIGINT | 业务ID | IDX |
| operate_type | VARCHAR(64) | 操作类型 | IDX |
| before_json | JSON | 操作前数据 | |
| after_json | JSON | 操作后数据 | |
| operator_id | BIGINT | 操作人ID | IDX |
| operator_name | VARCHAR(100) | 操作人姓名 | |
| operate_time | BIGINT | 操作时间 | IDX |

8. 后端 API 与 Service 设计

后端按升鲜宝模块目录结构组织：vs/controller、vs/service、vs/service/impl、vs/dao、vs/entity、vs/req、vs/resp、vs/xml。Service 接口负责业务编排，Dao/XML 负责查询与统计，Controller 负责权限、入参、返回。

|------------------------------|-----------------------|------------------------------|
| Service | 职责 | 接口前缀 |
| VsVehicleTypeService | 车辆类型 CRUD、启停、默认容量模板 | /api/admin/vs/vehicle-type |
| VsVehicleService | 车辆档案 CRUD、状态变更、证照到期摘要 | /api/admin/vs/vehicle |
| VsDriverService | 司机档案 CRUD、驾驶证有效期校验 | /api/admin/vs/driver |
| VsDriverVehicleService | 司机车辆绑定、解绑、主驾设置 | /api/admin/vs/driver-vehicle |
| VsVehicleCertificateService | 车辆证照维护与到期预警 | /api/admin/vs/certificate |
| VsVehicleInsuranceService | 保险管理、到期预警、费用生成 | /api/admin/vs/insurance |
| VsVehicleMaintenanceService | 保养计划、保养记录、保养提醒 | /api/admin/vs/maintenance |
| VsVehicleRepairService | 维修记录、停运状态联动 | /api/admin/vs/repair |
| VsVehicleFuelService | 加油/充电记录、油耗计算 | /api/admin/vs/fuel |
| VsVehicleExpenseService | 车辆费用归集、费用审核、导出 | /api/admin/vs/expense |
| VsVehicleAvailabilityService | 车辆可用性查询、派车占用、释放 | /api/admin/vs/availability |
| VsVehicleDispatchRefService | 出车/回车记录、配送任务关联 | /api/admin/vs/dispatch-ref |
| VsVehicleReportService | 车辆运营报表、成本、里程、异常统计 | /api/admin/vs/report |

8.1 核心接口清单

|------------------------------------|--------|----------|-------------------------------|
| 接口 | 方法 | 说明 | 关键校验 |
| /api/admin/vs/vehicle/page | GET | 车辆分页查询 | 按车牌、车型、仓库、状态、证照到期筛选 |
| /api/admin/vs/vehicle | POST | 新增车辆 | 车牌唯一、车型存在、载重体积非负 |
| /api/admin/vs/vehicle | PUT | 修改车辆 | 已派车车辆限制修改关键字段 |
| /api/admin/vs/vehicle/{id} | DELETE | 删除车辆 | 存在未完成任务时不允许删除 |
| /api/admin/vs/vehicle/updateStatus | PUT | 启停车辆 | 停用时释放可用状态并禁止派车 |
| /api/admin/vs/availability/check | POST | 派车前可用性校验 | 车辆、司机、证照、容量、占用状态 |
| /api/admin/vs/availability/occupy | POST | 占用车辆 | 幂等校验 dispatch_no + vehicle_id |
| /api/admin/vs/availability/release | POST | 释放车辆 | 仅占用任务可释放 |
| /api/admin/vs/dispatch/start | POST | 出车确认 | 记录司机、车辆、任务、出车里程 |
| /api/admin/vs/dispatch/return | POST | 回车确认 | 回车里程不得小于出车里程 |
| /api/admin/vs/warn/expire | GET | 证照到期预警 | 按预警天数过滤 |
| /api/admin/vs/report/operation | GET | 运营报表 | 按车辆、司机、线路、日期统计 |

9. 前端页面与交互规范

前端沿用升鲜宝现有 Vue3 + Element Plus 写法：每个功能目录下一个列表页面 xxx.vue，一个新增/修改共用弹窗页面 xxx-add-or-update.vue。列表页使用 useView；新增/修改页使用 el-dialog、baseService、defineExpose({ init })。

|---------------------------------------------------|---------------|
| 目录/文件 | 说明 |
| src/views/vs/vehicle.vue | 车辆档案列表页 |
| src/views/vs/vehicle-add-or-update.vue | 车辆档案新增/修改弹窗 |
| src/views/vs/driver.vue | 司机档案列表页 |
| src/views/vs/driver-add-or-update.vue | 司机档案新增/修改弹窗 |
| src/views/vs/vehiclemaintenance.vue | 保养记录列表页 |
| src/views/vs/vehiclemaintenance-add-or-update.vue | 保养记录新增/修改弹窗 |
| src/api/vs/vehicle.ts | 车辆档案 API 封装 |
| src/router/modules/vs.ts | 车辆管理静态路由或路由片段 |

前端列表字段展示要求：涉及 ID 的字段，列表优先显示名称，如 vehicleId 显示 plateNo 或 vehicleName；driverId 显示 driverName；workhouseId 显示 workhouseName；vehicleTypeId 显示 vehicleTypeName。ID 字段可保留为隐藏字段或辅助列。

10. 状态枚举与业务规则

|------------------|----------------------------------|--------------|
| 枚举 | 值 | 说明 |
| use_status | 1可用 2占用 3维修 4停用 5限制派车 | 车辆当前使用状态 |
| driver_status | 1可用 2请假 3停用 4限制派车 | 司机当前状态 |
| temperature_type | 0常温 1冷藏 2冷冻 3多温区 | 车辆温控类型 |
| bind_type | 1主驾 2副驾 3临时 | 司机车辆绑定类型 |
| certificate_type | 1行驶证 2运输证 3营运证 4冷链资质 | 车辆证照类型 |
| expense_type | 1油费 2维修 3保养 4保险 5违章 6停车 7过路 99其他 | 车辆费用类型 |
| dispatch_status | 0待出车 1已出车 2已回车 3异常 4取消 | 出车/回车状态 |
| warn_status | 0未预警 1即将到期 2已到期 3已处理 | 证照/保险/年检预警状态 |

同一车牌 plate_no 在未删除数据中必须唯一。
车辆存在未完成 dispatch_ref 时，不允许停用、删除或修改车型/载重/体积等关键字段。
驾驶证、保险、年检、营运证过期时，车辆或司机应进入限制派车状态。
车辆占用与释放必须使用 dispatch_no 做幂等，避免重复出车或重复释放。
维修开始后车辆状态变更为维修，维修完成后根据原占用情况恢复可用或占用。
回车里程必须大于等于出车里程；里程变更必须写入 vs_vehicle_mileage_record。
费用记录来源于保养、维修、保险、加油、违章时，要写 source_type/source_no 便于追溯。

11. 与配送/OMS/WMS/财务的集成

|---------|---------------|------------------|----------------|
| 集成点 | 调用方向 | 数据内容 | 说明 |
| 配送排车 | 配送模块 → VS | 车辆可用性、容量、司机、证照状态 | 排车前必须调用可用性校验。 |
| 出库装车 | WMS/配送 → VS | 出库任务、车辆、司机、装车时间 | 记录车辆与装车任务关联。 |
| OMS订单 | OMS → 配送 → VS | 配送任务号、客户、线路、重量体积 | VS不直接改订单。 |
| 财务费用 | VS → FIN | 车辆费用、油费、维修费、保险费 | 费用审核后可推送财务。 |
| 消息提醒 | VS → MSG | 证照到期、保险到期、维保提醒 | 推送物流主管和司机。 |
| GPS平台 | 外部平台 → VS | 定位、里程、温度、告警 | 可异步接入，避免高频写主库。 |

12. 非功能要求

性能：车辆档案、可用性查询、状态看板接口应支持分页和索引命中。
安全：身份证号、驾驶证号等敏感字段在列表页应脱敏显示，导出需权限控制。
审计：车辆启停、证照修改、派车占用、回车确认、费用审核必须记录操作日志。
缓存：车辆类型、状态字典、证照预警阈值可缓存；车辆可用状态建议读库为准。
幂等：出车、回车、占用、释放、费用生成均需业务幂等键。
数据权限：按组织、仓库、线路控制车辆与司机可见范围。
导出：车辆档案、费用、维保、违章事故导出应进入导出任务中心。

13. 开发优先级与验收标准

|----------|------------------------------|----------------------|
| 阶段 | 建设内容 | 验收标准 |
| 第一期：基础可用 | 车辆类型、车辆档案、司机档案、司机车辆绑定、车辆可用状态 | 调度员能维护车辆司机，并查询可派车辆。 |
| 第二期：合规预警 | 证照、保险、年检、驾驶证到期提醒 | 到期前自动预警，到期后限制派车。 |
| 第三期：调度联动 | 派车前校验、出车、回车、车辆占用释放 | 配送任务能占用车辆，回车后恢复可用。 |
| 第四期：维保费用 | 保养、维修、加油、里程、车辆费用 | 能按车辆统计里程、油耗和成本。 |
| 第五期：异常安全 | 违章、事故、冷链温度、GPS设备 | 能记录事故违章和冷链超温告警。 |
| 第六期：报表分析 | 车辆运营报表、成本分析、利用率分析 | 物流主管能按车辆/司机/线路看运营数据。 |

13.1 验收清单

新增车辆时，车牌号唯一校验生效。
车辆停用后，配送调度不能选择该车辆。
车辆保险/年检/证照过期后，车辆进入限制派车状态或返回不可派原因。
司机驾驶证过期后，不能参与派车。
车辆出车后状态变为占用，回车后自动释放。
回车里程更新车辆当前里程，并写入里程流水。
保养、维修、加油能生成车辆费用或可被车辆费用汇总。
所有关键操作都有操作日志。
列表页显示车辆名称、车牌、司机姓名、仓库名称，不只显示ID。
导出、删除、启停、费用审核均受按钮权限控制。

14. 附录：建议目录结构与命名规范

后端建议作为升鲜宝主项目中的 vs 业务子目录，结构参考 b2bmall 模块口径：

|-----------------|-------------------|
| 目录 | 说明 |
| vs/controller | 后台与业务端 Controller |
| vs/service | Service 接口 |
| vs/service/impl | ServiceImpl 实现类 |
| vs/dao | Mapper/Dao 接口 |
| vs/entity | 数据库实体 |
| vs/req | 请求入参 Req 对象 |
| vs/resp | 返回 Resp 对象 |
| vs/enums | 状态枚举 |
| vs/constant | 常量 |
| vs/converter | 对象转换器 |
| vs/xml | MyBatis XML |

前端目录建议：src/views/vs、src/api/vs、src/router/modules/vs.ts。每个功能页面保持升鲜宝原有写法：一个列表页面 xxx.vue，一个新增/修改共用弹窗页面 xxx-add-or-update.vue。