305 lines
21 KiB
Markdown
305 lines
21 KiB
Markdown
# 🎨 Frontend
|
||
|
||
## Общая информация
|
||
|
||
| Параметр | Значение |
|
||
|----------|----------|
|
||
| **Фреймворк** | Нет (Vanilla JavaScript) |
|
||
| **Модульная система** | ES6 Modules (`import`/`export`) |
|
||
| **Стили** | CSS (модульный подход) |
|
||
| **Шрифт** | Inter на странице входа, системный шрифт в кабинетах расписания |
|
||
| **Веб-сервер** | Apache httpd:alpine |
|
||
|
||
---
|
||
|
||
## Структура файлов
|
||
|
||
```
|
||
frontend/
|
||
├── index.html # 🔐 Страница авторизации (общая)
|
||
├── script.js # Логика авторизации
|
||
├── style.css # Стили страницы авторизации
|
||
├── theme-toggle.js # Переключение светлой/тёмной темы
|
||
├── Dockerfile # httpd:alpine
|
||
│
|
||
├── admin/ # 👨💼 Интерфейс администратора
|
||
│ ├── index.html # SPA-оболочка с sidebar
|
||
│ ├── css/
|
||
│ │ ├── main.css # CSS-переменные, цвета, типографика
|
||
│ │ ├── layout.css # Раскладка (sidebar, topbar, content)
|
||
│ │ ├── components.css # Кнопки, таблицы, карточки, формы
|
||
│ │ ├── modals.css # Модальные окна
|
||
│ │ ├── auditorium-workload.css # Таблицы загруженности аудиторий
|
||
│ │ └── departments-data.css # Стили создания кафедры/специальности
|
||
│ ├── js/
|
||
│ │ ├── main.js # Инициализация, маршрутизация, навигация
|
||
│ │ ├── api.js # HTTP-обёртка (fetch + Authorization)
|
||
│ │ ├── utils.js # Утилиты
|
||
│ │ ├── otel.js # OpenTelemetry (клиентская телеметрия, только прод)
|
||
│ │ └── views/ # Модули представлений
|
||
│ │ ├── users.js # Управление пользователями
|
||
│ │ ├── groups.js # Управление группами
|
||
│ │ ├── classrooms.js # Управление аудиториями
|
||
│ │ ├── subjects.js # Управление дисциплинами
|
||
│ │ ├── equipments.js # Управление оборудованием
|
||
│ │ ├── edu-forms.js # Формы обучения
|
||
│ │ ├── profiles.js # Профили обучения специальностей
|
||
│ │ ├── schedule.js # Конструктор правил расписания
|
||
│ │ ├── academic-calendar.js # Календарные учебные графики
|
||
│ │ ├── auditorium-workload.js # Загруженность аудиторий
|
||
│ │ ├── database.js # Управление тенантами
|
||
│ │ └── departments-data.js # Создание кафедры/специальности
|
||
│ ├── views/ # HTML-шаблоны представлений
|
||
│ │ ├── users.html
|
||
│ │ ├── groups.html
|
||
│ │ ├── classrooms.html
|
||
│ │ ├── subjects.html
|
||
│ │ ├── equipments.html
|
||
│ │ ├── edu-forms.html
|
||
│ │ ├── profiles.html
|
||
│ │ ├── schedule.html
|
||
│ │ ├── academic-calendar.html
|
||
│ │ ├── auditorium-workload.html
|
||
│ │ ├── database.html
|
||
│ │ └── departments-data.html
|
||
│ │
|
||
│ └── settings/ # ⚙️ Страница настроек (отдельный SPA)
|
||
│ ├── index.html # Оболочка с собственной sidebar
|
||
│ ├── css/
|
||
│ │ ├── main.css # CSS-переменные, базовые стили
|
||
│ │ └── layout.css # Sidebar, topbar, content
|
||
│ ├── js/
|
||
│ │ ├── main.js # Навигация по вкладкам настроек
|
||
│ │ └── views/
|
||
│ │ └── time-slots.js # Настройка временных слотов
|
||
│ └── views/
|
||
│ ├── general.html # Общие настройки (заглушка)
|
||
│ └── time-slots.html # Базовая, субботняя и ручные сетки времени
|
||
│
|
||
├── teacher/ # 👩🏫 Интерфейс преподавателя
|
||
│ └── index.html # Недельный просмотр динамического расписания преподавателя
|
||
│
|
||
└── student/ # 🎓 Интерфейс студента
|
||
└── index.html # Недельный просмотр динамического расписания группы
|
||
```
|
||
|
||
---
|
||
|
||
## Система маршрутизации (Admin SPA)
|
||
|
||
Админ-панель работает как **Single Page Application** без фреймворка.
|
||
|
||
Навигация реализована через `data-tab` атрибуты на элементах sidebar:
|
||
|
||
```html
|
||
<a href="#" class="nav-item" data-tab="users">Пользователи</a>
|
||
<a href="#" class="nav-item" data-tab="groups">Группы</a>
|
||
<a href="#" class="nav-item" data-tab="schedule">Расписание занятий</a>
|
||
<a href="#" class="nav-item" data-tab="academic-calendar">Календарный график</a>
|
||
```
|
||
|
||
При клике на пункт меню `main.js`:
|
||
1. Загружает HTML-шаблон из `views/{tab}.html` через `fetch()`
|
||
2. Вставляет его в `#app-content`
|
||
3. Подключает соответствующий JS-модуль из `js/views/{tab}.js`
|
||
4. Обновляет заголовок страницы (`#page-title`)
|
||
|
||
### Разделы админ-панели
|
||
|
||
| Tab | Описание | API |
|
||
|-----|----------|-----|
|
||
| `users` | CRUD пользователей | `/api/users` |
|
||
| `groups` | CRUD групп, подгруппы лабораторных и назначения графиков | `/api/groups`, `/api/subgroups` |
|
||
| `edu-forms` | Формы обучения | `/api/education-forms` |
|
||
| `profiles` | Создание, редактирование и удаление профилей обучения специальностей | `/api/specialties/{id}/profiles` |
|
||
| `equipments` | Оборудование | `/api/equipments` |
|
||
| `classrooms` | Аудитории | `/api/classrooms` |
|
||
| `subjects` | Дисциплины | `/api/subjects` |
|
||
| `schedule` | Конструктор правил динамического расписания | `/api/admin/schedule-rules`, `/api/admin/time-slots`, `/api/admin/calendar/years`, `/api/lesson-types`, `/api/subgroups` |
|
||
| `academic-calendar` | Учебные годы, семестры, создание календарных графиков и Excel-подобный редактор дневной сетки | `/api/admin/calendar`, `/api/admin/academic-calendars`, `/api/admin/calendar/activity-types`, `/api/education-forms` |
|
||
| `auditorium-workload` | Динамическая загруженность аудиторий: сводная матрица по дате или совмещённая таблица выбранной аудитории по чётной/нечётной неделе | `/api/classrooms`, `/api/admin/time-slots`, `/api/equipments`, `/api/groups`, `/api/schedule`, `/api/admin/calendar/years` |
|
||
| `database` | Тенанты | `/api/database` |
|
||
| `departments-data` | Создание, редактирование и удаление кафедр/специальностей | `/api/departments`, `/api/specialties` |
|
||
|
||
### Особенности админских вкладок
|
||
|
||
- Вкладка `groups` загружает кафедры, специальности, профили, учебные годы и календарные графики. Группа создаётся через `/api/groups` с `specialtyId` и `specialtyProfileId`, блок подгрупп использует `/api/subgroups` и `/api/groups/{id}/subgroups`, а блок назначений использует `/api/groups/{id}/calendar-assignments`.
|
||
- Вкладка `auditorium-workload` показывает матрицу загруженности по выбранной дате: строки — реальные аудитории из `/api/classrooms`, столбцы — эффективные временные слоты выбранного дня из `/api/admin/time-slots/effective`, занятость собирается из динамического расписания `/api/schedule` по группам. Фильтры корпуса, вместимости и оборудования заполняются из API. В поле «Отображение» можно выбрать конкретную аудиторию; тогда сводная матрица заменяется одной таблицей по дням недели и времени для двухнедельного периода от выбранной даты. Таблица выбранной аудитории растягивается до нижней части экрана. Ячейка делится вертикально только если верхняя и нижняя недели отличаются: нечётная неделя отображается сверху, чётная — снизу. Если состояние или занятие одинаковое, ячейка остаётся цельной. Чётность берётся из расписания, а для свободных дней рассчитывается по семестрам из `/api/admin/calendar/years`.
|
||
- Вкладка `profiles` выделена под профили обучения: администратор выбирает специальность, создаёт профиль, редактирует описание и удаляет неиспользуемые профили.
|
||
- Вкладка `schedule` не обращается к старым `lessons` API. Создание и редактирование расписания выполняется через правила `/api/admin/schedule-rules`, где каждое правило содержит группы, отдельные часы и недели начала для лекций, лабораторных и практик, а также набор базовых слотов. Группы выбираются через выпадающий мультиселект. Поле подгруппы появляется только при выборе лабораторной работы; для лекций и практик оно не отображается. Если в правиле выбрана одна группа, селект подгруппы содержит пункт `Вся группа`; если выбрано несколько групп, лабораторный слот показывает мультиселект подгрупп, чтобы выбрать разные подгруппы разных групп. Из календарной системы здесь используется список семестров для выбора периода действия правила.
|
||
- Вкладка `academic-calendar` полностью отделяет календарную систему от расписания занятий: администратор создаёт учебные годы и семестры, заводит календарные графики, выбирает форму обучения из общего справочника `/api/education-forms`, заполняет дневную сетку по курсам и кодам активностей, назначает ручную временную сетку на конкретную дату, а сохранение сетки идёт через `/api/admin/academic-calendars/{id}/grid`.
|
||
- Редактор годового графика во вкладке `academic-calendar` показывает компактную табличную сетку: курсы раскрываются отдельными секциями со стрелкой, семестры внутри курса идут вертикально друг под другом, столбцы подписаны номерами недель учебного года, строки — днями недели, а ячейки содержат буквенный код активности. Подробная расшифровка и изменение кода открываются в компактном модальном окне по клику на ячейку; выбранная ячейка и её код дополнительно подсвечиваются в общей сводке.
|
||
- Вкладка `departments-data` использует модальные формы редактирования и маршруты `PUT/DELETE /api/departments/{id}` и `PUT/DELETE /api/specialties/{id}`.
|
||
|
||
### Страница настроек (`/admin/settings/`)
|
||
|
||
Настройки — это **отдельный SPA** со своей боковой панелью и вкладками, не связанными с основной админ-панелью.
|
||
|
||
- Доступ: через dropdown «Настройки» в footer боковой панели админки
|
||
- Кнопка «Назад в панель» для возврата в `/admin/`
|
||
- Текущие вкладки:
|
||
- **Общие настройки** — заглушка (в разработке)
|
||
- **Временные слоты** — выбор сетки через выпадающий список, CRUD слотов выбранной сетки, добавление ручных сеток через модальное окно и удаление выбранной ручной сетки. Базовая сетка применяется по умолчанию, субботняя — автоматически по субботам; ручное применение выполняется в сетке календарного графика.
|
||
|
||
---
|
||
|
||
## API-клиент (`api.js`)
|
||
|
||
Все HTTP-запросы проходят через обёртку `apiFetch()`:
|
||
|
||
```javascript
|
||
export async function apiFetch(endpoint, method = 'GET', body = null) {
|
||
const response = await fetch(endpoint, {
|
||
method,
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: body ? JSON.stringify(body) : null
|
||
});
|
||
|
||
if (!response.ok) {
|
||
throw new Error(data?.message || `Ошибка HTTP: ${response.status}`);
|
||
}
|
||
|
||
return await response.json();
|
||
}
|
||
|
||
// Shortcut-методы
|
||
export const api = {
|
||
get: (url) => apiFetch(url, 'GET'),
|
||
post: (url, body) => apiFetch(url, 'POST', body),
|
||
put: (url, body) => apiFetch(url, 'PUT', body),
|
||
delete: (url, body) => apiFetch(url, 'DELETE', body)
|
||
};
|
||
```
|
||
|
||
Токен берётся из `localStorage.getItem('token')`.
|
||
|
||
---
|
||
|
||
## Аутентификация (Frontend)
|
||
|
||
### Страница входа (`/index.html`)
|
||
|
||
1. Пользователь вводит логин/пароль
|
||
2. `script.js` отправляет `POST /api/auth/login`
|
||
3. При успехе сохраняет в `localStorage`:
|
||
- `token` — UUID-токен
|
||
- `role` — роль пользователя
|
||
- `departmentId` — кафедра пользователя
|
||
- `userId` — ID пользователя для личного расписания преподавателя
|
||
4. Перенаправляет на соответствующий интерфейс:
|
||
- `ADMIN` → `/admin/`
|
||
- `TEACHER` → `/teacher/`
|
||
- `STUDENT` → `/student/`
|
||
|
||
### Проверка авторизации
|
||
|
||
На каждой странице проверяется наличие токена и роли:
|
||
|
||
```javascript
|
||
export function isAuthenticatedAsAdmin() {
|
||
const role = localStorage.getItem('role');
|
||
return token && role === 'ADMIN';
|
||
}
|
||
```
|
||
|
||
### Выход
|
||
|
||
Кнопка «Выйти» находится в dropdown-меню «Настройки» в footer боковой панели. Очищает `localStorage` и перенаправляет на `/`.
|
||
|
||
---
|
||
|
||
## Кабинеты расписания
|
||
|
||
### Преподаватель (`/teacher/`)
|
||
|
||
Страница показывает недельную сетку занятий преподавателя. ID преподавателя берётся из `localStorage.userId`, который сохраняется после `POST /api/auth/login`.
|
||
|
||
Основные элементы:
|
||
- навигация по неделям: предыдущая, текущая, следующая;
|
||
- выбор даты через `input[type="date"]`;
|
||
- запрос `GET /api/schedule?teacherId={userId}&startDate={YYYY-MM-DD}&endDate={YYYY-MM-DD}`;
|
||
- отображение дисциплины, времени, типа занятия, лабораторных подгрупп, аудитории и всех групп правила.
|
||
|
||
Если пользователь вошёл до появления поля `userId`, страница попросит выполнить вход заново.
|
||
|
||
### Студент (`/student/`)
|
||
|
||
В текущей модели студент не связан с конкретной группой, поэтому страница использует выбор группы из `/api/groups`.
|
||
|
||
Основные элементы:
|
||
- селект группы с сохранением выбора в `localStorage.studentGroupId`;
|
||
- недельная сетка по дням;
|
||
- запрос `GET /api/schedule?groupId={groupId}&startDate={YYYY-MM-DD}&endDate={YYYY-MM-DD}`;
|
||
- отображение дисциплины, времени, преподавателя, аудитории, формата, типа занятия и лабораторных подгрупп.
|
||
|
||
---
|
||
|
||
## CSS-архитектура
|
||
|
||
### Модульный подход
|
||
|
||
Стили разделены на модульные файлы (порядок подключения важен):
|
||
|
||
1. **`main.css`** — CSS-переменные (цвета, шрифты, отступы), глобальные стили, тёмная тема
|
||
2. **`layout.css`** — Sidebar, topbar, content area, dropdown настроек, responsive
|
||
3. **`components.css`** — Кнопки, таблицы, карточки, badge, формы, theme-toggle
|
||
4. **`modals.css`** — Модальные окна
|
||
5. **`departments-data.css`** — Стили создания кафедры/специальности
|
||
|
||
### Темизация
|
||
|
||
CSS-переменные позволяют поддерживать светлую/тёмную тему:
|
||
|
||
```css
|
||
:root {
|
||
--bg-primary: #ffffff;
|
||
--text-primary: #1a1a2e;
|
||
--accent: #6366f1;
|
||
}
|
||
|
||
[data-theme="dark"] {
|
||
--bg-primary: #0f0f23;
|
||
--text-primary: #e2e8f0;
|
||
--accent: #818cf8;
|
||
}
|
||
```
|
||
|
||
Переключение — через `theme-toggle.js`.
|
||
|
||
---
|
||
|
||
## Боковая панель (Sidebar)
|
||
|
||
- **Скрытие/раскрытие** — кнопка-крестик в правом верхнем углу sidebar
|
||
- **Десктоп** (`>768px`): sidebar складывается влево, контент расширяется; состояние сохраняется в `localStorage` (`sidebar-collapsed`)
|
||
- **Мобильные** (`≤768px`): sidebar скрывается за кнопкой-гамбургер, выезжает как overlay с затемнением
|
||
- **Dropdown «Настройки»** в footer sidebar — содержит ссылку на страницу настроек и кнопку выхода
|
||
|
||
---
|
||
|
||
## OpenTelemetry (`otel.js`)
|
||
|
||
Клиентская телеметрия (document-load, fetch, XHR) отправляется через `BatchSpanProcessor` на `/otel/v1/traces`.
|
||
|
||
- **На production** — загружается автоматически через динамический `import()`
|
||
- **На localhost** — пропускается, чтобы избежать таймаутов CDN `esm.sh`
|
||
|
||
```javascript
|
||
if (!['localhost', '127.0.0.1'].includes(window.location.hostname)) {
|
||
import('./otel.js').catch(e => console.warn('OTel init skipped:', e.message));
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Адаптивность
|
||
|
||
Интерфейс адаптирован под мобильные устройства:
|
||
- Sidebar скрывается на экранах < 768px, выезжает как overlay
|
||
- Появляется кнопка-гамбургер (`#menu-toggle`)
|
||
- Кнопка-крестик закрывает sidebar на всех устройствах
|
||
- Таблицы получают горизонтальный скролл
|