common & Shared Services

Author: Zhenyu Yang yangzhenyu@sust.edu.cn

Last updated: Apr 24, 2026

Corresponding API docs: Common Utilities API

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.