refactor(ops): OpsOrderController 参数统一为 @RequestBody VO

将 acceptOrder、completeOrder、pauseOrder、resumeOrder 四个接口从 @RequestParam 改为 @RequestBody VO，与其他 POST 接口风格保持一致。新增 OpsOrderAcceptReqVO、OpsOrderCompleteReqVO、OpsOrderPauseReqVO、 OpsOrderResumeReqVO 四个 Controller 层 VO 类。注意：此变更为破坏性 API 变更，前端调用方需同步更新请求方式。 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 09:45:39 +08:00
parent 4a105da46e
commit f9d0562a49
5 changed files with 125 additions and 22 deletions
--- a/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/OpsOrderController.java
+++ b/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/OpsOrderController.java
@@ -4,7 +4,11 @@ import com.viewsh.framework.apilog.core.annotation.ApiAccessLog;
 import com.viewsh.framework.common.pojo.CommonResult;
 import com.viewsh.framework.common.pojo.PageResult;
 import com.viewsh.framework.common.util.object.BeanUtils;
-import com.viewsh.module.ops.dal.dataobject.dto.*;
+import com.viewsh.module.ops.controller.admin.vo.OpsOrderAcceptReqVO;
+import com.viewsh.module.ops.controller.admin.vo.OpsOrderCompleteReqVO;
+import com.viewsh.module.ops.controller.admin.vo.OpsOrderPauseReqVO;
+import com.viewsh.module.ops.controller.admin.vo.OpsOrderResumeReqVO;
+import com.viewsh.module.ops.service.order.dto.*;
 import com.viewsh.module.ops.dal.dataobject.workorder.OpsOrderDO;
 import com.viewsh.module.ops.enums.OperatorTypeEnum;
 import com.viewsh.module.ops.service.order.OpsOrderService;
@@ -21,7 +25,11 @@ import org.springframework.web.bind.annotation.*;
 import static com.viewsh.framework.common.pojo.CommonResult.success;

 /**
- * 管理后台 - 工单 Controller
+ * 管理后台 - 通用工单 Controller
+ * <p>
+ * 职责边界：提供所有工单类型（保洁/安保/工程/客服）通用的 CRUD、状态转换接口。
+ * 保洁条线特有的业务操作（手动完单、优先级升级、时间线查询等）请使用
+ * {@link com.viewsh.module.ops.controller.admin.clean.CleanWorkOrderController}。
 *
 * @author lzh
 */
