docs: миграция на tgFlaskForm и производительность Flask; контур flask_app; UI без лишних описаний

Made-with: Cursor
2026-04-27 18:43:51 +05:00
parent 47279c72e3
commit b3e3757a92
20 changed files with 680 additions and 115 deletions
@@ -0,0 +1,87 @@
+# Перенос тестирования на кабинет HR — простым языком
+
+Это **короткий проектный документ** для заказчика и команды: зачем две базы, как они «сходятся» по людям, что делаем по шагам. Технические детали, таблицы и спринты — в отдельном файле: [migration-to-tgflaskform.md](migration-to-tgflaskform.md).
+
+---
+
+## 1. В чём суть
+
+Сейчас модуль тестирования может жить так:
+
+- **Старое приложение** (то, что уже есть): своя программа и своя база **`clinic_tests`**. В ней заведены «пользователи модуля» (логин, пароль и т.д.) и все тесты, попытки, ответы.
+- **Целевое место** — общий HR-кабинет на Python (**`tgFlaskForm`**): там уже есть раздел тестирования, данные лежат в другой базе — **`hr_bot_test`**, и каждый человек привязан к **карточке сотрудника** в HR (`staff_members`).
+
+**Перенос** — это не «скопировать файлы», а **аккуратно переложить смысл** из одной базы в другую так, чтобы в HR было понятно: *этот тест написал тот же Иванов, эту попытку прошла та же Петрова*, и чтобы баллы и история не потерялись.
+
+На переходный период можно держать **новый экран на Flask отдельно** (папка `flask_app` в этом репозитории) — тот же подход, что в кабинете, но свой адрес в браузере, пока не готовы полностью перейти на один вход.
+
+---
+
+## 2. Две базы — зачем и как они связаны
+
+| База | Простыми словами |
+|------|------------------|
+| **`clinic_tests`** | «Песочница» модуля тестирования: здесь живут тесты, версии, попытки в том виде, в каком их делало старое приложение. |
+| **`hr_bot_test`** | «Общий дом» HR: сотрудники, отделы, права, и при переносе — **те же тесты**, но уже в таблицах вида `testing_*`, привязанные к сотрудникам. |
+
+Обе базы обычно стоят **на одном сервере PostgreSQL**, но это **разные логические хранилища** (как два разных диска с разными папками). Скрипт переноса подключается к обеим и **переписывает данные** из одной в другую по правилам (сначала тесты и вопросы, потом попытки и ответы — чтобы ничего не «повисло» без ссылки).
+
+---
+
+## 3. Связка «пользователь модуля» ↔ «сотрудник в HR»
+
+В **`clinic_tests`** человек заведён как запись в таблице **`users`** (логин, роль в модуле и т.д.).
+
+В **`hr_bot_test`** человек — это **`staff_members`** (та самая карточка из кадрового контура).
+
+Чтобы перенос сработал, для **каждого**, кто важен для истории (автор теста, кто проходил, кто назначал), нужно знать одно число: **идентификатор сотрудника в HR** — `staff_members.id`.
+
+На практике это делается так:
+
+1. В таблице **`users`** (в `clinic_tests`) есть поле **`staff_id`** — туда записывается как раз **`staff_members.id`** из HR. Тогда программа понимает: *логин `ivanov` в модуле тестов = сотрудник № 12345 в HR*.
+2. Если **`staff_id` пустой** — автоматом не понять, кто это. Тогда до переноса нужно **вручную или полуавтоматом** составить соответствия: например таблица «логин / email / ФИО → номер сотрудника в HR», заполнить `staff_id` или отдать это скрипту миграции отдельным файлом.
+
+**Имеется в виду не «настроить взаимодействие двух баз в реальном времени»** (как два приложения, которые постоянно синхронизируются), а **один раз правильно сопоставить людей**, чтобы при копировании данных в HR не оказалось «логин есть, а сотрудник не найден».
+
+---
+
+## 4. Что делаем по этапам (без жаргона)
+
+**Подготовка**
+
+- Решить: пока живём на **старой базе** в новом Flask или сразу пишем в **HR-базу** — и не вести параллельно «два источника правды» без правил.
+- Список сценариев: создание теста, версии, назначение, прохождение, разбор, отчёты — и отметить, что уже есть в кабинете, чего не хватает.
+
+**Данные**
+
+- Проверить **`staff_id`** у нужных `users`.
+- Сделать **резервную копию** обеих баз.
+- Запустить скрипт в режиме **«только посмотреть»** (`--dry-run`): он ничего не пишет в HR, только показывает, сколько чего нашёл.
+- На **копии** HR-базы один раз прогнать **настоящий перенос**, открыть несколько тестов и попыток глазами.
+- В согласованное короткое окно (когда никто не правит тесты) — перенос на боевую HR-базу, проверка, смена ссылок для пользователей на кабинет.
+
+**После переноса**
+
+- Старое приложение можно оставить только для чтения или выключить, когда убедились, что в кабинете всё ок.
+- Бэкап старой базы и журнал переноса хранить по правилам клиники.
+
+Подробные шаги ETL, порядок таблиц и ограничения текущего скрипта — в [migration-to-tgflaskform.md](migration-to-tgflaskform.md), раздел 4. Скрипт: в монорепозитории HR, файл `HR_TG_Bot/tgFlaskForm/tools/migrate_clinic_tests_to_hr.py`.
+
+---
+
+## 5. Что может пойти не так
+
+- **Не все люди сопоставлены с HR** — часть тестов или попыток не перенесётся или перенесётся с ошибками. Лечится заранее: отчёт по пустым `staff_id` и дозаполнение.
+- **Два места, куда одновременно пишут** — данные разъедутся. Лечится правилом: в период перехода пишем только в одно место (или второе только для пилота).
+- **Назначения «на весь отдел»** в старой базе — в HR их нужно либо развернуть в список конкретных сотрудников на дату переноса, либо доработать логику отдельно — это заранее обсуждается с заказчиком.
+
+---
+
+## 6. Куда смотреть дальше
+
+| Нужно | Файл |
+|--------|------|
+| Технический план, спринты, таблицы | [migration-to-tgflaskform.md](migration-to-tgflaskform.md) |
+| Состояние кода старого приложения | [PROJECT_STATUS.md](PROJECT_STATUS.md) |
+| Запуск нового Flask-контура в Docker | [../flask_app/README.md](../flask_app/README.md) |
+| Установка и базы в целом | [../README.md](../README.md) |