```
Каждый класс = одно CSS-свойство. Это быстрее писать и легче менять.
### Двухцветная тема
По требованию заказчика, дизайн в двух цветах (белый + акцентный). Наши цвета определены в `index.css`:
```css
@theme {
--color-background: #ffffff; /* белый фон */
--color-primary: #2563eb; /* синий — акцентный цвет */
--color-foreground: #0f172a; /* тёмный текст */
}
```
---
## 7. Маршрутизация
### Что такое маршрутизация?
Когда вы нажимаете на ссылку «Вопросы», URL меняется на `/questions` и показывается нужная страница. Но **страница не перезагружается** — React Router просто меняет компонент.
```tsx
}> {/* общий каркас */}
} />
} />
} />
} />
} />
} />
```
`` — это **обёртка**: боковое меню слева, а справа — ``, куда подставляется текущая страница.
---
## 8. Как фронтенд общается с бэкендом
### API-запросы
Фронтенд отправляет запросы к бэкенду с помощью функции `fetch`:
```typescript
// Утилита из lib/utils.ts
async function apiFetch(path: string, options?: RequestInit): Promise {
const res = await fetch(`/api${path}`, {
headers: { "Content-Type": "application/json" },
...options,
});
return res.json();
}
// Использование
const questions = await apiFetch("/questions?date=2026-03-27");
```
### Прокси в Vite
Фронтенд работает на порту `5173`, бэкенд — на `3001`. Чтобы не было проблем с CORS, Vite проксирует запросы: всё, что начинается с `/api`, перенаправляется на бэкенд.
```typescript
// vite.config.ts
server: {
proxy: {
"/api": {
target: "http://localhost:3001",
changeOrigin: true,
},
},
}
```
---
## 9. Интеграция с ИИ (DeepSeek)
### Что такое DeepSeek?
DeepSeek — это **языковая модель** (LLM), похожая на ChatGPT. Она принимает текст и генерирует ответ.
### Как мы подключаемся?
DeepSeek использует **OpenAI-совместимый API**. Это значит, мы можем использовать библиотеку `openai` от OpenAI, просто поменяв адрес сервера:
```typescript
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.deepseek.com", // адрес DeepSeek вместо OpenAI
apiKey: "ваш-ключ",
});
```
### Промпты
**Промпт** (prompt) — это инструкция для ИИ. Мы используем разные промпты для разных задач:
- **prompt_answer** — для ответов на вопросы: «Ответь понятно, используй примеры»
- **prompt_textbook** — для учебника: «Объясняй просто, структурируй текст»
- **prompt_test** — для тестов: «Сгенерируй 10 вопросов с вариантами ответов»
- **prompt_report** — для отчёта: «Составь отчёт в таком-то формате»
Все промпты можно редактировать на странице «Настройки».
---
## 10. Стриминг ответов (SSE)
### Проблема
Когда ИИ генерирует длинный текст, ожидание может занять 10-30 секунд. Без стриминга пользователь видит пустой экран и думает, что приложение зависло.
### Решение: Server-Sent Events (SSE)
SSE — это технология, которая позволяет серверу **отправлять данные частями** по мере их генерации.
Как это работает:
1. Фронтенд отправляет запрос: «Ответь на вопрос»
2. Бэкенд начинает получать ответ от ИИ **по кусочкам**
3. Каждый кусочек сразу отправляется на фронтенд
4. Фронтенд показывает текст по мере поступления — как будто ИИ «печатает»
```
Сервер → Фронтенд:
data: {"content": "React"}
data: {"content": " — это"}
data: {"content": " библиотека"}
data: {"content": " для"}
data: {"content": " создания"}
data: {"content": " интерфейсов."}
data: [DONE]
```
На бэкенде:
```typescript
res.setHeader("Content-Type", "text/event-stream");
const stream = await client.chat.completions.create({
model: "deepseek-chat",
messages: [...],
stream: true, // ← включаем стриминг
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || "";
res.write(`data: ${JSON.stringify({ content })}\n\n`);
}
```
На фронтенде:
```typescript
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const text = decoder.decode(value);
// обработать полученные кусочки и обновить UI
}
```
---
## Словарь терминов
| Термин | Объяснение |
|--------|-----------|
| **API** | Application Programming Interface — способ общения между программами |
| **HTTP** | Протокол передачи данных в вебе (GET, POST, PUT, DELETE) |
| **JSON** | Формат данных: `{"name": "Константин", "age": 25}` |
| **REST** | Стиль проектирования API — каждый ресурс имеет свой URL |
| **ORM** | Object-Relational Mapping — работа с БД через объекты вместо SQL |
| **SSE** | Server-Sent Events — односторонняя отправка данных от сервера к клиенту |
| **LLM** | Large Language Model — большая языковая модель (ИИ) |
| **Промпт** | Текстовая инструкция для ИИ |
| **Компонент** | Переиспользуемый блок интерфейса в React |
| **Состояние** | Данные компонента, при изменении которых он перерисовывается |
| **Маршрут** | Связь между URL и страницей/обработчиком |
---
## 11. Дизайн: CSS-анимации и визуальные эффекты
### Почему дизайн важен?
Интерфейс — это первое, что видит пользователь. Если приложение выглядит современно и приятно, им хочется пользоваться. Claude, ChatGPT и другие ИИ-продукты ставят высокую планку дизайна.
### CSS-анимации
Анимации делают интерфейс «живым». В CSS анимация описывается через `@keyframes`:
```css
@keyframes fade-in {
from { opacity: 0; transform: translateY(8px); }
to { opacity: 1; transform: translateY(0); }
}
.animate-fade-in {
animation: fade-in 0.4s ease-out both;
}
```
Что происходит:
1. `from` — начальное состояние (элемент невидим и смещён вниз на 8px)
2. `to` — конечное состояние (полностью виден, на своём месте)
3. `0.4s` — длительность анимации
4. `ease-out` — плавное замедление в конце
5. `both` — применить конечное состояние после анимации
### Glow-эффект (свечение)
Свечение создаётся через `box-shadow` с цветом акцента:
```css
.glow-card:hover {
box-shadow:
0 0 0 1px rgba(79, 70, 229, 0.08), /* тонкая рамка */
0 4px 20px rgba(79, 70, 229, 0.08), /* мягкое свечение */
0 1px 3px rgba(0, 0, 0, 0.04); /* лёгкая тень */
transform: translateY(-1px); /* лёгкий подъём */
}
```
### Glassmorphism (стеклянный эффект)
Популярный тренд — полупрозрачный фон с размытием:
```css
.glass {
background: rgba(255, 255, 255, 0.85); /* полупрозрачный белый */
backdrop-filter: blur(12px); /* размытие фона за элементом */
}
```
### Пульсирующее свечение
Для привлечения внимания (например, иконка логотипа):
```css
@keyframes pulse-glow {
0%, 100% { box-shadow: 0 0 15px rgba(79, 70, 229, 0.15); }
50% { box-shadow: 0 0 30px rgba(79, 70, 229, 0.25); }
}
```
Свечение плавно усиливается и ослабевает — создаёт ощущение «дыхания».
### Принципы хорошей анимации
1. **Быстро** — не более 0.3-0.5 секунды (длиннее раздражает)
2. **Плавно** — используйте `ease-out` или `cubic-bezier`
3. **Ненавязчиво** — анимация не должна мешать работе
4. **Осмысленно** — анимируйте только то, что привлекает внимание к действию
---
## 12. Electron: веб-приложение как десктоп-программа
### Что такое Electron?
Electron — это фреймворк, который позволяет запускать веб-приложение **как обычную программу** на Windows, macOS и Linux. Технически, он встраивает браузер Chromium внутрь окна приложения.
Пример приложений на Electron: VS Code, Discord, Slack, Notion.
### Как это работает
```
┌──────────────────────────────────┐
│ Окно Electron (Chromium) │
│ ┌────────────────────────────┐ │
│ │ Наш React-фронтенд │ │
│ │ (http://localhost:5173) │ │
│ └────────────────────────────┘ │
│ │
│ Node.js (запускает бэкенд) │
└──────────────────────────────────┘
```
1. Electron запускает **бэкенд** (Express-сервер) как дочерний процесс
2. Открывает **окно** и загружает в него фронтенд
3. Пользователь видит обычное приложение, без адресной строки браузера
### Главный файл Electron (`electron/main.js`)
```javascript
const { app, BrowserWindow } = require("electron");
function createWindow() {
const win = new BrowserWindow({
width: 1200,
height: 800,
titleBarStyle: "hiddenInset", // macOS-стиль: кнопки светофора встроены
});
win.loadURL("http://localhost:5173");
}
app.whenReady().then(createWindow);
```
### Команды запуска
```bash
# Как десктоп-программу (Electron + бэкенд + фронтенд):
npm run dev
# Как обычное веб-приложение в браузере:
npm run dev:web
```
---
## Словарь терминов
| Термин | Объяснение |
|--------|-----------|
| **API** | Application Programming Interface — способ общения между программами |
| **HTTP** | Протокол передачи данных в вебе (GET, POST, PUT, DELETE) |
| **JSON** | Формат данных: `{"name": "Константин", "age": 25}` |
| **REST** | Стиль проектирования API — каждый ресурс имеет свой URL |
| **ORM** | Object-Relational Mapping — работа с БД через объекты вместо SQL |
| **SSE** | Server-Sent Events — односторонняя отправка данных от сервера к клиенту |
| **LLM** | Large Language Model — большая языковая модель (ИИ) |
| **Промпт** | Текстовая инструкция для ИИ |
| **Компонент** | Переиспользуемый блок интерфейса в React |
| **Состояние** | Данные компонента, при изменении которых он перерисовывается |
| **Маршрут** | Связь между URL и страницей/обработчиком |
| **Electron** | Фреймворк для создания десктоп-приложений из веб-технологий |
| **Glassmorphism** | Дизайн-тренд: полупрозрачные элементы с размытием фона |
| **@keyframes** | CSS-конструкция для описания шагов анимации |
---
## 13. Архив и поиск: работа с накопленными данными
### Зачем нужен архив?
Со временем в приложении накапливаются данные: вопросы, учебники, отчёты. Без архива старые данные «теряются» — их не видно на текущей странице. Архив собирает **всё** в одном месте.
### Группировка по датам
Данные в архиве организованы по дням. Для этого мы берём массив объектов и группируем:
```typescript
function groupByDate(items) {
const groups = {};
for (const item of items) {
const date = item.createdAt.split("T")[0]; // "2026-03-27T15:30:00" → "2026-03-27"
if (!groups[date]) groups[date] = [];
groups[date].push(item);
}
return groups;
// Результат: { "2026-03-27": [...], "2026-03-26": [...] }
}
```
### Поиск (фильтрация)
Поиск на фронтенде — это **фильтрация** массива по введённому тексту:
```typescript
const filtered = questions.filter(
(q) => q.text.toLowerCase().includes(search.toLowerCase())
);
```
`includes()` проверяет, содержит ли строка подстроку. `toLowerCase()` делает поиск нечувствительным к регистру.
### Табы (вкладки)
Табы — это состояние, определяющее какой контент показывать:
```typescript
const [tab, setTab] = useState("questions"); // "questions" | "textbooks" | "reports"
// В зависимости от tab показываем разные списки
{tab === "questions" && }
{tab === "textbooks" && }
```
---
## 14. Умное управление полями ввода
### Задача
По ТЗ нужно заполнить **минимум 5 вопросов в день**. Но если 3 уже сохранены — показывать 5 полей глупо. Нужно показать только 2 оставшихся (плюс кнопку «Ещё»).
### Решение
```typescript
function updateFieldCount(savedCount: number) {
const needed = Math.max(1, 5 - savedCount);
// Если сохранено 0 → 5 полей
// Если сохранено 3 → 2 поля
// Если сохранено 5+ → 1 поле (всегда можно добавить ещё)
setFields(Array(needed).fill(""));
}
```
`Math.max(1, ...)` гарантирует, что **хотя бы одно поле** всегда доступно.
---
*Учебник обновлён. Новые разделы: архив с поиском, умное управление полями.*