# Руководство пользователя [ИИ-Академия](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 | Все разделы | Финальная редакция и форматирование | Варухин Н. А. |