Add README user manual

README.md

@@ -0,0 +1,433 @@
+# Руководство пользователя [ИИ-Академия](https://gogs.itiscaf.ru/varukhin_na/ii-academy)
+
+## Аннотация
+
+Настоящий документ является руководством пользователя платформы **ИИ-Академия** — корпоративной системы развития профессиональных и личностных навыков сотрудников с применением искусственного интеллекта.
+
+**Использование документа**
+
+Документ предназначен для сотрудников организации, HR-менеджеров и системных администраторов, осуществляющих эксплуатацию и настройку платформы «ИИ-Академия».
+
+---
+
+## Содержание
+
+- [Руководство пользователя ИИ-Академия](#руководство-пользователя-ии-академия)
+  * [Аннотация](#аннотация)
+  * [1. Введение](#1-введение)
+  * [1.1. Область применения](#11-область-применения)
+  * [1.2. Краткое описание возможностей](#12-краткое-описание-возможностей)
+  * [1.3. Уровень подготовки пользователя](#13-уровень-подготовки-пользователя)
+  * [1.4. Перечень эксплуатационной документации](#14-перечень-эксплуатационной-документации)
+  * [2. Назначение и условия применения](#2-назначение-и-условия-применения)
+  * [3. Подготовка к работе](#3-подготовка-к-работе)
+  * [3.1. Состав и содержание дистрибутивного носителя данных](#31-состав-и-содержание-дистрибутивного-носителя-данных)
+  * [3.2. Порядок загрузки данных и программ](#32-порядок-загрузки-данных-и-программ)
+  * [3.3. Порядок проверки работоспособности](#33-порядок-проверки-работоспособности)
+  * [4. Описание операций](#4-описание-операций)
+  * [4.1. Вход в систему](#41-вход-в-систему)
+  * [4.2. Прохождение диалогового тренинга](#42-прохождение-диалогового-тренинга)
+  * [4.3. Просмотр карты навыков](#43-просмотр-карты-навыков)
+  * [4.4. Назначение заданий (HR)](#44-назначение-заданий-hr)
+  * [4.5. Формирование отчётов (HR)](#45-формирование-отчётов-hr)
+  * [4.6. Управление пользователями (Администратор)](#46-управление-пользователями-администратор)
+  * [5. Аварийные ситуации](#5-аварийные-ситуации)
+  * [6. Рекомендации по освоению](#6-рекомендации-по-освоению)
+  * [7. Термины и сокращения](#7-термины-и-сокращения)
+  * [8. Контакты для связи](#8-контакты-для-связи)
+  * [Лист регистрации изменений](#лист-регистрации-изменений)
+
+---
+
+## 1. Введение
+
+### 1.1. Область применения
+
+«ИИ-Академия» применяется в корпоративной среде для автоматизации процессов обучения и оценки компетенций персонала. Система обеспечивает интерактивное взаимодействие сотрудника с ИИ-наставником в формате диалоговых тренажёров и позволяет HR-подразделениям отслеживать прогресс и формировать аналитику.
+
+Типичные сценарии применения:
+
+- Отработка навыков деловых переговоров и коммуникации.
+- Подготовка к публичным выступлениям и презентациям.
+- Онбординг новых сотрудников.
+- Оценка уровня освоения корпоративных компетенций.
+- HR-аналитика по отделам и отдельным сотрудникам.
+
+### 1.2. Краткое описание возможностей
+
+«ИИ-Академия» предоставляет следующие возможности:
+
+- **Диалоговый тренажёр** — интерактивные сессии с ИИ-наставником по заданным сценариям.
+- **Карта навыков** — персональная страница с уровнем освоения каждой компетенции.
+- **Система назначений** — HR-менеджер назначает задания сотрудникам с указанием срока.
+- **Обратная связь от ИИ** — автоматическая оценка качества ответов по итогам сессии.
+- **Аналитика** — сводная статистика по отделам и сотрудникам на HR-дашборде.
+- **Отчёты** — выгрузка персональных отчётов в форматах **PDF** и **DOCX**.
+- **Журнал событий** — аудит всех действий пользователей (для администратора).
+- **Ролевая модель** — три уровня доступа: `employee` / `hr` / `admin`.
+
+### 1.3. Уровень подготовки пользователя
+
+Пользователь должен обладать следующими знаниями и навыками:
+
+- Базовые навыки работы с веб-браузером и электронной почтой.
+- Для **HR-менеджера**: знание структуры отделов и перечня сотрудников организации.
+- Для **администратора**: базовые навыки администрирования Linux-систем, знание PostgreSQL, опыт работы с командной строкой (`bash`, `pip`, `npm`).
+
+### 1.4. Перечень эксплуатационной документации
+
+При эксплуатации системы «ИИ-Академия» следует руководствоваться:
+
+- Настоящим руководством пользователя.
+- `README.md` в репозитории проекта: https://gogs.itiscaf.ru/varukhin_na/ii-academy
+- Swagger-документацией API: `http://<адрес_сервера>:8000/docs`
+- Документацией FastAPI: https://fastapi.tiangolo.com
+- Документацией Angular: https://angular.dev
+
+---
+
+## 2. Назначение и условия применения
+
+**«ИИ-Академия»** — корпоративная платформа для развития soft-skills персонала с применением технологий искусственного интеллекта. Предназначена для организаций, заинтересованных в систематическом развитии компетенций сотрудников.
+
+**Архитектура системы** включает три основных компонента:
+
+1. **Бэкенд-сервер (FastAPI)** — обрабатывает HTTP-запросы, реализует бизнес-логику, взаимодействует с СУБД и ИИ-провайдером.
+2. **Фронтенд-приложение (Angular 19)** — предоставляет пользовательский интерфейс в браузере.
+3. **СУБД PostgreSQL 15** — хранит данные пользователей, диалоговых сессий, навыков и журнала событий.
+
+**Минимальные технические требования:**
+
+| Компонент | Требование |
+| --- | --- |
+| ОС сервера | Ubuntu 22.04+ / Windows 10+ / macOS 12+ |
+| Python | 3.11 и выше |
+| Node.js | 20 LTS и выше |
+| PostgreSQL | 15 и выше |
+| Браузер клиента | Chrome 110+, Firefox 110+, Edge 110+ |
+| Разрешение экрана | Не менее 1280 × 720 пикселей |
+
+---
+
+## 3. Подготовка к работе
+
+### 3.1. Состав и содержание дистрибутивного носителя данных
+
+Исходный код системы размещён в репозитории: https://gogs.itiscaf.ru/varukhin_na/ii-academy
+
+Структура репозитория:
+
+```
+ii-academy/
+├── backend/
+│   ├── main.py                  # Точка входа FastAPI
+│   ├── models.py                # ORM-модели (SQLAlchemy)
+│   ├── schemas.py               # Pydantic-схемы
+│   ├── auth.py                  # JWT-аутентификация
+│   ├── config.py                # Настройки из .env
+│   ├── database.py              # Подключение к PostgreSQL
+│   ├── routers/                 # Маршрутизаторы API
+│   ├── services/                # Бизнес-логика и ИИ-провайдеры
+│   ├── requirements.txt         # Зависимости Python
+│   ├── init_db_postgres.sql     # Скрипт создания схемы БД
+│   └── seed.py                  # Начальное заполнение БД
+├── frontend/
+│   ├── src/app/
+│   │   ├── pages/               # Страницы приложения
+│   │   ├── services/            # HTTP-клиент и аутентификация
+│   │   └── guards/              # Защита маршрутов
+│   └── package.json
+└── README.md
+```
+
+### 3.2. Порядок загрузки данных и программ
+
+- [ ] **3.2.1. Получение исходного кода**
+
+```bash
+git clone https://gogs.itiscaf.ru/varukhin_na/ii-academy.git
+cd ii-academy
+```
+
+- [ ] **3.2.2. Создание и настройка базы данных**
+
+```bash
+createdb -U postgres soft_skills
+psql -U postgres -d soft_skills -f backend/init_db_postgres.sql
+```
+
+- [ ] **3.2.3. Настройка конфигурации бэкенда**
+
+Создайте файл `backend/.env` со следующим содержимым:
+
+```env
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/soft_skills
+SECRET_KEY=your-secret-key-here
+ACCESS_TOKEN_EXPIRE_HOURS=24
+CORS_ORIGINS=*
+
+# ИИ-провайдер: mock | gigachat | openai | ollama
+LLM_PROVIDER=gigachat
+GIGACHAT_AUTH_KEY=ваш_ключ_gigachat
+GIGACHAT_SCOPE=GIGACHAT_API_PERS
+GIGACHAT_VERIFY_SSL=false
+```
+
+> **Важно:** Замените значение `SECRET_KEY` на уникальную случайную строку перед развёртыванием в production.
+
+- [ ] **3.2.4. Установка зависимостей и запуск бэкенда**
+
+```bash
+cd backend
+pip install -r requirements.txt
+python seed.py
+uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+- [ ] **3.2.5. Установка зависимостей и запуск фронтенда**
+
+```bash
+cd frontend
+npm install
+ng serve --open
+```
+
+Приложение откроется по адресу: `http://localhost:4200`
+
+### 3.3. Порядок проверки работоспособности
+
+**1. Проверка бэкенда:**
+
+Откройте Swagger-документацию: `http://localhost:8000/docs` — должен отобразиться интерактивный список API-эндпоинтов.
+
+**2. Проверка фронтенда:**
+
+Откройте браузер по адресу `http://localhost:4200` — должна отобразиться страница входа в систему.
+
+![Страница входа](screenshots/login.png)
+
+**3. Проверка аутентификации:**
+
+Войдите с тестовыми данными:
+
+| Роль | Email | Пароль |
+| --- | --- | --- |
+| Сотрудник | employee@company.ru | emp123456 |
+| HR-менеджер | hr@company.ru | hr123456 |
+| Администратор | admin@company.ru | admin123 |
+
+**4. Запуск автоматических тестов:**
+
+```bash
+cd backend
+pytest tests/test_platform.py -v
+```
+
+При успешной установке все 17 тестов должны пройти со статусом `PASSED`.
+
+---
+
+## 4. Описание операций
+
+### 4.1. Вход в систему
+
+Откройте браузер и перейдите по адресу `http://localhost:4200`. На странице входа введите корпоративный email и пароль, затем нажмите кнопку **«Войти»**.
+
+![Страница входа](screenshots/login.png)
+
+При успешной аутентификации система перенаправит вас на дашборд в соответствии с вашей ролью.
+
+### 4.2. Прохождение диалогового тренинга
+
+1. Перейдите в раздел **«Мои задания»**.
+2. Выберите назначенное задание и нажмите **«Начать»**.
+3. В открывшемся тренажёре вводите ответы в поле внизу экрана и нажимайте **«Отправить»**.
+4. ИИ-наставник сформирует ответную реплику и оценит качество вашего ответа.
+5. По завершении диалога система отобразит итоговую оценку и обратную связь.
+
+![Диалоговый тренажёр](screenshots/simulator.png)
+
+Пример обращения к API диалога:
+
+```python
+import httpx
+
+# Авторизация
+resp = httpx.post(
+    "http://localhost:8000/api/auth/login",
+    data={"username": "employee@company.ru", "password": "emp123456"}
+)
+token = resp.json()["access_token"]
+headers = {"Authorization": f"Bearer {token}"}
+
+# Запуск сессии
+session = httpx.post(
+    "http://localhost:8000/api/dialog/start",
+    json={"scenario_id": 1},
+    headers=headers
+).json()
+
+# Отправка сообщения
+reply = httpx.post(
+    "http://localhost:8000/api/dialog/message",
+    json={"session_id": session["session_id"], "message": "Добрый день!"},
+    headers=headers
+).json()
+
+print(reply["ai_response"])
+```
+
+### 4.3. Просмотр карты навыков
+
+В разделе **«Карта навыков»** отображается прогресс освоения всех компетенций. Каждый навык имеет статус:
+
+- `not_started` — навык не начат (уровень 0%)
+- `in_progress` — навык в процессе освоения (1–79%)
+- `mastered` — навык освоен (80–100%)
+
+![Карта навыков](screenshots/skill_map.png)
+
+### 4.4. Назначение заданий (HR)
+
+1. Перейдите в **«HR-дашборд»** → **«Управление заданиями»**.
+2. Нажмите **«Назначить задание»**.
+3. Выберите сотрудника из выпадающего списка.
+4. Укажите навык, сценарий и срок выполнения.
+5. Нажмите **«Сохранить»**.
+
+![Форма назначения задания](screenshots/hr_assign.png)
+
+### 4.5. Формирование отчётов (HR)
+
+Перейдите в **«HR-дашборд»** → **«Отчёты»**, выберите сотрудника или отдел, укажите период и нажмите **«Сгенерировать»**. Готовый отчёт можно скачать в форматах **PDF** или **DOCX**.
+
+![Страница отчётов](screenshots/reports.png)
+
+### 4.6. Управление пользователями (Администратор)
+
+Раздел **«Администрирование»** → **«Пользователи»** позволяет:
+
+- создавать новые учётные записи;
+- редактировать роль и данные пользователей;
+- деактивировать учётные записи без удаления истории.
+
+В разделе **«Журнал событий»** доступна полная история всех действий пользователей с фильтрацией по типу события, пользователю и периоду.
+
+![Панель администратора](screenshots/admin.png)
+
+---
+
+## 5. Аварийные ситуации
+
+### 5.1. Бэкенд-сервер недоступен
+
+**Симптом:** страница входа не открывается, браузер показывает ошибку подключения.
+
+**Действия:**
+1. Убедитесь, что процесс `uvicorn` запущен.
+2. Проверьте доступность API: `curl http://localhost:8000/docs`.
+3. Проверьте подключение к базе данных в файле `.env`.
+4. Перезапустите сервер: `uvicorn main:app --host 0.0.0.0 --port 8000 --reload`.
+
+### 5.2. Ошибка «Неверный логин или пароль»
+
+**Симптом:** при вводе корректных данных система возвращает ошибку аутентификации.
+
+**Действия:**
+1. Проверьте правильность ввода email (регистр не важен) и пароля.
+2. Убедитесь, что учётная запись активна — обратитесь к администратору.
+3. Администратор может сбросить пароль через раздел «Управление пользователями».
+
+### 5.3. ИИ-наставник не отвечает
+
+**Симптом:** после отправки сообщения в тренажёре индикатор загрузки крутится более 30 секунд.
+
+**Действия:**
+1. Проверьте значение `LLM_PROVIDER` в файле `.env`.
+2. Убедитесь в корректности ключа `GIGACHAT_AUTH_KEY` (или ключа OpenAI).
+3. Для быстрой проверки временно установите `LLM_PROVIDER=mock` — это включит демо-режим без реального ИИ.
+
+### 5.4. Отчёт не формируется
+
+**Симптом:** при нажатии «Сгенерировать» кнопка неактивна или появляется ошибка.
+
+**Действия:**
+1. Убедитесь, что у выбранного сотрудника есть хотя бы одна завершённая диалоговая сессия.
+2. Проверьте, что в системе установлены библиотеки `reportlab` и `python-docx` (входят в `requirements.txt`).
+
+### 5.5. Белый экран после входа
+
+**Симптом:** после успешного входа отображается белая страница без содержимого.
+
+**Действия:**
+1. Нажмите `F5` для обновления страницы.
+2. Очистите кеш браузера (`Ctrl+Shift+Delete`).
+3. Убедитесь, что фронтенд-сервер запущен: `ng serve`.
+
+---
+
+## 6. Рекомендации по освоению
+
+1. **Начните с демо-режима.** Установите `LLM_PROVIDER=mock` в файле `.env` — система будет работать без реального ИИ-провайдера, что позволит изучить интерфейс без настройки API-ключей.
+
+2. **Используйте тестовые учётные данные** для проверки всех трёх ролей перед настройкой реальных пользователей.
+
+3. **Запустите автотесты** после каждого изменения конфигурации:
+
+```bash
+pytest backend/tests/test_platform.py -v
+```
+
+4. **Изучите Swagger-документацию** по адресу `http://localhost:8000/docs` — там доступен полный список эндпоинтов с возможностью тестирования прямо из браузера.
+
+5. **Не храните секретные ключи** (`SECRET_KEY`, `GIGACHAT_AUTH_KEY`) в репозитории. Используйте файл `.env`, который добавлен в `.gitignore`.
+
+6. **Регулярно создавайте резервные копии** базы данных:
+
+```bash
+pg_dump -U postgres -Fc soft_skills > backup_$(date +%Y%m%d).dump
+```
+
+7. **Для production-развёртывания** замените `--reload` на запуск через `gunicorn` или `systemd`-сервис и настройте HTTPS через Nginx.
+
+---
+
+## 7. Термины и сокращения
+
+| Термин / Сокращение | Расшифровка и описание |
+| :--- | :--- |
+| **ИИ** | Искусственный интеллект |
+| **JWT** | JSON Web Token — стандарт токенов для аутентификации пользователей |
+| **API** | Application Programming Interface — программный интерфейс приложения |
+| **REST API** | Архитектурный стиль взаимодействия компонентов через HTTP |
+| **HR** | Human Resources — управление персоналом |
+| **СУБД** | Система управления базами данных |
+| **Soft skills** | Надпрофессиональные личностные навыки |
+| **Сессия** | Одна диалоговая тренировка (завершённая или незавершённая) |
+| **Сценарий** | Заданный скрипт диалога для отработки конкретного навыка |
+| **Компетенция** | Измеримое умение, развиваемое в рамках платформы |
+| **Dashboard** | Дашборд — сводная страница с ключевыми показателями |
+| **FastAPI** | Python-фреймворк для создания REST API |
+| **Angular** | TypeScript-фреймворк для создания веб-приложений |
+| **PostgreSQL** | Реляционная СУБД, используемая для хранения данных платформы |
+| **GigaChat** | ИИ-модель от Сбера, используемая в качестве основного провайдера |
+| **bcrypt** | Алгоритм хэширования паролей |
+| **`mock`-режим** | Режим работы без реального ИИ-провайдера (для тестирования) |
+
+---
+
+## 8. Контакты для связи
+
+[Telegram](https://t.me/varukhin_dev) &nbsp;&nbsp; [GitHub](https://github.com/varukhin-na)
+
+---
+
+## Лист регистрации изменений
+
+| № | Дата | Раздел | Описание изменения | Автор |
+| --- | --- | --- | --- | --- |
+| 1 | 2026-05-20 | Все разделы | Первоначальное создание документа | Варухин Н. А. |
+| 2 | 2026-05-22 | 3.2, 3.3 | Добавление чек-боксов и примеров кода | Варухин Н. А. |
+| 3 | 2026-05-24 | 4.2 | Добавление примера Python-кода для API | Варухин Н. А. |
+| 4 | 2026-05-26 | 5 | Дополнение раздела аварийных ситуаций | Варухин Н. А. |
+| 5 | 2026-05-27 | Все разделы | Финальная редакция и форматирование | Варухин Н. А. |