# ШАГ 011 — Спринт 4: AI-помощник (DeepSeek)

**Дата:** 2026-03-21
**Контекст:** Мастер-класс по разработке системы тестирования сотрудников клиники.

---

## Запрос

> запускам спринт 4

---

## Реализовано

Интеграция с DeepSeek LLM при создании и редактировании тестов. Страница настроек для управления API ключом.

---

## Новые файлы

```
backend/app/models/setting.py            ← модель Setting (key-value)
backend/app/schemas/setting.py           ← SettingOut, SettingUpdate
backend/app/services/__init__.py         ← пакет services
backend/app/services/llm.py              ← DeepSeek клиент (все 4 функции)
backend/app/api/settings.py              ← GET/PUT /api/settings/{key}
backend/app/api/llm.py                   ← POST /api/llm/check|generate|improve|distractors|review
backend/alembic/versions/004_settings.py ← миграция: таблица settings
frontend/src/api/settings.ts             ← API клиент настроек
frontend/src/api/llm.ts                  ← API клиент LLM
frontend/src/pages/Settings/index.tsx    ← страница /settings
```

## Изменённые файлы

```
backend/app/main.py                            ← зарегистрированы роутеры settings и llm
backend/alembic/env.py                         ← импорт модели setting
backend/requirements.txt                       ← добавлен openai==1.57.0
frontend/src/components/TestForm/index.tsx     ← добавлены AI-кнопки
frontend/src/App.tsx                           ← Layout с шапкой, роут /settings
```

---

## API эндпоинты (новые)

| Метод | URL | Описание |
|-------|-----|----------|
| GET | `/api/settings/{key}` | Получить значение настройки |
| PUT | `/api/settings/{key}` | Сохранить значение настройки |
| POST | `/api/llm/check` | Проверить подключение к DeepSeek |
| POST | `/api/llm/generate` | Сгенерировать вопросы по теме |
| POST | `/api/llm/improve` | Улучшить формулировку вопроса |
| POST | `/api/llm/distractors` | Сгенерировать дистракторы |
| POST | `/api/llm/review` | Проверить качество всего теста |

---

## Схема БД (новое)

```
settings
  key         VARCHAR(100)  PK
  value       TEXT          nullable
  updated_at  TIMESTAMP     auto-updated
```

---

## AI-функции в форме теста

| Кнопка | Расположение | Действие |
|--------|-------------|---------|
| «Сгенерировать с AI» | Над списком вопросов | Открывает модал → ввод темы → превью → «Применить все вопросы» |
| «Проверить тест» | Над списком вопросов | Открывает модал с рекомендациями AI по всему тесту |
| «Улучшить» | В шапке каждого вопроса | Заменяет текст вопроса улучшенной AI-формулировкой |
| «Дистракторы» | В шапке каждого вопроса | Добавляет 3 новых неправильных варианта к вопросу |

---

## Технические детали

- DeepSeek API совместим с OpenAI SDK: `AsyncOpenAI(base_url="https://api.deepseek.com")`
- Модель: `deepseek-chat`
- `response_format={"type": "json_object"}` для generate и distractors — гарантирует JSON-ответ
- API ключ хранится в таблице `settings` с ключом `deepseek_api_key`; фронт ключ не видит
- Шапка приложения: новый `Layout` с `AppHeader` — ссылка «Настройки» в правом углу

---

## Следующие шаги

- [x] Спринт 1: Инфраструктура + Создание тестов
- [x] Спринт 2: Прохождение теста + результат
- [x] Спринт 3: Редактирование + версионность
- [x] Спринт 4: AI-помощник (DeepSeek)
- [ ] Спринт 5: Трекер результатов
- [ ] Спринт 6: Авторизация и роли
- [ ] Спринт 7: Уведомления в MAX