优化

order/src/main/java/com/baiyue/order/controller/PlatformUnifiedOrderController.java

@@ -2,9 +2,12 @@ package com.baiyue.order.controller;
 
 import com.baiyue.common.core.api.ApiResponse;
 import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.audit.annotation.BusinessAudit;
 import com.baiyue.common.security.AuthenticatedUser;
 import com.baiyue.order.dto.UnifiedOrderQuery;
 import com.baiyue.order.dto.UnifiedOrderResponse;
+import com.baiyue.order.dto.OrderRequests;
+import com.baiyue.order.service.OrderApplicationService;
 import com.baiyue.order.service.OrderScopeGuard;
 import com.baiyue.order.service.UnifiedOrderQueryService;
 import io.swagger.v3.oas.annotations.Operation;
@@ -17,6 +20,8 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RestController;
 
 /** Platform product-level order query. Legacy first-leg paths remain available. */
@@ -25,6 +30,7 @@ import org.springframework.web.bind.annotation.RestController;
 @RequestMapping("/api/platform/v1/orders")
 public class PlatformUnifiedOrderController {
     @Resource private UnifiedOrderQueryService service;
+    @Resource private OrderApplicationService orderService;
 
     @GetMapping
     @PreAuthorize("hasAuthority('platform:order:list')")
@@ -47,4 +53,17 @@ public class PlatformUnifiedOrderController {
         @PathVariable long orderId) {
         return ApiResponse.success(service.detail(OrderScopeGuard.platform(user, tenantId), orderId, true));
     }
+
+    @PostMapping("/{orderId}/internal-notes")
+    @BusinessAudit(event = "ORDER_INTERNAL_NOTE", resourceType = "FIRST_LEG_ORDER", resourceId = "#orderId", description = "Add internal note / 添加内部备注")
+    @PreAuthorize("hasAuthority('platform:order:note')")
+    @Operation(summary = "添加订单内部备注", description = "添加仅平台内部可见的订单备注。")
+    public ApiResponse<Long> addInternalNote(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam long tenantId,
+        @PathVariable long orderId,
+        @Valid @RequestBody OrderRequests.NoteRequest request) {
+        long scopedTenant = OrderScopeGuard.platform(user, tenantId);
+        return ApiResponse.success(orderService.addNote(scopedTenant, user.userId(), orderId, request.content()));
+    }
 }

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

@@ -52,6 +52,25 @@ paths:
       responses:
         '200': {description: 成功或业务失败，按响应体 code 判断}
         '403': {description: 需要平台身份和 platform:order:list 权限}
+  /api/platform/v1/orders/{orderId}/internal-notes:
+    post:
+      summary: 添加订单内部备注
+      description: 添加仅平台内部可见的订单备注，需要 platform:order:note 权限。
+      parameters:
+        - $ref: '#/components/parameters/UnifiedOrderId'
+        - $ref: '#/components/parameters/UnifiedTenantId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [content]
+              properties:
+                content: {type: string, minLength: 1, maxLength: 2000}
+      responses:
+        '200': {description: 备注添加成功或业务失败，按响应体 code 判断}
+        '403': {description: 需要 platform:order:note 权限}
   /api/merchant/v1/orders:
     get:
       summary: 客户统一订单列表

order/src/test/java/com/baiyue/order/controller/OrderControllerPermissionTest.java

@@ -57,6 +57,12 @@ class OrderControllerPermissionTest {
             AuthenticatedUser.class, long.class);
     }
 
+    @Test
+    void unifiedPlatformInternalNoteRequiresNotePermission() throws Exception {
+        assertAuthority(PlatformUnifiedOrderController.class, "addInternalNote", "hasAuthority('platform:order:note')",
+            AuthenticatedUser.class, long.class, long.class, OrderRequests.NoteRequest.class);
+    }
+
     private void assertAuthority(Class<?> controller, String methodName, String expected, Class<?>... parameterTypes)
         throws NoSuchMethodException {
         Method method = controller.getDeclaredMethod(methodName, parameterTypes);