change(车辆生命周期): 完善领域对象及服务的注释

补充车辆生命周期相关DTO、Mapper和Service的详细注释，包括：
1. 各DTO字段的业务含义和使用场景
2. Mapper接口的查询逻辑和权限控制说明
3. Service层的校验流程和聚合查询策略

ruoyi-system/src/main/java/com/ruoyi/system/domain/CarCheckLifecycleDTO.java

@@ -4,21 +4,44 @@ import java.io.Serializable;
 import java.util.Date;
 
 /**
- * 车辆生命周期关联轮胎质检记录。
+ * 车辆生命周期关联轮胎质检记录DTO。
+ * <p>
+ * 用于“车辆全生命周期”弹窗中【巡检/质检记录】Tab页的数据展示。
+ * 车辆与质检记录无直接外键，数据通过“该车曾装过的轮胎”间接关联 record_check 表获取。
+ * </p>
  */
 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()

ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleDTO.java

@@ -5,24 +5,36 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * 车辆生命周期聚合报表。
+ * 车辆生命周期聚合报表DTO。
+ * <p>
+ * 作为车辆全生命周期弹窗“首屏”的统一返回对象，承载车辆概要、当前装车轮胎快照、
+ * 最近事件时间线以及各维度记录总数量。各明细列表（装卸、维保、质检、里程）
+     * 通过独立分页接口按需加载，避免首屏返回数据量过大导致性能问题。
+ * </p>
  */
 public class CarLifecycleDTO implements Serializable
 {
     private static final long serialVersionUID = 1L;
 
-    /** 车辆主档概要，用于弹窗头部确认当前报表对象。 */
+    /** 车辆主档概要，用于弹窗头部确认当前报表对象。包含车牌号、所属车队、线路、车型及最近录入里程。 */
     private CarLifecycleSummaryDTO car;
 
-    /** 当前装车轮胎快照，数量较少，随概要一次返回。 */
+    /** 当前装车轮胎快照，数量较少（通常不超过车辆轮位数），随概要一次返回用于首屏快速展示。 */
     private List<CarMountedTyreDTO> mountedTyres = new ArrayList<>();
 
-    /** 最近事件时间线，用于快速定位最新装卸或维保动作。 */
+    /** 最近事件时间线，聚合装卸与维保两类关键事件，按时间倒序排列，用于快速定位最新动作。 */
     private List<CarLifecycleEventDTO> recentEvents = new ArrayList<>();
 
+    /** 该车辆历史轮胎装卸记录总条数，用于前端分页组件初始化总页数。 */
     private Integer installCount;
+
+    /** 该车辆关联维保工单总条数，用于前端分页组件初始化总页数。 */
     private Integer maintenanceCount;
+
+    /** 该车辆关联轮胎质检记录总条数，用于前端分页组件初始化总页数。 */
     private Integer checkCount;
+
+    /** 该车辆关联轮胎里程记录总条数，用于前端分页组件初始化总页数。 */
     private Integer mileageCount;
 
     public CarLifecycleSummaryDTO getCar()

ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleEventDTO.java

@@ -5,33 +5,81 @@ import java.math.BigDecimal;
 import java.util.Date;
 
 /**
- * 车辆生命周期统一事件。
+ * 车辆生命周期统一事件DTO。
+ * <p>
+ * 作为“最近事件时间线”的数据载体，将轮胎装卸事件与维保工单事件抽象为统一结构，
+ * 便于前端以同一套模板按时间轴展示。事件类型（eventType）区分数据来源：
+ * INSTALL 表示轮胎装卸动作，MAINTENANCE 表示维保工单动作。
+ * </p>
  */
 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()

ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleQuery.java

@@ -4,15 +4,33 @@ import com.ruoyi.common.core.domain.BaseEntity;
 
 /**
  * 车辆生命周期查询参数。
+ * <p>
+ * 继承若依通用基础实体 {@link BaseEntity}，天然支持分页参数（pageNum / pageSize）
+ * 以及标准的数据权限字段（deptAlias / userAlias）。
+ * 本查询对象同时作为“权限校验载体”与“子查询条件载体”：
+ * 入口以 carNo 做初步过滤，校验通过后由 Service 层回填 carId，后续子查询优先使用 carId 做精确匹配，提升性能并避免字符串歧义。
+ * </p>
  */
 public class CarLifecycleQuery extends BaseEntity
 {
     private static final long serialVersionUID = 1L;
 
-    /** 车牌号是生命周期报表的唯一入口，避免前端绕过车辆主档直接查历史流水。 */
+    /**
+     * 车牌号，生命周期报表的唯一业务入口。
+     * <p>
+     * 前端弹窗以车牌号为路径参数或查询参数传入，Service 层先通过该字段定位车辆主档，
+     * 并完成数据权限校验。不允许为空，且长度受数据库字段限制（varchar(50)）。
+     * </p>
+     */
     private String carNo;
 
-    /** 车辆主键只用于一致性展示和派生查询，不作为跨表唯一业务关联。 */
+    /**
+     * 车辆主键ID，由 Service 层在权限校验后自动回填。
+     * <p>
+     * 不作为前端传入参数，仅用于后续子查询（装卸、维保、质检、里程）中做精确关联，
+     * 避免跨表仅依赖字符串车牌号可能导致的性能与一致性问题。
+     * </p>
+     */
     private Long carId;
 
     public String getCarNo()

ruoyi-system/src/main/java/com/ruoyi/system/domain/CarLifecycleSummaryDTO.java

@@ -4,20 +4,41 @@ import java.io.Serializable;
 import java.math.BigDecimal;
 
 /**
- * 车辆生命周期头部概要。
+ * 车辆生命周期头部概要DTO。
+ * <p>
+ * 作为弹窗顶部的“车辆名片”数据，展示用户最关心的车辆静态属性与最近动态指标。
+ * 所有字段均来自 base_car 主档及其关联字典/部门表，通过 {@link BaseCarLifecycleMapper#selectLifecycleCar} 一次性查询返回。
+ * </p>
  */
 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;
 
-    /** 最近工单录入里程只作为展示快照，避免字符串里程直接参与统计。 */
+    /**
+     * 最近工单录入里程。
+     * <p>
+     * 取自该车辆最近一次维保工单中的 input_mileage 字段，仅作为弹窗头部的展示快照。
+     * 使用 BigDecimal 类型避免浮点精度问题，但不参与聚合统计，防止不同工单录入口径差异导致统计失真。
+     * </p>
+     */
     private BigDecimal inputMileage;
 
     public Long getCarId()

ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMaintenanceLifecycleDTO.java

@@ -5,22 +5,47 @@ import java.math.BigDecimal;
 import java.util.Date;
 
 /**
- * 车辆生命周期维保工单记录。
+ * 车辆生命周期维保工单记录DTO。
+ * <p>
+ * 用于“车辆全生命周期”弹窗中【维保工单记录】Tab页的数据展示。
+ * 数据来源为 biz_maintenance_order 表，通过 plate_number（车牌号）直接与车辆关联，无需额外表桥接。
+ * </p>
  */
 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()

ruoyi-system/src/main/java/com/ruoyi/system/domain/CarMileageLifecycleDTO.java

@@ -4,19 +4,38 @@ import java.io.Serializable;
 import java.util.Date;
 
 /**
- * 车辆生命周期关联轮胎里程记录。
+ * 车辆生命周期关联轮胎里程记录DTO。
+ * <p>
+ * 用于“车辆全生命周期”弹窗中【轮胎里程快照】Tab页的数据展示。
+ * 数据通过轮胎RFID间接关联车辆：先找到该车历史上装过的轮胎，再关联 record_tyre_mileage 表获取各轮胎的里程消耗记录。
+ * </p>
  */
 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()

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

ruoyi-system/src/main/java/com/ruoyi/system/domain/CarTyreInstallLifecycleDTO.java

@@ -4,22 +4,48 @@ import java.io.Serializable;
 import java.util.Date;
 
 /**
- * 车辆生命周期装卸记录。
+ * 车辆生命周期装卸记录DTO。
+ * <p>
+ * 用于“车辆全生命周期”弹窗中【轮胎安装/卸胎记录】Tab页的数据展示。
+ * 数据来源为 record_tyre_install 表，通过 car_no（车牌号）直接关联车辆，
+ * 展示该车辆历史上所有轮胎的安装与卸下动作，按操作时间倒序排列。
+ * </p>
  */
 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()

ruoyi-system/src/main/java/com/ruoyi/system/mapper/BaseCarLifecycleMapper.java

@@ -12,28 +12,141 @@ import com.ruoyi.system.domain.CarTyreInstallLifecycleDTO;
 
 /**
  * 车辆全生命周期报表Mapper接口。
+ * <p>
+ * 承担车辆全生命周期弹窗所需的所有数据持久化查询职责。
+ * 设计原则：
+ * 1. 以车牌号（carNo）为入口，通过 join sys_dept 等权限表支持 {@link DataScope} 拦截；
+ * 2. 首屏概要（selectLifecycleCar / selectMountedTyres / selectRecentEvents / count*）与明细分页（select*List）分离，避免大数据量拖慢首屏；
+ * 3. 各子查询优先使用回填后的 carId 做精确过滤，提升性能并减少字符串匹配歧义。
+ * </p>
  */
 public interface BaseCarLifecycleMapper
 {
+    /**
+     * 查询车辆主档概要及最近录入里程。
+     * <p>
+     * SQL 需 join sys_dept 并预留 d/u 别名，供 {@link DataScope} 拦截器拼接部门/用户权限条件。
+     * 若查询无结果，Service 层统一提示“车辆不存在或无权限访问”，防止接口探测攻击。
+     * </p>
+     *
+     * @param query 包含 carNo 的查询参数
+     * @return 车辆概要DTO；无权限或不存在时返回 null
+     */
     public CarLifecycleSummaryDTO selectLifecycleCar(CarLifecycleQuery query);
 
+    /**
+     * 查询车辆当前装车轮胎快照。
+     * <p>
+     * 仅返回当前仍安装在该车上的轮胎列表，数量通常较少（<= 车辆轮位数），随首屏一起返回。
+     * 逻辑上取该车辆各轮位最近一次 installType='INSTALL' 且未后续卸下的记录。
+     * </p>
+     *
+     * @param query 已回填 carId 的查询参数
+     * @return 当前装车轮胎列表；无记录时返回空列表
+     */
     public List<CarMountedTyreDTO> selectMountedTyres(CarLifecycleQuery query);
 
+    /**
+     * 查询车辆最近事件时间线（TopN）。
+     * <p>
+     * 聚合轮胎装卸记录与维保工单两类事件，取按时间倒序的最近 N 条（例如 10 条）。
+     * 用于弹窗首屏快速展示最新动态，避免加载全量历史。
+     * </p>
+     *
+     * @param query 已回填 carId 的查询参数
+     * @return 最近事件列表；无记录时返回空列表
+     */
     public List<CarLifecycleEventDTO> selectRecentEvents(CarLifecycleQuery query);
 
+    /**
+     * 分页查询车辆轮胎装卸历史明细。
+     * <p>
+     * 返回该车辆所有轮胎的安装、卸下、换位等操作记录，支持按操作时间倒序分页。
+     * 需配合前端分页参数（pageNum / pageSize）使用。
+     * </p>
+     *
+     * @param query 已回填 carId 且携带分页参数的查询对象
+     * @return 装卸记录列表；无记录时返回空列表
+     */
     public List<CarTyreInstallLifecycleDTO> selectInstallList(CarLifecycleQuery query);
 
+    /**
+     * 分页查询车辆维保工单历史明细。
+     * <p>
+     * 通过 plate_number = carNo 直接关联 biz_maintenance_order 表，返回维保工单列表。
+     * 支持按保养日期（maintain_date）倒序分页。
+     * </p>
+     *
+     * @param query 已回填 carId 且携带分页参数的查询对象
+     * @return 维保工单列表；无记录时返回空列表
+     */
     public List<CarMaintenanceLifecycleDTO> selectMaintenanceList(CarLifecycleQuery query);
 
+    /**
+     * 分页查询车辆关联轮胎质检历史明细。
+     * <p>
+     * 车辆与质检记录无直接外键，需通过“该车曾装过的轮胎RFID”间接关联 record_check 表。
+     * SQL 中通常使用子查询或 join record_tyre_install 做中间桥接。
+     * </p>
+     *
+     * @param query 已回填 carId 且携带分页参数的查询对象
+     * @return 质检记录列表；无记录时返回空列表
+     */
     public List<CarCheckLifecycleDTO> selectCheckList(CarLifecycleQuery query);
 
+    /**
+     * 分页查询车辆关联轮胎里程历史明细。
+     * <p>
+     * 通过轮胎RFID间接关联 record_tyre_mileage 表，获取该车历史上装过的各轮胎的里程记录。
+     * 展示各轮胎在不同装车周期内的起止时间与累计行驶里程。
+     * </p>
+     *
+     * @param query 已回填 carId 且携带分页参数的查询对象
+     * @return 轮胎里程记录列表；无记录时返回空列表
+     */
     public List<CarMileageLifecycleDTO> selectMileageList(CarLifecycleQuery query);
 
+    /**
+     * 统计该车辆轮胎装卸记录总条数。
+     * <p>
+     * 用于弹窗首屏返回 installCount，供前端分页组件计算总页数。
+     * </p>
+     *
+     * @param query 已回填 carId 的查询参数
+     * @return 装卸记录总条数；无记录时返回 0
+     */
     public int countInstallRecords(CarLifecycleQuery query);
 
+    /**
+     * 统计该车辆维保工单总条数。
+     * <p>
+     * 用于弹窗首屏返回 maintenanceCount，供前端分页组件计算总页数。
+     * </p>
+     *
+     * @param query 已回填 carId 的查询参数
+     * @return 维保工单总条数；无记录时返回 0
+     */
     public int countMaintenanceOrders(CarLifecycleQuery query);
 
+    /**
+     * 统计该车辆关联轮胎质检记录总条数。
+     * <p>
+     * 用于弹窗首屏返回 checkCount，供前端分页组件计算总页数。
+     * </p>
+     *
+     * @param query 已回填 carId 的查询参数
+     * @return 质检记录总条数；无记录时返回 0
+     */
     public int countCheckRecords(CarLifecycleQuery query);
 
+    /**
+     * 统计该车辆关联轮胎里程记录总条数。
+     * <p>
+     * 用于弹窗首屏返回 mileageCount，供前端分页组件计算总页数。
+     * </p>
+     *
+     * @param query 已回填 carId 的查询参数
+     * @return 里程记录总条数；无记录时返回 0
+     */
     public int countMileageRecords(CarLifecycleQuery query);
 }

ruoyi-system/src/main/java/com/ruoyi/system/service/impl/BaseCarLifecycleServiceImpl.java

@@ -18,6 +18,11 @@ import org.springframework.stereotype.Service;
 
 /**
  * 车辆全生命周期报表Service业务层处理。
+ * <p>
+ * 本服务以车牌号（carNo）为唯一入口，通过 {@link #buildAuthorizedCar(CarLifecycleQuery)} 完成：
+ * 1）参数校验；2）车辆存在性与数据权限校验；3）将 carId 回写到查询对象中，供后续聚合查询复用。
+ * 所有对外查询方法均标注 {@link DataScope}，确保与车辆列表页（system:car:view）保持一致的部门/用户权限过滤。
+ * </p>
  */
 @Service
 public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService
@@ -27,6 +32,18 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService
 
     /**
      * 查询车辆生命周期概要。
+     * <p>
+     * 作为弹窗“首屏”数据，一次性返回：
+     * - 车辆主档概要（车牌号、车队、线路、车型、最近录入里程）
+     * - 当前装车轮胎快照（mountedTyres）
+     * - 最近事件时间线（recentEvents）
+     * - 各维度记录总数量（installCount / maintenanceCount / checkCount / mileageCount）
+     * 各子列表具体明细需调用对应的独立分页接口获取，避免首屏数据量过大。
+     * </p>
+     *
+     * @param query 查询参数，必须包含非空且长度合法的 carNo
+     * @return 车辆生命周期聚合DTO，包含概要及计数
+     * @throws ServiceException 车牌号为空、超长、或车辆不存在/无权限时抛出
      */
     @Override
     @DataScope(deptAlias = "d", userAlias = "u")
@@ -45,7 +62,15 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService
     }
 
     /**
-     * 查询车辆装卸历史。
+     * 查询车辆轮胎装卸历史（分页/全量）。
+     * <p>
+     * 返回该车辆历史上所有轮胎安装与卸下记录，按操作时间倒序排列。
+     * 展示字段包括：轮胎RFID、轮胎自编号、品牌型号、轮位、操作类型（安装/卸下）、操作里程、花纹深度、操作时间等。
+     * </p>
+     *
+     * @param query 查询参数，内部通过 buildAuthorizedCar 回填 carId
+     * @return 装卸记录列表；无记录时返回空列表而非 null
+     * @throws ServiceException 车辆不存在或无权限访问时抛出
      */
     @Override
     @DataScope(deptAlias = "d", userAlias = "u")
@@ -56,7 +81,16 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService
     }
 
     /**
-     * 查询车辆维保工单历史。
+     * 查询车辆维保工单历史（分页/全量）。
+     * <p>
+     * 通过 {@code biz_maintenance_order.plate_number = carNo} 直接关联车辆，返回所有维保工单。
+     * 展示字段包括：工单编号、维保类型、修理厂、保养日期、工单状态、录入里程、上次里程、故障描述等。
+     * 数据按保养日期（maintain_date）倒序排列。
+     * </p>
+     *
+     * @param query 查询参数，内部通过 buildAuthorizedCar 回填 carId
+     * @return 维保工单列表；无记录时返回空列表
+     * @throws ServiceException 车辆不存在或无权限访问时抛出
      */
     @Override
     @DataScope(deptAlias = "d", userAlias = "u")
