Sem descrição

1 Ramos

Nickolay-Varuhin 38af3a3dd7 git_tg		há 1 mês atrás
README.md	38af3a3dd7 git_tg	há 1 mês atrás

Руководство пользователя ИИ-Академия

Аннотация

Настоящий документ является руководством пользователя платформы ИИ-Академия — корпоративной системы развития профессиональных и личностных навыков сотрудников с применением искусственного интеллекта.

Использование документа

Документ предназначен для сотрудников организации, HR-менеджеров и системных администраторов, осуществляющих эксплуатацию и настройку платформы «ИИ-Академия».

Содержание

Руководство пользователя ИИ-Академия

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 персонала с применением технологий искусственного интеллекта. Предназначена для организаций, заинтересованных в систематическом развитии компетенций сотрудников.

Архитектура системы включает три основных компонента:

Бэкенд-сервер (FastAPI) — обрабатывает HTTP-запросы, реализует бизнес-логику, взаимодействует с СУБД и ИИ-провайдером.
Фронтенд-приложение (Angular 19) — предоставляет пользовательский интерфейс в браузере.
СУБД 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. Получение исходного кода

git clone https://gogs.itiscaf.ru/varukhin_na/ii-academy.git
cd ii-academy

[ ] 3.2.2. Создание и настройка базы данных

createdb -U postgres soft_skills
psql -U postgres -d soft_skills -f backend/init_db_postgres.sql

[ ] 3.2.3. Настройка конфигурации бэкенда

Создайте файл backend/.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. Установка зависимостей и запуск бэкенда

cd backend
pip install -r requirements.txt
python seed.py
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

[ ] 3.2.5. Установка зависимостей и запуск фронтенда
```
cd frontend
npm install
ng serve --open
```

Приложение откроется по адресу: http://localhost:4200

3.3. Порядок проверки работоспособности

1. Проверка бэкенда:

Откройте Swagger-документацию: http://localhost:8000/docs — должен отобразиться интерактивный список API-эндпоинтов.

2. Проверка фронтенда:

Откройте браузер по адресу http://localhost:4200 — должна отобразиться страница входа в систему.

3. Проверка аутентификации:

Войдите с тестовыми данными:

Роль	Email	Пароль
Сотрудник	employee@company.ru	emp123456
HR-менеджер	hr@company.ru	hr123456
Администратор	admin@company.ru	admin123

4. Запуск автоматических тестов:

cd backend
pytest tests/test_platform.py -v

При успешной установке все 17 тестов должны пройти со статусом PASSED.

4. Описание операций

4.1. Вход в систему

Откройте браузер и перейдите по адресу http://localhost:4200. На странице входа введите корпоративный email и пароль, затем нажмите кнопку «Войти».

При успешной аутентификации система перенаправит вас на дашборд в соответствии с вашей ролью.

4.2. Прохождение диалогового тренинга

Перейдите в раздел «Мои задания».
Выберите назначенное задание и нажмите «Начать».
В открывшемся тренажёре вводите ответы в поле внизу экрана и нажимайте «Отправить».
ИИ-наставник сформирует ответную реплику и оценит качество вашего ответа.
По завершении диалога система отобразит итоговую оценку и обратную связь.

Пример обращения к API диалога:

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%)

4.4. Назначение заданий (HR)

Перейдите в «HR-дашборд» → «Управление заданиями».
Нажмите «Назначить задание».
Выберите сотрудника из выпадающего списка.
Укажите навык, сценарий и срок выполнения.
Нажмите «Сохранить».

4.5. Формирование отчётов (HR)

Перейдите в «HR-дашборд» → «Отчёты», выберите сотрудника или отдел, укажите период и нажмите «Сгенерировать». Готовый отчёт можно скачать в форматах PDF или DOCX.

4.6. Управление пользователями (Администратор)

Раздел «Администрирование» → «Пользователи» позволяет:

создавать новые учётные записи;
редактировать роль и данные пользователей;
деактивировать учётные записи без удаления истории.

В разделе «Журнал событий» доступна полная история всех действий пользователей с фильтрацией по типу события, пользователю и периоду.

5. Аварийные ситуации

5.1. Бэкенд-сервер недоступен

Симптом: страница входа не открывается, браузер показывает ошибку подключения.

Действия:

Убедитесь, что процесс uvicorn запущен.
Проверьте доступность API: curl http://localhost:8000/docs.
Проверьте подключение к базе данных в файле .env.
Перезапустите сервер: uvicorn main:app --host 0.0.0.0 --port 8000 --reload.

5.2. Ошибка «Неверный логин или пароль»

Симптом: при вводе корректных данных система возвращает ошибку аутентификации.

Действия:

Проверьте правильность ввода email (регистр не важен) и пароля.
Убедитесь, что учётная запись активна — обратитесь к администратору.
Администратор может сбросить пароль через раздел «Управление пользователями».

5.3. ИИ-наставник не отвечает

Симптом: после отправки сообщения в тренажёре индикатор загрузки крутится более 30 секунд.

Действия:

Проверьте значение LLM_PROVIDER в файле .env.
Убедитесь в корректности ключа GIGACHAT_AUTH_KEY (или ключа OpenAI).
Для быстрой проверки временно установите LLM_PROVIDER=mock — это включит демо-режим без реального ИИ.

5.4. Отчёт не формируется

Симптом: при нажатии «Сгенерировать» кнопка неактивна или появляется ошибка.

Действия:

Убедитесь, что у выбранного сотрудника есть хотя бы одна завершённая диалоговая сессия.
Проверьте, что в системе установлены библиотеки reportlab и python-docx (входят в requirements.txt).

5.5. Белый экран после входа

Симптом: после успешного входа отображается белая страница без содержимого.

Действия:

Нажмите F5 для обновления страницы.
Очистите кеш браузера (Ctrl+Shift+Delete).
Убедитесь, что фронтенд-сервер запущен: ng serve.

6. Рекомендации по освоению

Начните с демо-режима. Установите LLM_PROVIDER=mock в файле .env — система будет работать без реального ИИ-провайдера, что позволит изучить интерфейс без настройки API-ключей.
Используйте тестовые учётные данные для проверки всех трёх ролей перед настройкой реальных пользователей.
Запустите автотесты после каждого изменения конфигурации:
```
pytest backend/tests/test_platform.py -v
```
Изучите Swagger-документацию по адресу http://localhost:8000/docs — там доступен полный список эндпоинтов с возможностью тестирования прямо из браузера.
Не храните секретные ключи (SECRET_KEY, GIGACHAT_AUTH_KEY) в репозитории. Используйте файл .env, который добавлен в .gitignore.
Регулярно создавайте резервные копии базы данных:
```
pg_dump -U postgres -Fc soft_skills > backup_$(date +%Y%m%d).dump
```
Для 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 GitHub

Лист регистрации изменений

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