Описание технической архитектуры

Состав программы. Программа «Автоматизированная информационная система „Тренировочное тестирование для подготовки к НОК в сфере ЖКХ“» (альтернативное наименование — АИС «Тренировочное тестирование для подготовки к НОК в сфере ЖКХ»), версия 1.0.1, состоит из двух частей, которые поставляются вместе в одном дистрибутиве:

Серверная часть — веб-приложение, планировщик заданий, схема базы данных, сценарии установки и обслуживания. Устанавливается на сервер под управлением Linux.

Модуль обмена (aiszkh_export) — передаёт серверной части сведения из внешней системы АИС ОК ЖКХ. Устанавливается на сервер системы АИС ОК ЖКХ её владельцем или с его согласия и обращается к её базе данных только на чтение.

В состав программы не входят банк экзаменационных вопросов и ответов, настройки экзаменационных тестов и сведения о соискателях. Это данные лицензиата, которые он получает из системы АИС ОК ЖКХ на основании собственных прав. Не входят также операционная система, СУБД, веб-сервер и интерпретатор Python: они устанавливаются из репозиториев операционной системы.

Способы предоставления: интернет-сервис и установка на сервер лицензиата.

Для промышленной эксплуатации нужны: сервер Linux с СУБД MariaDB и веб-сервером nginx; доменное имя и сертификат TLS (работа только по HTTPS); модуль обмена на сервере системы АИС ОК ЖКХ и защищённый канал до него; почтовый сервер для уведомлений.

Демонстрационный режим: модуль обмена работает со встроенным набором вымышленных данных вместо базы системы АИС ОК ЖКХ; письма не отправляются. В этом режиме можно проверить все функции программы без доступа к системе АИС ОК ЖКХ.

1. Архитектурный стиль

Платформа — серверное веб-приложение с многоуровневой архитектурой (представление — прикладная логика — данные), работающее по модели «клиент — сервер». Пользователь работает через браузер; вся обработка выполняется на сервере. Обмен с внешней системой АИС ОК ЖКХ вынесен в отдельный модуль обмена, развёрнутый на её сервере. Взаимодействие построено на периодическом получении данных Платформой («pull») по защищённому каналу.

2. Структурные элементы

 Браузер пользователя
        │ HTTPS
        ▼
 ┌─────────────── Сервер Платформы (Linux) ────────────────┐
 │ nginx ──► gunicorn ──► веб-приложение (Flask)            │
 │                          │                               │
 │ планировщик (APScheduler)├──► MariaDB (база Платформы)  │
 │        │                 └──► файловое хранилище media/  │
 │        │ SMTP ──► почтовый сервер                        │
 │        ▼                                                 │
 │   SSH-туннель (autossh)                                  │
 └────────┼─────────────────────────────────────────────────┘
          │ SSH
 ┌────────▼──── Сервер системы АИС ОК ЖКХ (Windows) ───────┐
 │ модуль обмена (Flask + waitress, 127.0.0.1:8789)         │
 │        │ только чтение                                   │
 │        ▼                                                 │
 │ PostgreSQL (база системы АИС ОК ЖКХ)                     │
 └──────────────────────────────────────────────────────────┘

Элемент	Технология	Назначение
Веб-сервер	nginx	Приём HTTPS-запросов, выдача статических файлов, ограничение частоты запросов, заголовки безопасности
Сервер приложений	gunicorn	Запуск веб-приложения в нескольких процессах
Веб-приложение	Python 3.12, Flask, Jinja2	Интерфейс и прикладная логика: вход, личные кабинеты, тесты, отчёты, администрирование
Планировщик	APScheduler (отдельная служба)	Обмен с системой АИС ОК ЖКХ, рассылка писем, напоминания, закрытие истёкших доступов
База данных	MariaDB 10.11	Пользователи, допуски, банк вопросов, ответы и сессии тестов, журналы, настройки
Файловое хранилище	каталог `media/`	Изображения и файлы к вопросам
Модуль обмена	Python, Flask, waitress, psycopg	Выдача Платформе ограниченной проекции данных системы АИС ОК ЖКХ
Канал обмена	SSH-туннель (autossh)	Шифрование обмена; порт модуля не публикуется в сеть

3. Программные компоненты веб-приложения

Компонент	Файлы	Назначение
Фабрика приложения	`webapp/app_factory.py`	Сборка приложения, защита от CSRF, проверка согласий, обработка ошибок
Безопасность	`webapp/security.py`, `webapp/auth_routes.py`	Вход, хеширование паролей (argon2), защита от подбора, роли и области видимости
Кабинет тестируемого	`webapp/candidate.py`, `grading.py`, `questions.py`, `candidate_stats.py`, `gamification.py`	Направления, тесты, проверка ответов, статистика, мотивация
Кабинеты ЦОК и СПК	`webapp/operator.py`	Сводки, отчёты, карточки, продление доступа
Администрирование	`webapp/admin.py`	Банк вопросов, справочники, операторы, почта, документы
Отчёты и выгрузки	`webapp/reports.py`, `webapp/exports.py`	29 отчётов, выгрузка в Excel (openpyxl) и PDF (reportlab)
Почта	`webapp/mailer.py`	Очередь писем, шаблоны, повторные попытки
Срок подготовки	`webapp/lifecycle.py`	Расчёт и закрытие доступов
Обмен	`services/aiszkh_sync.py`, `aiszkh_users.py`, `aiszkh_bank_sync.py`	Приём заявлений, учётных записей и банка вопросов
Импорт	`importers/`	Загрузка банка вопросов с предпросмотром и журналом
Данные	`webapp/db.py`, `migrations/`	Доступ к БД, схема и её версии

