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

========================
Common & Shared Services
========================

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

Last updated: Apr 24, 2026

Corresponding API docs: `Common Utilities API <../../api/common.rst>`__

``common`` / ``services`` Code Entry
------------------------------------

-  ``backend/common/models.py``
-  ``backend/common/views.py``
-  ``backend/common/pagination.py``
-  ``backend/common/middleware/request_timezone.py``
-  ``backend/services/``

System Configuration
--------------------

``SystemConfig``
~~~~~~~~~~~~~~~~

This is a singleton table, currently storing:

-  ``season``
-  ``semester_start_date``
-  ``updated_at``

Associated endpoints:

-  ``GET /api/v1/config``
-  ``POST /api/v1/config/season``

Season switching is only allowed when the current active role is
``superadmin``.

Uploads
-------

-  Entry: ``common.views.upload_file``
-  The current implementation writes files directly to
   ``LOCAL_UPLOAD_DIR``.
-  The returned URL is assembled using ``LOCAL_UPLOAD_URL_PREFIX``.

Caveat:

-  ``services/file_storage.py`` already implements a local/S3
   dual-backend abstraction.
-  However, the upload endpoint has not yet been integrated with this
   abstraction; the actual runtime still writes directly to the local
   filesystem.

Pagination
----------

-  Default pagination class: ``common.pagination.DefaultPagination``
-  Supported query parameters:

   -  ``page_size``
   -  ``size``

-  Maximum page size is 200.

Middleware
----------

``RequestTimezoneMiddleware``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-  Reads the ``X-Timezone`` header.
-  Dynamically activates the request timezone.

Other Cross-Module Middleware
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Although the code does not reside in ``common/``, these middleware are
closely related to shared capabilities:

-  ``apps.logs.utils.OperationLogContextMiddleware``
-  ``apps.accounts.middleware.CurrentRoleMiddleware``

``services/`` Directory
-----------------------

This directory currently holds stateless or cross-app reusable services:

-  ``wechat.py``
-  ``totp.py``
-  ``webauthn.py``
-  ``sm2_crypto.py``
-  ``file_storage.py``

These services are mostly used indirectly by ``accounts`` and
``common``.