baiyue-firstleg/lastleg-service/src/main/resources/openapi/fba-appointment-calendar-v1.yaml

openapi: 3.0.3
info:
  title: 跨客户 FBA 预约与日历
  version: 1.0.0
  description: 按同一目的FBA仓合并多个客户的货物，预约号全局唯一。货物明细保留客户归属，只有平台可读取或维护完整预约；不改变库存与客户订单归属。
security:
  - bearerAuth: []
paths:
  /api/platform/v1/last-leg/inbound-plans/fba-appointments/batch:
    post:
      summary: 为同一目的仓的跨客户入仓明细创建预约
      description: '权限：platform:overseas-warehouse:inbound-order:fba-appointment。平台身份限定。客户归属由服务端入仓计划确定，不接受预约主单customerId；同号同内容重放返回原预约，异内容拒绝。已有有效预约的货物不能重复建约。'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - {$ref: '#/components/schemas/AppointmentWrite'}
                - type: object
                  required: [lineIds, appointmentNo]
                  properties:
                    lineIds: {type: array, minItems: 1, maxItems: 500, items: {type: string}}
                    appointmentNo: {type: string, maxLength: 64}
      responses:
        '200': {$ref: '#/components/responses/AppointmentResult'}
        '403': {description: 非平台身份或无写权限}
  /api/platform/v1/last-leg/inbound-plans/fba-appointments/{appointmentNo}:
    parameters:
      - name: appointmentNo
        in: path
        required: true
        schema: {type: string}
    delete:
      summary: 删除未关联有效排车的预约
      description: '平台专用，权限platform:appointment:delete。校验当前版本后原子删除预约及预约明细，不删除客户货物。已有关联有效排车时拒绝。'
      parameters:
        - {name: version, in: query, required: true, schema: {type: integer, minimum: 0}}
      responses:
        '200': {description: 业务响应，成功code为字符串200；版本冲突或已关联排车返回业务错误}
        '403': {description: 无删除权限}
    get:
      summary: 读取完整跨客户预约
      description: '仅平台，权限：platform:appointment:list 或 platform:overseas-warehouse:inbound-order:list。客户只能经原订单/入仓单接口读取自己的货物，不开放整张预约。'
      responses:
        '200': {$ref: '#/components/responses/AppointmentResult'}
        '403': {description: 无读取权限}
    put:
      summary: 按版本更新预约
      description: '权限：platform:overseas-warehouse:inbound-order:fba-appointment。平台限定，版本冲突拒绝；取消不删除货物。恢复时重新校验货物是否已被其他有效预约占用。'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - {$ref: '#/components/schemas/AppointmentWrite'}
                - type: object
                  required: [version]
                  properties:
                    version: {type: integer, minimum: 0}
      responses:
        '200': {$ref: '#/components/responses/AppointmentResult'}
        '403': {description: 无写权限}
  /api/platform/v1/last-leg/inbound-plans/fba-appointments/calendar:
    get:
      operationId: fbaAppointmentCalendar
      summary: 按日期范围查询 FBA 预约
      description: '权限：platform:appointment:list。仅平台身份可读取跨客户预约。固定批量查询预约及关联明细，不逐预约查详情。'
      parameters:
        - name: from
          in: query
          required: true
          description: 包含该日期零点，以现有预约业务日期为准。
          schema: {type: string, format: date}
        - name: to
          in: query
          required: true
          description: 不包含该日期零点；必须晚于from，间隔不超过42天。
          schema: {type: string, format: date}
      responses:
        '200':
          description: 业务响应；成功code为字符串200，空区间返回空数组。
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  message: {type: string}
                  data:
                    type: array
                    items: {$ref: '#/components/schemas/Appointment'}
        '401': {description: 未登录或会话失效}
        '403': {description: 无列表权限}
components:
  responses:
    AppointmentResult:
      description: 业务响应，成功code为字符串200，业务冲突返回对应业务错误码。
      content:
        application/json:
          schema:
            type: object
            properties:
              code: {type: string}
              message: {type: string}
              data: {$ref: '#/components/schemas/Appointment'}
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
  schemas:
    AppointmentWrite:
      type: object
      required: [appointmentAt, expectedLoadingAt, appointmentStatus]
      properties:
        appointmentAt: {type: string, description: 预约开始日期时间}
        appointmentEndAt: {type: string, nullable: true, description: 明确结束时间时必须晚于开始时间；未知留空，不推算}
        expectedLoadingAt: {type: string}
        appointmentStatus: {type: string, enum: [PENDING, SUCCESS, FAILED, CANCELLED]}
        appointmentRemark: {type: string, maxLength: 1000, nullable: true}
    Appointment:
      type: object
      properties:
        id: {type: string, description: 内部标识，不作为展示编号}
        appointmentNo: {type: string}
        appointmentAt: {type: string, description: 业务日期时间，不含时区偏移}
        appointmentEndAt: {type: string, nullable: true}
        version: {type: integer, minimum: 0}
        expectedLoadingAt: {type: string}
        appointmentStatus: {type: string, enum: [PENDING, SUCCESS, FAILED, CANCELLED]}
        appointmentRemark: {type: string, nullable: true}
        fbaWarehouseCode: {type: string}
        selectedCount: {type: integer}
        createdBy: {type: string, nullable: true}
        createdAt: {type: string}
        updatedAt: {type: string}
        items:
          type: array
          items:
            type: object
            properties:
              id: {type: string}
              customerId: {type: string, description: 本票货物客户归属，不在预约主单指定客户}
              planId: {type: string}
              lineId: {type: string}
              orderId: {type: string}
              inboundCode: {type: string}
              fbaWarehouseCode: {type: string}