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

==============
Operation Logs
==============

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

Last updated: Apr 24, 2026

Corresponding API docs: `Audit Log API <../../api/logs.rst>`__

``logs`` Code Entry
-------------------

-  ``backend/apps/logs/models.py``
-  ``backend/apps/logs/views/operation_log.py``
-  ``backend/apps/logs/utils.py``
-  ``backend/apps/logs/permissions.py``

``logs`` Core Data
------------------

``OperationLog``
~~~~~~~~~~~~~~~~

Core dimensions logged:

-  ``user``
-  ``user_role``
-  ``action``
-  ``module``
-  ``target_type``
-  ``target_id``
-  ``description``
-  ``request_ip``
-  ``user_agent``
-  ``extra``
-  ``created_at``

Write Mechanism
---------------

-  ``OperationLogContextMiddleware`` stores the current request in a
   ``ContextVar``.
-  Business code can call ``log_operation(...)`` directly.
-  If the call site does not explicitly pass a ``request``, the logging
   utility attempts to retrieve it from the current context.

Key actions in borrowings, repairs, check-ins, and signage now have
explicit operation logging.

Query & Export
--------------

-  ``OperationLogViewSet`` is a read-only endpoint.
-  Supports filtering by time, user, role, module, and action.
-  ``export`` exports the same filtered results as CSV.

Known Issues
------------

-  The permission class ``IsLogAdmin`` still checks the legacy
   ``user.role`` field to identify super admins.
-  However, the current user model uses ``roles`` (JSON) and no longer
   has a ``role`` field.
-  As a result, the only reliably accessible log endpoints currently are
   for:

   -  Django ``is_superuser``
   -  Django ``is_staff``

To properly integrate the log endpoints into the new role system, this
permission class needs to be fixed first.