feat(appointments): expose bounded terminal pickup calendar

2026-10-10 11:43:47 +08:00
parent 47dc9e8bf6
commit 46ae8ab1c6
9 changed files with 271 additions and 0 deletions
@@ -1,6 +1,48 @@
 openapi: 3.0.3
 info: {title: Firstleg Terminal Drayage API, version: 1.0.0}
 paths:
+  /api/platform/v1/terminal-drayages/calendar:
+    get:
+      summary: 美国目的仓相关的提柜预约日历
+      description: 平台身份，同时要求预约列表和码头拖车列表权限。按原业务预约提柜日期查询，不将实际提柜或预计到仓替代预约时间。美国范围按启用目的仓国家确认，不代表已确认港口所在国。原字段未提供港口时区，timeBasis明确待核实，禁止当作UTC或套用收货仓时区。最多42天、读取1001条以检测截断；返回最多1000条中的美国范围记录，未知目的仓计入unclassifiedCount，不能将缺失数据当零。
+      x-permissions: [platform:appointment:list, 'platform:firstleg:terminal-drayage:list']
+      parameters:
+        - {name: from, in: query, required: true, schema: {type: string, format: date}, description: 包含的原业务当地日期}
+        - {name: to, in: query, required: true, schema: {type: string, format: date}, description: 不包含的原业务当地日期}
+      responses:
+        '200':
+          description: 业务响应，code为200；仓库目录不可用则返回错误，不假装空列表
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    type: object
+                    required: [records, truncated, unclassifiedCount, scopeBasis, timeBasis]
+                    properties:
+                      truncated: {type: boolean}
+                      unclassifiedCount: {type: integer, minimum: 0}
+                      scopeBasis: {type: string, enum: [US_DESTINATION_WAREHOUSE]}
+                      timeBasis: {type: string, enum: [SOURCE_LOCAL_UNSPECIFIED]}
+                      records:
+                        type: array
+                        maxItems: 1000
+                        items:
+                          type: object
+                          properties:
+                            containerBookingId: {type: string, description: 仅用于来源详情定位}
+                            bookingNo: {type: string}
+                            containerNo: {type: string, nullable: true}
+                            destinationPortName: {type: string, nullable: true}
+                            destinationWarehouseCode: {type: string, nullable: true}
+                            fleetSupplierName: {type: string, nullable: true}
+                            pickupAppointmentAt: {type: string, description: 原业务当地时间，无时区偏移，不是UTC时间点}
+                            actualPickupAt: {type: string, nullable: true}
+        '400': {description: 日期范围非法}
+        '403': {description: 非平台身份或权限不足}
+        '503': {description: 无法核对仓库范围}
  /api/platform/v1/terminal-drayages:
    get:
      summary: 批量查询货柜码头拖车及服务端报空预警