Feature: серверная часть, ФИО и результаты теста в БД; правка ответа эскалация 80%

Made-with: Cursor

README.md

@@ -5,22 +5,46 @@
 ## Назначение
 
 - Раздача контента обучения и тестирования (HTML).
-- Фиксация ФИО сотрудника при старте обучения и при прохождении теста.
-- Сохранение результатов тестирования в базе данных.
+- Фиксация ФИО сотрудника при старте обучения (экран входа).
+- Сохранение результатов тестирования в PostgreSQL после прохождения теста.
 
 ## Требования и зависимости
 
 - Docker, Docker Compose
-- (Планируется) PostgreSQL для хранения записей о прохождении и результатах тестов
+- PostgreSQL 15 (запускается в контейнере)
 
 ## Установка и настройка
 
-1. Скопировать `.env.example` в `.env` и при необходимости задать переменные.
-2. Запуск: `docker compose up -d` (после добавления серверной части).
+1. Скопировать `.env.example` в `.env` и задать пароль БД:
+   ```bash
+   cp .env.example .env
+   # Отредактировать .env: POSTGRES_PASSWORD=...
+   ```
+2. Запуск:
+   ```bash
+   cd /opt/lms-it-oms
+   docker compose up -d
+   ```
+3. Курс доступен по адресу: **http://localhost:8000/** (редирект на `/content/it_course_v2.html`).
 
 ## Конфигурация
 
-См. `.env.example`. Переменные задаются в `.env` (файл не коммитится).
+Переменные в `.env` (файл не коммитится):
+
+| Переменная | Описание | По умолчанию |
+|------------|----------|--------------|
+| POSTGRES_HOST | Хост БД | db |
+| POSTGRES_PORT | Порт БД | 5432 |
+| POSTGRES_DB | Имя БД | lms_it_oms |
+| POSTGRES_USER | Пользователь БД | lms |
+| POSTGRES_PASSWORD | Пароль БД | **обязательно задать** |
+| CONTENT_PATH | Путь к каталогу content в контейнере | /content |
+
+## API
+
+- `POST /api/start` — регистрация начала обучения. Тело: `{"fio": "ФИО"}`. Ответ: `{"participant_id": "...", "fio": "..."}`.
+- `POST /api/complete` — фиксация результата теста. Тело: `{"participant_id": "...", "score": 20, "total_questions": 25, "percent": 80, "passed": true}`.
+- `GET /api/health` — проверка доступности API.
 
 ## Структура проекта
 
@@ -30,27 +54,37 @@
 ├── HISTORY.md
 ├── .env.example
 ├── docker-compose.yml
-├── content/          # HTML-файлы обучения и тестирования (положить сюда для анализа)
-└── (backend/ и static/ — будут добавлены при реализации серверной части)
+├── content/                 # HTML курса
+│   └── it_course_v2.html
+└── backend/
+    ├── Dockerfile
+    ├── requirements.txt
+    └── app/
+        ├── main.py          # FastAPI, статика, API
+        ├── config.py
+        ├── database.py
+        ├── models.py
+        └── schemas.py
 ```
 
-### Куда положить HTML для анализа
+## Docker Compose
 
-**Положите ваши HTML-файлы обучения и тестирования в каталог:**
-
-```
-/opt/lms-it-oms/content/
-```
-
-После размещения файлов можно запросить анализ и корректировку контента, а затем — добавление серверной части для учёта ФИО и результатов тестов.
+- **app** — FastAPI на порту 8000, раздаёт статику из `./content` и обрабатывает `/api/*`.
+- **db** — PostgreSQL 15, volume `lms_it_oms_data` для данных.
 
 ## Логирование
 
-(Будет описано после внедрения серверной части.)
+- Логи приложения: `docker compose logs -f app`
+- Логи БД: `docker compose logs -f db`
+- Ротация логов app: json-file, max-size 10m, max-file 3.
 
 ## Резервное копирование
 
-Volumes проекта будут добавлены в `/opt/gen7x/backup/include-volumes.txt`.
+Volume `lms-it-oms_lms_it_oms_data` добавлен в `/opt/gen7x/backup/include-volumes.txt`. Бэкапить данные PostgreSQL по общему регламенту платформы.
+
+## Восстановление из бэкапа
+
+Восстановить volume БД по инструкции платформы. После восстановления перезапустить: `docker compose up -d`.
 
 ## История изменений