⚓ Тренажёр ISSA Inshore Skipper + SRC (Telegram-бот + Mini App)

Телеграм-бот и набор Telegram Mini Apps для подготовки к теоретическим экзаменам по яхтингу на русском. Три лицензии: ISSA Inshore Skipper + SRC (605 вопросов, RU) и польские Żeglarz jachtowy (150) + Sternik motorowodny (460) в гибридном формате PL/RU. Плюс конспекты (ISSA + PL с разбором каждого ответа), шпаргалки, словарь, библиотека учебников (PDF), тренажёры задач, карта ветра (Windy-стиль) и интерактивные тренажёры огней судов и буёв IALA. Вопросы не повторяются, пока не пройдёшь весь круг.

Большинство функций доступно как удобные Mini App прямо в Telegram (тесты, калькулятор, конспект, словарь, шпаргалки, библиотека) — открываются с одного стартового экрана. Интерфейс оформлен в едином стиле: все значки — инлайн-SVG (Lucide) под тему Telegram, без эмодзи и сторонних CDN.

Mini App ведёт обучение как продукт, а не как набор тестов: интервальное повторение (SRS), карточка «Готовность к экзамену %», дневная цель и серия, достижения (бейджи), профиль и история попыток. Прогресс синхронизируется между устройствами через лёгкий backend-API (по желанию; без него всё работает локально).

⚠️ Важно. Бот и база вопросов — оригинальные, созданы для тренировки. Они не содержат экзаменационных ключей и не являются официальным материалом ISSA или какой-либо школы. Это вспомогательный учебный материал для самостоятельной подготовки. Вопросы составлены по открытым первоисточникам (COLREG/МППСС-72, IALA MBS, GMDSS/SRC, стандартная навигация).

Лицензия и использование ИИ

© 2026 ipostatos. All rights reserved. Личное некоммерческое использование тренажёра разрешено; продажа, распространение банков вопросов/конспектов и создание производных продуктов — только с письменного разрешения. Подробнее — LICENSE.

AI / scraping / training prohibited. Использование любых материалов этого репозитория (кода и учебного контента) для обучения, дообучения, оценки или наполнения датасетов систем машинного обучения и ИИ, а также массовый автоматический сбор — запрещены без письменного разрешения. Права на text/data mining явно зарезервированы (в т.ч. как машиночитаемый opt-out — см. AI-POLICY.md и robots.txt). Запросы: @ipostatos (Telegram).

Доступность файлов не отменяет условия лицензии и авторские права.

Содержание

• Как это устроено
• Что умеет
• Mini Apps и навигация
• Банк вопросов
• Установка и запуск
• Команды бота
• Как добавить свои вопросы
• Хранение прогресса
• Развёртывание на сервере
• Тесты и качество
• Лицензия и приватность

Как это устроено

Три слоя, каждый работает самостоятельно:

┌─────────────────────────────────────────────────────────────┐
│  Telegram-бот (Python/aiogram, long-polling)                 │
│  • точка входа: /start, кнопка-меню, нативные quiz-поллы      │
│  • ЛАУНЧЕР: крупная кнопка «Открыть приложение» + быстрый     │
│    доступ в чате (случайный вопрос, экзамен, статистика)      │
└───────────────┬─────────────────────────────────────────────┘
                │ открывает
┌───────────────▼─────────────────────────────────────────────┐
│  Telegram Mini Apps (статика HTML/JS, тема Telegram)         │
│  • ОСНОВНОЙ интерфейс: тесты, конспект, калькуляторы,         │
│    словарь, шпаргалки, библиотека, профиль, история           │
│  • SRS, готовность %, дневная цель, серия, бейджи             │
│  • единый стиль: инлайн-SVG (Lucide), без CDN                 │
└───────────────┬─────────────────────────────────────────────┘
                │ синхронизация прогресса (опц.)
┌───────────────▼─────────────────────────────────────────────┐
│  Backend-API (FastAPI + SQLite, systemd, за Caddy)           │
│  • HMAC-проверка Telegram initData, слияние без перезатирания │
│  • синхрон между устройствами + история попыток              │
└─────────────────────────────────────────────────────────────┘

