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

===============
MyUCSpace - Web
===============

Author: Sixu Wei <reisa@sust.edu.cn>

Last updated: Jan 29, 2026

This document describes the core architecture, feature modules, and
development conventions of the Classroom Manager Web admin panel.

Architecture & Tech Stack
-------------------------

-  **Framework**: Vue 3 + Vite
-  **UI Component Library**: Element Plus
-  **State Management**: Pinia
-  **Routing**: Vue Router 4
-  **HTTP Client**: Axios
-  **Encryption**: SM2 (Chinese national cryptographic algorithm, used
   for password transmission)
-  **Reverse Proxy**: Nginx (handles reverse proxying, SSL termination,
   and static asset hosting)

Project Structure
-----------------

::

   web/src/
   ├── api/          # API request wrappers
   ├── assets/       # Static assets
   ├── components/   # Shared components
   ├── layouts/      # Page layouts
   ├── router/       # Route configuration
   ├── stores/       # Pinia state stores
   ├── utils/        # Utility functions
   └── views/        # Page views

Feature Modules
---------------

-  **User Authentication**

   -  Email and password login; passwords are encrypted with SM2 for
      transmission
   -  JWT token authentication (access + refresh dual-token scheme)
   -  WebAuthn passwordless login support
   -  TOTP two-factor authentication

-  **Classroom Management**

   -  Classroom list and detail views
   -  Classroom status management (available / under maintenance /
      occupied)
   -  Free classroom search

-  **Reservation Management**

   -  Reservation application and approval workflow
   -  Application status tracking
   -  Time conflict detection

-  **Maintenance Request Management**

   -  Maintenance ticket processing
   -  Status lifecycle (pending → in progress → completed)
   -  Image attachment support

-  **Violation Management**

   -  Violation report handling
   -  Resolution record keeping

-  **Course Center** (new)

   -  Class schedule data queries
   -  Real-time course status display

Quick Start
-----------

.. code:: bash

   # Install dependencies
   npm install

   # Start the development server (defaults to port 3000)
   npm run dev

   # Build for production
   npm run build

Development Configuration
-------------------------

Backend Proxy
~~~~~~~~~~~~~

The frontend dev server proxies ``/api`` requests to
``http://localhost:8000`` by default. The configuration is in
``vite.config.js``. ``web/package.json`` declares ``"type": "module"``,
so the frontend toolchain configuration is maintained as ESM.

.. code:: javascript

   server: {
     proxy: {
       '/api': {
         target: 'http://localhost:8000',
         changeOrigin: true
       }
     }
   }

Development Conventions
-----------------------

-  **Component Naming**: Use PascalCase, e.g. ``ClassroomList.vue``
-  **API Wrappers**: Organize by module under ``src/api/``
-  **State Management**: Use Pinia stores for global state; use
   ``ref``/``reactive`` for component-local state
-  **Error Handling**: API requests use interceptors for unified error
   handling, displaying Element Plus message notifications