@@ -67,7 +101,16 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService
     }
 
     /**
-     * 查询车辆关联轮胎质检历史。
+     * 查询车辆关联轮胎质检历史（分页/全量）。
+     * <p>
+     * 车辆与质检记录无直接外键关联，需通过“该车辆曾装过的轮胎”间接查询：
+     * 以 record_tyre_install 中出现过且 car_no 匹配的记录为桥梁，找到对应轮胎在 record_check 中的质检记录。
+     * 展示字段包括：轮胎RFID、轮胎编号、品牌型号、质检结果、维保类型、里程、花纹深度、质检时间等。
+     * </p>
+     *
+     * @param query 查询参数，内部通过 buildAuthorizedCar 回填 carId
+     * @return 质检记录列表；无记录时返回空列表
+     * @throws ServiceException 车辆不存在或无权限访问时抛出
      */
     @Override
     @DataScope(deptAlias = "d", userAlias = "u")
@@ -78,7 +121,16 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService
     }
 
     /**
-     * 查询车辆关联轮胎里程历史。
+     * 查询车辆关联轮胎里程历史（分页/全量）。
+     * <p>
+     * 轮胎里程通过 record_tyre_mileage 记录，间接关联到车辆。
+     * 展示字段包括：轮胎RFID、轮胎编号、品牌、开始时间、结束时间、行驶里程、花纹深度等。
+     * 用于展示车辆使用过的各轮胎在其装车周期内的里程消耗情况。
+     * </p>
+     *
+     * @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);
     }
 
+    /**
+     * 构建受权车辆主档并回填查询条件。
+     * <p>
+     * 核心权限闸口：所有公开查询方法均先调用本方法。
+     * 1. 调用 {@link #validateQuery(CarLifecycleQuery)} 做基础参数校验；
+     * 2. 通过 Mapper 查询车辆主档，SQL 中已拼接 {@code DataScope} 部门/用户别名（d/u）；
+     * 3. 若查询结果为 null，统一提示“车辆不存在或无权限访问”，防止攻击者通过接口枚举判断某车牌是否存在；
+     * 4. 将车辆主键 carId 回写到 query 对象，供后续子查询作为精确过滤条件，避免仅依赖字符串车牌号跨表查询带来的性能与歧义问题。
+     * </p>
+     *
+     * @param query 生命周期查询参数对象
+     * @return 车辆主档概要DTO
+     * @throws ServiceException 参数非法、车辆不存在或无数据权限时抛出
+     */
     private CarLifecycleSummaryDTO buildAuthorizedCar(CarLifecycleQuery query)
     {
         validateQuery(query);
@@ -101,6 +167,18 @@ public class BaseCarLifecycleServiceImpl implements IBaseCarLifecycleService
         return car;
     }
 
+    /**
+     * 校验生命周期查询参数。
+     * <p>
+     * 校验规则：
+     * 1. query 对象不能为 null，且 carNo 不能为空或空白字符；
+     * 2. 车牌号去除前后空格后，长度不得超过 50 字符（与数据库表 base_car.car_no 的 varchar(50) 定义保持一致）；
+     * 3. 校验通过后将规范化后的车牌号（trim 后）重新设置回 query，避免后续 SQL 中因前后空格导致匹配失败。
+     * </p>
+     *
+     * @param query 待校验的查询参数
+     * @throws ServiceException 校验不通过时抛出，携带明确错误提示
+     */
     private void validateQuery(CarLifecycleQuery query)
     {
         if (query == null || StringUtils.isBlank(query.getCarNo()))