asyncapi: 3.0.0
id: 'https://ch.kochse/educ/plantit/planning/api'
info:
  title: Plantit-Planning
  version: '2.1.5'
  description: Manages reservations and orders and dispatches the production and transport
  contact:
    email: plantit@kochse.ch
    name: Andres Koch
    url: 'https://www.kochse.ch'
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0'
  externalDocs:
    description: Design Documentation
    url: 'https://gitlab.ost.ch/masse/ads/plantit/planning/planning-api'
defaultContentType: application/json
servers: 
  production:
    protocol: amqp
    description: message broker for MAS/SE ADS exercise 
    host: 'tcp://masse-mq.dynu.net:62616'
channels:
  PlanningRequest:
    address: 'Q.plantit.prod.planning.{grpid}'
    parameters:
      $ref: '#/components/parameters/grpid'
    messages:    
      Reservation:
        $ref: '#/components/messages/PlanningReservationReqMsg'
      Cancellation: 
        $ref: '#/components/messages/PlanningCancellationReqMsg'
      Order:
        $ref: '#/components/messages/PlanningOrderReqMsg'
operations:
  reserve:
    action: receive
    channel:
      $ref: '#/channels/PlanningRequest'
    reply: 
      address:
        location: '$message.header#/replyTo'
      messages:
        - $ref: '#/components/messages/PlanningReservationRspMsg' 
  cancel:
    action: receive
    channel:
      $ref: '#/channels/PlanningRequest'
    reply: 
      address:
        location: '$message.header#/replyTo'
      messages:
      - $ref: '#/components/messages/PlanningCancellationRspMsg'
  order:
    action: receive
    channel:
      $ref: '#/channels/PlanningRequest'
    reply: 
      address:
        location: '$message.header#/replyTo'
      messages:
        - $ref: '#/components/messages/PlanningOrderRspMsg'
  notify:
    action: receive
    channel:
      $ref: '#/channels/PlanningRequest'
    reply: 
      address:
        location: $message.header#/replyTo
      messages:
        - $ref: '#/components/messages/PlanningDeliveryNotificationMsg'

