alrahma_sunday_school/public/docs/openapi_inventory_controller.yaml

openapi: 3.0.3
info:
  title: Inventory API - Al Rahma Sunday School
  version: 1.0.0
  description: Manage inventory items and movements.
servers:
  - url: https://alrahmaisgl.org/api/v1
security:
  - BearerAuth: []
tags:
  - name: Inventory
    description: Items and movements

paths:
  /inventory:
    get:
      tags: [Inventory]
      summary: List inventory items
      parameters:
        - name: page
          in: query
          schema: { type: integer, example: 1 }
        - name: per_page
          in: query
          schema: { type: integer, example: 20 }
        - name: type
          in: query
          schema: { type: string, enum: [classroom, book, office, kitchen] }
        - name: school_year
          in: query
          schema: { type: string }
        - name: semester
          in: query
          schema: { type: string }
      responses:
        200:
          description: Paginated items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInventoryResponse'
    post:
      tags: [Inventory]
      summary: Create inventory item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInventoryItemRequest'
      responses:
        201:
          description: Inventory item created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItemResponse'

  /inventory/{id}:
    get:
      tags: [Inventory]
      summary: Get inventory item
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItemResponse'
        404: { description: Not found }
    put:
      tags: [Inventory]
      summary: Update inventory item
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInventoryItemRequest'
      responses:
        200:
          description: Updated item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItemResponse'
    delete:
      tags: [Inventory]
      summary: Delete inventory item
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

  /inventory/movements:
    get:
      tags: [Inventory]
      summary: List inventory movements
      parameters:
        - name: page
          in: query
          schema: { type: integer, example: 1 }
        - name: per_page
          in: query
          schema: { type: integer, example: 20 }
        - name: item_id
          in: query
          schema: { type: integer }
      responses:
        200:
          description: Paginated movements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMovementsResponse'
    post:
      tags: [Inventory]
      summary: Create inventory movement (adjust quantity)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [item_id, qty_change, movement_type]
              properties:
                item_id: { type: integer }
                qty_change: { type: integer, description: "positive for add, negative for remove" }
                movement_type: { type: string, enum: [issue, return, purchase, adjustment, correction] }
                reason: { type: string }
                note: { type: string }
                teacher_id: { type: integer }
                student_id: { type: integer }
                class_section_id: { type: integer }
      responses:
        201:
          description: Movement created and item quantity updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  message: { type: string }
                  data:
                    type: object
                    properties:
                      movement: { $ref: '#/components/schemas/Movement' }
                      item: { $ref: '#/components/schemas/InventoryItem' }

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    BasicSuccess:
      type: object
      properties:
        status: { type: string, example: "success" }
        message: { type: string }
        data: {}

    InventoryItem:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        type: { type: string }
        category_id: { type: integer, nullable: true }
        quantity: { type: integer }
        good_qty: { type: integer }
        condition: { type: string }
        notes: { type: string, nullable: true }
        school_year: { type: string }
        semester: { type: string }

    Movement:
      type: object
      properties:
        id: { type: integer }
        item_id: { type: integer }
        change: { type: integer }
        reason: { type: string }
        created_at: { type: string, format: date-time }

    PaginatedInventoryResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: object
          properties:
            data:
              type: array
              items: { $ref: '#/components/schemas/InventoryItem' }
            pagination:
              type: object
              properties:
                current_page: { type: integer }
                per_page: { type: integer }
                total: { type: integer }
                total_pages: { type: integer }
            categories:
              type: array
              items:
                type: object
                properties:
                  id: { type: integer }
                  name: { type: string }

    PaginatedMovementsResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: object
          properties:
            data:
              type: array
              items: { $ref: '#/components/schemas/Movement' }
            pagination:
              type: object
              properties:
                current_page: { type: integer }
                per_page: { type: integer }
                total: { type: integer }
                total_pages: { type: integer }

    InventoryItemResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data: { $ref: '#/components/schemas/InventoryItem' }

    CreateInventoryItemRequest:
      type: object
      required: [name, type]
      properties:
        name: { type: string }
        type: { type: string, enum: [classroom, book, office, kitchen] }
        category_id: { type: integer, nullable: true }
        quantity: { type: integer, example: 0 }
        good_qty: { type: integer, example: 0 }
        condition: { type: string, example: good }
        school_year: { type: string }
        semester: { type: string }

    UpdateInventoryItemRequest:
      type: object
      properties:
        name: { type: string }
        category_id: { type: integer }
        quantity: { type: integer }
        good_qty: { type: integer }
        condition: { type: string }
        notes: { type: string }