openapi: 3.0.3
info:
  title: Firstleg Sailing Calendar API
  version: v1
  description: 船期实例、固定周模板、渠道管理、收货事实汇总和已放舱订舱关联。
paths:
  /api/platform/v1/sailings/calendar:
    get:
      summary: 查询船期月历
      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: 月历和按船期汇总}}
  /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: 查询只读订柜建议
      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}}