oneos-backend/MAINTAIN_ITEM_REPORT.md

# 车型参数模块 - 保养项目功能完善报告

## 完成时间
2026-03-12 01:20 - 01:24

## 功能说明

根据原型系统和老系统的设计，车型参数模块需要支持**保养项目**的管理。每个车型可以关联多个保养项目，记录保养的详细信息。

## 数据库设计

### 车型维保项目关联表（asset_vehicle_model_maintain_item）

**字段列表**:
1. `id` - 主键
2. `vehicle_model_id` - 车型ID（外键）
3. `maintain_item_id` - 维保项目ID（预留字段）
4. `maintain_item` - 保养项目名称
5. `maintain_content` - 保养内容描述
6. `materials_expenses` - 材料费（decimal）
7. `hour_fee` - 工时费（decimal）
8. `kilometer_cycle` - 保养公里周期（KM）
9. `time_cycle` - 保养时间周期（月）
10. 标准字段：creator、create_time、updater、update_time、deleted、tenant_id

**索引**:
- `idx_vehicle_model_id` - 车型ID索引
- `idx_maintain_item_id` - 维保项目ID索引

## 代码实现

### 1. DO 层（数据对象）
**文件**: `VehicleModelMaintainItemDO.java`
- ✅ 完整的字段定义
- ✅ 使用 BigDecimal 存储费用
- ✅ 继承 BaseDO

### 2. Mapper 层（数据访问）
**文件**: `VehicleModelMaintainItemMapper.java`

**方法**:
- `selectListByVehicleModelId(Long vehicleModelId)` - 根据车型ID查询
- `deleteByVehicleModelId(Long vehicleModelId)` - 根据车型ID删除

### 3. VO 层（视图对象）
**文件**: `VehicleModelMaintainItemVO.java`
- ✅ 完整的字段定义
- ✅ Swagger 注解完整

**更新的文件**:
- `VehicleModelSaveReqVO.java` - 新增 `maintainItems` 列表字段
- `VehicleModelRespVO.java` - 新增 `maintainItems` 列表字段

### 4. Service 层（业务逻辑）
**更新**: `VehicleModelServiceImpl.java`

**新增方法**:
- `getVehicleModelMaintainItems(Long vehicleModelId)` - 获取车型的维保项目列表
- `saveMaintainItems(Long vehicleModelId, List maintainItems)` - 保存维保项目（私有方法）

**更新逻辑**:
- `createVehicleModel()` - 创建车型时同时保存维保项目
- `updateVehicleModel()` - 更新车型时先删除旧的维保项目，再保存新的
- `deleteVehicleModel()` - 删除车型时同时删除维保项目

**事务控制**:
- ✅ 使用 `@Transactional` 保证数据一致性

### 5. Controller 层（接口）
**更新**: `VehicleModelController.java`

**修改的接口**:
- `GET /get` - 获取车型详情时返回维保项目列表

## 业务流程

### 创建车型参数
```
1. 保存车型基本信息
2. 保存维保项目列表（如果有）
3. 提交事务
```

### 更新车型参数
```
1. 校验车型是否存在
2. 更新车型基本信息
3. 删除旧的维保项目
4. 保存新的维保项目列表
5. 提交事务
```

### 删除车型参数
```
1. 校验车型是否存在
2. 删除车型基本信息
3. 删除关联的维保项目
4. 提交事务
```

### 获取车型详情
```
1. 查询车型基本信息
2. 查询关联的维保项目列表
3. 组装返回数据
```

## 接口示例

### 创建车型参数（带保养项目）
```http
POST /admin-api/asset/vehicle-model/create
Content-Type: application/json

{
  "brand": 1,
  "model": 1,
  "modelName": "江淮骏铃V6",
  "hydrogenCapacity": 165,
  "reserveElectricity": 80.00,
  "maintainItems": [
    {
      "maintainItem": "更换机油",
      "maintainContent": "更换机油、机滤",
      "materialsExpenses": 200.00,
      "hourFee": 100.00,
      "kilometerCycle": 5000,
      "timeCycle": 6
    },
    {
      "maintainItem": "更换空滤",
      "maintainContent": "更换空气滤芯",
      "materialsExpenses": 50.00,
      "hourFee": 50.00,
      "kilometerCycle": 10000,
      "timeCycle": 12
    }
  ]
}
```

