From 6964e3afa3a223049fe10c4793d18e573c61328e Mon Sep 17 00:00:00 2001
From: ouyangxq <775153912@qq.com>
Date: Thu, 6 Aug 2026 19:03:09 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../PlatformUnifiedOrderController.java       | 19 +++++++++++++++++++
 .../src/main/resources/openapi/order-v1.yaml  | 19 +++++++++++++++++++
 .../OrderControllerPermissionTest.java        |  6 ++++++
 3 files changed, 44 insertions(+)

diff --git a/order/src/main/java/com/baiyue/order/controller/PlatformUnifiedOrderController.java b/order/src/main/java/com/baiyue/order/controller/PlatformUnifiedOrderController.java
index 30a503f59..b01f39eab 100644
--- a/order/src/main/java/com/baiyue/order/controller/PlatformUnifiedOrderController.java
+++ b/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()));
+    }
 }
diff --git a/order/src/main/resources/openapi/order-v1.yaml b/order/src/main/resources/openapi/order-v1.yaml
index 408cbd66d..c952b3ae2 100644
--- a/order/src/main/resources/openapi/order-v1.yaml
+++ b/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: 客户统一订单列表
diff --git a/order/src/test/java/com/baiyue/order/controller/OrderControllerPermissionTest.java b/order/src/test/java/com/baiyue/order/controller/OrderControllerPermissionTest.java
index 80b72d7d4..f1716f81d 100644
--- a/order/src/test/java/com/baiyue/order/controller/OrderControllerPermissionTest.java
+++ b/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);