优化

warehouse/src/main/resources/openapi/supplier-v1.yaml

@@ -15,7 +15,7 @@ paths:
         - { name: region, in: query, schema: { type: string } }
         - { name: status, in: query, schema: { $ref: '#/components/schemas/Status' } }
         - { name: keyword, in: query, description: 供应商名称或联系人, schema: { type: string } }
-      responses: { '200': { description: 统一 ApiResponse 包装的分页结果 } }
+      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/SupplierPageResponse' } } } }, '400': { $ref: '#/components/responses/BadRequest' } }
     post:
       summary: 新增供应商
       description: 权限 platform:supplier:create。
@@ -29,7 +29,7 @@ paths:
       description: 权限 platform:supplier:list。
       security: [{ bearerAuth: [] }]
       parameters: [{ $ref: '#/components/parameters/TenantId' }]
-      responses: { '200': { description: booking/customs/trucking/certificate 计数 } }
+      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/StatsResponse' } } } } }
   /api/platform/v1/suppliers/{id}:
     parameters: [{ name: id, in: path, required: true, schema: { type: integer, format: int64 } }]
     get:
@@ -37,7 +37,7 @@ paths:
       description: 权限 platform:supplier:list。
       security: [{ bearerAuth: [] }]
       parameters: [{ $ref: '#/components/parameters/RequiredTenantId' }]
-      responses: { '200': { description: 统一 ApiResponse 包装的 Supplier } }
+      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/SupplierResponse' } } } } }
     put:
       summary: 编辑供应商
       description: 权限 platform:supplier:edit。
@@ -54,6 +54,20 @@ paths:
       parameters: [{ $ref: '#/components/parameters/RequiredTenantId' }]
       requestBody: { required: true, content: { application/json: { schema: { type: object, required: [status], properties: { status: { $ref: '#/components/schemas/Status' } } } } } }
       responses: { '200': { description: 成功 } }
+  /internal/warehouse/v1/suppliers/{supplierId}:
+    get:
+      summary: 内部服务查询并校验供应商快照
+      description: 仅服务间调用，需 X-Internal-Service-Token；不经 Gateway。可要求 ACTIVE，并校验类别与订舱范围。
+      security: [{ internalServiceToken: [] }]
+      parameters:
+        - { name: supplierId, in: path, required: true, schema: { type: integer, format: int64, minimum: 1 } }
+        - { name: requireActive, in: query, schema: { type: boolean, default: false } }
+        - { name: category, in: query, schema: { $ref: '#/components/schemas/Category' } }
+        - { name: scope, in: query, schema: { $ref: '#/components/schemas/Scope' } }
+      responses:
+        '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/InternalSnapshotResponse' } } } }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
 components:
   parameters:
     TenantId: { name: tenantId, in: query, required: false, schema: { type: integer, format: int64, enum: [0] } }
@@ -80,5 +94,63 @@ components:
         status: { $ref: '#/components/schemas/Status' }
         settlementPeriod: { type: string, enum: [MONTHLY_30, MONTHLY_45, MONTHLY_60, MONTHLY_90, PER_TRANSACTION, IMMEDIATE] }
         remark: { type: string, maxLength: 500 }
+    Supplier:
+      allOf:
+        - $ref: '#/components/schemas/SupplierSave'
+        - type: object
+          required: [id, tenantId]
+          properties:
+            id: { type: integer, format: int64 }
+            tenantId: { type: integer, format: int64, enum: [0] }
+    PageResult:
+      type: object
+      required: [records, total, current, size]
+      properties:
+        records: { type: array, items: { $ref: '#/components/schemas/Supplier' } }
+        total: { type: integer, format: int64 }
+        current: { type: integer, format: int64 }
+        size: { type: integer, format: int64 }
+    Stats:
+      type: object
+      required: [booking, customs, trucking, certificate]
+      properties:
+        booking: { type: integer, format: int64 }
+        customs: { type: integer, format: int64 }
+        trucking: { type: integer, format: int64 }
+        certificate: { type: integer, format: int64 }
+    ApiResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code: { type: string }
+        message: { type: string }
+        data: {}
+        requestId: { type: string }
+        traceId: { type: string }
+    SupplierPageResponse:
+      allOf: [{ $ref: '#/components/schemas/ApiResponse' }, { type: object, properties: { data: { $ref: '#/components/schemas/PageResult' } } }]
+    SupplierResponse:
+      allOf: [{ $ref: '#/components/schemas/ApiResponse' }, { type: object, properties: { data: { $ref: '#/components/schemas/Supplier' } } }]
+    StatsResponse:
+      allOf: [{ $ref: '#/components/schemas/ApiResponse' }, { type: object, properties: { data: { $ref: '#/components/schemas/Stats' } } }]
+    InternalSnapshot:
+      type: object
+      required: [supplierId, name, category, status]
+      properties:
+        supplierId: { type: integer, format: int64 }
+        name: { type: string }
+        category: { $ref: '#/components/schemas/Category' }
+        scope: { $ref: '#/components/schemas/Scope' }
+        status: { $ref: '#/components/schemas/Status' }
+    InternalSnapshotResponse:
+      allOf: [{ $ref: '#/components/schemas/ApiResponse' }, { type: object, properties: { data: { $ref: '#/components/schemas/InternalSnapshot' } } }]
+    Error:
+      type: object
+      properties: { code: { type: string }, message: { type: string }, requestId: { type: string }, traceId: { type: string } }
+  responses:
+    BadRequest: { description: 参数错误, content: { application/json: { schema: { $ref: '#/components/schemas/ApiResponse' } } } }
+    Forbidden: { description: 无权访问, content: { application/json: { schema: { $ref: '#/components/schemas/ApiResponse' } } } }
+    NotFound: { description: 供应商不存在, content: { application/json: { schema: { $ref: '#/components/schemas/ApiResponse' } } } }
   securitySchemes:
     bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
+    internalServiceToken: { type: apiKey, in: header, name: X-Internal-Service-Token }