.. SPDX-License-Identifier: GPL-3.0-or-later

===================
Repair Workflow API
===================

Work-Order Status Flow
----------------------

.. code:: text

   open -> processing -> completed -> confirmed

============== =============================================
Status         Description
============== =============================================
``open``       Pending; newly created work order
``processing`` In progress; an administrator has taken over
``completed``  Completed; waiting for requester confirmation
``confirmed``  Confirmed; workflow finished
============== =============================================

1. Standard Repair Request (All Authenticated Users)
----------------------------------------------------

.. code:: bash

   POST /api/v1/repairs

Body:

.. code:: json

   {
     "classroom_id": 121,
     "description": "The projector cannot be powered on.",
     "images": ["url1", "url2"]
   }

Restriction:

-  Duplicate submissions are prohibited when the same classroom has a
   work order with ``open`` or ``processing`` status.

2. Emergency Repair
-------------------

.. code:: bash

   POST /api/v1/repairs/emergency

Body: same as a standard repair request.

Returns:

-  Phone number of the assistant on duty.
-  A work order is created at the same time.

3. Work-Order List
------------------

.. code:: bash

   GET /api/v1/repairs

Permissions:

-  ``assistant`` / ``superadmin`` / ``counselor``: view all work orders.
-  Other roles: view only work orders they created.

4. Update Work Order (assistant / superadmin / counselor)
---------------------------------------------------------

.. code:: bash

   PUT /api/v1/repairs/{id}

Body:

.. code:: json

   {
     "status": "processing",
     "remark": "Processing notes"
   }

Notes:

-  ``remark`` is optional.
-  The current user is automatically set as the processor during update.

5. Requester Confirms Repair Completion
---------------------------------------

.. code:: bash

   PUT /api/v1/repairs/{id}/confirm

Permission: only the work-order creator may call this endpoint.

Notes: changes the work-order status from ``completed`` to
``confirmed``.