Бот — лаунчер, Mini App — основной продукт, API — необязательная синхронизация. Источник правды для данных — Python-модули, из них генерируются *_data.js для Mini App (CI следит, чтобы они не отставали).

Что умеет

В чате (бот — лаунчер + быстрый доступ)

Главное меню (/start) — крупная кнопка «Открыть приложение» и компактный быстрый доступ к самому ходовому, что удобно «на бегу» без открытия приложения:

Режим в чате	Описание
🎯 Случайный вопрос	Подряд новые вопросы из всего банка, без повторов. Нативные Telegram-quiz: нажимаешь вариант — бот сразу подсвечивает верный/неверный и даёт пояснение
📝 Экзамен	100 вопросов, проходной балл 90%, в конце — результат и разбор ошибок (длинный разбор автоматически режется под лимит Telegram)
🔁 Работа над ошибками	Повтор только тех вопросов, где вы ошибались (исправились → вопрос уходит из списка)
📊 Статистика	Сколько отвечено, % правильных, пройдено из банка

У каждого вопроса под ответом — пояснение и разбор каждого варианта (почему верный верен, почему остальные нет) со ссылкой на источник. Полный набор тем, тренажёры и весь учебный контент — в приложении (кнопка «Открыть приложение»).

В приложении (Mini App — основной интерфейс)

Раздел	Описание
🎓 Тесты ISSA	Тренировка (случайные / по темам) и экзамен (100 вопросов, таймер, проходной балл, разбор). Варианты перемешиваются при каждом показе. После ответа в тренировке — 💡 «Где изучить» (ссылка в конспект/библиотеку). После теста — фидбек по темам. Режим 🔁 «Повторить сегодня» (SRS), сертификат самопроверки, восстановление незавершённого теста. quiz.html
🇵🇱 Польские лицензии	Żeglarz jachtowy (150) и Sternik motorowodny (460) — экзамен 75/65/90 мин + тренировка. Вопросы в гибридном формате PL/RU «как на листе» (без перевода). В тренировке у каждого вопроса лампочка-разбор → конспект PL. exam_pl.html
📖 Конспект	Теория ISSA по 16 темам строго по учебнику. Конспект PL — 7 тем PL/RU, покрывает 100% польских банков (610 вопросов), каждый факт помечен id обосновываемого вопроса. Быстрый поиск, зум схем. konspekt.html, konspekt_pl.html
📊 Дашборд	Стартовый экран: готовность к экзамену % (свайп-карусель ISSA / Żeglarz / Sternik), дневная цель, серия, тепловая карта активности. home.html
🏅 Профиль / История	Достижения-бейджи (морская тематика), статистика; таблица прошлых попыток. profile.html, history.html
🌦 Погода (BETA)	Ветер / волна / температура по точке (Open-Meteo), почасовой прогноз, «Мои точки». Карта ветра в стиле Windy: карта берегов (Leaflet + CARTO) + слои — стрелки, анимированные частицы, тепловые заливки волн и осадков, таймлайн по часам. weather.html
🚢 Бонус · интерактив	Огни судов — распознавание типа/ракурса по навигационным огням (COLREG), переключатель день/ночь (ночью огни, днём чёрные знаки), справочник + тест. Буи IALA — знаки Region A с анимированным ритмом проблесков, «с какой стороны обходить». lights.html, buoys.html
🧮 Калькуляторы	TVMDC (поправки компаса), S·D·T·ETA; задачки на приливы; 50 задач T-V-M-D-C; интерактивный компас. index.html/calc.html, tasks.html, navtasks.html
📌 Шпаргалки	T-V-M-D-C, МППСС, огни, звуки, буи IALA, Бофорт, узлы (пошаговые фото), швартовки, повороты, VHF/Mayday. cheatsheet.html
📚 Словарь	180+ морских терминов простыми словами в 10 категориях, поиск по русскому/английскому/польскому. glossary.html
📚 Библиотека	Учебники целиком (PDF) — учебник ISSA, рабочая тетрадь, пособие Тогхилла — во встроенном просмотрщике (PDF.js), не выходя в браузер. book.html + reader.html

