Common Services

API fact source: Django backend generated docs

Why These Capabilities Are Shared

common holds system-level capabilities: configuration, uploads, pagination, task status, and OpenAPI wrapping. services/ holds cross-app reusable services that do not own business state.

Code entry:

• backend/common/models.py
• backend/common/models_task.py
• backend/common/views.py
• backend/common/views_task.py
• backend/common/pagination.py
• backend/common/middleware/
• backend/services/

System Configuration

• SystemConfig is a singleton config record for seasonal schedule and semester start date.
• Season switching is restricted to superadmin.
• Season configuration affects course-time caches, so config changes need to be reviewed with course services.

Why Task Ownership Is Not In Redis

• Background task status uses TaskRecord as the source of truth.
• /api/v1/tasks/ is a read-only viewset with list and detail endpoints.
• Non-admin users see only their own tasks; superadmin and secretary can see all tasks.
• Status values are database enum values: pending, started, success, failure.
• The old Redis task_owner:<task_id> ownership scheme is retired. Keeping task state and ownership in the database makes permission filtering, audit, and process-restart recovery simpler.

Current Upload Path

• The current upload endpoint writes directly to LOCAL_UPLOAD_DIR and builds URLs with LOCAL_UPLOAD_URL_PREFIX.
• services/file_storage.py already has a local/S3 abstraction, but the upload endpoint does not use it yet.
• Upload changes first need a storage direction: preserve local-upload semantics or formally migrate to the storage abstraction. The two paths differ in deployment, URLs, permissions, and rollback behavior.

Pagination and Request Context

• The default pagination class is DefaultPagination, with max page size 200.
• RequestTimezoneMiddleware activates request timezone from X-Timezone.
• OperationLogContextMiddleware and CurrentRoleMiddleware are outside common/, but they are system-level request-context capabilities.

What Belongs In Shared Code

• Shared code can serve business modules, but depending back on specific business modules blurs system boundaries.
• Single-module logic stays in the owning app. services/ is for stable behavior reused by multiple modules.
• The OpenAPI envelope hook affects generated docs and frontend generated types, so both need verification after changes.