refactor(api): 统一 HTTP 200 响应契约

firstleg/src/main/java/com/baiyue/firstleg/controller/PlatformFulfillmentAssignmentController.java

@@ -54,10 +54,7 @@ public class PlatformFulfillmentAssignmentController {
     )
     @ApiResponses({
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Assignment succeeded / 指派成功"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid tenant or request / 租户或请求参数无效"),
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Platform access required / 需要平台端权限"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "Task not found in target tenant / 目标租户下任务不存在"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "409", description = "Task is closed or concurrently updated / 任务已关闭或发生并发更新")
     })
     @PostMapping("/{taskId}/assignment")
     @PreAuthorize("hasAuthority('platform:firstleg:assignment:assign')")
@@ -101,7 +98,6 @@ public class PlatformFulfillmentAssignmentController {
     @ApiResponses({
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功"),
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "无查看权限"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "任务不存在")
     })
     @GetMapping("/{taskId}")
     @PreAuthorize("hasAuthority('platform:firstleg:task:view')")
@@ -118,7 +114,6 @@ public class PlatformFulfillmentAssignmentController {
     @ApiResponses({
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功"),
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "无查看权限"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "任务不存在")
     })
     @GetMapping("/by-order/{orderId}")
     @PreAuthorize("hasAuthority('platform:firstleg:task:view')")
@@ -135,7 +130,6 @@ public class PlatformFulfillmentAssignmentController {
     @ApiResponses({
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功"),
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "无历史查看权限"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "任务不存在")
     })
     @GetMapping("/{taskId}/assignment-history")
     @PreAuthorize("hasAuthority('platform:firstleg:assignment:history')")

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -1,6 +1,7 @@
 openapi: 3.0.3
 info:
   title: 柏悦头程履约 API
+  description: 业务成功和失败均使用 HTTP 200；仅响应体 code 为字符串 "200" 时表示成功，其他 code 表示失败。
   version: 1.1.0
 security:
   - bearerAuth: []
@@ -17,7 +18,7 @@ paths:
         - {name: status, in: query, schema: {type: string, enum: [PENDING_ASSIGNMENT, ASSIGNED, PROCESSING, COMPLETED, CANCELLED]}}
         - {name: assigneeId, in: query, schema: {type: integer, format: int64}}
       responses:
-        '200': {description: 查询成功}
+        '200': {description: 成功或业务失败，按响应体 code 判断}
         '403': {description: 无查询权限}
   /api/platform/v1/first-leg/tasks/{taskId}:
     get:
@@ -27,9 +28,8 @@ paths:
         - $ref: '#/components/parameters/TenantId'
         - $ref: '#/components/parameters/TaskId'
       responses:
-        '200': {description: 查询成功}
+        '200': {description: 成功或业务失败，按响应体 code 判断}
         '403': {description: 无查看权限}
-        '404': {description: 任务不存在}
   /api/platform/v1/first-leg/tasks/by-order/{orderId}:
     get:
       summary: 按订单查询履约任务
@@ -38,9 +38,8 @@ paths:
         - $ref: '#/components/parameters/TenantId'
         - {name: orderId, in: path, required: true, schema: {type: integer, format: int64}}
       responses:
-        '200': {description: 查询成功}
+        '200': {description: 成功或业务失败，按响应体 code 判断}
         '403': {description: 无查看权限}
-        '404': {description: 任务不存在}
   /api/platform/v1/first-leg/tasks/{taskId}/assignment-history:
     get:
       summary: 分页查询任务分配历史
@@ -51,9 +50,8 @@ paths:
         - $ref: '#/components/parameters/Page'
         - $ref: '#/components/parameters/Size'
       responses:
-        '200': {description: 查询成功}
+        '200': {description: 成功或业务失败，按响应体 code 判断}
         '403': {description: 无历史查看权限}
-        '404': {description: 任务不存在}
   /api/platform/v1/first-leg/tasks/{taskId}/assignment:
     post:
       summary: 分配或改派履约任务
@@ -67,10 +65,8 @@ paths:
           application/json:
             schema: {$ref: '#/components/schemas/AssignRequest'}
       responses:
-        '200': {description: 分配成功}
+        '200': {description: 成功或业务失败，按响应体 code 判断}
         '403': {description: 无分配权限}
-        '404': {description: 任务不存在}
-        '409': {description: 任务已关闭或发生并发更新}
 components:
   securitySchemes:
     bearerAuth:

firstleg/src/test/java/com/baiyue/firstleg/controller/FulfillmentTaskControllerContractTest.java

@@ -49,7 +49,10 @@ class FulfillmentTaskControllerContractTest {
             .contains("/api/platform/v1/first-leg/tasks/by-order/{orderId}:")
             .contains("/api/platform/v1/first-leg/tasks/{taskId}/assignment-history:")
             .contains("platform:firstleg:task:list")
-            .contains("platform:firstleg:assignment:history");
+            .contains("platform:firstleg:assignment:history")
+            .contains("仅响应体 code 为字符串 \"200\" 时表示成功")
+            .doesNotContain("'404':")
+            .doesNotContain("'409':");
     }
 
     private void assertAuthority(String methodName, String permission, Class<?>... parameterTypes)