openapi: "3.0.3"
info:
  title: "预约工作事项"
  version: "1.0.0"
  description: "工作事项只保存需求、路线、责任、跟进及影响基线。提柜/还空、预约、PDA和Fleet计划与执行事实由原业务提供。独立DDL仍需总控集成。"
security:
  -
    bearerAuth: []
paths:
  /api/platform/v1/last-leg/appointment-work/items/resolve:
    get:
      operationId: appointmentWorkResolveBatch
      summary: 按当前权威批次精确进入送仓事项
      description: "要求platform:appointment:list及原来源读取资格。batchKey使用原业务返回的完整稳定键；customerId来自所选客户货源。精确匹配返回detail，未传客户且存在多个客户时detail为空并返回candidates，必须选择后重新解析；不得选首项或回退已替代旧批次。需求关系未同步返回409，未生成返回404。"
      parameters:
        - name: batchKey
          in: query
          required: true
          schema:
            type: string
            pattern: '^(FBA_APPOINTMENT|DISPATCH):[1-9][0-9]*$'
        - name: customerId
          in: query
          required: false
          schema: {type: string, minLength: 1}
      responses:
        200:
          description: data为客户送仓精确解析结果或可见客户候选
          content:
            application/json:
              schema:
                type: object
                required: [code, data]
                properties:
                  code: {type: string}
                  message: {type: string, nullable: true}
                  data:
                    $ref: '#/components/schemas/BatchWorkResolution'
        400:
          description: 批次键无效
        403:
          description: 缺少平台或原来源读取资格
        404:
          description: 当前批次未生成活动送仓事项
        409:
          description: 需求关系尚未同步或存在不唯一的事项关系
  /api/platform/v1/last-leg/appointment-work/calendar:
    get:
      operationId: "appointmentWorkCalendar"
      summary: "完整日期区间的工作聚合"
      description: "platform:appointment:list并逐事项核验来源读取资格；最大62个当地日期；五个桶互斥；到港参考不计工作量。完整扫描未就绪、scopeVersion变化或任一权威事实失败均拒绝伪造统计。"
      parameters:
        -
          name: "from"
          in: "query"
          required: true
          schema:
            type: "string"
            format: "date"
        -
          name: "to"
          in: "query"
          required: true
          schema:
            type: "string"
            format: "date"
        -
          name: "flow"
          in: "query"
          required: false
          schema:
            "$ref": "#/components/schemas/Flow"
        -
          name: "types"
          in: "query"
          required: false
          schema:
            type: "array"
            items:
              type: "string"
              enum:
                - "PICKUP"
                - "WAREHOUSE_RECEIPT"
                - "DELIVERY"
                - "TRANSPORT"
                - "EMPTY_RETURN"
      responses:
        200:
          description: "code为字符串200时成功；data为业务结果"
          content:
            application/json:
              schema:
                type: "object"
                additionalProperties: false
                required:
                  - "code"
                  - "data"
                properties:
                  code:
                    type: "string"
                  message:
                    type: "string"
                    nullable: true
                  data:
                    "$ref": "#/components/schemas/CalendarResult"
        400:
          description: "参数、时区或判别式payload不合法"
        403:
          description: "非平台或缺少关联来源/命令权限"
        404:
          description: "事项不存在"
        409:
          description: "版本、来源集合、影响版本或并发冲突；必须刷新"
        503:
          description: "权威来源/原域适配/目录未就绪；不得显示零值或假成功"
  /api/platform/v1/last-leg/appointment-work/summary:
    get:
      operationId: "appointmentWorkSummary"
      summary: "全部活动事项全局统计"
      description: "不接收月份/流程/类型条件。集合可重叠；无日期有跟进日仍是未定日期。未知地点提醒按America/Los_Angeles业务默认时区判断并在missingFields说明。"
      responses:
        200:
          description: "code为字符串200时成功；data为业务结果"
          content:
            application/json:
              schema:
                type: "object"
                additionalProperties: false
                required:
                  - "code"
                  - "data"
                properties:
                  code:
                    type: "string"
                  message:
                    type: "string"
                    nullable: true
                  data:
                    "$ref": "#/components/schemas/Summary"
        400:
          description: "参数、时区或判别式payload不合法"
        403:
          description: "非平台或缺少关联来源/命令权限"
        404:
          description: "事项不存在"
        409:
          description: "版本、来源集合、影响版本或并发冲突；必须刷新"
        503:
          description: "权威来源/原域适配/目录未就绪；不得显示零值或假成功"
  /api/platform/v1/last-leg/appointment-work/items:
    get:
      operationId: "appointmentWorkItems"
      summary: "工作明细"
      description: "ALL不传date时排除已完成；传date时包含当日已完成。共享车次按稳定车次键仅一项，containers中任一柜均可命中。"
      parameters:
        -
          name: "view"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "ALL"
              - "FOLLOW_TODAY"
              - "OVERDUE"
              - "UNDATED"
              - "REVIEW"
            default: "ALL"
        -
          name: "page"
          in: "query"
          required: false
          schema:
            type: "integer"
            minimum: 1
            default: 1
        -
          name: "size"
          in: "query"
          required: false
          schema:
            type: "integer"
            minimum: 1
            maximum: 100
            default: 20
        -
          name: "date"
          in: "query"
          required: false
          schema:
            type: "string"
            format: "date"
        -
          name: "flow"
          in: "query"
          required: false
          schema:
            "$ref": "#/components/schemas/Flow"
        -
          name: "types"
          in: "query"
          required: false
          schema:
            type: "array"
            items:
              "$ref": "#/components/schemas/Type"
        -
          name: "containerBookingId"
          in: "query"
          required: false
          schema:
            type: "string"
        -
          name: "bucket"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "PENDING"
              - "CONFIRMED"
              - "NO_BOOKING_REQUIRED"
              - "REVIEW"
              - "COMPLETED"
        -
          name: "keyword"
          in: "query"
          required: false
          schema:
            type: "string"
            maxLength: 128
      responses:
        200:
          description: "code为字符串200时成功；data为业务结果"
          content:
            application/json:
              schema:
                type: "object"
                additionalProperties: false
                required:
                  - "code"
                  - "data"
                properties:
                  code:
                    type: "string"
                  message:
                    type: "string"
                    nullable: true
                  data:
                    "$ref": "#/components/schemas/Page"
        400:
          description: "参数、时区或判别式payload不合法"
        403:
          description: "非平台或缺少关联来源/命令权限"
        404:
          description: "事项不存在"
        409:
          description: "版本、来源集合、影响版本或并发冲突；必须刷新"
        503:
          description: "权威来源/原域适配/目录未就绪；不得显示零值或假成功"
  /api/platform/v1/last-leg/appointment-work/items/{workItemKey}:
    parameters:
      -
        name: "workItemKey"
        in: "path"
        required: true
        schema:
          type: "string"
    get:
      operationId: "appointmentWorkDetail"
      summary: "事项、业务引用、关联与历史"
      responses:
        200:
          description: "code为字符串200时成功；data为业务结果"
          content:
            application/json:
              schema:
                type: "object"
                additionalProperties: false
                required:
                  - "code"
                  - "data"
                properties:
                  code:
                    type: "string"
                  message:
                    type: "string"
                    nullable: true
                  data:
                    "$ref": "#/components/schemas/WorkDetail"
        400:
          description: "参数、时区或判别式payload不合法"
        403:
          description: "非平台或缺少关联来源/命令权限"
        404:
          description: "事项不存在"
        409:
          description: "版本、来源集合、影响版本或并发冲突；必须刷新"
        503:
          description: "权威来源/原域适配/目录未就绪；不得显示零值或假成功"
  /api/platform/v1/last-leg/appointment-work/items/{workItemKey}/commands:
    parameters:
      -
        name: "workItemKey"
        in: "path"
        required: true
        schema:
          type: "string"
    post:
      operationId: "appointmentWorkCommand"
      summary: "执行事项自有数据命令"
      description: "SAVE_FOLLOWUP/RESOLVE_REVIEW要求platform:appointment:followup；其他命令要求platform:appointment:manage-work，同时核验list与来源资格。USER本人接手；外部责任方须运营记录明确反馈。只确认责任，不写实际还空。事务幂等键按事项唯一，同操作者同内容重放原响应；未知字段拒绝；不支持标为完成。"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CommandRequest"
      responses:
        200:
          description: "code为字符串200时成功；data为业务结果"
          content:
            application/json:
              schema:
                type: "object"
                additionalProperties: false
                required:
                  - "code"
                  - "data"
                properties:
                  code:
                    type: "string"
                  message:
                    type: "string"
                    nullable: true
                  data:
                    "$ref": "#/components/schemas/CommandResult"
        400:
          description: "参数、时区或判别式payload不合法"
        403:
          description: "非平台或缺少关联来源/命令权限"
        404:
          description: "事项不存在"
        409:
          description: "版本、来源集合、影响版本或并发冲突；必须刷新"
        503:
          description: "权威来源/原域适配/目录未就绪；不得显示零值或假成功"
  /internal/lastleg/appointment-work/synchronize:
    post:
      operationId: "synchronizeAppointmentWork"
      summary: "服务端分页同步完整已开船事项"
      description: "仅X-Internal-Service-Token，不经公网Gateway。由后台编排分页调用；GET不写库。afterContainerBookingId为空开始完整扫描，逐页回传nextCursor直到complete。跨页scopeVersion漂移拒绝；首次完整扫描前查询拒绝零值。未出现在新候选页的旧未还空工作保留。"
      security:
        -
          internalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SyncRequest"
      responses:
        200:
          description: "code为字符串200时成功；data为业务结果"
          content:
            application/json:
              schema:
                type: "object"
                additionalProperties: false
                required:
                  - "code"
                  - "data"
                properties:
                  code:
                    type: "string"
                  message:
                    type: "string"
                    nullable: true
                  data:
                    "$ref": "#/components/schemas/SyncResult"
        400:
          description: "参数、时区或判别式payload不合法"
        403:
          description: "非平台或缺少关联来源/命令权限"
        404:
          description: "事项不存在"
        409:
          description: "版本、来源集合、影响版本或并发冲突；必须刷新"
        503:
          description: "权威来源/原域适配/目录未就绪；不得显示零值或假成功"
  /internal/lastleg/appointment-work/containers/{id}/route:
    get:
      operationId: readAppointmentWorkContainerRoute
      summary: 读取本地已确认路线，不锁工作守卫或回调Firstleg
      security: [{internalToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string}}
      responses:
        '200':
          description: ApiResponse包装的本地持久路线
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  message: {type: string, nullable: true}
                  data:
                    type: object
                    required: [flow]
                    properties:
                      flow: {type: string, enum: [TRANSFER, DIRECT, UNKNOWN]}
        '403': {description: 内部身份无效}
        '409': {description: 当前有效事项路线冲突}
  /api/platform/v1/last-leg/appointment-planning/batches/{batchKey}/dispatch-candidates:
    get:
      operationId: appointmentWorkBatchDispatchCandidates
      summary: 按不可变FBA预约批次读取逐票实物排车候选
      description: 客户仓使用原排车单批次键DISPATCH:<id>，逐票实物由原排车事务生成；按工作项batchNo进入原排车单并关联车次，不调用本FBA候选接口。平台主体且同时具有platform:appointment:list、platform:overseas-warehouse:last-mile-order:list、platform:overseas-warehouse:inbound-order:list。候选不足不补造数量；超过500托拒绝截断。写入沿用dispatches/pre-arrange及drafts/pre-arrange的batchAllocations，跨客户分别生成排车单后绑定同一车次。
      security: [{bearerAuth: []}]
      parameters:
        - {name: batchKey, in: path, required: true, schema: {type: string}}
      responses:
        '200':
          description: ApiResponse包装的完整候选及阻断原因
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  message: {type: string, nullable: true}
                  data: {$ref: '#/components/schemas/BatchDispatchCandidates'}
        '403': {description: 非平台主体或无来源读取权限}
        '409': {description: 批次或实物范围不能完整读取}
        '503': {description: 原来源目录不可用}