### 获取车型详情（含保养项目）
```http
GET /admin-api/asset/vehicle-model/get?id=1

Response:
{
  "code": 0,
  "data": {
    "id": 1,
    "brand": 1,
    "model": 1,
    "modelName": "江淮骏铃V6",
    "hydrogenCapacity": 165,
    "reserveElectricity": 80.00,
    "maintainItems": [
      {
        "id": 1,
        "maintainItem": "更换机油",
        "maintainContent": "更换机油、机滤",
        "materialsExpenses": 200.00,
        "hourFee": 100.00,
        "kilometerCycle": 5000,
        "timeCycle": 6
      },
      {
        "id": 2,
        "maintainItem": "更换空滤",
        "maintainContent": "更换空气滤芯",
        "materialsExpenses": 50.00,
        "hourFee": 50.00,
        "kilometerCycle": 10000,
        "timeCycle": 12
      }
    ],
    "createTime": "2026-03-12T01:00:00"
  }
}
```

## SQL 更新脚本

**文件**: `sql/update-2026-03-12-停车场和车型参数模块.sql`

**新增内容**:
```sql
-- 4. 更新车型维保项目关联表（添加保养详情字段）
ALTER TABLE `asset_vehicle_model_maintain_item`
ADD COLUMN `maintain_item` varchar(100) DEFAULT NULL COMMENT '保养项目' AFTER `maintain_item_id`,
ADD COLUMN `maintain_content` varchar(500) DEFAULT NULL COMMENT '保养内容' AFTER `maintain_item`,
ADD COLUMN `materials_expenses` decimal(10,2) DEFAULT NULL COMMENT '材料费' AFTER `maintain_content`,
ADD COLUMN `hour_fee` decimal(10,2) DEFAULT NULL COMMENT '工时费' AFTER `materials_expenses`,
ADD COLUMN `kilometer_cycle` int DEFAULT NULL COMMENT '保养公里周期(KM)' AFTER `hour_fee`,
ADD COLUMN `time_cycle` int DEFAULT NULL COMMENT '保养时间周期(月)' AFTER `kilometer_cycle`;
```

## 编译验证

```
[INFO] BUILD SUCCESS
[INFO] Total time:  14.831 s
[INFO] yudao-module-asset-server .......................... SUCCESS [  0.332 s]
```

## 代码统计

### 新增文件
- VehicleModelMaintainItemDO.java
- VehicleModelMaintainItemMapper.java
- VehicleModelMaintainItemVO.java

**总计**: 3 个文件

### 修改文件
- VehicleModelSaveReqVO.java
- VehicleModelRespVO.java
- VehicleModelService.java
- VehicleModelServiceImpl.java
- VehicleModelController.java
- update-2026-03-12-停车场和车型参数模块.sql

**总计**: 6 个文件

## 功能特点

1. **一对多关系** - 一个车型可以关联多个保养项目
2. **级联操作** - 删除车型时自动删除关联的保养项目
3. **事务保证** - 使用事务确保数据一致性
4. **完整的 CRUD** - 支持保养项目的增删改查
5. **费用管理** - 记录材料费和工时费
6. **周期管理** - 支持公里周期和时间周期

## 业务价值

1. **标准化管理** - 为每个车型定义标准的保养项目
2. **成本控制** - 记录保养费用，便于成本核算
3. **周期提醒** - 根据公里数和时间提醒保养
4. **数据支撑** - 为车辆保养计划提供数据支持

## 状态

✅ 功能完善完成
✅ 编译通过
✅ 代码质量良好
✅ 事务控制正确

---

**完成时间**: 2026-03-12 01:24
**状态**: ✅ 开发完成，待测试验收