@@ -88,45 +96,36 @@ public class OpsOrderController {

    @PostMapping("/accept")
    @Operation(summary = "接单")
-    @Parameter(name = "orderId", description = "工单ID", required = true)
-    @Parameter(name = "userId", description = "保洁员ID", required = true)
    @PreAuthorize("@ss.hasPermission('ops:order:accept')")
-    public CommonResult<Boolean> acceptOrder(@RequestParam("orderId") Long orderId,
-                                             @RequestParam("userId") Long userId) {
-        opsOrderService.acceptOrder(orderId, userId);
+    public CommonResult<Boolean> acceptOrder(@Valid @RequestBody OpsOrderAcceptReqVO reqVO) {
+        opsOrderService.acceptOrder(reqVO.getOrderId(), reqVO.getUserId());
        return success(true);
    }

    @PostMapping("/complete")
    @Operation(summary = "完成工单")
    @PreAuthorize("@ss.hasPermission('ops:order:complete')")
-    public CommonResult<Boolean> completeOrder(@Valid @RequestBody OpsOrderCompleteReqDTO completeReq,
-                                               @Parameter(description = "执行人ID") @RequestParam("userId") Long userId) {
-        opsOrderService.completeOrder(completeReq, userId);
+    public CommonResult<Boolean> completeOrder(@Valid @RequestBody OpsOrderCompleteReqVO reqVO) {
+        OpsOrderCompleteReqDTO completeReq = new OpsOrderCompleteReqDTO();
+        completeReq.setOrderId(reqVO.getOrderId());
+        completeReq.setRemark(reqVO.getRemark());
+        opsOrderService.completeOrder(completeReq, reqVO.getUserId());
        return success(true);
    }

    @PostMapping("/pause")
    @Operation(summary = "暂停工单")
-    @Parameter(name = "orderId", description = "工单ID", required = true)
-    @Parameter(name = "userId", description = "保洁员ID", required = true)
-    @Parameter(name = "reason", description = "暂停原因", required = true)
    @PreAuthorize("@ss.hasPermission('ops:order:pause')")
-    public CommonResult<Boolean> pauseOrder(@RequestParam("orderId") Long orderId,
-                                            @RequestParam("userId") Long userId,
-                                            @RequestParam("reason") String reason) {
-        opsOrderService.pauseOrder(orderId, userId, reason);
+    public CommonResult<Boolean> pauseOrder(@Valid @RequestBody OpsOrderPauseReqVO reqVO) {
+        opsOrderService.pauseOrder(reqVO.getOrderId(), reqVO.getUserId(), reqVO.getReason());
        return success(true);
    }

    @PostMapping("/resume")
    @Operation(summary = "恢复工单")
-    @Parameter(name = "orderId", description = "工单ID", required = true)
-    @Parameter(name = "userId", description = "保洁员ID", required = true)
    @PreAuthorize("@ss.hasPermission('ops:order:resume')")
-    public CommonResult<Boolean> resumeOrder(@RequestParam("orderId") Long orderId,
-                                             @RequestParam("userId") Long userId) {
-        opsOrderService.resumeOrder(orderId, userId);
+    public CommonResult<Boolean> resumeOrder(@Valid @RequestBody OpsOrderResumeReqVO reqVO) {
+        opsOrderService.resumeOrder(reqVO.getOrderId(), reqVO.getUserId());
        return success(true);
    }

--- a/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/vo/OpsOrderAcceptReqVO.java
+++ b/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/vo/OpsOrderAcceptReqVO.java
@@ -0,0 +1,24 @@
+package com.viewsh.module.ops.controller.admin.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
+import lombok.Data;
+
+/**
+ * 管理后台 - 接单请求 VO
+ *
+ * @author lzh
+ */
+@Schema(description = "管理后台 - 接单 Request VO")
+@Data
+public class OpsOrderAcceptReqVO {
+
+    @Schema(description = "工单ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "1001")
+    @NotNull(message = "工单ID不能为空")
+    private Long orderId;
+
+    @Schema(description = "保洁员ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "2001")
+    @NotNull(message = "保洁员ID不能为空")
+    private Long userId;
+
+}
--- a/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/vo/OpsOrderCompleteReqVO.java
+++ b/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/vo/OpsOrderCompleteReqVO.java
@@ -0,0 +1,27 @@
+package com.viewsh.module.ops.controller.admin.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
+import lombok.Data;
+
+/**
+ * 管理后台 - 完成工单请求 VO
+ *
+ * @author lzh
+ */
+@Schema(description = "管理后台 - 完成工单 Request VO")
+@Data
+public class OpsOrderCompleteReqVO {
+
+    @Schema(description = "工单ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "1001")
+    @NotNull(message = "工单ID不能为空")
+    private Long orderId;
+
+    @Schema(description = "执行人ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "2001")
+    @NotNull(message = "执行人ID不能为空")
+    private Long userId;
+
+    @Schema(description = "完成备注", example = "已完成清洁")
+    private String remark;
+
+}
--- a/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/vo/OpsOrderPauseReqVO.java
+++ b/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/vo/OpsOrderPauseReqVO.java
@@ -0,0 +1,29 @@
+package com.viewsh.module.ops.controller.admin.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import lombok.Data;
+
+/**
+ * 管理后台 - 暂停工单请求 VO
+ *
+ * @author lzh
+ */
+@Schema(description = "管理后台 - 暂停工单 Request VO")
+@Data
+public class OpsOrderPauseReqVO {
+
+    @Schema(description = "工单ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "1001")
+    @NotNull(message = "工单ID不能为空")
+    private Long orderId;
+
+    @Schema(description = "保洁员ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "2001")
+    @NotNull(message = "保洁员ID不能为空")
+    private Long userId;
+
+    @Schema(description = "暂停原因", requiredMode = Schema.RequiredMode.REQUIRED, example = "P0紧急工单插队")
+    @NotBlank(message = "暂停原因不能为空")
+    private String reason;
+
+}
--- a/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/vo/OpsOrderResumeReqVO.java
+++ b/viewsh-module-ops/viewsh-module-ops-server/src/main/java/com/viewsh/module/ops/controller/admin/vo/OpsOrderResumeReqVO.java
@@ -0,0 +1,24 @@
+package com.viewsh.module.ops.controller.admin.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
+import lombok.Data;
+
+/**
+ * 管理后台 - 恢复工单请求 VO
+ *
+ * @author lzh
+ */
+@Schema(description = "管理后台 - 恢复工单 Request VO")
+@Data
+public class OpsOrderResumeReqVO {
+
+    @Schema(description = "工单ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "1001")
+    @NotNull(message = "工单ID不能为空")
+    private Long orderId;
+
+    @Schema(description = "保洁员ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "2001")
+    @NotNull(message = "保洁员ID不能为空")
+    private Long userId;
+
+}