From 33005c8bf998104acaa057f1ceddb9ac74a846fb Mon Sep 17 00:00:00 2001 From: zch Date: Mon, 27 Apr 2026 12:38:53 +0800 Subject: [PATCH] =?UTF-8?q?change(=E8=BD=A6=E8=BE=86=E7=94=9F=E5=91=BD?= =?UTF-8?q?=E5=91=A8=E6=9C=9F):=20=E5=AE=8C=E5=96=84=E9=A2=86=E5=9F=9F?= =?UTF-8?q?=E5=AF=B9=E8=B1=A1=E5=8F=8A=E6=9C=8D=E5=8A=A1=E7=9A=84=E6=B3=A8?= =?UTF-8?q?=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补充车辆生命周期相关DTO、Mapper和Service的详细注释，包括： 1. 各DTO字段的业务含义和使用场景 2. Mapper接口的查询逻辑和权限控制说明 3. Service层的校验流程和聚合查询策略 --- .../system/domain/CarCheckLifecycleDTO.java | 25 +++- .../ruoyi/system/domain/CarLifecycleDTO.java | 20 +++- .../system/domain/CarLifecycleEventDTO.java | 50 +++++++- .../system/domain/CarLifecycleQuery.java | 22 +++- .../system/domain/CarLifecycleSummaryDTO.java | 25 +++- .../domain/CarMaintenanceLifecycleDTO.java | 27 ++++- .../system/domain/CarMileageLifecycleDTO.java | 21 +++- .../system/domain/CarMountedTyreDTO.java | 22 +++- .../domain/CarTyreInstallLifecycleDTO.java | 28 ++++- .../system/mapper/BaseCarLifecycleMapper.java | 113 ++++++++++++++++++ .../impl/BaseCarLifecycleServiceImpl.java | 86 ++++++++++++- 11 files changed, 421 insertions(+), 18 deletions(-) diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarCheckLifecycleDTO.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarCheckLifecycleDTO.java index 465858f0..7596334a 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarCheckLifecycleDTO.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarCheckLifecycleDTO.java @@ -4,21 +4,44 @@ import java.io.Serializable; import java.util.Date; /** - * 车辆生命周期关联轮胎质检记录。 + * 车辆生命周期关联轮胎质检记录DTO。 + *

+ * 用于“车辆全生命周期”弹窗中【巡检/质检记录】Tab页的数据展示。 + * 车辆与质检记录无直接外键，数据通过“该车曾装过的轮胎”间接关联 record_check 表获取。 + *

*/ public class CarCheckLifecycleDTO implements Serializable { private static final long serialVersionUID = 1L; + /** 质检记录主键ID，对应 record_check.id。 */ private Long id; + + /** 轮胎RFID编码，唯一标识一条轮胎实物。 */ private String tyreRfid; + + /** 轮胎自编号（轮胎编号），业务展示用。 */ private String tyreNo; + + /** 轮胎品牌，例如：米其林、普利司通等。 */ private String tyreBrand; + + /** 轮胎规格型号，例如：295/80R22.5。 */ private String tyreModel; + + /** 质检结果，例如：合格、不合格、建议更换等字典值。 */ private String result; + + /** 质检时的维保类型/检测类型，例如：一级保养、二级保养、日常巡检。 */ private String maintenanceType; + + /** 质检时记录的行驶里程（字符串形式保留原始录入值）。 */ private String mileage; + + /** 质检时测量的花纹深度（毫米），用于评估轮胎磨损程度。 */ private String patternDepth; + + /** 质检记录创建时间，即质检实际发生时间。 */ private Date createTime; public Long getId() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleDTO.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleDTO.java index e9439b9c..d7787117 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleDTO.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleDTO.java @@ -5,24 +5,36 @@ import java.util.ArrayList; import java.util.List; /** - * 车辆生命周期聚合报表。 + * 车辆生命周期聚合报表DTO。 + *

+ * 作为车辆全生命周期弹窗“首屏”的统一返回对象，承载车辆概要、当前装车轮胎快照、 + * 最近事件时间线以及各维度记录总数量。各明细列表（装卸、维保、质检、里程） + * 通过独立分页接口按需加载，避免首屏返回数据量过大导致性能问题。 + *

*/ public class CarLifecycleDTO implements Serializable { private static final long serialVersionUID = 1L; - /** 车辆主档概要，用于弹窗头部确认当前报表对象。 */ + /** 车辆主档概要，用于弹窗头部确认当前报表对象。包含车牌号、所属车队、线路、车型及最近录入里程。 */ private CarLifecycleSummaryDTO car; - /** 当前装车轮胎快照，数量较少，随概要一次返回。 */ + /** 当前装车轮胎快照，数量较少（通常不超过车辆轮位数），随概要一次返回用于首屏快速展示。 */ private List mountedTyres = new ArrayList<>(); - /** 最近事件时间线，用于快速定位最新装卸或维保动作。 */ + /** 最近事件时间线，聚合装卸与维保两类关键事件，按时间倒序排列，用于快速定位最新动作。 */ private List recentEvents = new ArrayList<>(); + /** 该车辆历史轮胎装卸记录总条数，用于前端分页组件初始化总页数。 */ private Integer installCount; + + /** 该车辆关联维保工单总条数，用于前端分页组件初始化总页数。 */ private Integer maintenanceCount; + + /** 该车辆关联轮胎质检记录总条数，用于前端分页组件初始化总页数。 */ private Integer checkCount; + + /** 该车辆关联轮胎里程记录总条数，用于前端分页组件初始化总页数。 */ private Integer mileageCount; public CarLifecycleSummaryDTO getCar() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleEventDTO.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleEventDTO.java index 853ddbe8..b26edae6 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleEventDTO.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleEventDTO.java @@ -5,33 +5,81 @@ import java.math.BigDecimal; import java.util.Date; /** - * 车辆生命周期统一事件。 + * 车辆生命周期统一事件DTO。 + *

+ * 作为“最近事件时间线”的数据载体，将轮胎装卸事件与维保工单事件抽象为统一结构， + * 便于前端以同一套模板按时间轴展示。事件类型（eventType）区分数据来源： + * INSTALL 表示轮胎装卸动作，MAINTENANCE 表示维保工单动作。 + *

*/ public class CarLifecycleEventDTO implements Serializable { private static final long serialVersionUID = 1L; + /** 事件类型字典值，区分数据来源。例如：INSTALL（轮胎装卸）、MAINTENANCE（维保工单）。 */ private String eventType; + + /** 事件发生时间，统一取各来源表中的操作/创建时间，用于时间轴排序。 */ private Date eventTime; + + /** 轮胎RFID编码，仅在事件类型为轮胎装卸时有效。 */ private String tyreRfid; + + /** 轮胎编号，业务展示用。 */ private String tyreNo; + + /** 轮胎自编号，与 tyreNo 区分，用于内部管理。 */ private String selfNo; + + /** 轮胎品牌。 */ private String tyreBrand; + + /** 轮胎规格型号。 */ private String tyreModel; + + /** 轮位名称，例如：左前轮、右后第二轴等，仅在装卸事件中有效。 */ private String wheelPostion; + + /** 事件关联的行驶里程（字符串形式，保留原始录入格式）。 */ private String mileage; + + /** 事件关联的花纹深度（毫米），用于磨损评估。 */ private String patternDepth; + + /** 状态字典值，例如：工单状态、轮胎状态等，视 eventType 而定。 */ private String status; + + /** 工单编号，仅在事件类型为维保工单时有效。 */ private String orderNo; + + /** 类型编码，例如：维保类型字典值、操作类型字典值。 */ private String typeCode; + + /** 修理厂/工厂名称，仅在维保工单事件中有效。 */ private String factoryName; + + /** 录入里程（数值型），维保工单或质检记录中由用户录入的当前总里程。 */ private BigDecimal inputMileage; + + /** 上次里程（数值型），维保工单中记录的上一次保养时的里程。 */ private BigDecimal lastMileage; + + /** 保养/维修日期，维保工单事件中的计划或实际执行日期。 */ private Date maintainDate; + + /** 事件描述/故障描述，维保工单中的故障现象或备注信息。 */ private String description; + + /** 质检结果，仅在轮胎质检相关事件中有效。 */ private String result; + + /** 维保/检测类型字典值，例如：一级保养、二级保养、日常巡检。 */ private String maintenanceType; + + /** 轮胎里程记录开始时间，仅在里程类事件中有效。 */ private Date startTime; + + /** 轮胎里程记录结束时间，仅在里程类事件中有效。 */ private Date endTime; public String getEventType() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleQuery.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleQuery.java index 7627b65b..439d287f 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleQuery.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleQuery.java @@ -4,15 +4,33 @@ import com.ruoyi.common.core.domain.BaseEntity; /** * 车辆生命周期查询参数。 + *

+ * 继承若依通用基础实体 {@link BaseEntity}，天然支持分页参数（pageNum / pageSize） + * 以及标准的数据权限字段（deptAlias / userAlias）。 + * 本查询对象同时作为“权限校验载体”与“子查询条件载体”： + * 入口以 carNo 做初步过滤，校验通过后由 Service 层回填 carId，后续子查询优先使用 carId 做精确匹配，提升性能并避免字符串歧义。 + *

*/ public class CarLifecycleQuery extends BaseEntity { private static final long serialVersionUID = 1L; - /** 车牌号是生命周期报表的唯一入口，避免前端绕过车辆主档直接查历史流水。 */ + /** + * 车牌号，生命周期报表的唯一业务入口。 + *

+ * 前端弹窗以车牌号为路径参数或查询参数传入，Service 层先通过该字段定位车辆主档， + * 并完成数据权限校验。不允许为空，且长度受数据库字段限制（varchar(50)）。 + *

+ */ private String carNo; - /** 车辆主键只用于一致性展示和派生查询，不作为跨表唯一业务关联。 */ + /** + * 车辆主键ID，由 Service 层在权限校验后自动回填。 + *

+ * 不作为前端传入参数，仅用于后续子查询（装卸、维保、质检、里程）中做精确关联， + * 避免跨表仅依赖字符串车牌号可能导致的性能与一致性问题。 + *

+ */ private Long carId; public String getCarNo() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleSummaryDTO.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleSummaryDTO.java index ee413ed7..70848bc6 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleSummaryDTO.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleSummaryDTO.java @@ -4,20 +4,41 @@ import java.io.Serializable; import java.math.BigDecimal; /** - * 车辆生命周期头部概要。 + * 车辆生命周期头部概要DTO。 + *

+ * 作为弹窗顶部的“车辆名片”数据，展示用户最关心的车辆静态属性与最近动态指标。 + * 所有字段均来自 base_car 主档及其关联字典/部门表，通过 {@link BaseCarLifecycleMapper#selectLifecycleCar} 一次性查询返回。 + *

*/ public class CarLifecycleSummaryDTO implements Serializable { private static final long serialVersionUID = 1L; + /** 车辆主键ID，base_car 表的唯一标识，用于后续子查询精确关联。 */ private Long carId; + + /** 车牌号，车辆的唯一业务标识，例如：粤B12345。 */ private String carNo; + + /** 所属部门ID，关联 sys_dept，用于数据权限过滤。 */ private Long deptId; + + /** 所属车队名称，由部门ID关联翻译而来，前端直接展示。 */ private String team; + + /** 线路名称，车辆运营的公交/客运线路。 */ private String line; + + /** 车型，例如：纯电动大巴、混合动力公交等字典值。 */ private String type; - /** 最近工单录入里程只作为展示快照，避免字符串里程直接参与统计。 */ + /** + * 最近工单录入里程。 + *

+ * 取自该车辆最近一次维保工单中的 input_mileage 字段，仅作为弹窗头部的展示快照。 + * 使用 BigDecimal 类型避免浮点精度问题，但不参与聚合统计，防止不同工单录入口径差异导致统计失真。 + *

+ */ private BigDecimal inputMileage; public Long getCarId() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMaintenanceLifecycleDTO.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMaintenanceLifecycleDTO.java index 3bd62e96..d446035b 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMaintenanceLifecycleDTO.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMaintenanceLifecycleDTO.java @@ -5,22 +5,47 @@ import java.math.BigDecimal; import java.util.Date; /** - * 车辆生命周期维保工单记录。 + * 车辆生命周期维保工单记录DTO。 + *

+ * 用于“车辆全生命周期”弹窗中【维保工单记录】Tab页的数据展示。 + * 数据来源为 biz_maintenance_order 表，通过 plate_number（车牌号）直接与车辆关联，无需额外表桥接。 + *

*/ public class CarMaintenanceLifecycleDTO implements Serializable { private static final long serialVersionUID = 1L; + /** 工单主键ID，对应 biz_maintenance_order.order_id。 */ private Long orderId; + + /** 工单编号，业务展示的唯一编号，例如：WB202401150001。 */ private String orderNo; + + /** 车辆ID，对应工单表中的 vehicle_id 外键（若存在）。 */ private Long vehicleId; + + /** 车牌号，工单中直接记录的车牌号，用于与车辆主档确认关联。 */ private String plateNumber; + + /** 维保类型编码，字典值，例如：一级保养、二级保养、小修、大修。 */ private String typeCode; + + /** 工单状态编码，字典值，例如：待派工、维修中、已完成、已结算。 */ private String status; + + /** 录入里程，本次维保/保养时车辆的总行驶里程（数值型）。 */ private BigDecimal inputMileage; + + /** 上次里程，上一次保养时记录的里程，用于计算两次保养间的行驶距离。 */ private BigDecimal lastMileage; + + /** 保养/维修日期，工单的计划或实际执行日期。 */ private Date maintainDate; + + /** 修理厂名称，执行本次维保的外部或内部修理厂。 */ private String factoryName; + + /** 故障描述/备注，记录车辆故障现象、维修内容或用户补充说明。 */ private String description; public Long getOrderId() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMileageLifecycleDTO.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMileageLifecycleDTO.java index d8d52dd3..8600a845 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMileageLifecycleDTO.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMileageLifecycleDTO.java @@ -4,19 +4,38 @@ import java.io.Serializable; import java.util.Date; /** - * 车辆生命周期关联轮胎里程记录。 + * 车辆生命周期关联轮胎里程记录DTO。 + *

+ * 用于“车辆全生命周期”弹窗中【轮胎里程快照】Tab页的数据展示。 + * 数据通过轮胎RFID间接关联车辆：先找到该车历史上装过的轮胎，再关联 record_tyre_mileage 表获取各轮胎的里程消耗记录。 + *

*/ public class CarMileageLifecycleDTO implements Serializable { private static final long serialVersionUID = 1L; + /** 里程记录主键ID，对应 record_tyre_mileage.id。 */ private Long id; + + /** 轮胎RFID编码，唯一标识轮胎实物，关联 record_tyre_mileage 中的轮胎标识。 */ private String tyreRfid; + + /** 轮胎编号，业务展示用。 */ private String tyreNo; + + /** 轮胎品牌。 */ private String tyreBrand; + + /** 里程统计开始时间，即该轮胎装车或本次统计周期的起始时间点。 */ private Date startTime; + + /** 里程统计结束时间，即该轮胎卸车或本次统计周期的结束时间点。 */ private Date endTime; + + /** 该统计周期内累计行驶里程（公里），数值型。 */ private Long mileage; + + /** 统计结束时的花纹深度（毫米），用于与起始深度对比评估磨损速率。 */ private String patternDepth; public Long getId() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMountedTyreDTO.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMountedTyreDTO.java index 2e99c351..0bdfe5c7 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMountedTyreDTO.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMountedTyreDTO.java @@ -3,19 +3,39 @@ package com.ruoyi.system.domain; import java.io.Serializable; /** - * 当前装车轮胎快照。 + * 当前装车轮胎快照DTO。 + *

+ * 用于“车辆全生命周期”弹窗首屏的【当前装车轮胎】区域展示。 + * 仅返回当前仍安装在该车辆上的轮胎列表（通常数量等于车辆轮位数）， + * 数据来源于 record_tyre_install 中该车辆最新一次安装且尚未卸下（或卸下时间最新但已重新装上）的轮胎记录。 + *

*/ public class CarMountedTyreDTO implements Serializable { private static final long serialVersionUID = 1L; + /** 轮胎主键ID，对应 base_tyre.id。 */ private Long tyreId; + + /** 轮胎编号，业务展示的唯一编号。 */ private String tyreNo; + + /** 轮胎自编号，与 tyreNo 区分，用于仓库或车队内部管理。 */ private String selfNo; + + /** 轮胎RFID/EPC编码，物联网识别标签，用于RFID读写器扫描匹配。 */ private String tyreEpc; + + /** 轮胎品牌，例如：米其林、固特异。 */ private String tyreBrand; + + /** 轮胎规格型号，例如：12R22.5、295/80R22.5。 */ private String tyreModel; + + /** 轮位名称，例如：左前转向轮、右后驱动轴第二轴等，指示轮胎安装在车辆的具体位置。 */ private String wheelPostion; + + /** 当前花纹深度（毫米），反映轮胎剩余磨损寿命，用于安全预警。 */ private String patternDepth; public Long getTyreId() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarTyreInstallLifecycleDTO.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarTyreInstallLifecycleDTO.java index 2e4ebdb6..abe4f335 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarTyreInstallLifecycleDTO.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/CarTyreInstallLifecycleDTO.java @@ -4,22 +4,48 @@ import java.io.Serializable; import java.util.Date; /** - * 车辆生命周期装卸记录。 + * 车辆生命周期装卸记录DTO。 + *

+ * 用于“车辆全生命周期”弹窗中【轮胎安装/卸胎记录】Tab页的数据展示。 + * 数据来源为 record_tyre_install 表，通过 car_no（车牌号）直接关联车辆， + * 展示该车辆历史上所有轮胎的安装与卸下动作，按操作时间倒序排列。 + *

*/ public class CarTyreInstallLifecycleDTO implements Serializable { private static final long serialVersionUID = 1L; + /** 装卸记录主键ID，对应 record_tyre_install.id。 */ private Long id; + + /** 轮胎RFID编码，唯一标识被操作的轮胎实物。 */ private String tyreRfid; + + /** 操作类型字典值，例如：INSTALL（安装）、UNINSTALL（卸下）、SWAP（换位）。 */ private String installType; + + /** 操作时的车辆行驶里程（公里），数值型，记录动作发生瞬间的车辆总里程。 */ private Long mileage; + + /** 操作发生时间，即装卸动作的实际执行时间/录入时间。 */ private Date createTime; + + /** 轮位名称，例如：左前轮、右后第二轴，指示轮胎安装或卸下的具体位置。 */ private String wheelPostion; + + /** 操作时的花纹深度（毫米），用于追溯轮胎在每次装卸时的磨损状态。 */ private String patternDepth; + + /** 轮胎编号，被操作轮胎的业务展示编号。 */ private String tyreNo; + + /** 轮胎自编号，被操作轮胎的内部管理编号。 */ private String selfNo; + + /** 轮胎品牌。 */ private String tyreBrand; + + /** 轮胎规格型号。 */ private String tyreModel; public Long getId() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/mapper/BaseCarLifecycleMapper.java b/ruoyi-system/src/main/java/com/ruoyi/system/mapper/BaseCarLifecycleMapper.java index 59f3cb3a..94d35571 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/mapper/BaseCarLifecycleMapper.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/mapper/BaseCarLifecycleMapper.java @@ -12,28 +12,141 @@ import com.ruoyi.system.domain.CarTyreInstallLifecycleDTO; /** * 车辆全生命周期报表Mapper接口。 + *

+ * 承担车辆全生命周期弹窗所需的所有数据持久化查询职责。 + * 设计原则： + * 1. 以车牌号（carNo）为入口，通过 join sys_dept 等权限表支持 {@link DataScope} 拦截； + * 2. 首屏概要（selectLifecycleCar / selectMountedTyres / selectRecentEvents / count*）与明细分页（select*List）分离，避免大数据量拖慢首屏； + * 3. 各子查询优先使用回填后的 carId 做精确过滤，提升性能并减少字符串匹配歧义。 + *

*/ public interface BaseCarLifecycleMapper { + /** + * 查询车辆主档概要及最近录入里程。 + *

+ * SQL 需 join sys_dept 并预留 d/u 别名，供 {@link DataScope} 拦截器拼接部门/用户权限条件。 + * 若查询无结果，Service 层统一提示“车辆不存在或无权限访问”，防止接口探测攻击。 + *

+ * + * @param query 包含 carNo 的查询参数 + * @return 车辆概要DTO；无权限或不存在时返回 null + */ public CarLifecycleSummaryDTO selectLifecycleCar(CarLifecycleQuery query); + /** + * 查询车辆当前装车轮胎快照。 + *

+ * 仅返回当前仍安装在该车上的轮胎列表，数量通常较少（<= 车辆轮位数），随首屏一起返回。 + * 逻辑上取该车辆各轮位最近一次 installType='INSTALL' 且未后续卸下的记录。 + *

+ * + * @param query 已回填 carId 的查询参数 + * @return 当前装车轮胎列表；无记录时返回空列表 + */ public List selectMountedTyres(CarLifecycleQuery query); + /** + * 查询车辆最近事件时间线（TopN）。 + *

+ * 聚合轮胎装卸记录与维保工单两类事件，取按时间倒序的最近 N 条（例如 10 条）。 + * 用于弹窗首屏快速展示最新动态，避免加载全量历史。 + *

+ * + * @param query 已回填 carId 的查询参数 + * @return 最近事件列表；无记录时返回空列表 + */ public List selectRecentEvents(CarLifecycleQuery query); + /** + * 分页查询车辆轮胎装卸历史明细。 + *

+ * 返回该车辆所有轮胎的安装、卸下、换位等操作记录，支持按操作时间倒序分页。 + * 需配合前端分页参数（pageNum / pageSize）使用。 + *

+ * + * @param query 已回填 carId 且携带分页参数的查询对象 + * @return 装卸记录列表；无记录时返回空列表 + */ public List selectInstallList(CarLifecycleQuery query); + /** + * 分页查询车辆维保工单历史明细。 + *

+ * 通过 plate_number = carNo 直接关联 biz_maintenance_order 表，返回维保工单列表。 + * 支持按保养日期（maintain_date）倒序分页。 + *

+ * + * @param query 已回填 carId 且携带分页参数的查询对象 + * @return 维保工单列表；无记录时返回空列表 + */ public List selectMaintenanceList(CarLifecycleQuery query); + /** + * 分页查询车辆关联轮胎质检历史明细。 + *

+ * 车辆与质检记录无直接外键，需通过“该车曾装过的轮胎RFID”间接关联 record_check 表。 + * SQL 中通常使用子查询或 join record_tyre_install 做中间桥接。 + *

+ * + * @param query 已回填 carId 且携带分页参数的查询对象 + * @return 质检记录列表；无记录时返回空列表 + */ public List selectCheckList(CarLifecycleQuery query); + /** + * 分页查询车辆关联轮胎里程历史明细。 + *

+ * 通过轮胎RFID间接关联 record_tyre_mileage 表，获取该车历史上装过的各轮胎的里程记录。 + * 展示各轮胎在不同装车周期内的起止时间与累计行驶里程。 + *

+ * + * @param query 已回填 carId 且携带分页参数的查询对象 + * @return 轮胎里程记录列表；无记录时返回空列表 + */ public List selectMileageList(CarLifecycleQuery query); + /** + * 统计该车辆轮胎装卸记录总条数。 + *

+ * 用于弹窗首屏返回 installCount，供前端分页组件计算总页数。 + *

+ * + * @param query 已回填 carId 的查询参数 + * @return 装卸记录总条数；无记录时返回 0 + */ public int countInstallRecords(CarLifecycleQuery query); + /** + * 统计该车辆维保工单总条数。 + *

+ * 用于弹窗首屏返回 maintenanceCount，供前端分页组件计算总页数。 + *

+ * + * @param query 已回填 carId 的查询参数 + * @return 维保工单总条数；无记录时返回 0 + */ public int countMaintenanceOrders(CarLifecycleQuery query); + /** + * 统计该车辆关联轮胎质检记录总条数。 + *

+ * 用于弹窗首屏返回 checkCount，供前端分页组件计算总页数。 + *

+ * + * @param query 已回填 carId 的查询参数 + * @return 质检记录总条数；无记录时返回 0 + */ public int countCheckRecords(CarLifecycleQuery query); + /** + * 统计该车辆关联轮胎里程记录总条数。 + *

+ * 用于弹窗首屏返回 mileageCount，供前端分页组件计算总页数。 + *

+ * + * @param query 已回填 carId 的查询参数 + * @return 里程记录总条数；无记录时返回 0 + */ public int countMileageRecords(CarLifecycleQuery query); } diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/service/impl/BaseCarLifecycleServiceImpl.java b/ruoyi-system/src/main/java/com/ruoyi/system/service/impl/BaseCarLifecycleServiceImpl.java index 8ee44c72..beafbb06 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/service/impl/BaseCarLifecycleServiceImpl.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/service/impl/BaseCarLifecycleServiceImpl.java @@ -18,6 +18,11 @@ import org.springframework.stereotype.Service; /** * 车辆全生命周期报表Service业务层处理。 + *

+ * 本服务以车牌号（carNo）为唯一入口，通过 {@link #buildAuthorizedCar(CarLifecycleQuery)} 完成： + * 1）参数校验；2）车辆存在性与数据权限校验；3）将 carId 回写到查询对象中，供后续聚合查询复用。 + * 所有对外查询方法均标注 {@link DataScope}，确保与车辆列表页（system:car:view）保持一致的部门/用户权限过滤。 + *

*/ @Service public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService @@ -27,6 +32,18 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService /** * 查询车辆生命周期概要。 + *

+ * 作为弹窗“首屏”数据，一次性返回： + * - 车辆主档概要（车牌号、车队、线路、车型、最近录入里程） + * - 当前装车轮胎快照（mountedTyres） + * - 最近事件时间线（recentEvents） + * - 各维度记录总数量（installCount / maintenanceCount / checkCount / mileageCount） + * 各子列表具体明细需调用对应的独立分页接口获取，避免首屏数据量过大。 + *

+ * + * @param query 查询参数，必须包含非空且长度合法的 carNo + * @return 车辆生命周期聚合DTO，包含概要及计数 + * @throws ServiceException 车牌号为空、超长、或车辆不存在/无权限时抛出 */ @Override @DataScope(deptAlias = "d", userAlias = "u") @@ -45,7 +62,15 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService } /** - * 查询车辆装卸历史。 + * 查询车辆轮胎装卸历史（分页/全量）。 + *

+ * 返回该车辆历史上所有轮胎安装与卸下记录，按操作时间倒序排列。 + * 展示字段包括：轮胎RFID、轮胎自编号、品牌型号、轮位、操作类型（安装/卸下）、操作里程、花纹深度、操作时间等。 + *

+ * + * @param query 查询参数，内部通过 buildAuthorizedCar 回填 carId + * @return 装卸记录列表；无记录时返回空列表而非 null + * @throws ServiceException 车辆不存在或无权限访问时抛出 */ @Override @DataScope(deptAlias = "d", userAlias = "u") @@ -56,7 +81,16 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService } /** - * 查询车辆维保工单历史。 + * 查询车辆维保工单历史（分页/全量）。 + *

+ * 通过 {@code biz_maintenance_order.plate_number = carNo} 直接关联车辆，返回所有维保工单。 + * 展示字段包括：工单编号、维保类型、修理厂、保养日期、工单状态、录入里程、上次里程、故障描述等。 + * 数据按保养日期（maintain_date）倒序排列。 + *

+ * + * @param query 查询参数，内部通过 buildAuthorizedCar 回填 carId + * @return 维保工单列表；无记录时返回空列表 + * @throws ServiceException 车辆不存在或无权限访问时抛出 */ @Override @DataScope(deptAlias = "d", userAlias = "u") @@ -67,7 +101,16 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService } /** - * 查询车辆关联轮胎质检历史。 + * 查询车辆关联轮胎质检历史（分页/全量）。 + *

+ * 车辆与质检记录无直接外键关联，需通过“该车辆曾装过的轮胎”间接查询： + * 以 record_tyre_install 中出现过且 car_no 匹配的记录为桥梁，找到对应轮胎在 record_check 中的质检记录。 + * 展示字段包括：轮胎RFID、轮胎编号、品牌型号、质检结果、维保类型、里程、花纹深度、质检时间等。 + *

+ * + * @param query 查询参数，内部通过 buildAuthorizedCar 回填 carId + * @return 质检记录列表；无记录时返回空列表 + * @throws ServiceException 车辆不存在或无权限访问时抛出 */ @Override @DataScope(deptAlias = "d", userAlias = "u") @@ -78,7 +121,16 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService } /** - * 查询车辆关联轮胎里程历史。 + * 查询车辆关联轮胎里程历史（分页/全量）。 + *

+ * 轮胎里程通过 record_tyre_mileage 记录，间接关联到车辆。 + * 展示字段包括：轮胎RFID、轮胎编号、品牌、开始时间、结束时间、行驶里程、花纹深度等。 + * 用于展示车辆使用过的各轮胎在其装车周期内的里程消耗情况。 + *

+ * + * @param query 查询参数，内部通过 buildAuthorizedCar 回填 carId + * @return 轮胎里程记录列表；无记录时返回空列表 + * @throws ServiceException 车辆不存在或无权限访问时抛出 */ @Override @DataScope(deptAlias = "d", userAlias = "u") @@ -88,6 +140,20 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService return baseCarLifecycleMapper.selectMileageList(query); } + /** + * 构建受权车辆主档并回填查询条件。 + *

+ * 核心权限闸口：所有公开查询方法均先调用本方法。 + * 1. 调用 {@link #validateQuery(CarLifecycleQuery)} 做基础参数校验； + * 2. 通过 Mapper 查询车辆主档，SQL 中已拼接 {@code DataScope} 部门/用户别名（d/u）； + * 3. 若查询结果为 null，统一提示“车辆不存在或无权限访问”，防止攻击者通过接口枚举判断某车牌是否存在； + * 4. 将车辆主键 carId 回写到 query 对象，供后续子查询作为精确过滤条件，避免仅依赖字符串车牌号跨表查询带来的性能与歧义问题。 + *

+ * + * @param query 生命周期查询参数对象 + * @return 车辆主档概要DTO + * @throws ServiceException 参数非法、车辆不存在或无数据权限时抛出 + */ private CarLifecycleSummaryDTO buildAuthorizedCar(CarLifecycleQuery query) { validateQuery(query); @@ -101,6 +167,18 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService return car; } + /** + * 校验生命周期查询参数。 + *

+ * 校验规则： + * 1. query 对象不能为 null，且 carNo 不能为空或空白字符； + * 2. 车牌号去除前后空格后，长度不得超过 50 字符（与数据库表 base_car.car_no 的 varchar(50) 定义保持一致）； + * 3. 校验通过后将规范化后的车牌号（trim 后）重新设置回 query，避免后续 SQL 中因前后空格导致匹配失败。 + *

+ * + * @param query 待校验的查询参数 + * @throws ServiceException 校验不通过时抛出，携带明确错误提示 + */ private void validateQuery(CarLifecycleQuery query) { if (query == null || StringUtils.isBlank(query.getCarNo()))