feat(device): 添加设备报修验收审批功能

云

7 天以前 e973906d326d2c19da645368eb3808bf638887ae

feat(device): 添加设备报修验收审批功能

- 在DeviceRepair实体类中新增验收人、验收时间和验收备注字段
- 修改数据库映射文件以支持新的验收相关字段查询
- 添加设备报修验收审批的状态流转逻辑(0:待维修 -> 3:待验收 -> 1:完结)
- 实现confirmRepair方法用于提交维修确认进入待验收状态
- 实现approveRepairAcceptance方法用于验收审批通过并完结报修
- 在Excel导出功能中添加验收相关字段的导出支持
- 新增设备保养定时任务中的保养人字段并关联到保养记录
- 修改印章申请管理的部门查询逻辑以支持多部门显示
- 添加详细的前端联调文档说明接口变更和使用方式

 doc/Ç°¶ËÁªµ÷Îĵµ-É豸±¨ÐÞ±£Ñø²ÆÎñÄ£¿é¸ÄÔì.md

¶Ô±ÈÐÂÎļþ
@@ -0,0 +1,233 @@
# å‰ç«¯è”调文档（设备报修 / è®¾å¤‡ä¿å…»å®šæ—¶ä»»åŠ¡ / è´¢åŠ¡ç§‘目总账）

## 1. å˜æ›´èŒƒå›´

本次联调涉及 3 ä¸ªæ¨¡å—：

1. è´¢åŠ¡æ¨¡å—：科目总账去掉凭证字号、摘要，只返回 1 æ¡åˆè®¡æ•°æ®ã€‚
2. è®¾å¤‡ä¿å…»å®šæ—¶ä»»åŠ¡ï¼šæ–°å¢ž `保养人` å­—段，定时任务生成保养记录时带入。
3. è®¾å¤‡æŠ¥ä¿®ï¼šç¡®è®¤æŠ¥ä¿®åŽæ–°å¢žéªŒæ”¶å®¡æ‰¹ï¼ŒéªŒæ”¶é€šè¿‡åŽæ‰ç®—完结。

---

## 2. æŽ¥å£æ¸…单

### 2.1 è´¢åŠ¡-科目总账

- **GET** `/financial/ledger/general`
- è¯´æ˜Žï¼šè¿”回科目总账合计，仅 1 æ¡è®°å½•ã€‚

#### è¯·æ±‚参数（Query）

| å‚æ•° | ç±»åž‹ | å¿…å¡« | è¯´æ˜Ž |
|---|---|---|---|
| `subjectCode` | string | æ˜¯ | ç§‘目编码 |
| `startMonth` | string | æ˜¯ | å¼€å§‹æœˆä»½ï¼Œæ ¼å¼ `YYYY-MM` |
| `endMonth` | string | æ˜¯ | ç»“束月份，格式 `YYYY-MM` |

#### è¿”回结构

