feat(appointments): expose authoritative arrival forecast observations

2026-10-10 14:10:17 +08:00
parent 71111bf21b
commit 4b5b639adc
6 changed files with 199 additions and 0 deletions
@@ -0,0 +1,54 @@
+openapi: 3.0.3
+info:
+  title: 预约筹划船期事实内部查询
+  version: 1.0.0
+paths:
+  /internal/firstleg/appointment-forecasts/batch:
+    post:
+      operationId: readAppointmentForecastFacts
+      summary: 批量读取有效柜次最新两个到港船节点观察
+      description: 仅内部服务令牌，不开放公网。最多200个不重复柜次，一次批量读取；按照观察时间及事实ID降序。最新观察没有预计时间时保持空，不沿用旧ETA；实际到港单独返回。缺失或非有效柜次返回空latest/previous。原来源时间没有可靠时区，明确SOURCE_LOCAL_UNSPECIFIED，不转成UTC或伪造备妥时间。
+      security: [{internalToken: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [containerBookingIds]
+              properties:
+                containerBookingIds: {type: array, minItems: 1, maxItems: 200, uniqueItems: true, items: {type: integer, format: int64, minimum: 1}}
+      responses:
+        '200':
+          description: ApiResponse；每个请求柜次恰好一行，按请求顺序
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        containerBookingId: {type: string}
+                        timeBasis: {type: string, enum: [SOURCE_LOCAL_UNSPECIFIED]}
+                        latest: {$ref: '#/components/schemas/Fact'}
+                        previous: {$ref: '#/components/schemas/Fact'}
+        '401': {description: 内部身份缺失、错误或服务端未配置}
+components:
+  securitySchemes:
+    internalToken: {type: apiKey, in: header, name: X-Internal-Service-Token}
+  schemas:
+    Fact:
+      type: object
+      nullable: true
+      properties:
+        containerBookingId: {type: string}
+        factId: {type: string, description: 技术关联标识，不展示为业务编号}
+        providerCode: {type: string, nullable: true}
+        sourceReference: {type: string, nullable: true}
+        observedAt: {type: string, nullable: true, description: 来源观察时间}
+        estimatedAt: {type: string, nullable: true, description: 来源当地预计到港时间，时区未核实}
+        actualAt: {type: string, nullable: true, description: 来源实际到港时间，与预测分开}