openapi: 3.0.0
info:
  title: Demand
  version: 2.0.0
  description: >
    A **Demand** represents a compliance requirement: the link between a
    preventive action

    and a work group that requires that action. It indicates that a specific
    work group

    (job role, work phase, or homogeneous group) needs a specific action
    (training,

    maintenance, check, etc.).


    For example: a Demand linking the action "Fire Safety Training" to the work
    group "Welders"

    means that welders need that training course.


    Demands can be linked to risks via RiskDemand, establishing that an action

    mitigates a specific risk.


    Use this API to:

    - Define which actions are required by which work groups

    - Find all requirements for a work group (filter by `resource_id` with the
    `work_group_id`)

    - Find all work groups that require an action (filter by `action_id`)


    The combination of `action_id` + `resource_id` must be unique.


    Supports historicization.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/demand/index:
    post:
      summary: index
      operationId: indexDemand
      tags:
        - Demands
      description: >
        Returns a paginated list of demands.


        Most useful filters:

        - `resource_id` (work_group_id): all requirements for a specific work
        group

        - `action_id`: all work groups that require a specific action

        - `action_type`: filter by action type
      requestBody:
        description: Parameters for searching demands
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DemandIndexParams"
            example:
              filter:
                resource_id: 3a4b5c6d-7e8f-9012-abcd-ef3456789012
                action_type: TRAINING
              per-page: 20
              page: 1
              sort: action_name
      responses:
        "200":
          description: List of demands
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewDemand"
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/demand/create:
    post:
      summary: create
      operationId: createDemand
      tags:
        - Demands
      description: |
        Creates a new demand.

        Requires `action_id`, `action_type`, `resource_id`, and `resource_type`.
        The `demand_id` is auto-generated if not provided.

        The action and work group must belong to the same office.
      requestBody:
        description: Demand to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Demand"
      responses:
        "201":
          description: Demand created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Demand"
  /v2/demand/view/{id}:
    get:
      summary: view
      operationId: viewDemand
      tags:
        - Demands
      description: Retrieves a single demand by its ID.
      parameters:
        - name: id
          in: path
          description: The demand_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Demand found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewDemand"
        "404":
          description: Demand not found
  /v2/demand/update/{id}:
    put:
      summary: update
      operationId: updateDemand
      tags:
        - Demands
      description: Updates an existing demand.
      parameters:
        - name: id
          in: path
          description: The demand_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Demand"
      responses:
        "200":
          description: Demand updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Demand"
        "404":
          description: Demand not found
  /v2/demand/delete/{id}:
    delete:
      summary: delete
      operationId: deleteDemand
      tags:
        - Demands
      description: >
        Deletes a demand.


        If `force=false` (default), the response lists child entities
        (RiskDemand links).

        If `force=true`, the demand and all related entities are deleted.
      parameters:
        - name: id
          in: path
          description: The demand_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the demand and all child entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Demand deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    Demand:
      type: object
      required:
        - action_id
        - action_type
        - resource_id
        - resource_type
      properties:
        demand_id:
          type: string
          format: uuid
          description: Unique identifier. Auto-generated if not provided.
        action_id:
          type: string
          format: uuid
          description: The required action. Pass the `action_id` from the Action API.
        action_type:
          type: string
          enum:
            - TRAINING
            - MAINTENANCE
            - HEALTH
            - CHECK
            - PER
          description: Type of the required action.
        resource_id:
          type: string
          format: uuid
          description: The work group that requires this action. Pass the `work_group_id`
            from the WorkGroup API.
        resource_type:
          type: string
          enum:
            - WORK_GROUP
          description: Type of resource. Use `WORK_GROUP`.
        data:
          type: object
          description: Additional structured data in JSON format.
    ViewDemand:
      type: object
      properties:
        demand_id:
          type: string
          format: uuid
        action_id:
          type: string
          format: uuid
        action_type:
          type: string
          enum:
            - TRAINING
            - MAINTENANCE
            - HEALTH
            - CHECK
            - PER
        resource_id:
          type: string
          format: uuid
        resource_type:
          type: string
        data:
          type: object
        action_code:
          type: string
          description: Code of the required action.
        action_name:
          type: string
          description: Name of the required action.
        resource_code:
          type: string
          description: Code of the work group.
        resource_name:
          type: string
          description: Name of the work group.
        office_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        owned_active:
          type: boolean
          nullable: true
          description: Whether this demand is currently active.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent entities are currently active.
    DemandIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewDemand"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - action_code
            - action_name
            - action_type
            - resource_code
            - resource_name
            - resource_type
        history:
          type: boolean
          description: If true, includes historicized entries.
      example:
        filter:
          resource_id: 3a4b5c6d-7e8f-9012-abcd-ef3456789012
          action_type: TRAINING
        per-page: 100
        page: 1
        sort: action_name
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
