Жолдас ПДД

Индивидуальная подготовка к теоретическому экзамену ПДД РК (2026) по всем 15 категориям: личный план, учебник, 1803 вопроса с разбором и схемами ситуаций, картинки знаков, работа над ошибками и симулятор экзамена спецЦОН. Сайт на трех языках (русский, казахский, английский), учебные материалы, не официальное издание. Сайт: https://joldaspdd.kz

Из чего состоит репозиторий

Путь	Что там
content/	Банк вопросов и учебник (JSON по темам), пакеты переводов на kk и en (content/i18n), справочники знаков и категорий
src/	Код страницы: app.js (приложение), scene.js и anim.js (схемы ситуаций), стили, шаблон, словари интерфейса (src/i18n), шрифты (src/fonts, лицензия OFL), материалы SEO
build.py	Сборка страниц. Без ключей: один офлайн-файл на русском. С --api --lang all: сайт для сервера (ru, kk, en)
tools/	Сборка SEO-страниц, готовый первый экран (prerender.py), сборка и подпись релиза (build_release.js), генератор ключа (release_keygen.js, setup_release_key.sh), тесты
server/	Сервер: API (Node.js, PostgreSQL), админка, миграции, скрипты установки (server/deploy)
docs/DEPLOY.md	Как работает автообновление: push в main, проверки, подписанный релиз, сервер ставит сам

Быстрый старт

Нужны Python 3.11+, Node.js 22+, для тестов в браузере pip install playwright && python -m playwright install chromium, для серверных тестов PostgreSQL.

npm ci --prefix server                                    # зависимости сервера
python3 build.py                                          # офлайн-файл site/joldas-pdd.html (русский)
python3 build.py --verified --api --lang all --strict     # сайт для сервера в site/public (ru, kk, en)
python3 tools/prerender.py                                # готовый первый экран в HTML
node tools/build_release.js release-out                   # релиз: release-out/joldas-release.signed (нужен ключ, см. docs/DEPLOY.md)

Тесты

node tools/signs_test.js                # картинки знаков: где находятся, ложные срабатывания, три языка
python3 tools/seo_test.py               # SEO-страницы, sitemap, разметка
python3 tools/i18n_build_test.py        # полнота переводов, отсутствие кириллицы в en
python3 tools/e2e_perf.py <адрес>       # шрифты и файлы, отложенные схемы, знаки в экзамене, экзамен меняется
bash tools/api_test.sh                  # API сервера, админка, обновление с GitHub (чистая тестовая база)
bash tools/caddy_test.sh                # настройки Caddy: сжатие, кеш, типы файлов, 404 (нужен caddy и собранный релиз)

Проверки в браузере с аккаунтами и админкой (tools/e2e_accounts.py, tools/e2e_admin.py, tools/e2e_i18n.py) работают с локальным сервером и базой: bash tools/dev_server.sh --fresh (PostgreSQL по сокету /tmp, порт 55432; для админки после этого node tools/seed_dev.js из каталога server). Аккаунты проверяйте на чистой базе без тестовых данных.

Как устроена быстрая загрузка

• Главная отдается маленьким HTML (около 50 КБ) с готовым первым экраном гостя и встроенными стилями. Код, данные и схемы лежат в файлах с отпечатком в имени и кешируются на год.
• Данные (текст учебника и вопросов) грузятся после первой отрисовки и разбираются по одной теме с паузами, чтобы страница не подвисала на слабых телефонах.
• Шрифты свои (Golos Text, Unbounded), с подмножествами по алфавитам и запасным шрифтом нужной ширины, внешних запросов нет.
• Схемы ситуаций подгружаются, когда нужны (тренировка, экзамен) или в простое.
• Релиз заранее сжимается brotli и gzip, сервер отдает готовые файлы.

Замер Lighthouse (локально, через Caddy, имитация медленного 4G и слабого телефона): mobile 99, desktop 100, доступность, лучшие практики и SEO по 100. На боевом сервере значения зависят от расстояния до места теста.

Принципы

• Никаких секретов в репозитории: ключ подписи релизов хранится только в секретах GitHub и у владельца (*.key исключены в .gitignore).
• Обновление сайта ставится только если подпись релиза совпала с ключом, записанным на сервере.
• Правовые тексты (согласия, политика) и контент носят информационный характер и требуют проверки юристом и носителями языка перед публичным запуском.