`R<List<FinLedgerRowVo>>`

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "rowType": "yearly_total",
      "date": "2026-05-31",
      "debit": 12000.00,
      "credit": 8000.00,
      "direction": "借",
      "balance": 4000.00
    }
  ]
}
```

#### è”调注意

1. `data` å›ºå®šåªæœ‰ 1 æ¡ï¼ˆåˆè®¡ï¼‰ã€‚
2. `voucherNo`、`summary` ä¸è¿”回（不再展示凭证字号、摘要）。

---

### 2.2 è®¾å¤‡ä¿å…»å®šæ—¶ä»»åŠ¡ï¼ˆæ–°å¢žä¿å…»äººï¼‰

- åŸºç¡€è·¯å¾„：`/deviceMaintenanceTask`
- ç›¸å…³æŽ¥å£ï¼š
  - **POST** `/add`
  - **POST** `/update`
  - **GET** `/listPage`

#### æ–°å¢žå­—段

| å­—段 | ç±»åž‹ | è¯´æ˜Ž |
|---|---|---|
| `maintenancePerson` | string | ä¿å…»äºº |

#### æ–°å¢ž/更新请求示例

```json
{
  "id": 1,
  "taskName": "空压机保养任务",
  "taskId": 1001,
  "maintenancePerson": "张三",
  "frequencyType": "MONTHLY",
  "frequencyDetail": "10,09:00",
  "remarks": "每月例行保养"
}
```

#### å®šæ—¶ä»»åŠ¡ä¸‹å‘行为

定时任务执行后，系统自动创建保养记录（`device_maintenance`）时会写入：

- `maintenanceActuallyName = maintenancePerson`

即前端在定时任务里维护的保养人，会自动带入到保养记录。

---

### 2.3 è®¾å¤‡æŠ¥ä¿®ï¼ˆç¡®è®¤åŽéªŒæ”¶å®¡æ‰¹ï¼‰

- åŸºç¡€è·¯å¾„：`/device/repair`

#### çŠ¶æ€å®šä¹‰

| çŠ¶æ€å€¼ | å«ä¹‰ |
|---|---|
| `0` | å¾…ç»´ä¿® |
| `3` | å¾…验收 |
| `1` | å®Œç»“ |
| `2` | å¤±è´¥ |

#### 2.3.1 ç»´ä¿®ç¡®è®¤ï¼ˆåŽŸç¡®è®¤æŠ¥ä¿®ï¼‰

- **POST** `/device/repair/repair`
- è¯´æ˜Žï¼šæäº¤åŽçŠ¶æ€ä»Ž `待维修(0)` è¿›å…¥ `待验收(3)`，不再直接完结。

请求示例：

```json
{
  "id": 10001,
  "maintenanceName": "李四",
  "maintenanceTime": "2026-05-14 10:30:00",
  "maintenanceResult": "更换轴承并试运行正常",
  "sparePartsUseList": [
    {
      "id": 501,
      "quantity": 2
    }
  ]
}
```

常见失败提示（用于前端弹窗）：

- `报修记录不存在`
- `该报修已完结，不能重复确认维修`
- `该报修已提交验收审批`
- `备件 xxx æ•°é‡ä¸è¶³`

#### 2.3.2 éªŒæ”¶å®¡æ‰¹ï¼ˆæ–°å¢žï¼‰

- **POST** `/device/repair/acceptance`
- è¯´æ˜Žï¼šä»… `待验收(3)` å¯å®¡æ‰¹ï¼›å®¡æ‰¹é€šè¿‡åŽçŠ¶æ€æ”¹ä¸º `完结(1)`。

请求参数（Body）：

| å­—段 | ç±»åž‹ | å¿…å¡« | è¯´æ˜Ž |
|---|---|---|---|
| `id` | long | æ˜¯ | æŠ¥ä¿®è®°å½•ID |
| `acceptanceName` | string | æ˜¯ | éªŒæ”¶äºº |
| `acceptanceTime` | string | æ˜¯ | éªŒæ”¶æ—¶é—´ï¼Œæ ¼å¼ `yyyy-MM-dd HH:mm:ss` |
| `acceptanceRemark` | string | æ˜¯ | éªŒæ”¶å¤‡æ³¨ |

请求示例：

```json
{
  "id": 10001,
  "acceptanceName": "王五",
  "acceptanceTime": "2026-05-14 11:00:00",
  "acceptanceRemark": "维修项核验通过，设备运行正常"
}
```

常见失败提示：

- `报修记录id不能为空`
- `报修记录不存在`
- `该报修未进入待验收状态，不能审批`
- `验收人不能为空`
- `验收时间不能为空`
- `验收备注不能为空`

#### 2.3.3 æ™®é€šæ›´æ–°æŽ¥å£é™åˆ¶

- **PUT** `/device/repair`
- é™åˆ¶ï¼šä¸èƒ½é€šè¿‡æ™®é€šæ›´æ–°ç›´æŽ¥æŠŠçŠ¶æ€æ”¹æˆ `完结(1)`（必须走验收审批接口）。
- å¤±è´¥æç¤ºï¼š`请先提交验收审批，验收通过后才可完结`

---

## 3. è¿”回字段变更（报修列表/详情）

以下接口返回已新增验收字段：

- **GET** `/device/repair/page`
- **GET** `/device/repair/{id}`

新增返回字段：

| å­—段 | ç±»åž‹ | è¯´æ˜Ž |
|---|---|---|
| `acceptanceName` | string | éªŒæ”¶äºº |
| `acceptanceTime` | string | éªŒæ”¶æ—¶é—´ |
| `acceptanceRemark` | string | éªŒæ”¶å¤‡æ³¨ |

---

## 4. å‰ç«¯æ”¹é€ å»ºè®®

1. æŠ¥ä¿®åˆ—表增加状态值 `3=待验收` çš„展示文案与筛选项。
2. â€œç¡®è®¤ç»´ä¿®â€æŒ‰é’®è°ƒç”¨ `/device/repair/repair`，成功后刷新为待验收状态。
3. æ–°å¢žâ€œéªŒæ”¶å®¡æ‰¹â€å¼¹çª—，必填：
   - éªŒæ”¶äºº
   - éªŒæ”¶æ—¶é—´
   - éªŒæ”¶å¤‡æ³¨
4. ç¦æ­¢åœ¨æ™®é€šç¼–辑页直接将状态置为完结。
5. è®¾å¤‡ä¿å…»å®šæ—¶ä»»åŠ¡æ–°å¢žâ€œä¿å…»äººâ€è¾“入项，并在列表/详情展示。
6. ç§‘目总账页面按单行合计渲染，不再显示凭证字号、摘要列。

---

## 5. è”调检查清单

1. ç§‘目总账查询返回 `data.length === 1`，且无 `voucherNo/summary`。
2. æ–°å¢žä¿å…»å®šæ—¶ä»»åŠ¡æ—¶ä¼  `maintenancePerson`，列表能回显。
3. å®šæ—¶ä»»åŠ¡è§¦å‘后，生成的保养记录 `maintenanceActuallyName` ä¸Žå®šæ—¶ä»»åŠ¡ä¿å…»äººä¸€è‡´ã€‚
4. æŠ¥ä¿®å•æµç¨‹ï¼š`0待维修 -> 3待验收 -> 1完结`。
5. å¾…验收单据未填验收人/验收时间/验收备注时，后端返回对应错误提示。
6. å°è¯•é€šè¿‡ `PUT /device/repair` ç›´æŽ¥è®¾ä¸ºå®Œç»“时，后端返回拦截提示。

---

## 6. æ•°æ®åº“变更（联调前确认）

```sql
ALTER TABLE maintenance_task
  ADD COLUMN maintenance_person VARCHAR(100) NULL COMMENT '保养人';

