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: 来源实际到港时间，与预测分开}