# `common` & Shared Services

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

Last updated: Apr 24, 2026

Corresponding API docs: [Common Utilities API](../../api/common.md)

## `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`.