Прогресс приложения (SRS, готовность, серия, история) синхронизируется между устройствами через backend-API; без него всё работает локально (localStorage).

Mini Apps и навигация

Все Mini App открываются с общего стартового экрана (home.html), используют тему Telegram (тёмная/светлая) и единый набор иконок (инлайн-SVG Lucide). Системная кнопка «‹ Назад» возвращает на предыдущий экран или на главную, а не закрывает приложение (nav.js). Зум схем — общий лайтбокс (lightbox.js).

Страницы (webapp/): home.html (публикуется как index.html), quiz.html, exam_pl.html (польские лицензии), index.html→calc.html, konspekt.html, konspekt_pl.html, tasks.html, navtasks.html, cheatsheet.html, glossary.html, book.html+reader.html, weather.html, lights.html, buoys.html, profile.html, history.html, about.html.

Общие модули: theme.css (дизайн-система), icons.js (SVG Lucide), nav.js (навигация/BackButton), lightbox.js (зум), srs.js (интервальное повторение), progress.js (готовность/цель/серия), pl_progress.js (прогресс польских лицензий), badges.js (достижения), sync.js (синхрон через API), heatmap.js. Локально в vendor/: PDF.js (просмотрщик), Leaflet (карта ветра).

Данные для Mini App собираются из Python-модулей (единый источник правды) скриптами webapp/build_*_data.py в *_data.js. CI проверяет, что эти файлы не отстали от исходников, и кросс-сверяет JS-математику с Python.

Банк вопросов

605 уникальных вопросов по 15 темам:

Тема	Кол-во
Навигация	89
COLREG (МППСС)	69
VHF / SRC	61
Огни и знаки	47
Безопасность	43
IALA (буи и знаки)	40
Метео	39
Терминология	36
Паруса	36
Якорение	32
Маневры	30
Принятие яхты	22
Планирование	22
Звуковые сигналы	21
Практика	18

Все вопросы хранятся в questions.json (UTF-8). Дубликаты (точные и смысловые) удалены, у каждого вопроса 4 варианта и пояснение. Дистракторы переработаны, чтобы не выдавать правильный ответ длиной/подробностью; в Mini App порядок вариантов дополнительно перемешивается при показе. Каждый вопрос прошёл адверсариальную верификацию (отдельные агенты проверяли корректность ответа и пояснения). Качество проверяется автотестом run_audit.py (11-пунктовый пред-релизный чек-лист).

Локальный запуск (для разработки)

Требуется Python 3.10+ (проверено на 3.12). aiogram уже умеет работать на Windows.

Этот раздел — только про свою машину: свой каталог, своё виртуальное окружение, свой тестовый бот от @BotFather. Для боевого сервера порядок другой (всё от пользователя issa) — см. «Развёртывание на сервере».

# 1. Перейти в папку бота
cd "c:\Users\user\Desktop\ISSA\bot"

# 2. (рекомендуется) создать виртуальное окружение
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 3. Установить зависимости
pip install -r requirements.txt

# 4. Получить токен бота:
#    - открыть в Telegram @BotFather
#    - /newbot -> задать имя и username
#    - скопировать выданный токен

# 5. Создать файл .env (скопировать из .env.example) и вписать токен:
#    BOT_TOKEN=123456789:AA...ваш_токен

# 6. Запустить
python bot.py

После запуска откройте своего бота в Telegram и отправьте /start.

⚠️ Чтобы бот мог фиксировать ответы на quiz, опросы отправляются не анонимно (is_anonymous=False) — это требование Telegram для получения ответов. В личной переписке имя видит только сам бот.

Команды бота

• /start — главное меню
• /menu — меню режимов
• /stats — статистика
• /help — справка

Как добавить свои вопросы

Вариант A — через CSV (с автопроверкой дубликатов)

Подготовьте CSV с заголовком:

topic,question,A,B,C,D,answer,explanation
VHF / SRC,Какой канал для DSC?,70,16,13,72,A,DSC использует канал 70.

answer — буква A/B/C/D (или индекс). Затем:

python import_csv.py путь\к\новым_вопросам.csv

Вопросы с уже существующим текстом пропускаются — повторов не будет.

Вариант B — вручную в questions.json

Добавьте объект в массив:

