fix install diogram

2026-04-02 12:00:11 +05:00
parent 22bbc3a0a6
commit 8a189e310b
23 changed files with 1212 additions and 189 deletions
--- a/README.md
+++ b/README.md
@@ -2,6 +2,474 @@

 Веб-приложение для создания, проведения и анализа психологических тестов. Включает API-сервер на FastAPI и пользовательский интерфейс на Flet. Поставляется в Docker и поддерживает готовый тест по методике профессиональной ориентации Голланда.

+---
+
+## Содержание
+
+- [Архитектура](#архитектура)
+- [Быстрый старт](#быстрый-старт)
+- [Переменные окружения](#переменные-окружения)
+- [Структура проекта](#структура-проекта)
+- [База данных](#база-данных)
+- [API](#api)
+- [Тест Голланда](#тест-голланда)
+- [Паутинная диаграмма](#паутинная-диаграмма)
+- [Фронтенд](#фронтенд)
+- [Деплой с внешним прокси](#деплой-с-внешним-прокси)
+- [Известные ошибки и просчёты](#известные-ошибки-и-просчёты)
+
+---
+
+## Архитектура
+
+```
+Пользователь (браузер)
+       │
+       │ :80
+ [ Внешний прокси / nginx ]   ← необязателен для локальной сети
+       │
+       │ :80
+  [ web — Flet ASGI ]         ← единственный публичный сервис
+       │
+       │ http://api:8000  (только внутри Docker-сети)
+  [ api — FastAPI ]
+       │              │
+ [ PostgreSQL :5432 ] [ Redis :6379 ]
+```
+
+**Важно:** сервис `api` не публикует порты наружу — он доступен только контейнеру `web` внутри Docker-сети. Пользователь никогда не обращается к API напрямую.
+
+**Сетевая топология Docker:** PostgreSQL и Redis запускаются отдельным compose-файлом `docker-compose_db.yml` и подключаются к той же Docker network.
+
+---
+
+## Быстрый старт
+
+### 1. Инфраструктура (PostgreSQL + Redis)
+
+```bash
+docker compose -f docker-compose_db.yml up -d
+```
+
+### 2. Приложение (API + Web)
+
+```bash
+docker compose up -d --build
+```
+
+После запуска:
+
+| Адрес | Что |
+|---|---|
+| `http://localhost` | Веб-интерфейс (Flet) |
+| `http://localhost:8000/docs` | Swagger UI — **только с хоста сервера**, порт не опубликован |
+| `http://localhost:8000/redoc` | ReDoc |
+
+> В продакшне API недоступен снаружи. Для работы с `/docs` используйте SSH-туннель:
+> ```bash
+> ssh -L 8000:localhost:8000 user@your-server
+> ```
+
+Доступ к документации — логин/пароль из переменных `DOCS_USERNAME` / `DOCS_PASSWORD`.
+
+### 3. Инициализация БД
+
+После первого запуска выполните (с хоста сервера или через туннель):
+
+```bash
+# Создать таблицы
+curl -X POST http://localhost:8000/db/create-tables \
+  -H "X-Admin-Key: <ADMIN_KEY>"
+
+# Применить миграции (добавляет колонки, если БД уже была создана ранее)
+curl -X POST http://localhost:8000/db/migrate \
+  -H "X-Admin-Key: <ADMIN_KEY>"
+```
+
+### 4. Загрузка теста Голланда
+
+```bash
+# Создать тест (возвращает poll_id)
+curl -X POST http://localhost:8000/polls/holland \
+  -H "X-Admin-Key: <ADMIN_KEY>"
+
+# Загрузить ключ расшифровки (42 пары → 6 типов × 14 баллов)
+curl -X POST http://localhost:8000/polls/holland/<poll_id>/seed-scores \
+  -H "X-Admin-Key: <ADMIN_KEY>"
+```
+
+---
+
+## Переменные окружения
+
+> **Важно:** перед деплоем в продакшн обязательно смените `SECRET_KEY`, `ADMIN_KEY`, `DOCS_PASSWORD` и пароли БД.
+
+| Переменная | Описание | Пример |
+|---|---|---|
+| `APP_PATH` | Абсолютный путь к директории приложения внутри контейнера | `/app` |
+| `DB_HOST` | Хост PostgreSQL | `postgres` |
+| `DB_PORT` | Порт PostgreSQL | `5432` |
+| `DB_USER` | Пользователь БД | `postgres` |
+| `DB_PASS` | Пароль БД | `postgres` |
+| `DB_NAME` | Имя базы данных | `profi` |
+| `REDIS_HOST` | Хост Redis | `redis` |
+| `REDIS_PORT` | Порт Redis | `6379` |
+| `REDIS_DB` | Номер БД Redis | `0` |
+| `REDIS_PASSWORD` | Пароль Redis | — |
+| `SECRET_KEY` | Секрет для подписи JWT-токенов (min 32 символа) | `python -c "import secrets; print(secrets.token_hex(32))"` |
+| `ADMIN_KEY` | Ключ для защищённых admin-эндпоинтов | — |
+| `DOCS_USERNAME` | Логин для доступа к `/docs` и `/redoc` | `admin` |
+| `DOCS_PASSWORD` | Пароль для доступа к `/docs` и `/redoc` | — |
+| `API_URL` | Внутренний URL API для фронтенда (только Docker-сеть) | `http://api:8000` |
+
+Файл `docker-compose.yml` содержит **демо-значения** — не используйте их в продакшн.
+
+---
+
+## Структура проекта
+
+```
+api-copp/
+├── main.py                  # точка входа FastAPI, регистрация роутеров
+├── requirements.txt         # зависимости API
+├── pyproject.toml           # метаданные проекта
+├── Dockerfile.api           # образ API (python:3.14-slim)
+├── Dockerfile.web           # образ фронтенда (python:3.11-slim + flet), порт 80
+├── docker-compose.yml       # API (без портов) + Web (порт 80)
+├── docker-compose_db.yml    # PostgreSQL + Redis
+├── nginx.conf               # пример конфига nginx (для внешнего прокси)
+│
+├── bd/                      # слой доступа к данным
+│   ├── __init__.py          # Settings (pydantic), make_engine()
+│   └── tables/
+│       ├── simple_base.py   # общий Base для SQLAlchemy
+│       ├── users.py         # User
+│       ├── organization.py  # Organization
+│       ├── group.py         # Group
+│       ├── poll.py          # Poll
+│       ├── question.py      # Question
+│       ├── choice.py        # Choice
+│       ├── response.py      # Response, Answer
+│       ├── scale.py         # ScaleDimension, ChoiceScore
+│       └── radar_result.py  # RadarResult, RadarResultItem
+│
+├── route/                   # FastAPI-роутеры
+│   ├── auth_utils.py        # JWT, bcrypt, require_admin_key
+│   ├── auth.py              # /auth/register, /auth/login
+│   ├── base.py              # /health, /version
+│   ├── init_data_base.py    # /db/create-tables, /db/migrate
+│   ├── users_crud.py        # CRUD пользователей
+│   ├── groups_crud.py       # CRUD групп
+│   ├── organizations_crud.py# CRUD организаций
+│   ├── poll_crud.py         # CRUD опросов
+│   ├── question_crud.py     # CRUD вопросов
+│   ├── choice_crud.py       # CRUD вариантов ответов
+│   ├── response_crud.py     # приём ответов + авто-расчёт радара
+│   ├── holland_crud.py      # генерация теста Голланда + seed-scores
+│   ├── scale_crud.py        # CRUD осей и расшифровок
+│   ├── radar_crud.py        # расчёт и чтение радарных результатов
+│   └── radar_svg_gen.py     # серверная генерация SVG-диаграмм
+│
+├── web/                     # Flet-фронтенд
+│   ├── main.py              # точка входа Flet ASGI
+│   ├── router.py            # маршрутизация страниц
+│   ├── api_client.py        # httpx-обёртки над API (API_URL из env)
+│   ├── designer.py          # компоненты дизайн-системы
+│   ├── radar_chart.py       # виджет RadarChart (flet.canvas)
+│   ├── radar_svg.py         # генератор SVG-data-URI (на клиенте, не используется)
+│   └── views/
+│       ├── login_view.py
+│       ├── reg_view.py
+│       ├── user_view.py
+│       ├── profile_view.py
+│       ├── poll_view.py
+│       ├── response_view.py
+│       ├── my_tests_view.py
+│       ├── take_test_view.py
+│       └── content_users/
+│           ├── main_page.py       # главная: «Все тесты» / «Мои тесты»
+│           ├── poll_page.py       # прохождение теста (кастомные кнопки выбора)
+│           ├── response_page.py   # результат с паутинной диаграммой
+│           ├── my_tests_page.py   # список пройденных тестов
+│           ├── take_test_page.py  # список доступных тестов
+│           └── profile_page.py    # редактирование профиля
+│
+└── data/                    # смонтированный том Docker (./data:/app/data)
+    ├── postgres/            # данные PostgreSQL
+    └── radar/               # сохранённые SVG-файлы диаграмм
+```
+
+---
+
+## База данных
+
+### Схема таблиц
+
+```
+organizations ──< groups ──< users
+                              │
+polls ──< questions ──< choices ──< choice_scores
+  │                                     │
+  └──< responses ──< answers            │
+         │                              │
+         └──< radar_results ──< radar_result_items
+              (image_path)         └── (dimension_id FK → scale_dimensions)
+                                               ↑
+polls ──< scale_dimensions ──────────────────-─┘
+```
+
+### Ключевые таблицы
+
+| Таблица | Описание |
+|---|---|
+| `users` | Испытуемые: `username`, `hashed_password`, `first_name`, `last_name`, FK на `groups` и `organizations` |
+| `polls` | Тест/опрос: `title`, `description` |
+| `questions` | Вопросы теста с `type` (`single` / `multiple`) |
+| `choices` | Варианты ответов к вопросам |
+| `responses` | Один факт прохождения теста (user + poll + timestamp) |
+| `answers` | Конкретные ответы внутри прохождения |
+| `scale_dimensions` | Оси радарной диаграммы: `name`, `color`, `position`, FK на `polls` |
+| `choice_scores` | Расшифровка: какой вариант ответа сколько баллов вносит в какую ось |
+| `radar_results` | Итоговый результат по осям + `image_path` (путь к SVG-файлу) |
+| `radar_result_items` | Снимок значений по каждой оси на момент расчёта |
+
+### Миграции
+
+Таблицы создаются через `POST /db/create-tables`. Для уже существующих БД применяются дополнительные ALTER-миграции через `POST /db/migrate`. Текущие миграции:
+
+- Добавление колонок `username` / `hashed_password` в `users`
+- Добавление колонки `image_path` в `radar_results`
+
+---
+
+## API
+
+### Аутентификация
+
+```
+POST /auth/register      — регистрация (username ≥ 3 симв., password ≥ 8 симв.)
+POST /auth/login         — получить JWT-токен (OAuth2 password flow)
+```
+
+JWT-токен передаётся заголовком `Authorization: Bearer <token>`. Admin-операции требуют заголовок `X-Admin-Key`.
+
+### Основные эндпоинты
+
+```
+# Тесты
+GET    /polls                    — список тестов
+POST   /polls                    — создать тест
+GET    /polls/{id}               — тест с вопросами и вариантами
+DELETE /polls/{id}               — удалить тест
+
+# Вопросы / Варианты ответов
+POST   /polls/{id}/questions
+POST   /questions/{id}/choices
+
+# Прохождение
+POST   /polls/{poll_id}/responses           — сдать тест (автоматически считает радар)
+GET    /polls/users/{user_id}/responses     — история пользователя
+GET    /responses/{id}                      — конкретный результат
+
+# Результаты (радар)
+POST   /responses/{id}/radar/compute        — (пере)считать радарный результат
+GET    /responses/{id}/radar                — данные для диаграммы
+GET    /responses/{id}/radar/image          — SVG-файл диаграммы
+GET    /users/{user_id}/radar-results       — история радарных результатов
+
+# Оси и расшифровки
+POST   /polls/{poll_id}/dimensions          — создать ось
+GET    /polls/{poll_id}/dimensions          — список осей
+PUT    /dimensions/{id}
+DELETE /dimensions/{id}
+POST   /dimensions/{id}/scores              — задать расшифровку варианта ответа
+GET    /choices/{choice_id}/scores
+
+# Тест Голланда
+POST   /polls/holland                       — создать тест с 42 парами
+POST   /polls/holland/{poll_id}/seed-scores — загрузить ключ расшифровки
+
+# База данных (admin)
+POST   /db/create-tables
+POST   /db/migrate
+
+# Служебные
+GET    /health
+GET    /version
+```
+
+---
+
+## Тест Голланда
+
+Реализована **модификация Г.В. Резапкиной** теста профессиональной ориентации Дж. Голланда. 42 пары профессий, испытуемый выбирает предпочтительную в каждой паре.
+
+### Типы личности
+
+| Код | Название | Цвет |
+|---|---|---|
+| Р | Реалистичный | `#FF8C00` |
+| И | Интеллектуальный | `#4169E1` |
+| С | Социальный | `#32CD32` |
+| К | Конвенциональный | `#9370DB` |
+| П | Предприимчивый | `#DC143C` |
+| А | Артистический | `#FF69B4` |
+
+Каждый тип получает ровно 14 вопросов (= 14 максимально возможных баллов). Результат — паутинная диаграмма с 6 осями.
+
+### Процедура загрузки
+
+1. `POST /polls/holland` — создаёт тест с 42 вопросами-парами
+2. `POST /polls/holland/{poll_id}/seed-scores` — создаёт 6 `ScaleDimension` и 84 `ChoiceScore`
+
+---
+
+## Паутинная диаграмма
+
+### Как работает
+
+При сдаче теста (`POST /polls/{id}/responses`) сервер автоматически:
+
+1. Суммирует баллы по каждой оси (`ChoiceScore.score`) для выбранных вариантов
+2. Сохраняет результат в `radar_results` + `radar_result_items`
+3. Генерирует SVG-файл и сохраняет в `{APP_PATH}/data/radar/{result_id}.svg`
+4. Записывает относительный путь в `image_path` — всё в одном `commit()`
+
+### Скачивание SVG
+
+Фронтенд получает SVG-байты с API через внутреннюю Docker-сеть (`api_client.get_radar_svg_bytes()`), кодирует в `data:application/octet-stream;base64,...` и передаёт в `page.launch_url()`. Браузер скачивает файл **напрямую из data URI** — никаких запросов к API из браузера, никакой зависимости от публичности API.
+
+### Генерация SVG
+
+SVG генерируется чистым Python без зависимостей (`route/radar_svg_gen.py`):
+
+- Фон `#2F184B`, полигон `rgba(155,114,207,0.55)`
+- 5 концентрических сеток
+- Подписи с именем типа и баллом
+- Размер холста: 520×520 пикселей
+
+---
+
+## Фронтенд
+
+Написан на **Flet** — Python-фреймворке поверх Flutter. Работает как ASGI-приложение через uvicorn на порту 80.
+
+### Адаптация под мобильные устройства
+
+Интерфейс адаптирован для экранов с малым горизонтальным разрешением:
+
+- Формы входа и регистрации растягиваются на всю ширину экрана (без фиксированной ширины `360px`)
+- Карточки навигации («Все тесты» / «Мои тесты») переносятся на следующую строку при нехватке места (`ft.Row(wrap=True)`)
+- Варианты ответов в тесте реализованы кастомными контейнерами вместо `ft.Radio` — текст длинных вариантов переносится на следующую строку
+- Заголовок страницы пользователя не выталкивает кнопку профиля
+
+### Варианты ответов в тесте
+
+Вместо стандартного `ft.RadioGroup` / `ft.Radio` (лейбл которого не переносится) используются кастомные кликабельные контейнеры (`poll_page.py: _build_choice_group`). При выборе варианта:
+- фон меняется с `laer3` → `laer1`
+- появляется белая рамка
+- иконка меняется с `RADIO_BUTTON_UNCHECKED` → `CHECK_CIRCLE`
+
+### Маршруты
+
+| Путь | Страница |
+|---|---|
+| `/login` | Вход |
+| `/reg` | Регистрация |
+| `/user/{url_key}` | Главная страница пользователя |
+| `/take_test/{url_key}` | Список тестов для прохождения |
+| `/poll/{url_key}/{poll_id}` | Прохождение теста |
+| `/response/{url_key}/{response_id}` | Результат с диаграммой |
+| `/my_tests/{url_key}` | Мои результаты |
+| `/profile/{url_key}` | Профиль пользователя |
+
+`{url_key}` — одноразовый 32-символьный hex-ключ, генерируется при успешном входе (`secrets.token_hex(16)`). Обращение к защищённому маршруту с чужим ключом перенаправляет на `/login`.
+
+---
+
+## Деплой с внешним прокси
+
+В репозитории есть готовый файл `nginx.conf` для случая, когда nginx развёрнут на отдельном сервере или уже управляет несколькими сайтами.
+
+Минимальная конфигурация upstream в вашем nginx:
+
+```nginx
+location / {
+    proxy_pass         http://<server-ip>:80;
+    proxy_set_header   Host              $host;
+    proxy_set_header   X-Real-IP         $remote_addr;
+    proxy_http_version 1.1;
+    proxy_set_header   Upgrade    $http_upgrade;
+    proxy_set_header   Connection "Upgrade";
+}
+```
+
+Заголовки `Upgrade` / `Connection` обязательны — Flet использует WebSocket.
+
+---
+
+## Известные ошибки и просчёты
+
+### 1. Лишнее дублирование генерации SVG
+
+**Проблема:** SVG-генератор написан дважды — `route/radar_svg_gen.py` (сервер) и `web/radar_svg.py` (клиент).
+
+**Решение:** Кнопка «Сохранить» скачивает SVG через `api_client.get_radar_svg_bytes()`. `web/radar_svg.py` больше не используется, но файл остался — можно удалить при следующем рефакторинге.
+
+---
+
+### 2. Несовместимость Python 3.14 и psycopg ✅ исправлено
+
+**Проблема:** `pyproject.toml` указывал `psycopg>=3.3.3`, но реально используется синхронный `pg8000`.
+
+**Решение:** Зависимость заменена на `pg8000>=1.29.0`.
+
+---
+
+### 3. Нет транзакции при сохранении SVG ✅ исправлено
+
+**Проблема:** `image_path` обновлялся отдельным `commit()` после основного — при падении между ними запись оставалась без пути к файлу.
+
+**Решение:** SVG генерируется до коммита, `image_path` устанавливается до коммита. Один атомарный `session.commit()`.
+
+---
+
+### 4. Перенос подписей в диаграмме по буквам ✅ исправлено
+
+**Решение:** `_W_LBL` увеличен до 130, добавлен `max_lines=2, no_wrap=False`.
+
+---
+
+### 5. Текст вариантов ответов обрезался ✅ исправлено
+
+**Проблема:** `ft.Radio(label=...)` в Flet не переносит текст метки — длинные варианты ответов обрезались.
+
+**Решение:** Реализованы кастомные кликабельные контейнеры с `ft.Text(expand=True, no_wrap=False)`.
+
+---
+
+### 6. Браузер не может обратиться к `http://api:8000` ✅ исправлено
+
+**Проблема:** Внутреннее Docker-имя `api` недоступно из браузера пользователя.
+
+**Решение:** Фронтенд скачивает SVG через httpx (внутри Docker-сети) и передаёт браузеру как `data:application/octet-stream;base64,...`.
+
+---
+
+### 7. `image_path` добавлен после создания таблиц ✅ исправлено
+
+**Решение:** Добавлена явная миграция:
+```sql
+ALTER TABLE radar_results ADD COLUMN IF NOT EXISTS image_path VARCHAR(512);
+```
+
+---
+
+### 8. Документация API доступна без авторизации ✅ исправлено
+
+**Решение:** Стандартные маршруты `/docs`, `/redoc`, `/openapi.json` отключены. Зарегистрированы собственные с HTTP Basic Auth через `secrets.compare_digest`.
+
+
 ---

 ## Содержание
@@ -350,11 +818,14 @@ SVG генерируется чистым Python без зависимостей
 |---|---|
 | `/login` | Вход |
 | `/reg` | Регистрация |
+| `/user/{url_key}` | Главная страница пользователя |
 | `/take_test/{url_key}` | Список тестов для прохождения |
-| `/poll/{poll_id}` | Прохождение теста |
-| `/response/{response_id}` | Результат с диаграммой |
-| `/my_tests` | Мои результаты |
-| `/profile` | Профиль пользователя |
+| `/poll/{url_key}/{poll_id}` | Прохождение теста |
+| `/response/{url_key}/{response_id}` | Результат с диаграммой |
+| `/my_tests/{url_key}` | Мои результаты |
+| `/profile/{url_key}` | Профиль пользователя |
+
+`{url_key}` — одноразовый 32-символьный hex-ключ, генерируется при успешном входе (`secrets.token_hex(16)`) и сохраняется в сессии. Обращение к защищённому маршруту с чужим или отсутствующим ключом автоматически сбрасывает сессию и перенаправляет на `/login`.

 ### Диаграмма после теста

@@ -374,21 +845,21 @@ SVG генерируется чистым Python без зависимостей

 ---

-### 2. Несовместимость Python 3.14 и psycopg
+### 2. Несовместимость Python 3.14 и psycopg ✅ исправлено

-**Проблема:** `pyproject.toml` указывает `requires-python = ">=3.14"` и зависимость `psycopg>=3.3.3`, однако `Dockerfile.api` использует `python:3.14-slim`. `psycopg` (асинхронный адаптер) на 3.14 может не иметь собранных wheels. В `requirements.txt` вместо psycopg используется `pg8000==1.29.0` — синхронный pure-Python драйвер.
+**Проблема:** `pyproject.toml` указывал `requires-python = ">=3.14"` и зависимость `psycopg>=3.3.3`, однако `Dockerfile.api` использует `python:3.14-slim`. `psycopg` (асинхронный адаптер) на 3.14 может не иметь собранных wheels. В `requirements.txt` вместо psycopg используется `pg8000==1.29.0` — синхронный pure-Python драйвер.

-**Решение:** Все запросы к БД синхронные (`make_engine()` возвращает синхронный `create_engine` с `postgresql+pg8000://...`). Фактически psycopg не используется. `pyproject.toml` содержит ошибочную зависимость `psycopg`, которую следует убрать.
+**Решение:** Все запросы к БД синхронные (`make_engine()` возвращает синхронный `create_engine` с `postgresql+pg8000://...`). Фактически psycopg не используется. Ошибочная зависимость `psycopg` заменена на `pg8000>=1.29.0` в `pyproject.toml`.

 ---

-### 3. Нет транзакции при сохранении SVG
+### 3. Нет транзакции при сохранении SVG ✅ исправлено

-**Проблема:** После основного `session.commit()` (сохранение `RadarResult` и `RadarResultItem`) идёт отдельное обновление `result.image_path`. Если процесс упадёт между commit и вторым commit — в БД окажется запись без `image_path`, но файл будет создан на диске.
+**Проблема:** После основного `session.commit()` (сохранение `RadarResult` и `RadarResultItem`) шло отдельное обновление `result.image_path`. Если процесс падал между первым и вторым commit — в БД оставалась запись без `image_path`, хотя файл уже существовал на диске.

-**Последствие:** При повторном прохождении теста пересчёт (`compute_radar`) удаляет старый `RadarResult` и создаёт новый, что восстанавливает корректность. Но исторический файл `.svg` осиротеет на диске.
+**Последствие:** При повторном прохождении теста пересчёт (`compute_radar`) удалял старый `RadarResult` и создавал новый, что восстанавливало корректность. Но исторический файл `.svg` «осиротевал» на диске.

-**Рекомендация:** Объединить записи + генерацию SVG в одну транзакцию с rollback-обработчиком, либо хранить SVG в БД как blob/base64.
+**Решение:** `items_data` теперь строится непосредственно из `scores_map`/`dimensions` (данные уже в памяти после `flush()`), SVG генерируется до коммита, `result.image_path` устанавливается до коммита. Итого один `session.commit()` атомарно сохраняет `RadarResult`, `RadarResultItem` и путь к SVG.

 ---