instructions

1. Название и назначение

instructions — набор статических HTML-страниц с пошаговыми инструкциями по подключению VPN-клиента на Android, iPhone/iPad, Windows, macOS и Linux. Страницы рассчитаны на открытие внутри Telegram Mini App (WebApp) из бота сервиса.

2. Цель проекта

Дать конечному пользователю без технической подготовки понятную инструкцию «что нажать» для своей платформы, чтобы снизить нагрузку на поддержку. Каждая страница ведёт от установки приложения до включения VPN и содержит раздел «Не работает? Проверьте».

3. Функциональные требования

Реализовано:

• пять самостоятельных страниц, по одной на платформу (шаги, подсказки, блок FAQ);
• ссылка на бота сервиса в начале и в конце каждой страницы;
• кнопка «Готово, закрыть» через Telegram.WebApp.close(); при загрузке вызываются Telegram.WebApp.ready() и expand();
• оформление под тему Telegram (цвета берутся из CSS-переменных клиента);
• «водяные знаки» и защита от копирования: запрет контекстного меню, выделения текста и горячих клавиш F12 / Ctrl+Shift+I / Ctrl+Shift+C / Ctrl+U, авторская подпись в консоли браузера.

Замечание: защита от копирования на стороне клиента носит лишь декоративный характер и обходится тривиально.

4. Технологический стек

• HTML5 + встроенный CSS и JavaScript (без сборки, без зависимостей);
• Telegram Web Apps JS API (подключается с telegram.org).

5. Структура проекта

.
├── android.html   # Android, свой клиент OshaVPN
├── ios.html       # iPhone и iPad, клиент OneXray
├── windows.html   # Windows 10/11 и (раздел #win7) Windows 7, свой клиент OshaVPN
├── macos.html     # macOS, клиент V2Box
├── linux.html     # Linux, клиент NekoBox
├── README.md
└── CHANGELOG.md

Каждый файл самодостаточен: стили и скрипты встроены.

6. Установка и запуск

Сборки, Docker и .env не требуются.

Локальный просмотр: открыть любой *.html в браузере или поднять простой сервер:

python -m http.server 8000

Вне Telegram объект Telegram.WebApp может быть недоступен, поэтому кнопка закрытия там не работает — это ожидаемо.

Публикация: GitHub Pages этого репозитория, https://toshatoshiba.github.io/instructions/<платформа>.html. Адреса прописаны в боте polybot (config.INSTRUCTIONS_URLS), Windows 7 открывается как windows.html#win7. Пуш в main публикует страницы.

7. Переменные окружения

Не используются. Файла .env.example в проекте нет.

8. Критерии приёмки

1. Все пять страниц открываются в браузере без ошибок в консоли, кроме недоступности Telegram.WebApp вне Telegram.
2. Внутри Telegram страница раскрывается на весь экран, кнопка закрытия возвращает в чат.
3. Ссылка на бота ведёт в Telegram.
4. Вёрстка читается на экране телефона, цвета следуют теме Telegram.
5. Шаги инструкции соответствуют текущему интерфейсу клиента (проверяется вручную на устройстве).

9. Известные ограничения и TODO

• macOS (V2Box) и Linux (NekoBox) ещё на сторонних клиентах — переписать, когда появятся свои клиенты OshaVPN; дальше страницы для роутеров и серверов.
• Шаги в OneXray (iPhone) описаны без проверки на устройстве.
• Инструкции привязаны к конкретным клиентам и названиям пунктов их меню; при обновлении клиентов устаревают и требуют ручной проверки.
• В страницах в HTML-виде зашит адрес бота сервиса; при смене бота нужно править все пять файлов. Общего шаблона нет, стили и скрипты дублируются.
• Защита от копирования (запрет выделения, контекстного меню, F12) ухудшает доступность и не защищает содержимое; её стоит убрать или оставить осознанно.
• Автоматических тестов и проверки ссылок нет.
• Способ публикации и деплоя не определён по коду.
• Лицензия в репозитории не указана.

10. История версий

См. CHANGELOG.md.