{
  "id": "vhf-019",
  "topic": "VHF / SRC",
  "q": "Текст вопроса?",
  "options": ["Вариант 1", "Вариант 2", "Вариант 3", "Вариант 4"],
  "answer": 0,
  "expl": "Пояснение к правильному ответу."
}

answer — индекс правильного варианта (0 = первый).

Вариант C — объединить несколько баз с дедупликацией (merge_dedup.py)

Если у вас несколько CSV-баз (из разных школ) и их нужно слить в одну без повторов — положите все .csv в папку sources/ и запустите:

python merge_dedup.py            # объединить + записать questions.json + отчёт
python merge_dedup.py --dry-run  # только анализ и отчёт, без записи
python merge_dedup.py --collapse-semantic  # ещё и свернуть смысловые дубли

Инструмент делает три уровня проверки дубликатов:

1. Точные дубли — одинаковый текст вопроса (после нормализации регистра, пунктуации, пробелов). Удаляются автоматически; study_material/пояснение подтягиваются из лучшего варианта.
2. Близкие по тексту — почти одинаковая формулировка (схожесть ≥ 0.88, алгоритм SequenceMatcher). Помечаются в отчёте.
3. Смысловые дубли — один и тот же факт, разная формулировка. Группируются по «подписи факта» (номер правила МППСС, комбинация огней, паттерн гудков, кардинальный знак, определяемый термин, числа в навигационной задаче). Например, «Что требует Rule 5?» и «Что капитан обязан вести всегда — зрением и слухом?» получают одну подпись colreg:rule5-lookout, хотя текст разный.

Также отчёт отдельно показывает конфликты — когда один и тот же вопрос в разных базах имеет разный правильный ответ (требует ручной проверки).

Полный отчёт пишется в dedup_report.txt. По умолчанию смысловые дубли только помечаются (решение за вами); с флагом --collapse-semantic из каждой группы остаётся один лучший вопрос (с пояснением/study_material).

Хранение прогресса

Прогресс каждого пользователя — в progress/<user_id>.json:

• seen — какие вопросы уже показаны (логика «без повторов»);
• wrong — вопросы для «работы над ошибками»;
• stats — общая статистика.

Сбросить можно кнопкой «♻️ Сбросить прогресс» в меню (или см. /privacy).

При перезапуске бота сохранённый прогресс не теряется. Сбрасываются только сессии, активные в момент перезапуска: незавершённый экзамен, текущая задача и режим поиска по словарю (всё это пока хранится в памяти).

Бот работает только в личном чате: прогресс и quiz привязаны к одному пользователю. В группах бот вежливо отправляет в личку.

Развёртывание на сервере

Бот работает на long-polling — внешний адрес/домен не нужен. Подробная пошаговая инструкция для Linux-VPS (Ubuntu) с автозапуском через systemd: см. deploy/DEPLOY.md.

Главное правило боевой установки: venv, pip, git и генерация данных выполняются от пользователя issa, а не от root. Root нужен ровно для двух вещей — systemctl и копирование в системные каталоги раздачи. Иначе в окружении остаются файлы root:root: деплой от непривилегированной учётной записи ломается по правам, а компрометация кода в репозитории даёт root в обход systemd-песочницы.

⚠️ Здесь намеренно нет краткого сниппета установки на сервер. Раньше он тут был, создавал .venv от root и воспроизводил ровно эту проблему; в основном руководстве порядок уже исправили, а сокращённая копия осталась старой. Дублировать пошаговую инструкцию — значит разъехаться снова, поэтому поддерживается один источник правды:

• бот — deploy/DEPLOY.md;
• Sync API — deploy/DEPLOY_API.md.

Обновление кода бота: git pull → systemctl restart issa-bot (или bash deploy/update.sh).

Mini App публикуются отдельным скриптом — он делает git pull, регенерирует данные (*_data.js) и копирует страницы туда, откуда их раздаёт веб-сервер (Caddy/nginx):

sudo bash deploy/update_webapp.sh

PDF-книги для Библиотеки в git не хранятся (вес + авторские права): их кладут на сервер в webapp/books/ латинскими именами (book.pdf, studbook.pdf, toghill.pdf) — деплой-скрипт их публикует. Папку progress/ стоит включить в резервное копирование.

