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

====================
Common Utilities API
====================

1. Attachment Upload
--------------------

.. code:: bash

   POST /api/v1/upload
   Content-Type: multipart/form-data

Returns:

.. code:: json

   {
     "code": 0,
     "message": "success",
     "data": { "url": "/media/uploads/<uuid>.<ext>" }
   }

Notes:

-  Two storage backends are supported: local disk and S3-compatible
   object storage. Switch them with the ``FILE_STORAGE_BACKEND``
   environment variable (``local`` / ``s3``).
-  In local mode, files are saved by default to
   ``/var/www/classroom-manager/uploads/`` on the server. Override the
   storage path and access prefix with ``LOCAL_UPLOAD_DIR`` and
   ``LOCAL_UPLOAD_URL_PREFIX``.
-  S3 mode requires ``S3_BUCKET_NAME``, ``S3_ACCESS_KEY_ID``, and
   ``S3_SECRET_ACCESS_KEY``. Optional ``S3_ENDPOINT_URL`` or
   ``S3_BASE_URL`` can be used to customize the access domain for any
   S3-compatible service.
-  Login is required (``Authorization: Bearer <token>``).
-  The current implementation uploads to local disk and returns a
   relative path accessible within the site.

2. Get System Configuration
---------------------------

.. code:: bash

   GET /api/v1/config

Permission: login required.

Returns:

.. code:: json

   {
     "code": 0,
     "message": "success",
     "data": {
       "season": "winter",
       "season_display": "Winter Schedule",
       "semester_start_date": "2026-02-17",
       "updated_at": "2026-01-20T10:00:00+08:00"
     }
   }

3. Set Seasonal Schedule (superadmin Only)
------------------------------------------

.. code:: bash

   POST /api/v1/config/season

Body:

.. code:: json

   { "season": "winter" }

Returns: same as getting system configuration.