обновил документацию

2026-03-27 15:24:29 +03:00
parent 6be8db0cd0
commit e015758caf
3 changed files with 73 additions and 18 deletions
--- a/.agents/skills/auto-update-docs/SKILL.md
+++ b/.agents/skills/auto-update-docs/SKILL.md
@@ -30,6 +30,7 @@ description: Автоматическое обновление документ
 | `utils/*.java` | `docs/BUSINESS_LOGIC.md` |
 | `frontend/admin/js/views/*.js` | `docs/FRONTEND.md` |
 | `frontend/admin/css/*.css` | `docs/FRONTEND.md` |
+| `frontend/admin/settings/**` | `docs/FRONTEND.md` |
 | `compose.yaml`, `Dockerfile` | `docs/INFRASTRUCTURE.md` |
 | `application.properties` | `docs/ARCHITECTURE.md` |

--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,6 +26,7 @@ magistr/
 │   └── src/main/resources/db/migration/ # Flyway SQL миграции (версионирование схемы БД)
 ├── frontend/          # Статические файлы
 │   ├── admin/         # Интерфейс администратора
+│   │   └── settings/  # Страница настроек (отдельный SPA)
 │   ├── teacher/       # Интерфейс преподавателя
 │   └── student/       # Интерфейс студента
 ├── docs/              # 📖 Документация проекта
--- a/docs/FRONTEND.md
+++ b/docs/FRONTEND.md
@@ -28,12 +28,14 @@ frontend/
 │   │   ├── main.css        # CSS-переменные, цвета, типографика
 │   │   ├── layout.css      # Раскладка (sidebar, topbar, content)
 │   │   ├── components.css  # Кнопки, таблицы, карточки, формы
-│   │   └── modals.css      # Модальные окна
+│   │   ├── modals.css      # Модальные окна
+│   │   ├── department.css  # Стили кафедры
+│   │   └── departments-data.css # Стили создания кафедры/специальности
 │   ├── js/
 │   │   ├── main.js         # Инициализация, маршрутизация, навигация
 │   │   ├── api.js          # HTTP-обёртка (fetch + Authorization)
 │   │   ├── utils.js        # Утилиты
-│   │   ├── otel.js         # OpenTelemetry (клиентская телеметрия)
+│   │   ├── otel.js         # OpenTelemetry (клиентская телеметрия, только прод)
 │   │   └── views/          # Модули представлений
 │   │       ├── users.js        # Управление пользователями
 │   │       ├── groups.js       # Управление группами
@@ -42,16 +44,30 @@ frontend/
 │   │       ├── equipments.js   # Управление оборудованием
 │   │       ├── edu-forms.js    # Формы обучения
 │   │       ├── schedule.js     # Расписание занятий
-│   │       └── database.js     # Управление тенантами
-│   └── views/              # HTML-шаблоны представлений
-│       ├── users.html
-│       ├── groups.html
-│       ├── classrooms.html
-│       ├── subjects.html
-│       ├── equipments.html
-│       ├── edu-forms.html
-│       ├── schedule.html
-│       └── database.html
+│   │       ├── database.js     # Управление тенантами
+│   │       ├── department.js   # Кафедры
+│   │       └── departments-data.js # Создание кафедры/специальности
+│   ├── views/              # HTML-шаблоны представлений
+│   │   ├── users.html
+│   │   ├── groups.html
+│   │   ├── classrooms.html
+│   │   ├── subjects.html
+│   │   ├── equipments.html
+│   │   ├── edu-forms.html
+│   │   ├── schedule.html
+│   │   ├── database.html
+│   │   ├── department.html
+│   │   └── departments-data.html
+│   │
+│   └── settings/           # ⚙️ Страница настроек (отдельный SPA)
+│       ├── index.html      # Оболочка с собственной sidebar
+│       ├── css/
+│       │   ├── main.css    # CSS-переменные, базовые стили
+│       │   └── layout.css  # Sidebar, topbar, content
+│       ├── js/
+│       │   └── main.js     # Навигация по вкладкам настроек
+│       └── views/
+│           └── general.html # Общие настройки (заглушка)
 │
 ├── teacher/                # 👩‍🏫 Интерфейс преподавателя
 │   └── index.html          # Просмотр расписания
@@ -92,6 +108,17 @@ frontend/
 | `subjects` | Дисциплины | `/api/subjects` |
 | `schedule` | Расписание | `/api/users/lessons` |
 | `database` | Тенанты | `/api/database` |
+| `department` | Кафедры | `/api/departments` |
+| `departments-data` | Создание кафедры/специальности | `/api/departments` |
+
+### Страница настроек (`/admin/settings/`)
+
+Настройки — это **отдельный SPA** со своей боковой панелью и вкладками, не связанными с основной админ-панелью.
+
+- Доступ: через dropdown «Настройки» в footer боковой панели админки
+- Кнопка «Назад в панель» для возврата в `/admin/`
+- Текущие вкладки:
+  - **Общие настройки** — заглушка (в разработке)

 ---

@@ -157,7 +184,7 @@ export function isAuthenticatedAsAdmin() {

 ### Выход

-Кнопка «Выйти» очищает `localStorage` и перенаправляет на `/`.
+Кнопка «Выйти» находится в dropdown-меню «Настройки» в footer боковой панели. Очищает `localStorage` и перенаправляет на `/`.

 ---

@@ -165,12 +192,14 @@ export function isAuthenticatedAsAdmin() {

 ### Модульный подход

-Стили разделены на 4 файла (порядок подключения важен):
+Стили разделены на модульные файлы (порядок подключения важен):

 1. **`main.css`** — CSS-переменные (цвета, шрифты, отступы), глобальные стили, тёмная тема
-2. **`layout.css`** — Sidebar, topbar, content area, responsive
-3. **`components.css`** — Кнопки, таблицы, карточки, badge, формы
+2. **`layout.css`** — Sidebar, topbar, content area, dropdown настроек, responsive
+3. **`components.css`** — Кнопки, таблицы, карточки, badge, формы, theme-toggle
 4. **`modals.css`** — Модальные окна
+5. **`department.css`** — Стили страницы кафедр
+6. **`departments-data.css`** — Стили создания кафедры/специальности

 ### Темизация

@@ -194,10 +223,34 @@ CSS-переменные позволяют поддерживать светл

 ---

+## Боковая панель (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
+- Sidebar скрывается на экранах < 768px, выезжает как overlay
 - Появляется кнопка-гамбургер (`#menu-toggle`)
- Sidebar выезжает как overlay
+- Кнопка-крестик закрывает sidebar на всех устройствах
 - Таблицы получают горизонтальный скролл