4. Интерфейсы

Интерфейс	Протокол	Описание
Пользовательский	HTTPS, HTML	Веб-интерфейс на русском языке, адаптированный для компьютеров, планшетов и смартфонов
Модуль обмена	HTTP через SSH-туннель, JSON	`GET /api/v1/applications`, `/exams`, `/centers`, `/councils`, `/users` — постранично по времени изменения; `POST /api/v1/auth/verify` — проверка пароля; `GET /bundle/…` — выгрузка банка вопросов. Доступ по ключу `X-API-Key` / `X-Bundle-Token`
Почтовый	SMTP (STARTTLS/SSL)	Отправка уведомлений
Выгрузки	XLSX, PDF	Файлы отчётов

5. Данные и их защита

Что	Как защищено
Адреса электронной почты	Шифруются (Fernet: AES-128-CBC + HMAC-SHA256, ключ `PDN_ENCRYPTION_KEY`); поиск по адресу — по слепому индексу HMAC-SHA256 (ключ `EMAIL_HMAC_KEY`)
Хеши паролей, полученные из системы АИС ОК ЖКХ	Шифруются тем же способом
Пароли, установленные на Платформе	Хранятся только как хеш argon2
Фамилия, имя, отчество, логин, ответы и результаты	Хранятся без шифрования в базе MariaDB; к базе подключаются только учётная запись Платформы (с локального адреса сервера) и администратор сервера
Передача между браузером и сервером	HTTPS (TLS), cookie сеанса с признаками Secure, HttpOnly, SameSite
Обмен с модулем обмена	SSH-туннель; модуль слушает только локальный адрес и требует ключ доступа
Модуль обмена — база системы АИС ОК ЖКХ	Режим только чтения (`default_transaction_read_only`), отдельная учётная запись с правами SELECT
Ключи шифрования	В файле настроек `.env` (права 640, владелец — учётная запись службы); без ключа зашифрованные поля не восстановить
Резервные копии	Дамп базы и копия `.env` ежесуточно, каталог `/var/backups/test_aiszkh` с доступом только для root (права файлов 600), хранение 30 дней; копии не шифруются — их перенос во внешнее хранилище и защита определяются владельцем сервера

Действия пользователей, обмен с системой АИС ОК ЖКХ, отправка писем и события безопасности журналируются.

6. Внешние зависимости

Платформа во время работы не обращается к внешним сервисам в сети «Интернет»: шрифты, библиотеки интерфейса и изображения раздаются с собственного сервера. Внешние соединения — только с модулем обмена (через SSH-туннель) и с почтовым сервером, заданным администратором. Сторонние компоненты — программные библиотеки с открытыми лицензиями, перечень приведён в THIRD_PARTY_LICENSES.md.

7. Масштабирование и надёжность

Число процессов и потоков веб-приложения задаётся в test_aiszkh.service (по умолчанию 5 процессов × 4 потока).
Обмен идемпотентен: каждые 5 минут сверяется полный список заявлений, повторное получение данных не создаёт дублей; после сбоя связи изменения применяются при следующей успешной сверке.
Отправка писем выполняется с повторными попытками.
При недоступности модуля обмена вход работает по данным, полученным при последнем обмене. Если пароль изменён в системе АИС ОК ЖКХ после последнего обмена, вход с новым паролем возможен только после восстановления связи.

8. Хранение исходного текста, сборка и выпуск

Средство	Описание
Объектный код	Не создаётся: программа на Python и JavaScript исполняется интерпретатором и браузером без компиляции
Сборка дистрибутива	Сценарий `scripts/build_dist.sh` на рабочем месте разработчика на территории Российской Федерации: архив исходного текста и библиотек Python (`wheelhouse/`) с контрольной суммой SHA-256
Хранение дистрибутивов	Архивы версий хранит правообладатель; публичная загрузка не предусмотрена
Распространение	Интернет-сервис — установка правообладателем на сервер в Российской Федерации; установка у лицензиата — передача архива дистрибутива по лицензионному договору
Предоставление доступа пользователям	Учётные записи соискателей и работников ЦОК и СПК создаются автоматически по сведениям системы АИС ОК ЖКХ, остальные — администратором Платформы; права определяются ролью
Не применяются	Активация, лицензионные ключи, серверы лицензий, телеметрия и автоматическое обновление из сети «Интернет»