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

================================
MyUCSpace - WeChat Mini Program
================================

Author: Sixu Wei <reisa@sust.edu.cn> Last updated: Jan 29, 2026

This document describes the core architecture, feature modules, and development
guidelines for the MyUCSpace WeChat Mini Program.

Architecture and Tech Stack
===========================

- **Framework**: WeChat Mini Program native framework
- **Styling**: WXSS (with CSS variable support)
- **Component library**: Native components + custom business components
- **Utilities**: Promise-based API request wrapper built on ``wx.request``

Project Structure
=================

::

   miniapp/
   ├── assets/           # Static resources (icons, images)
   ├── components/       # Shared custom components (e.g. image uploader, classroom picker)
   ├── pages/            # Page views
   │   ├── index/        # Home page (current borrowings / courses in progress)
   │   ├── service/      # Service hub (entry points for each business function)
   │   ├── mine/         # User profile
   │   ├── classroom/    # Classroom search and details
   │   ├── borrow/       # Classroom borrowing application and management
   │   ├── repair/       # Repair request submission and management
   │   └── login/        # Login page
   ├── utils/            # Utility functions (API wrappers, validation logic)
   ├── app.js            # Mini program logic and global lifecycle
   ├── app.json          # Global configuration
   └── config.js         # Environment and base URL configuration

Core Features and Mechanisms
============================

1. Silent Login
---------------

The mini program uses a "silent login" mechanism to improve user experience:

- **How it works**: During the ``onLaunch`` lifecycle in ``app.js``, ``wx.login``
  is called to obtain a ``code``, which is sent to the backend in exchange for
  a ``token``.
- **Promise coordination**: ``globalData.loginPromise`` manages the asynchronous
  login state. Pages call ``await app.globalData.loginPromise`` before loading
  data to ensure a valid identity.
- **Auto-redirect**: If silent login fails and the current page is not the login
  page, the system automatically navigates to the login page.

2. User Authentication
----------------------

- **WeChat one-tap login**: Automatically associates the backend user via the
  WeChat OpenID.
- **Role-based views**: Supports multiple roles — student, teacher, assistant,
  secretary, etc. — displaying different function menus based on the user's role.

3. Major Business Modules
-------------------------

- **Active tasks**: The home page displays classroom borrowings or scheduled
  courses for the current time period in real time.
- **Classroom search**: Filter available classrooms by building and status.
- **Borrowing application**: Full borrowing workflow including time selection
  (with conflict checking), purpose description, and attachment upload.
- **Repair system**: Supports standard and urgent repair requests with image
  upload.
- **Approval flow**: Secretary and admin roles can approve borrowing requests
  directly from the mini program.

Development and Debugging
=========================

Getting Started
---------------

1. Open the ``miniapp`` directory in WeChat Developer Tools.
2. Update ``baseUrl`` in ``config.js`` to point to your backend API address.
3. Go to Details -> Local Settings -> check "Do not verify valid domain names".

Configuration (config.js)
-------------------------

.. code:: javascript

   module.exports = {
     baseUrl: 'http://localhost:8000/api/v1',
     version: '1.0.0'
   }

Development Guidelines
======================

- API calls: Always use the methods defined in ``utils/api.js``. Never call
  ``wx.request`` directly in pages.
- Page lifecycle: In ``onShow``, await ``app.globalData.loginPromise`` to
  ensure the login state before loading business data.
- Styling: Prefer the color variables defined in ``styles/theme.wxss`` to
  maintain UI consistency.
- Componentization: Extract reusable modules (e.g. image uploader, list
  items) into ``components``.