PDF-просмотрщик (reader.html) использует локальный PDF.js (webapp/vendor/pdfjs/, Apache-2.0) — без CDN: работает офлайн и под строгим Content-Security-Policy. Деплой-скрипт копирует его автоматически.

Синхронизация прогресса (опционально)

Прогресс Mini App (SRS, серия, готовность, история попыток) хранится локально и дополнительно синхронизируется между устройствами через лёгкий API (api/ — FastAPI + SQLite, отдельный systemd-сервис за reverse-proxy Caddy). Аутентификация — проверка Telegram initData по HMAC-SHA256; слияние прогресса идёт без перезатирания (SRS — по максимальному боксу, серия/рекорд — по максимуму, дни — объединением). Без API всё работает автономно на localStorage. Установка — см. deploy/DEPLOY_API.md.

Тесты и качество

• python run_audit.py — пред-релизный чек-лист (валидность банка, картинки, лимиты Telegram, дубли, .env в .gitignore и т.д.).
• python test_nav.py — тесты решателя T-V-M-D-C (вкл. границу 0°/360°).
• python test_calc.py — тесты калькулятора TVMDC (calc.solve) и парсера ввода.
• python test_marine.py — S-D-T, ETA, практические задачи (marine.py).
• python test_webapp.py — разбор результата из Mini App «Тесты».
• python test_tides.py — правило двенадцатых и калькулятор приливов.
• node webapp/_solver_check.mjs — кросс-проверка JS-математики TVMDC.
• node webapp/_marine_check.mjs — кросс-проверка JS-математики S-D-T/ETA.
• node webapp/_quiz_check.mjs — валидность данных тестов, размер payload и passPercent.
• node webapp/_konspekt_check.mjs / _tasks_check.mjs / _glossary_check.mjs / _content_check.mjs / _tide_check.mjs — сверка данных Mini App с исходниками.
• node webapp/_srs_check.mjs / _progress_check.mjs / _badges_check.mjs — логика интервального повторения, готовности/цели/серии и достижений.
• node webapp/_sync_check.mjs — JS-слияние прогресса совпадает с серверным (без потерь).
• node webapp/_sw_check.mjs — PWA/офлайн: стратегии service worker (эмуляция офлайна), манифест и полнота деплой-списка (каждый файл webapp/ упомянут в update_webapp.sh).
• python test_load.py — нагрузка 10 одновременных пользователей.

CI (GitHub Actions, .github/workflows/ci.yml) гоняет всё это на каждый push, плюс secret-scan на случай утечки токена.

Лицензия и приватность

• Условия использования — LICENSE: © 2026 ipostatos, all rights reserved. Разрешены личное некоммерческое использование тренажёра и изучение кода в ознакомительных целях; продажа, распространение банков вопросов и конспектов, создание производных продуктов — только с письменного разрешения. Условия те же, что в разделе «Лицензия и использование ИИ» выше: лицензионная модель в этом репозитории одна.
• Использование материалов для обучения ИИ и массового сбора — запрещено, см. AI-POLICY.md.
• Какие данные хранит бот — PRIVACY.md (команда /privacy).
• Нашли уязвимость — SECURITY.md (не через публичные Issues).

О результатах поиска готовых решений

Перед разработкой проверены открытые источники:

• Готового специализированного бота для ISSA Inshore Skipper / SRC на русском языке в открытом доступе не нашлось — на GitHub есть только универсальные quiz-боты без морской базы вопросов.
• Скачиваемых банков вопросов школы не публикуют: онлайн-тесты (например, 12knots.ru с тестами Skipper Sail/Power, VHF и COLREG/МППСС) доступны только в процессе прохождения, без API/экспорта.
• Поэтому база собрана и переработана из открытой программы курса и общепринятых морских правил (COLREG/МППСС-72, IALA MBS, процедуры VHF/GMDSS) — полный разбор с цифрами по каждой группе источников в docs/SOURCES.md.

Бот и база вопросов оригинальны, не содержат экзаменационных ключей и не являются официальным материалом ISSA или какой-либо школы.