优化

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

@@ -2,12 +2,12 @@ openapi: 3.0.3
 info:
   title: Warehouse Pallet API
   version: 1.0.0
-  description: 托盘是可复用标识和称重主数据，不承载 AVAILABLE、RESERVED 或 OCCUPIED 动态状态。
+  description: 托盘是可复用标识和称重主数据；称重候选按当前启用国内仓、同仓归属和未删除资格过滤，不按预占或占用过滤。
 paths:
   /internal/warehouse/v1/pallets/{palletId}/snapshot:
     get:
-      summary: 查询单条托盘主数据快照
-      description: 固定使用平台公共作用域 tenant_id=0，并按 warehouseId 校验归属；不返回状态或可用性。
+      summary: 查询单条当前称重可用托盘快照
+      description: 固定使用平台公共作用域 tenant_id=0，并校验启用国内仓、warehouseId 归属和当前未删除资格。
       parameters:
         - $ref: '#/components/parameters/InternalToken'
         - { in: path, name: palletId, required: true, schema: { type: integer, format: int64, minimum: 1 } }
@@ -18,15 +18,18 @@ paths:
           content: { application/json: { schema: { $ref: '#/components/schemas/PalletSnapshotResponse' } } }
   /internal/warehouse/v1/pallets/snapshots:
     get:
-      summary: 查询仓库全部托盘主数据快照
-      description: 固定使用平台公共作用域 tenant_id=0，返回该仓全部未删除主数据，不按状态或占用过滤。
+      summary: 分页查询仓库当前称重托盘候选
+      description: 固定使用平台公共作用域 tenant_id=0，按启用国内仓、同仓归属和当前未删除资格过滤；托盘可复用，不按预占或占用过滤。
       parameters:
         - $ref: '#/components/parameters/InternalToken'
         - { in: query, name: warehouseId, required: true, schema: { type: integer, format: int64, minimum: 1 } }
+        - { in: query, name: page, required: false, schema: { type: integer, format: int64, minimum: 1, default: 1 } }
+        - { in: query, name: size, required: false, schema: { type: integer, format: int64, minimum: 1, maximum: 100, default: 20 } }
+        - { in: query, name: keyword, required: false, description: 匹配托盘编码或类型, schema: { type: string, maxLength: 50 } }
       responses:
         '200':
           description: 业务响应
-          content: { application/json: { schema: { $ref: '#/components/schemas/PalletSnapshotListResponse' } } }
+          content: { application/json: { schema: { $ref: '#/components/schemas/PalletSnapshotPageResponse' } } }
 components:
   parameters:
     InternalToken:
@@ -61,12 +64,21 @@ components:
           required: [data]
           properties:
             data: { $ref: '#/components/schemas/PalletSnapshot' }
-    PalletSnapshotListResponse:
+    PalletSnapshotPageResponse:
       allOf:
         - { $ref: '#/components/schemas/ApiEnvelope' }
         - type: object
           required: [data]
           properties:
             data:
-              type: array
-              items: { $ref: '#/components/schemas/PalletSnapshot' }
+              type: object
+              required: [records, page, size, total, pages]
+              properties:
+                records:
+                  type: array
+                  maxItems: 100
+                  items: { $ref: '#/components/schemas/PalletSnapshot' }
+                page: { type: integer, format: int64, minimum: 1 }
+                size: { type: integer, format: int64, minimum: 1, maximum: 100 }
+                total: { type: integer, format: int64, minimum: 0 }
+                pages: { type: integer, format: int64, minimum: 0 }