Спринт 4: AI-помощник на базе DeepSeek
- Страница /settings: ввод и проверка API ключа DeepSeek - POST /api/llm/generate — генерация вопросов по названию теста - POST /api/llm/improve — улучшение формулировки вопроса + ответов (модал с галочками) - POST /api/llm/distractors — генерация дистракторов - POST /api/llm/review — рецензия теста + кнопка «Предложить вариант» - POST /api/llm/improve_all — улучшение всего теста с постатейным сравнением - Миграция 004: таблица settings (key-value) - Шапка приложения с навигацией на /settings Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Aleksey Razorvin
@@ -0,0 +1,101 @@
|
||||
# ШАГ 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
|
||||
@@ -0,0 +1,78 @@
|
||||
# ШАГ 012 — Спринт 4: Доработки после тестирования
|
||||
|
||||
**Дата:** 2026-03-21
|
||||
**Контекст:** Мастер-класс по разработке системы тестирования сотрудников клиники.
|
||||
|
||||
---
|
||||
|
||||
## Запрос (серия правок после тестирования)
|
||||
|
||||
> 1. «Сгенерировать с AI» не должен спрашивать тему — использовать название теста
|
||||
> 2. «Улучшить» должен показывать сравнение старого и нового с галочками, а не затирать текст
|
||||
> 3. «Проверить тест» → добавить кнопку «Предложить вариант» с полным сравнением всего теста
|
||||
|
||||
---
|
||||
|
||||
## Доработки
|
||||
|
||||
### 1. Кнопка «Сгенерировать с AI»
|
||||
|
||||
**Было:** при нажатии открывался модал с полем ввода темы.
|
||||
|
||||
**Стало:**
|
||||
- Кнопка задизаблена, пока не заполнено поле «Название теста» (`shouldUpdate` на поле `title`)
|
||||
- При нажатии сразу берёт название теста как тему и запускает генерацию
|
||||
- Открывается модал с анимацией загрузки → превью вопросов → «Применить» / «Сгенерировать заново»
|
||||
|
||||
### 2. Кнопка «Улучшить» в карточке вопроса
|
||||
|
||||
**Было:** заменяла текст вопроса новой формулировкой без предупреждения.
|
||||
|
||||
**Стало:**
|
||||
- Открывается модал с двумя колонками: текущая формулировка и предложение AI
|
||||
- Изменения разбиты на позиции: текст вопроса + каждый вариант ответа отдельно
|
||||
- Чекбокс «Применить» у каждой позиции
|
||||
- Кнопка «Применить выбранные» — применяет только отмеченные пункты
|
||||
|
||||
**Изменения в бэкенде:**
|
||||
- `improve_question(db, question, answers)` — теперь принимает список ответов и возвращает JSON `{question, answers[]}`
|
||||
- `POST /api/llm/improve` — `ImproveRequest` добавлено поле `answers`, `ImproveResponse` теперь `{improved_question, improved_answers[]}`
|
||||
|
||||
### 3. Кнопка «Предложить вариант» в модале «Проверить тест»
|
||||
|
||||
**Новая кнопка** появляется после получения рекомендаций AI.
|
||||
|
||||
**Поведение:**
|
||||
- При нажатии вызывает новый `POST /api/llm/improve_all`
|
||||
- Модал переключается в режим сравнения: весь тест постранично
|
||||
- Для каждого вопроса: текущий vs AI-предложение + чекбокс
|
||||
- Для каждого варианта ответа: текущий vs AI-предложение + чекбокс
|
||||
- Правильные ответы помечены `(правильный ✓)`
|
||||
- Кнопки: «Применить выбранные» / «← К рекомендациям» / «Закрыть»
|
||||
|
||||
**Новые файлы/функции бэкенда:**
|
||||
- `improve_all(db, title, questions)` в `services/llm.py`
|
||||
- `POST /api/llm/improve_all` в `api/llm.py`
|
||||
|
||||
---
|
||||
|
||||
## Изменённые файлы
|
||||
|
||||
```
|
||||
backend/app/services/llm.py ← improve_question принимает answers; новая функция improve_all
|
||||
backend/app/api/llm.py ← обновлён ImproveRequest/ImproveResponse; новый /improve_all
|
||||
frontend/src/api/llm.ts ← обновлена сигнатура improve; новый метод improveAll
|
||||
frontend/src/components/TestForm/ ← все три доработки UI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Следующие шаги
|
||||
|
||||
- [x] Спринт 1: Инфраструктура + Создание тестов
|
||||
- [x] Спринт 2: Прохождение теста + результат
|
||||
- [x] Спринт 3: Редактирование + версионность
|
||||
- [x] Спринт 4: AI-помощник (DeepSeek)
|
||||
- [ ] Спринт 5: Трекер результатов
|
||||
- [ ] Спринт 6: Авторизация и роли
|
||||
- [ ] Спринт 7: Уведомления в MAX
|
||||
Reference in New Issue
Block a user