components:
  securitySchemes:
    bearerAuth:
      type: "http"
      scheme: "bearer"
      bearerFormat: "JWT"
    internalToken:
      type: "apiKey"
      in: "header"
      name: "X-Internal-Service-Token"
  schemas:
    Flow:
      type: "string"
      enum:
        - "TRANSFER"
        - "DIRECT"
        - "UNKNOWN"
    Type:
      type: "string"
      enum:
        - "ROUTE"
        - "PICKUP"
        - "WAREHOUSE_RECEIPT"
        - "DELIVERY"
        - "TRANSPORT"
        - "EMPTY_RETURN"
    Command:
      type: "string"
      enum:
        - "CONFIRM_ROUTE"
        - "SAVE_FOLLOWUP"
        - "RESOLVE_REVIEW"
        - "SAVE_REQUIREMENT"
        - "HANDOFF_RETURN"
        - "ACCEPT_RETURN"
    ActionCode:
      type: "string"
      enum:
        - "VIEW_DETAIL"
        - "SAVE_PLAN"
        - "REQUEST_BOOKING"
        - "RECORD_CONFIRMATION"
        - "CHANGE_BOOKING"
        - "CANCEL_BOOKING"
        - "VERIFY_CARGO"
        - "EDIT_BATCH"
        - "ARRANGE_TRANSPORT"
        - "RECORD_EXECUTION"
        - "CONFIRM_ROUTE"
        - "SAVE_FOLLOWUP"
        - "RESOLVE_REVIEW"
        - "SAVE_REQUIREMENT"
        - "HANDOFF_RETURN"
        - "ACCEPT_RETURN"
        - "VIEW_HISTORY"
    Slot:
      type: "object"
      additionalProperties: false
      required:
        - "date"
        - "startTime"
        - "endDate"
        - "endTime"
        - "timezone"
      properties:
        date:
          type: "string"
          format: "date"
        startTime:
          type: "string"
          pattern: "^\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$"
          nullable: true
        endDate:
          type: "string"
          format: "date"
          nullable: true
          description: "与endTime同时为空或同时填写；不推断次日"
        endTime:
          type: "string"
          pattern: "^\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$"
          nullable: true
        timezone:
          type: "string"
          nullable: true
          description: "原业务缺失时区可为空并标SOURCE_TIMEZONE；SAVE_REQUIREMENT写入仍须有效IANA时区"
    Actual:
      type: "object"
      additionalProperties: false
      description: "occurredAt与localOccurredAt至少一个非空；未知时区按原始当地日期展示，不推断UTC"
      required:
        - "occurredAt"
        - "localOccurredAt"
        - "timezone"
      properties:
        occurredAt:
          type: "string"
          format: "date-time"
          nullable: true
        localOccurredAt:
          type: "string"
          description: "无偏移的原始当地日期时间"
          nullable: true
        timezone:
          type: "string"
          nullable: true
    Owner:
      type: "object"
      additionalProperties: false
      required:
        - "id"
        - "name"
      properties:
        id:
          type: "string"
        name:
          type: "string"
    ContainerReference:
      type: "object"
      additionalProperties: false
      required:
        - "containerBookingId"
        - "bookingNo"
        - "containerNo"
      properties:
        containerBookingId:
          type: "string"
        bookingNo:
          type: "string"
          nullable: true
        containerNo:
          type: "string"
          nullable: true
    SourceReference:
      type: "object"
      additionalProperties: false
      required:
        - "customerId"
        - "sourceKey"
        - "destinationKey"
      properties:
        customerId:
          type: "string"
        sourceKey:
          type: "string"
          pattern: "^(ORDER|BOOKING):.+$"
        destinationKey:
          type: "string"
          nullable: true
    BusinessReference:
      type: "object"
      additionalProperties: false
      required:
        - "kind"
        - "key"
        - "businessNo"
        - "label"
      properties:
        kind:
          type: "string"
        key:
          type: "string"
        businessNo:
          type: "string"
          nullable: true
        label:
          type: "string"
    Responsibility:
      type: "object"
      additionalProperties: false
      required:
        - "kind"
        - "id"
        - "name"
      properties:
        kind:
          type: "string"
          enum:
            - "USER"
            - "SUPPLIER"
            - "EXTERNAL"
        id:
          type: "string"
          nullable: true
        name:
          type: "string"
          minLength: 1
          maxLength: 200
    WorkTarget:
      type: "object"
      additionalProperties: false
      required:
        - "kind"
        - "command"
      properties:
        kind:
          type: "string"
          enum:
            - "WORK_COMMAND"
        command:
          "$ref": "#/components/schemas/Command"
    CargoTarget:
      type: "object"
      additionalProperties: false
      required:
        - "kind"
        - "source"
      properties:
        kind:
          type: "string"
          enum:
            - "CARGO_VERIFICATION"
        source:
          "$ref": "#/components/schemas/SourceReference"
    AppointmentTarget:
      type: "object"
      additionalProperties: false
      required:
        - "kind"
        - "appointmentId"
        - "batchKey"
        - "sources"
      properties:
        kind:
          type: "string"
          enum:
            - "FBA_APPOINTMENT"
        appointmentId:
          type: "string"
          nullable: true
        batchKey:
          type: "string"
          nullable: true
        sources:
          type: "array"
          items:
            "$ref": "#/components/schemas/SourceReference"
    ContainerTarget:
      type: "object"
      additionalProperties: false
      required:
        - "kind"
        - "containerBookingId"
      properties:
        kind:
          type: "string"
          enum:
            - "FIRSTLEG_CONTAINER"
        containerBookingId:
          type: "string"
    TripTarget:
      type: "object"
      description: FLEET_TRIP动作。tripId存在时维护原车次，业务车次号取工作项businessNo。未绑定车次的客户仓批次以DISPATCH:<原排车单不可变ID>放入batchKeys，原排车业务号取工作项batchNo；直接进入该原排车单关联车次，不能解析为FBA预约或再建立排车。FBA批次仍通过实物候选及batchAllocations安排。
      additionalProperties: false
      required:
        - "kind"
        - "tripId"
        - "batchKeys"
      properties:
        kind:
          type: "string"
          enum:
            - "FLEET_TRIP"
        tripId:
          type: "string"
          nullable: true
        batchKeys:
          type: "array"
          items:
            type: "string"
    ReceiptTarget:
      type: "object"
      additionalProperties: false
      required:
        - "kind"
        - "inboundPlanId"
        - "inboundPlanNo"
        - "customerId"
        - "containerBookingId"
      properties:
        kind:
          type: "string"
          enum:
            - "WAREHOUSE_RECEIPT"
        inboundPlanId:
          type: "string"
          nullable: true
        inboundPlanNo:
          type: "string"
          nullable: true
        customerId:
          type: "string"
          nullable: true
        containerBookingId:
          type: "string"
    ReadTarget:
      type: "object"
      description: 原业务只读入口。客户仓派送使用DELIVERY引用（key与businessNo均为派送业务号）；DISPATCH引用的key为DISPATCH:<原排车单ID>，businessNo为原排车单号。仅供导航，不代表已经执行写入动作。
      additionalProperties: false
      required:
        - "kind"
        - "references"
      properties:
        kind:
          type: "string"
          enum:
            - "READ_ONLY"
        references:
          type: "array"
          items:
            "$ref": "#/components/schemas/BusinessReference"
    ActionTarget:
      oneOf:
        -
          "$ref": "#/components/schemas/WorkTarget"
        -
          "$ref": "#/components/schemas/CargoTarget"
        -
          "$ref": "#/components/schemas/AppointmentTarget"
        -
          "$ref": "#/components/schemas/ContainerTarget"
        -
          "$ref": "#/components/schemas/TripTarget"
        -
          "$ref": "#/components/schemas/ReceiptTarget"
        -
          "$ref": "#/components/schemas/ReadTarget"
      discriminator:
        propertyName: "kind"
        mapping:
          WORK_COMMAND: "#/components/schemas/WorkTarget"
          CARGO_VERIFICATION: "#/components/schemas/CargoTarget"
          FBA_APPOINTMENT: "#/components/schemas/AppointmentTarget"
          FIRSTLEG_CONTAINER: "#/components/schemas/ContainerTarget"
          FLEET_TRIP: "#/components/schemas/TripTarget"
          WAREHOUSE_RECEIPT: "#/components/schemas/ReceiptTarget"
          READ_ONLY: "#/components/schemas/ReadTarget"
    Action:
      type: "object"
      additionalProperties: false
      required:
        - "code"
        - "label"
        - "targetWorkItemKey"
        - "target"
      properties:
        code:
          "$ref": "#/components/schemas/ActionCode"
        label:
          type: "string"
        targetWorkItemKey:
          type: "string"
          nullable: true
        target:
          "$ref": "#/components/schemas/ActionTarget"
    WorkItem:
      type: "object"
      additionalProperties: false
      required:
        - "workItemKey"
        - "version"
        - "type"
        - "flow"
        - "title"
        - "businessNo"
        - "containers"
        - "requirementKey"
        - "batchKey"
        - "batchNo"
        - "originName"
        - "destinationName"
        - "planStatus"
        - "executionStatus"
        - "reviewRequired"
        - "target"
        - "confirmed"
        - "actual"
        - "calendarDate"
        - "dateBasis"
        - "timezone"
        - "owner"
        - "followupDate"
        - "overdueReasons"
        - "allowedActions"
        - "nextAction"
        - "blockReasons"
        - "missingFields"
      properties:
        workItemKey:
          type: "string"
        version:
          type: "integer"
          minimum: 0
        type:
          "$ref": "#/components/schemas/Type"
        flow:
          "$ref": "#/components/schemas/Flow"
        title:
          type: "string"
        businessNo:
          type: "string"
          nullable: true
        containers:
          type: "array"
          items:
            "$ref": "#/components/schemas/ContainerReference"
        requirementKey:
          type: "string"
          nullable: true
        batchKey:
          type: "string"
          nullable: true
        batchNo:
          type: "string"
          nullable: true
        originName:
          type: "string"
          nullable: true
        destinationName:
          type: "string"
          nullable: true
        planStatus:
          type: "string"
          enum:
            - "UNPLANNED"
            - "TARGET_SET"
            - "AWAITING_REPLY"
            - "CONFIRMED"
            - "NOT_REQUIRED"
        executionStatus:
          type: "string"
          enum:
            - "PENDING"
            - "IN_PROGRESS"
            - "COMPLETED"
        reviewRequired:
          type: "boolean"
        target:
          "$ref": "#/components/schemas/Slot"
          nullable: true
        confirmed:
          "$ref": "#/components/schemas/Slot"
          nullable: true
        actual:
          "$ref": "#/components/schemas/Actual"
          nullable: true
        calendarDate:
          type: "string"
          format: "date"
          nullable: true
        dateBasis:
          type: "string"
          enum:
            - "ACTUAL"
            - "CONFIRMED"
            - "TARGET"
            - "NONE"
        timezone:
          type: "string"
          nullable: true
        owner:
          "$ref": "#/components/schemas/Owner"
          nullable: true
        followupDate:
          type: "string"
          format: "date"
          nullable: true
        overdueReasons:
          type: "array"
          items:
            type: "string"
        allowedActions:
          type: "array"
          items:
            "$ref": "#/components/schemas/Action"
        nextAction:
          "$ref": "#/components/schemas/Action"
          nullable: true
          description: "按当前权限和白名单目标引导；已确认送仓预约可指向本批车辆安排或本车复核，不代表授权发车。取消预约沿原批次重新预约，不恢复旧确认。"
        blockReasons:
          type: "array"
          items:
            type: "string"
        missingFields:
          type: "array"
          description: "未完成事项分别提示负责人、下次跟进日期和作业日期等缺口；跟进日期不能作为作业日历日期。"
          items:
            type: "string"
    Review:
      type: "object"
      additionalProperties: false
      required:
        - "version"
        - "reasons"
      properties:
        version:
          type: "integer"
          minimum: 0
        reasons:
          type: "array"
          items:
            type: "string"
    RequirementDetails:
      type: "object"
      additionalProperties: false
      required:
        - "bookingRequired"
        - "receivingRequirements"
        - "reason"
      properties:
        bookingRequired:
          type: "boolean"
        receivingRequirements:
          type: "string"
        reason:
          type: "string"
          nullable: true
    ReturnHandoff:
      type: "object"
      additionalProperties: false
      required:
        - "version"
        - "from"
        - "to"
        - "status"
        - "reason"
      properties:
        version:
          type: "integer"
          minimum: 0
        from:
          "$ref": "#/components/schemas/Responsibility"
        to:
          "$ref": "#/components/schemas/Responsibility"
        status:
          type: "string"
          enum:
            - "PENDING_ACCEPTANCE"
            - "ACCEPTED"
        reason:
          type: "string"
    HistoryEntry:
      type: "object"
      additionalProperties: false
      required:
        - "occurredAt"
        - "operatorName"
        - "action"
        - "summary"
      properties:
        occurredAt:
          type: "string"
          format: "date-time"
        operatorName:
          type: "string"
          nullable: true
        action:
          type: "string"
        summary:
          type: "string"
    BatchWorkResolution:
      type: object
      required: [batchKey, candidates]
      properties:
        batchKey: {type: string}
        customerId: {type: string, nullable: true}
        detail:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/WorkDetail'
        candidates:
          type: array
          items:
            type: object
            required: [customerId, workItemKey]
            properties:
              customerId: {type: string}
              workItemKey: {type: string}
              batchNo: {type: string, nullable: true}
    WorkDetail:
      type: "object"
      additionalProperties: false
      required:
        - "item"
        - "relatedItems"
        - "references"
        - "history"
        - "review"
        - "requirement"
        - "returnHandoff"
      properties:
        item:
          "$ref": "#/components/schemas/WorkItem"
        relatedItems:
          type: "array"
          items:
            "$ref": "#/components/schemas/WorkItem"
        references:
          type: "array"
          items:
            "$ref": "#/components/schemas/BusinessReference"
        history:
          type: "array"
          items:
            "$ref": "#/components/schemas/HistoryEntry"
        review:
          "$ref": "#/components/schemas/Review"
          nullable: true
        requirement:
          "$ref": "#/components/schemas/RequirementDetails"
          nullable: true
        returnHandoff:
          "$ref": "#/components/schemas/ReturnHandoff"
          nullable: true
    Summary:
      type: "object"
      additionalProperties: false
      required:
        - "all"
        - "followToday"
        - "overdue"
        - "undated"
        - "review"
      properties:
        all:
          type: "integer"
          minimum: 0
        followToday:
          type: "integer"
          minimum: 0
        overdue:
          type: "integer"
          minimum: 0
        undated:
          type: "integer"
          minimum: 0
        review:
          type: "integer"
          minimum: 0
    BucketCounts:
      type: "object"
      additionalProperties: false
      required:
        - "pending"
        - "confirmed"
        - "noBookingRequired"
        - "review"
        - "completed"
      properties:
        pending:
          type: "integer"
          minimum: 0
        confirmed:
          type: "integer"
          minimum: 0
        noBookingRequired:
          type: "integer"
          minimum: 0
        review:
          type: "integer"
          minimum: 0
        completed:
          type: "integer"
          minimum: 0
    DayAggregate:
      type: "object"
      additionalProperties: false
      required:
        - "date"
        - "total"
        - "typeCounts"
        - "counts"
      properties:
        date:
          type: "string"
          format: "date"
        total:
          type: "integer"
          minimum: 0
        typeCounts:
          type: "object"
          additionalProperties:
            type: "integer"
            minimum: 0
        counts:
          "$ref": "#/components/schemas/BucketCounts"
    CalendarResult:
      type: "object"
      additionalProperties: false
      required:
        - "from"
        - "to"
        - "total"
        - "counts"
        - "days"
      properties:
        from:
          type: "string"
          format: "date"
        to:
          type: "string"
          format: "date"
        total:
          type: "integer"
          minimum: 0
        counts:
          "$ref": "#/components/schemas/BucketCounts"
        days:
          type: "array"
          items:
            "$ref": "#/components/schemas/DayAggregate"
    Page:
      type: "object"
      additionalProperties: false
      required:
        - "records"
        - "page"
        - "size"
        - "total"
        - "pages"
      properties:
        records:
          type: "array"
          items:
            "$ref": "#/components/schemas/WorkItem"
        page:
          type: "integer"
          minimum: 1
        size:
          type: "integer"
          minimum: 1
          maximum: 100
        total:
          type: "integer"
          minimum: 0
        pages:
          type: "integer"
          minimum: 0
    CommandResult:
      type: "object"
      additionalProperties: false
      required:
        - "item"
        - "affectedWorkItemKeys"
      properties:
        item:
          "$ref": "#/components/schemas/WorkItem"
        affectedWorkItemKeys:
          type: "array"
          items:
            type: "string"
    SyncRequest:
      type: "object"
      additionalProperties: false
      required:
        - "size"
      properties:
        afterContainerBookingId:
          type: "string"
          nullable: true
          maxLength: 128
        size:
          type: "integer"
          minimum: 1
          maximum: 100
    SyncResult:
      type: "object"
      additionalProperties: false
      required:
        - "sources"
        - "created"
        - "nextCursor"
        - "complete"
      properties:
        sources:
          type: "integer"
          minimum: 0
        created:
          type: "integer"
          minimum: 0
        nextCursor:
          type: "string"
          nullable: true
        complete:
          type: "boolean"
    CONFIRM_ROUTERequest:
      type: "object"
      additionalProperties: false
      required:
        - "command"
        - "expectedVersion"
        - "idempotencyKey"
        - "payload"
      properties:
        command:
          type: "string"
          enum:
            - "CONFIRM_ROUTE"
        expectedVersion:
          type: "integer"
          minimum: 0
        idempotencyKey:
          type: "string"
          minLength: 1
          maxLength: 64
        payload:
          type: "object"
          additionalProperties: false
          required:
            - "flow"
          properties:
            flow:
              type: "string"
              enum:
                - "TRANSFER"
                - "DIRECT"
            reason:
              type: "string"
              nullable: true
              maxLength: 1000
    SAVE_FOLLOWUPRequest:
      type: "object"
      additionalProperties: false
      required:
        - "command"
        - "expectedVersion"
        - "idempotencyKey"
        - "payload"
      properties:
        command:
          type: "string"
          enum:
            - "SAVE_FOLLOWUP"
        expectedVersion:
          type: "integer"
          minimum: 0
        idempotencyKey:
          type: "string"
          minLength: 1
          maxLength: 64
        payload:
          type: "object"
          additionalProperties: false
          required:
            - "ownerId"
            - "followupDate"
            - "note"
          properties:
            ownerId:
              type: "string"
              minLength: 1
              maxLength: 64
            followupDate:
              type: "string"
              format: "date"
              nullable: true
            note:
              type: "string"
              minLength: 1
              maxLength: 1000
    RESOLVE_REVIEWRequest:
      type: "object"
      description: "须匹配当前影响版本，并核对本事项及关联安排的最新权威影响；需求关系未同步或出现新影响时拒绝清除。车次货物成员变化仅要求相关客户及车辆核对，未变化客户预约不连带复核；车辆、司机、时间变化影响当前关联预约。复核不恢复取消的确认、不修改原预约和车辆，也不制造新的业务影响。"
      additionalProperties: false
      required:
        - "command"
        - "expectedVersion"
        - "idempotencyKey"
        - "payload"
      properties:
        command:
          type: "string"
          enum:
            - "RESOLVE_REVIEW"
        expectedVersion:
          type: "integer"
          minimum: 0
        idempotencyKey:
          type: "string"
          minLength: 1
          maxLength: 64
        payload:
          type: "object"
          additionalProperties: false
          required:
            - "reviewVersion"
            - "note"
          properties:
            reviewVersion:
              type: "integer"
              minimum: 0
            note:
              type: "string"
              minLength: 1
              maxLength: 1000
    SAVE_REQUIREMENTRequest:
      type: "object"
      additionalProperties: false
      required:
        - "command"
        - "expectedVersion"
        - "idempotencyKey"
        - "payload"
      properties:
        command:
          type: "string"
          enum:
            - "SAVE_REQUIREMENT"
        expectedVersion:
          type: "integer"
          minimum: 0
        idempotencyKey:
          type: "string"
          minLength: 1
          maxLength: 64
        payload:
          type: "object"
          additionalProperties: false
          required:
            - "target"
            - "bookingRequired"
            - "receivingRequirements"
            - "reason"
          properties:
            target:
              "$ref": "#/components/schemas/Slot"
              nullable: true
            bookingRequired:
              type: "boolean"
            receivingRequirements:
              type: "string"
              nullable: true
              maxLength: 1000
            reason:
              type: "string"
              minLength: 1
              maxLength: 1000
    HANDOFF_RETURNRequest:
      type: "object"
      additionalProperties: false
      required:
        - "command"
        - "expectedVersion"
        - "idempotencyKey"
        - "payload"
      properties:
        command:
          type: "string"
          enum:
            - "HANDOFF_RETURN"
        expectedVersion:
          type: "integer"
          minimum: 0
        idempotencyKey:
          type: "string"
          minLength: 1
          maxLength: 64
        payload:
          type: "object"
          additionalProperties: false
          required:
            - "recipient"
            - "reason"
          properties:
            recipient:
              "$ref": "#/components/schemas/Responsibility"
            reason:
              type: "string"
              minLength: 1
              maxLength: 1000
    ACCEPT_RETURNRequest:
      type: "object"
      additionalProperties: false
      required:
        - "command"
        - "expectedVersion"
        - "idempotencyKey"
        - "payload"
      properties:
        command:
          type: "string"
          enum:
            - "ACCEPT_RETURN"
        expectedVersion:
          type: "integer"
          minimum: 0
        idempotencyKey:
          type: "string"
          minLength: 1
          maxLength: 64
        payload:
          type: "object"
          additionalProperties: false
          required:
            - "handoffVersion"
            - "note"
          properties:
            handoffVersion:
              type: "integer"
              minimum: 0
            note:
              type: "string"
              nullable: true
              maxLength: 1000
    CommandRequest:
      description: SAVE_REQUIREMENT新增目标须为分钟精度且有IANA时区；原业务Slot允许保留秒、纳秒及未知时区。
      oneOf:
        -
          "$ref": "#/components/schemas/CONFIRM_ROUTERequest"
        -
          "$ref": "#/components/schemas/SAVE_FOLLOWUPRequest"
        -
          "$ref": "#/components/schemas/RESOLVE_REVIEWRequest"
        -
          "$ref": "#/components/schemas/SAVE_REQUIREMENTRequest"
        -
          "$ref": "#/components/schemas/HANDOFF_RETURNRequest"
        -
          "$ref": "#/components/schemas/ACCEPT_RETURNRequest"
      discriminator:
        propertyName: "command"
        mapping:
          CONFIRM_ROUTE: "#/components/schemas/CONFIRM_ROUTERequest"
          SAVE_FOLLOWUP: "#/components/schemas/SAVE_FOLLOWUPRequest"
          RESOLVE_REVIEW: "#/components/schemas/RESOLVE_REVIEWRequest"
          SAVE_REQUIREMENT: "#/components/schemas/SAVE_REQUIREMENTRequest"
          HANDOFF_RETURN: "#/components/schemas/HANDOFF_RETURNRequest"
          ACCEPT_RETURN: "#/components/schemas/ACCEPT_RETURNRequest"
    DispatchBatchAllocation:
      type: object
      additionalProperties: false
      required: [planPalletId, batchKey, customerId, sourceKey, destinationKey, packageCount]
      properties:
        planPalletId: {type: integer, format: int64}
        batchKey: {type: string, pattern: '^FBA_APPOINTMENT:[1-9][0-9]*$'}
        customerId: {type: string}
        sourceKey: {type: string}
        destinationKey: {type: string}
        packageCount: {type: integer, minimum: 1}
    BatchDispatchCandidates:
      type: object
      required: [batchKey, version, candidates, blockReasons]
      properties:
        batchKey: {type: string}
        version: {type: integer}
        blockReasons: {type: array, items: {type: string}}
        candidates:
          type: array
          items:
            type: object
            required: [planPalletId, palletNo, planId, planNo, customerId, sourceStage, packageCount, allocations, blockReasons]
            properties:
              planPalletId: {type: integer, format: int64}
              palletNo: {type: string}
              planId: {type: integer, format: int64}
              planNo: {type: string}
              customerId: {type: string}
              sourceStage: {type: string, enum: [PLAN, RECEIVED]}
              packageCount: {type: integer, nullable: true}
              allocations: {type: array, items: {$ref: '#/components/schemas/DispatchBatchAllocation'}}
              blockReasons: {type: array, items: {type: string}}