openapi: 3.0.3
info:
  title: Firstleg Sailing Calendar API
  version: v1
  description: 船期实例、固定周模板、渠道管理、收货事实汇总和已放舱订舱关联。
paths:
  /api/platform/v1/sailings/calendar:
    get:
      summary: 查询船期月历
      description: 按 Asia/Shanghai 自然日仅返回今天及之后开船的船期和同范围汇总。有效已放舱订舱对应的排柜货量保留在其 OPEN/CLOSED 船期，截仓后仍保留；未安排或原船期取消、日期过期的未离仓余量，计入同仓、同渠道最近一班 OPEN 且尚未截仓的船期，按开船时间、船期编号和 ID 稳定排序。只调整展示投影，不改写订舱或排柜归属。响应 nextRefreshAt 为上海本地时间，取下一零点和同仓渠道范围内最近截仓时刻之后 1 毫秒的较早值，截仓查询不受展示月份、船名和港口筛选限制。
      x-permission: platform:firstleg:sailing-calendar:list
      parameters:
        - {name: month, in: query, required: true, schema: {type: string, pattern: '^\\d{4}-\\d{2}$'}}
        - {name: warehouseId, in: query, schema: {type: integer, format: int64}}
        - {name: channelId, in: query, schema: {type: integer, format: int64}}
        - {name: channelCode, in: query, schema: {type: string, maxLength: 64}}
        - {name: departurePortCode, in: query, schema: {type: string, maxLength: 32}}
        - {name: destinationPortCode, in: query, schema: {type: string, maxLength: 32}}
        - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
        - {name: status, in: query, schema: {type: string}}
      responses: {'200': {description: 月历和按船期汇总；nextRefreshAt 为下次自动刷新时间，volumeSummary 和 summary 的 availableBookedCapacityCbm 为扣除已离仓柜后的可用订舱容量，各船期 volumeSummary 的 bookedPlanningCapacityCbm 保留订舱总容量。}}
  /api/platform/v1/sailings:
    post:
      summary: 新增单次船期
      x-permission: platform:firstleg:sailing-calendar:create
      responses: {'200': {description: OK}}
  /api/platform/v1/sailings/{id}:
    get:
      summary: 查询船期详情
      x-permission: platform:firstleg:sailing-calendar:list
      parameters: [{name: id, in: path, required: true, schema: {type: integer, format: int64}}]
      responses: {'200': {description: OK}}
    put:
      summary: 编辑船期
      x-permission: platform:firstleg:sailing-calendar:edit
      parameters: [{name: id, in: path, required: true, schema: {type: integer, format: int64}}]
      responses: {'200': {description: OK}}
  /api/platform/v1/sailings/{id}/history:
    get:
      summary: 查询船期变更历史
      x-permission: platform:firstleg:sailing-calendar:list
      parameters: [{name: id, in: path, required: true, schema: {type: integer, format: int64}}]
      responses: {'200': {description: OK}}
  /api/platform/v1/sailings/{id}/cancel:
    post:
      summary: 取消船期
      x-permission: platform:firstleg:sailing-calendar:edit
      responses: {'200': {description: OK}}
  /api/platform/v1/sailings/{id}/copy:
    post:
      summary: 复制下一班船期
      x-permission: platform:firstleg:sailing-calendar:create
      responses: {'200': {description: OK}}
  /api/platform/v1/sailings/{id}/volume-summary:
    get:
      summary: 查询实收、预报和归班明细
      x-permission: platform:firstleg:sailing-calendar:list
      responses: {'200': {description: OK}}
  /api/platform/v1/sailings/{id}/booking-advice:
    get:
      summary: 查询只读订柜建议
      description: 建议柜数按当前展示的全部待发实测与可核验预计体积除以统一柜型容量向上取整，正货量至少一柜；待补柜先扣除未离仓柜的可用订舱容量后再向上取整，下限为零。已离仓柜按所属柜型需求整柜扣除容量，同柜多票只扣一次。日历、汇总和柜型方案使用相同口径。
      x-permission: platform:firstleg:sailing-calendar:list
      responses: {'200': {description: OK}}
  /api/platform/v1/sailings/{id}/booking-links:
    post:
      summary: 关联一条 RELEASED 海运订舱
      x-permission: platform:firstleg:sailing-booking:link
      responses: {'200': {description: ACTIVE 关联结果}}
  /api/platform/v1/sailing-channels:
    get:
      summary: 查询当前生效船期价格表渠道
      x-permission: platform:firstleg:sailing-calendar:list
      parameters:
        - {name: keyword, in: query, schema: {type: string, maxLength: 64}}
        - {name: status, in: query, schema: {type: string, enum: [ACTIVE, INACTIVE]}}
        - {name: warehouseId, in: query, schema: {type: integer, format: int64, minimum: 1}, description: 按收货仓筛选有有效报价的渠道}
      responses: {'200': {description: OK}}
    post:
      summary: 新增船期渠道
      x-permission: platform:firstleg:sailing-template:manage
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-channels/{id}:
    put:
      summary: 编辑或启停船期渠道
      x-permission: platform:firstleg:sailing-template:manage
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-templates:
    get:
      summary: 查询固定周模板
      x-permission: platform:firstleg:sailing-template:manage
      responses: {'200': {description: OK}}
    post:
      summary: 新增固定周模板
      x-permission: platform:firstleg:sailing-template:manage
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-templates/{id}:
    put:
      summary: 编辑固定周模板
      x-permission: platform:firstleg:sailing-template:manage
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-templates/{id}/generation-preview:
    post:
      summary: 预览模板生成实例
      x-permission: platform:firstleg:sailing-template:manage
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-templates/{id}/generate:
    post:
      summary: 按模板生成实例
      x-permission: platform:firstleg:sailing-template:manage
      responses: {'200': {description: OK}}
  /api/platform/v1/sailings/{id}/exception-reassign:
    post:
      summary: 受限异常重新安排
      x-permission: platform:firstleg:sailing-volume:exception-reassign
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-assignments/exceptions:
    get:
      summary: 查询未安排和晚到待办
      x-permission: platform:firstleg:sailing-calendar:list
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-forecasts:
    post:
      summary: 新增未收货量预报
      x-permission: platform:firstleg:sailing-volume:forecast-manage
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-forecasts/{id}:
    put:
      summary: 修订未收货量预报
      x-permission: platform:firstleg:sailing-volume:forecast-manage
      parameters: [{name: id, in: path, required: true, schema: {type: integer, format: int64}}]
      responses: {'200': {description: 新版本预报}}
  /api/platform/v1/sailing-forecasts/{id}/void:
    post:
      summary: 作废未收货量预报
      x-permission: platform:firstleg:sailing-volume:forecast-manage
      parameters: [{name: id, in: path, required: true, schema: {type: integer, format: int64}}]
      responses: {'200': {description: OK}}
  /api/platform/v1/sailing-forecasts/{id}/bind-receipt:
    post:
      summary: 将实收批次绑定到预报批次
      x-permission: platform:firstleg:sailing-volume:forecast-manage
      parameters: [{name: id, in: path, required: true, schema: {type: integer, format: int64}}]
      responses: {'200': {description: OK}}