ALTER TABLE device_repair
  ADD COLUMN acceptance_name VARCHAR(100) NULL COMMENT '验收人',
  ADD COLUMN acceptance_time DATETIME NULL COMMENT '验收时间',
  ADD COLUMN acceptance_remark VARCHAR(500) NULL COMMENT '验收备注';
```

> è‹¥æœªæ‰§è¡Œä»¥ä¸Š SQL，相关接口会出现字段不存在异常。


 src/main/java/com/ruoyi/device/controller/DeviceRepairController.java

@@ -46,10 +46,16 @@
        return deviceRepairService.updateDeviceRepair(deviceRepairDto);
    }

    @PostMapping ("repair")
    @PostMapping ("/repair")
    @Operation(summary = "设备维修")
    public AjaxResult repair( @RequestBody DeviceRepairDto deviceRepairDto) {
        return deviceRepairService.updateDeviceRepair(deviceRepairDto);
        return deviceRepairService.confirmRepair(deviceRepairDto);
    }

    @PostMapping ("/acceptance")
    @Operation(summary = "设备报修验收审批")
    public AjaxResult acceptance(@RequestBody DeviceRepairDto deviceRepairDto) {
        return deviceRepairService.approveRepairAcceptance(deviceRepairDto);
    }

    @DeleteMapping("/{ids}")

 src/main/java/com/ruoyi/device/execl/DeviceRepairExeclDto.java

@@ -47,6 +47,18 @@
    @Excel(name = "维修结果")
    private String maintenanceResult;

    @Schema(description = "验收人")
    @Excel(name = "验收人")
    private String acceptanceName;

    @Schema(description = "验收时间")
    @Excel(name = "验收时间", width = 30, dateFormat = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime acceptanceTime;

    @Schema(description = "验收备注")
    @Excel(name = "验收备注")
    private String acceptanceRemark;

    @Schema(description = "状态")
    @Excel(name = "状态")
    private String statusStr;

 src/main/java/com/ruoyi/device/pojo/DeviceRepair.java

@@ -50,7 +50,19 @@
    @Schema(description = "维修结果")
    private String maintenanceResult;

    @Schema(description = "验收人")
    private String acceptanceName;

    @Schema(description = "验收时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime acceptanceTime;

    @Schema(description = "验收备注")
    private String acceptanceRemark;

    @Schema(description = "状态 0 å¾…ç»´ä¿® 1完结 2 å¤±è´¥")
    // 0:待维修 1:完结 2:失败 3:待验收
    private Integer status;

    @Schema(description = "创建时间")

 src/main/java/com/ruoyi/device/pojo/MaintenanceTask.java

@@ -44,6 +44,10 @@
    @Schema(description = "设备id")
    private Long taskId;

    @Schema(description = "保养人")
    @Excel(name = "保养人")
    private String maintenancePerson;

    @Schema(description = "频次")
    @Excel(name = "频次")
    private String frequencyType;

 src/main/java/com/ruoyi/device/service/IDeviceRepairService.java

@@ -19,6 +19,10 @@

    AjaxResult updateDeviceRepair(DeviceRepairDto deviceRepairDto);

    AjaxResult confirmRepair(DeviceRepairDto deviceRepairDto);

    AjaxResult approveRepairAcceptance(DeviceRepairDto deviceRepairDto);

    void export(HttpServletResponse response, Long[] ids);

    DeviceRepairVo detailById(Long id);

 src/main/java/com/ruoyi/device/service/impl/DeviceRepairServiceImpl.java

@@ -47,6 +47,11 @@
    private final SparePartsRequisitionRecordService sparePartsRequisitionRecordService;
    private final FileUtil fileUtil;

    private static final int STATUS_PENDING_REPAIR = 0;
    private static final int STATUS_COMPLETED = 1;
    private static final int STATUS_FAILED = 2;
    private static final int STATUS_PENDING_ACCEPTANCE = 3;

    @Override
    public IPage<DeviceRepairVo> queryPage(Page page, DeviceRepairDto deviceRepairDto) {
        IPage<DeviceRepairVo> pageDto = deviceRepairMapper.queryPage(page, deviceRepairDto);
@@ -62,6 +67,9 @@
        DeviceLedger byId = deviceLedgerService.getById(deviceRepairDto.getDeviceLedgerId());
        deviceRepairDto.setDeviceName(byId.getDeviceName());
        deviceRepairDto.setDeviceModel(byId.getDeviceModel());
        if (deviceRepairDto.getStatus() == null) {
            deviceRepairDto.setStatus(STATUS_PENDING_REPAIR);
        }
        boolean save = this.save(deviceRepairDto);
        if (save) {
            // å¤„理图片上传
@@ -75,6 +83,15 @@
    @Transactional(rollbackFor = Exception.class)
    public AjaxResult updateDeviceRepair(DeviceRepairDto deviceRepairDto) {
        DeviceRepair oldDeviceRepair = this.getById(deviceRepairDto.getId());
        if (oldDeviceRepair == null) {
            return AjaxResult.error("报修记录不存在");
        }
        if (deviceRepairDto.getStatus() != null
                && deviceRepairDto.getStatus() == STATUS_COMPLETED
                && (oldDeviceRepair.getStatus() == null
                || oldDeviceRepair.getStatus() != STATUS_COMPLETED)) {
            return AjaxResult.error("请先提交验收审批，验收通过后才可完结");
        }
        // å¤„理备件使用情况
        if (CollectionUtils.isNotEmpty(deviceRepairDto.getSparePartsUseList())) {
            List<Long> sparePartIds = new ArrayList<>();
@@ -131,6 +148,58 @@
    }

    @Override
    @Transactional(rollbackFor = Exception.class)
    public AjaxResult confirmRepair(DeviceRepairDto deviceRepairDto) {
        DeviceRepair oldDeviceRepair = this.getById(deviceRepairDto.getId());
        if (oldDeviceRepair == null) {
            return AjaxResult.error("报修记录不存在");
        }
        if (oldDeviceRepair.getStatus() != null && oldDeviceRepair.getStatus() == STATUS_COMPLETED) {
            return AjaxResult.error("该报修已完结，不能重复确认维修");
        }
        if (oldDeviceRepair.getStatus() != null && oldDeviceRepair.getStatus() == STATUS_PENDING_ACCEPTANCE) {
            return AjaxResult.error("该报修已提交验收审批");
        }
        deviceRepairDto.setStatus(STATUS_PENDING_ACCEPTANCE);
        return updateDeviceRepair(deviceRepairDto);
    }

    @Override
    @Transactional(rollbackFor = Exception.class)
    public AjaxResult approveRepairAcceptance(DeviceRepairDto deviceRepairDto) {
        if (deviceRepairDto.getId() == null) {
            return AjaxResult.error("报修记录id不能为空");
        }
        DeviceRepair oldDeviceRepair = this.getById(deviceRepairDto.getId());
        if (oldDeviceRepair == null) {
            return AjaxResult.error("报修记录不存在");
        }
        if (oldDeviceRepair.getStatus() == null || oldDeviceRepair.getStatus() != STATUS_PENDING_ACCEPTANCE) {
            return AjaxResult.error("该报修未进入待验收状态，不能审批");
        }
        if (StringUtils.isBlank(deviceRepairDto.getAcceptanceName())) {
            return AjaxResult.error("验收人不能为空");
        }
        if (deviceRepairDto.getAcceptanceTime() == null) {
            return AjaxResult.error("验收时间不能为空");
        }
        if (StringUtils.isBlank(deviceRepairDto.getAcceptanceRemark())) {
            return AjaxResult.error("验收备注不能为空");
        }

        DeviceRepair update = new DeviceRepair();
        update.setId(deviceRepairDto.getId());
        update.setAcceptanceName(deviceRepairDto.getAcceptanceName());
        update.setAcceptanceTime(deviceRepairDto.getAcceptanceTime());
        update.setAcceptanceRemark(deviceRepairDto.getAcceptanceRemark());
        update.setStatus(STATUS_COMPLETED);
        if (this.updateById(update)) {
            return AjaxResult.success();
        }
        return AjaxResult.error("验收审批失败");
    }

    @Override
    public void export(HttpServletResponse response, Long[] ids) {
        if (ids == null || ids.length == 0) {
            List<DeviceRepair> supplierManageList = this.list();
@@ -138,24 +207,19 @@
            supplierManageList.stream().forEach(deviceRepair -> {
                DeviceRepairExeclDto deviceRepairExeclDto = new DeviceRepairExeclDto();
                BeanUtils.copyProperties(deviceRepair,deviceRepairExeclDto);
                deviceRepairExeclDto.setStatusStr(deviceRepair.getStatus() == 0 ? "待维修" : deviceRepair.getStatus() == 1 ? "完结" : "失败");

                deviceRepairExeclDto.setStatusStr(resolveStatusText(deviceRepair.getStatus()));
                deviceLedgerExeclDtos.add(deviceRepairExeclDto);
            });
            ExcelUtil<DeviceRepairExeclDto> util = new ExcelUtil<DeviceRepairExeclDto>(DeviceRepairExeclDto.class);
            util.exportExcel(response, deviceLedgerExeclDtos, "设备报修导出");
        }else {
            ArrayList<Long> arrayList = new ArrayList<>();
            Arrays.stream(ids).map(id -> {
                return arrayList.add( id);
            });
            ArrayList<Long> arrayList = new ArrayList<>(Arrays.asList(ids));
            List<DeviceRepair> supplierManageList = deviceRepairMapper.selectBatchIds(arrayList);
            ArrayList<DeviceRepairExeclDto> deviceLedgerExeclDtos = new ArrayList<>();
            supplierManageList.stream().forEach(deviceRepair -> {
                DeviceRepairExeclDto deviceRepairExeclDto = new DeviceRepairExeclDto();
                BeanUtils.copyProperties(deviceRepair,deviceRepairExeclDto);
                deviceRepairExeclDto.setStatusStr(deviceRepair.getStatus() == 0 ? "待维修" : deviceRepair.getStatus() == 1 ? "完结" : "失败");

                deviceRepairExeclDto.setStatusStr(resolveStatusText(deviceRepair.getStatus()));
                deviceLedgerExeclDtos.add(deviceRepairExeclDto);
            });
            ExcelUtil<DeviceRepairExeclDto> util = new ExcelUtil<DeviceRepairExeclDto>(DeviceRepairExeclDto.class);
@@ -164,6 +228,25 @@

    }

    private String resolveStatusText(Integer status) {
        if (status == null) {
            return "";
        }
        if (status == STATUS_PENDING_REPAIR) {
            return "待维修";
        }
        if (status == STATUS_COMPLETED) {
            return "完结";
        }
        if (status == STATUS_FAILED) {
            return "失败";
        }
        if (status == STATUS_PENDING_ACCEPTANCE) {
            return "待验收";
        }
        return "未知";
    }

    @Override
    public DeviceRepairVo detailById(Long id) {
        DeviceRepairVo vo = deviceRepairMapper.detailById(id);

 src/main/java/com/ruoyi/device/service/impl/MaintenanceTaskJob.java

@@ -93,6 +93,7 @@
        inspectionTask.setMaintenanceTaskId(timingTask.getId());
        inspectionTask.setDeviceLedgerId(timingTask.getTaskId());
        inspectionTask.setMaintenancePlanTime(LocalDateTime.now());
        inspectionTask.setMaintenanceActuallyName(timingTask.getMaintenancePerson());
        inspectionTask.setFrequencyType(timingTask.getFrequencyType());
        inspectionTask.setFrequencyDetail(timingTask.getFrequencyDetail());
        inspectionTask.setTenantId(timingTask.getTenantId());

 src/main/resources/mapper/collaborativeApproval/SealApplicationManagementMapper.xml

@@ -4,13 +4,27 @@


    <select id="listPage" resultType="com.ruoyi.collaborativeApproval.dto.SealApplicationManagementDTO">
        select sam.*, su.user_name as create_user_name, d.dept_name as department,
        su1.nick_name as approveUserName
        from seal_application_management sam
        left join sys_user su on sam.create_user = su.user_id
        left join sys_user su1 on sam.approve_user_id = su1.user_id
        left join sys_user_dept sud on su.user_id = sud.user_id
        left join sys_dept d on sud.dept_id = d.dept_id
        SELECT
        sam.*,
        su.user_name AS create_user_name,

        GROUP_CONCAT(DISTINCT d.dept_name ORDER BY d.dept_id SEPARATOR ',') AS department,

        su1.nick_name AS approveUserName

        FROM seal_application_management sam

        LEFT JOIN sys_user su
        ON sam.create_user = su.user_id

        LEFT JOIN sys_user su1
        ON sam.approve_user_id = su1.user_id

        LEFT JOIN sys_user_dept sud
        ON su.user_id = sud.user_id

        LEFT JOIN sys_dept d
        ON sud.dept_id = d.dept_id
        <where>
            <if test="ew.applicationNum != null and ew.applicationNum != ''">
                and sam.application_num like concat('%',#{ew.applicationNum},'%')
@@ -22,5 +36,6 @@
                and sam.status = #{ew.status}
            </if>
        </where>
        GROUP BY sam.id
    </select>
</mapper>

 src/main/resources/mapper/device/DeviceRepairMapper.xml

@@ -11,10 +11,13 @@
                dr.repair_time,
                dr.repair_name,
                dr.remark,
                dr.maintenance_name,
                dr.maintenance_time,
                dr.maintenance_result,
                dr.status,
                 dr.maintenance_name,
                 dr.maintenance_time,
                 dr.maintenance_result,
                 dr.acceptance_name,
                 dr.acceptance_time,
                 dr.acceptance_remark,
                 dr.status,
                dr.create_time,
                dr.update_time,
                dr.create_user,
@@ -60,6 +63,9 @@
               dr.maintenance_name,
               dr.maintenance_time,
               dr.maintenance_result,
               dr.acceptance_name,
               dr.acceptance_time,
               dr.acceptance_remark,
               dr.status,
               dr.create_time,
               dr.update_time,