init + api use

2025-11-03 17:59:08 +03:00
commit e777b57991
52 changed files with 20725 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,258 @@
+# Challenge Admin Panel
+
+Админская панель для управления Challenge Service - системой автоматической проверки заданий с помощью LLM.
+
+## 🎯 Реализованная функциональность
+
+### ✅ Dashboard (Главная страница)
+- **Основные метрики:**
+  - Количество пользователей, заданий, цепочек
+  - Общее количество проверок
+  - Статус очереди с загруженностью
+  - Среднее время проверки
+- **Статистика проверок:**
+  - Принятые/отклоненные/ожидающие
+  - Распределение по статусам
+- **Real-time обновление:** автоматическое обновление данных каждые 10 секунд
+
+### ✅ CRUD для Tasks (Заданий)
+- **Список заданий:**
+  - Таблица с названием, автором, датой создания
+  - Индикатор наличия скрытых инструкций (🔒)
+  - Поиск по названию
+  - Действия: редактировать, удалить
+- **Создание/редактирование задания:**
+  - Название (обязательное, до 255 символов)
+  - Описание в формате Markdown с вкладками "Редактор" и "Превью"
+  - **Скрытые инструкции для LLM** (🔒 только для преподавателей):
+    - Специальное поле с визуальным выделением
+    - Инструкции передаются LLM при проверке, но не видны студентам
+    - Примеры использования в подсказках
+  - Отображение метаданных (автор, даты создания/обновления)
+  - Валидация и обработка ошибок
+
+### ✅ CRUD для Chains (Цепочек)
+- **Список цепочек:**
+  - Таблица с названием, количеством заданий, датой создания
+  - Поиск по названию
+  - Действия: редактировать, удалить
+- **Создание/редактирование цепочки:**
+  - Название цепочки (обязательное)
+  - Выбор заданий из существующих
+  - Управление порядком заданий (кнопки вверх/вниз)
+  - Добавление/удаление заданий в цепочку
+  - Поиск доступных заданий
+
+### ✅ Users (Пользователи)
+- **Список пользователей:**
+  - Таблица с nickname, ID, датой регистрации
+  - Поиск по nickname
+  - Кнопка просмотра статистики
+- **Детальная статистика пользователя (модальное окно):**
+  - Общие метрики: выполнено, всего попыток, в процессе, требует доработки
+  - Прогресс по цепочкам с визуальными прогресс-барами
+  - Детали по заданиям со статусами
+  - Среднее время проверки
+
+### ✅ Submissions (Попытки)
+- **Список попыток:**
+  - Таблица с пользователем, заданием, статусом, попыткой
+  - Дата отправки и время проверки
+  - **Фильтрация:**
+    - Поиск по пользователю или заданию
+    - Фильтр по статусу (все/принято/доработка/проверяется/ожидает)
+  - Цветные бейджи статусов
+- **Детали попытки (модальное окно):**
+  - Метаданные: пользователь, статус, даты
+  - Описание задания (Markdown)
+  - Решение пользователя
+  - Обратная связь от LLM
+  - Время проверки
+
+## 🛠 Технологический стек
+
+- **React 18** + **TypeScript**
+- **React Router** для навигации
+- **Redux Toolkit** + **RTK Query** для state management и API
+- **Chakra UI v3** для UI компонентов
+- **react-markdown** для отображения Markdown
+- **Keycloak** для авторизации преподавателей
+
+## 📁 Структура проекта
+
+```
+src/
+├── __data__/
+│   ├── api/
+│   │   └── api.ts              # RTK Query API endpoints
+│   ├── kc.ts                   # Keycloak конфигурация
+│   ├── store.ts                # Redux store
+│   └── urls.ts                 # URL константы
+├── components/
+│   ├── ui/
+│   │   └── toaster.tsx         # Toast уведомления
+│   ├── ConfirmDialog.tsx       # Диалог подтверждения
+│   ├── EmptyState.tsx          # Пустое состояние
+│   ├── ErrorAlert.tsx          # Отображение ошибок
+│   ├── Layout.tsx              # Общий layout с навигацией
+│   ├── LoadingSpinner.tsx      # Индикатор загрузки
+│   ├── StatCard.tsx            # Карточка метрики
+│   └── StatusBadge.tsx         # Бейдж статуса
+├── pages/
+│   ├── dashboard/
+│   │   └── DashboardPage.tsx   # Главная страница
+│   ├── tasks/
+│   │   ├── TasksListPage.tsx   # Список заданий
+│   │   └── TaskFormPage.tsx    # Форма задания
+│   ├── chains/
+│   │   ├── ChainsListPage.tsx  # Список цепочек
+│   │   └── ChainFormPage.tsx   # Форма цепочки
+│   ├── users/
+│   │   └── UsersPage.tsx       # Список пользователей
+│   └── submissions/
+│       └── SubmissionsPage.tsx # Список попыток
+├── types/
+│   └── challenge.ts            # TypeScript типы
+├── app.tsx                     # Главный компонент
+├── dashboard.tsx               # Роутинг
+├── index.tsx                   # Entry point
+└── theme.tsx                   # Chakra UI theme
+```
+
+## 🔐 Авторизация
+
+Приложение требует авторизации через **Keycloak** с ролью **`teacher`** в клиенте **`journal`**.
+
+Конфигурация в `bro.config.js`:
+```javascript
+KC_URL: 'https://auth.brojs.ru'
+KC_REALM: 'itpark'
+KC_CLIENT_ID: 'journal'
+```
+
+Все API запросы автоматически отправляют Bearer токен через RTK Query middleware.
+
+## 🚀 Запуск проекта
+
+```bash
+# Установка зависимостей
+npm install
+
+# Запуск в режиме разработки (с стабами API)
+npm start
+
+# Сборка для production
+npm run build:prod
+```
+
+Приложение будет доступно по адресу: `http://localhost:8099`
+
+### 📡 Стабовый API сервер
+
+Проект включает полнофункциональный стабовый API сервер для разработки и тестирования без реального бэкенда.
+
+**Тестовые данные:**
+- `stubs/api/data/tasks.json` - 5 заданий с hiddenInstructions
+- `stubs/api/data/chains.json` - 3 цепочки заданий
+- `stubs/api/data/users.json` - 8 пользователей
+- `stubs/api/data/submissions.json` - 8 попыток с feedback от LLM
+- `stubs/api/data/stats.json` - системная статистика
+
+**Возможности:**
+- ✅ Полный CRUD для заданий и цепочек
+- ✅ In-memory хранилище (изменения сбрасываются при перезапуске)
+- ✅ Автоматическое обновление статистики
+- ✅ Генерация статистики пользователей на лету
+- ✅ Поддержка всех endpoints из документации
+
+**Примечание:** Все ответы возвращаются в формате `{ error: null, data: ... }`
+
+## 📡 API Endpoints
+
+Все endpoints используют базовый URL из конфига (`/api`).
+
+### Tasks
+- `GET /challenge/tasks` - список заданий
+- `GET /challenge/task/:id` - одно задание
+- `POST /challenge/task` - создать задание
+- `PUT /challenge/task/:id` - обновить задание
+- `DELETE /challenge/task/:id` - удалить задание
+
+### Chains
+- `GET /challenge/chains` - список цепочек
+- `GET /challenge/chain/:id` - одна цепочка
+- `POST /challenge/chain` - создать цепочку
+- `PUT /challenge/chain/:id` - обновить цепочку
+- `DELETE /challenge/chain/:id` - удалить цепочку
+
+### Users & Stats
+- `GET /challenge/users` - список пользователей
+- `GET /challenge/stats` - общая статистика системы
+- `GET /challenge/user/:userId/stats` - статистика пользователя
+
+### Submissions
+- `GET /challenge/submissions` - все попытки
+- `GET /challenge/user/:userId/submissions` - попытки пользователя
+
+## ⚙️ Ключевые особенности реализации
+
+### RTK Query с кэшированием
+Настроены `tagTypes` для автоматической инвалидации кэша:
+- `Task` - для заданий
+- `Chain` - для цепочек
+- `User` - для пользователей
+- `Submission` - для попыток
+- `Stats` - для статистики
+
+### Real-time обновления
+Dashboard использует `pollingInterval: 10000` для автоматического обновления статистики каждые 10 секунд.
+
+### hiddenInstructions (Скрытые инструкции)
+Специальное поле только для преподавателей:
+- Визуально выделено фиолетовым цветом
+- Передаётся LLM при проверке решений
+- Не видно студентам
+- Позволяет тонко настроить проверку
+
+### UX оптимизации
+- Loading состояния для всех запросов
+- Toast уведомления для успеха/ошибок
+- Confirm диалоги для опасных действий (удаление)
+- Empty states для пустых списков
+- Поиск и фильтрация на всех страницах
+- Адаптивный дизайн
+
+## 🔗 Навигация
+
+Переход между проектами настроен через `bro.config.js`:
+```javascript
+navigations: {
+  'challenge-admin-pl.main': '/challenge-admin-pl',
+  'link.challenge': '/challenge',
+}
+```
+
+В Layout есть кнопка "Открыть проигрыватель" для перехода к студенческому интерфейсу.
+
+## 📝 Документация
+
+Подробная документация по API и архитектуре системы находится в папке `docs/`:
+- `CHALLENGE_FRONTEND_GUIDE.md` - руководство для фронтенд разработчиков
+- `TEACHER_GUIDE.md` - руководство для преподавателей
+- `CHALLENGE_ANALYTICS_SUMMARY.md` - аналитика и метрики
+- `CHALLENGE_REACT_EXAMPLE.md` - примеры React компонентов
+
+## ✨ Дополнительно
+
+- Все компоненты типизированы с TypeScript
+- Markdown поддержка с превью и стилизацией
+- Обработка ошибок API с понятными сообщениями
+- Валидация форм
+- Responsive design
+
+---
+
+**Версия:** 1.0.0  
+**Дата:** Ноябрь 2025  
+**Статус:** ✅ Production Ready
+