components:
  messages:
    PlanningReservationReqMsg:
      name: Reservation Request
      title: Planning Reservation Request
      summary: Requests for a reservation for delivery specific products 
      payload:
        $ref: '#/components/schemas/PlanningReservationReqDTO'    

    PlanningReservationRspMsg:
      name: Planning Reservation Response 
      title: Planning Reservation Response
      summary: response to a reservation request for delivery specific products
      payload:
        $ref: '#/components/schemas/PlanningReservationRspDTO'    
        
    PlanningOrderReqMsg:
      name: Planning Order Request 
      title: Planning Order Request
      summary: Definitive order or change of a reservation to an order 
      payload:
        $ref: '#/components/schemas/PlanningOrderReqDTO'
 
    PlanningOrderRspMsg:
        name: Planning Order Response
        title: Planning Order Response
        summary: Response of a definitive order or change of a reservation to an order 
        payload:
          $ref: '#/components/schemas/PlanningOrderRspDTO'   
           
    PlanningCancellationReqMsg: 
        name: Planning Cancellation Request
        title: Planning Order or Reservation Cancellation
        summary: Request to cancel a previous reservation or an order 
        payload:
          $ref: '#/components/schemas/PlanningCancellationReqDTO'

    PlanningCancellationRspMsg: 
        name: Planning Cancellation Response
        title: Response Cancellation  Order or Reservation 
        summary: Response of a cancellation of a previous reservation or an order 
        payload:
          $ref: '#/components/schemas/PlanningCancellationRspDTO'
            
    PlanningDeliveryNotificationMsg: 
        name: Planning Delivery Notification
        title: Planning  Goods Ready  Notification
        summary: Notification of the delivery of the ordered products
        payload:
          $ref: '#/components/schemas/PlanningDeliveryNotificationDTO'

  schemas:
    PlanningReservationReqDTO:
      description: 
        Request which defines a reservation for producing a specific product for delivery
        including transport to a desired location
      type: object
      properties:
        inquiryId: 
          type: string
          description: 'uuid to correlate the reservation to the corresponding order'
        customerId:
          type: string
          description: 'Customer reference for who the reservation is designated'
        productId:
          type: string
          description: 'product identifier'
        productname: 
          type: string
          description: 'short description such as name of the product'
        unit:
          $ref: '#/components/schemas/ProductUnit'
          description: 'quantity related unit of product'
        plannedDelivery:
          type: string
          format: date-time
          description: 'requested delivery date of the required or minimal quantity of the product'
        requiredQty: 
          type: number
          description: 'requested quantity of product to grow and deliver'
        minimalQty:
          type: number
          description: 'minimal quantity to reserve in case the complete quatity cannot be covered.'
        deliveryLocation:
          $ref: '#/components/schemas/DeliveryLocation'
          description: '(optional) defines where the goods have to be delivered to'

    PlanningReservationRspDTO:
      type: object
      properties:
        reservationId:
          type: string
          description: 'reservation id of the reservation'
        inquiryId: 
          type: string
          description: 'uuid to correlate the reservation to corresponding order'
        reservationStatus:
          $ref: '#/components/schemas/ProductionStatus'
          description: 'current state of the production cylce'
        productId:
          type: string
          description: 'product identifier'
        productname: 
          type: string
          description: 'short description such as name of the product'
        expectedDelivery:
          type: string
          format: date-time
          description: 'expected delivery date of the reserved quantity of the product'
        unit:
          $ref: '#/components/schemas/ProductUnit'
          description: 'quantity related unit of product'
        reservedQty:
          type: number
          description: 'effectively reserved quanity. 0 means minimalQty cannot be satisfied'
        completion:
          $ref: '#/components/schemas/CompletionInfo'

    PlanningOrderReqDTO: 
      type: object
      properties:
        reservationId:
          type: string
          description: 'reservation id of the reservation of the supplier'
        inquiryId: 
          type: string
          description: 'uuid to correlate the reservation to the corresponding order'
        customerId:
          type: string
          description: 'Customer reference for who the reservation is designated'
        productId:
          type: string
          description: 'product identifier'
        productname: 
          type: string
          description: 'short description such as name of the product'
        unit:
          $ref: '#/components/schemas/ProductUnit'
          description: 'quantity related unit of product'
        plannedDelivery:
          type: string
          format: date-time
          description: 'requested delivery date of the required or minimal quantity of the product'
        orderedQty: 
          type: number
          description: 'requested quantity of product to grow and deliver. This quantity has to be the same or less than the reserved quanity'
        deliveryLocation:
          $ref: '#/components/schemas/DeliveryLocation'
          description: '(optional) defines where the goods have to be delivered to'

    PlanningOrderRspDTO: 
      type: object
      properties:
        orderId:
          type: string
          description: 'id of the reservation or order'
        inquiryId: 
          type: string
          description: 'uuid to correlate the reservation to corresponding order'
        orderStatus:
          $ref: '#/components/schemas/ProductionStatus'
          description: 'status of the order after last transaction'
        productId:
          type: string
          description: 'product identifier'
        productname: 
          type: string
          description: 'short description such as name of the product'
        expectedDelivery:
          type: string
          format: date-time
          description: 'expected delivery date of the amount of the product'
        orderedQty: 
          type: number
          description: 'requested quantity of product to grow and deliver'
        unit:
          $ref: '#/components/schemas/ProductUnit'
          description: 'quantity related unit of product'
        completion:
          $ref: '#/components/schemas/CompletionInfo'

    PlanningCancellationReqDTO:
      type: object
      properties:
        planningId:
          type: string
          description: 'id of the reservation or order'
        inquiryId: 
          type: string
          description: 'uuid to correlate the reservation to corresponding order'
        reason:
          type: string
          description: 'reason for the cancellation'

    PlanningCancellationRspDTO:
      type: object
      properties:
        planningId:
          type: string
          description: 'id of the reservation or order'
        inquiryId: 
          type: string
          description: 'uuid to correlate the reservation to corresponding order'
        cancellationStatus:
          $ref: '#/components/schemas/ProductionStatus'
          description: 'new status after cancellation. cancelled = ok, denied = to late to cancel order, delivery will be executed'
        completion:
          $ref: '#/components/schemas/CompletionInfo'
    
    PlanningDeliveryNotificationDTO:
      type: object
      properties:
        orderId:
          type: string
          description: 'order id of the order'
        inquiryId: 
          type: string
          description: 'uuid to correlate to the to corresponding reservation or order'
        deliveryShares:
          description: 'one or more (in case of partial production) delivery location where the goods can be picked up'
          type: array
          items:
            $ref: '#/components/schemas/DeliveryShare'
        deliveryDate:
          type: string
          description: 'time when goods can be picked up'
          format: date-time
        info:
          type: string
          description: 'additional information about the delivered goods'


    DeliveryShare:
      description: 
        defines a location of storage where the whole or part of the original order is available
        or in case of depraved production which part is not delivered
      type: object
      properties:
        deliveryStatus:
          $ref: '#/components/schemas/ProductionStatus'
          description: 'defines the current state of the delivery of this share'  
        shareAmount:
          type: integer
          minimum: 0
          maximum: 100
          description: 'Share of delivery in %. Partial  1..99% full delivery 100%'
        deliveryLocation:
          $ref: '#/components/schemas/DeliveryLocation'
          description: 'location where the partial delivery is available and can be picked up'
        storageRef:
          type: string
          description: 'reference at the storage location to pickup and access the goods'

    DeliveryLocation:
      type: object
      required:
        - longitude
        - latitude
      properties: 
        longitude:
          type: number
          description: 'longitude of location'
        latitude:
          type: number
          description: 'latitude of location'
        siteSpecifics:
          type: string
          description:  'specific instruction at site'

    CompletionInfo:
      type: object
      properties:
        responseCode:
          type: integer
          description: 'Error code 0 = success <0 error codes >0 completion: code'
        responseMessage:
          type: string
          description: 'individual human readable completion: message' 

    ProductUnit:
      type: string
      enum: 
        - 'kg'
        - 'ton'
        - 'liter'
        - 'm3'
        - 'pcs'
      description: 'quantity related unit of product'
   
    ProductionStatus:
      type: string
      enum:
        - 'unavailable'
        - 'reserved' 
        - 'ordered' 
        - 'cancelled' 
        - 'planted' 
        - 'growing'
        - 'harvested' 
        - 'depraved' 
        - 'loaded'
        - 'moving' 
        - 'unloaded' 
        - 'delivered'
        - 'undefined'
      default: 'undefined'       
  parameters:
    grpid:
      description: Group number