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

==============
Repair Tickets
==============

Author: Zhenyu Yang <yangzhenyu@sust.edu.cn>

Last updated: Apr 24, 2026

Corresponding API docs: `Repair Process API <../../api/repairs.rst>`__

``repairs`` Code Entry
----------------------

-  ``backend/apps/repairs/models/__init__.py``
-  ``backend/apps/repairs/views/__init__.py``

``repairs`` Core Data
---------------------

``RepairTicket``
~~~~~~~~~~~~~~~~

Key fields:

-  ``creator``
-  ``assignee``
-  ``classroom``
-  ``description``
-  ``images``
-  ``status``
-  ``remark``

Status transitions:

.. code:: text

   open -> processing -> completed -> confirmed

``repairs`` Permission Boundaries
---------------------------------

-  Ticket list:

   -  ``assistant`` / ``superadmin`` / ``counselor`` can see all
      tickets.
   -  Other roles can only see tickets they created.

-  Update ticket:

   -  ``assistant`` / ``superadmin`` / ``counselor``.

-  Confirm completion:

   -  Only the ticket creator themselves.

Business Rules
--------------

Standard Repair
~~~~~~~~~~~~~~~

-  Before creation, the system checks whether an ``open`` or
   ``processing`` ticket already exists for the same classroom.
-  If one exists, the duplicate submission is rejected.

Emergency Repair
~~~~~~~~~~~~~~~~

-  No duplicate ticket blocking.
-  The response includes ``duty_phone``.
-  Currently ``duty_phone`` comes from the request body, defaulting to
   ``"000-0000"``.

Update Ticket
~~~~~~~~~~~~~

-  On status update, the current operator is written into ``assignee``.
-  ``RepairUpdateSerializer`` currently only allows transitioning the
   status to ``processing`` or ``completed``.

Confirm Completion
~~~~~~~~~~~~~~~~~~

-  ``/confirm`` directly sets the status to ``confirmed``.
-  The current implementation does not validate that the prior status
   must be ``completed``.