Expand project documentation for users and agents

2026-05-19 17:56:07 +00:00 · 2026-04-26 12:53:21 +03:00
parent f483028c53
commit 4332990fd5
3 changed files with 200 additions and 50 deletions
--- a/DOCS_AI.md
+++ b/DOCS_AI.md
@@ -2,13 +2,30 @@

 **Версия:** 2.5.0
 **Репозиторий:** `anten-ka/gotelegram_pro`
-**Активная ветка:** `main` — основной код и продакшен.
+**Активная ветка:** `main` — основной код и продакшен. `beta` и `alpha` существуют для следующих сборок.
 **Целевая ОС:** Ubuntu 20.04+, Debian 11+

 Этот документ описывает устройство проекта с максимальным количеством нюансов — все ловушки, на которые мы уже наступали, все причины «почему именно так», формат всех внешних интерфейсов, и checklist действий для типовых задач. Цель: чтобы новый агент мог продолжить работу без повторения ошибок и без регрессий.

 ---

+## 0. Быстрый старт для нового ИИ
+
+Если ты агент, который впервые открыл репозиторий:
+
+1. Не трогай токены, ключи VPS и BotFather-токены в истории диалога; не печатай их в ответах и не клади в файлы.
+2. Основной код устанавливается из `main`; `bootstrap.sh` по умолчанию скачивает `main`, если не задан `GOTELEGRAM_BRANCH`.
+3. Рабочая модель веток: `alpha` для ранних экспериментов, `beta` для проверочных сборок, `main` для продакшена.
+4. Главный код установки — `install.sh` + `lib/*.sh`. Не исправляй Telegram-бот или web-admin в отрыве от bash-слоя: все три интерфейса должны показывать одно и то же состояние.
+5. Главный конфиг пользователя — `/opt/gotelegram/config.json`; главный runtime-конфиг ядра — `/etc/telemt/config.toml`.
+6. `telemt` использует TOML v3, не совместимый со старым `mtg`. Не возвращай старые секции `[security]`, `[[users]]`, `bind_to`.
+7. Любая bash-функция, которую вызывают через `$()`, обязана писать UI и логи в stderr (`>&2`), а в stdout возвращать только значение.
+8. Перед пушем запускай проверки из раздела 20. Для документации минимум: bash syntax, unit tests, py_compile, node check, `git diff --check`.
+9. Если меняешь поведение, обновляй `DOCS_HUMAN.md`, `DOCS_AI.md`, changelog и при необходимости `GOTELEGRAM_VERSION`.
+10. Если меняешь бэкапы, сохраняй обратную совместимость restore для старых архивов.
+
+---
+
 ## 1. Общая картина

 goTelegram Pro — это менеджер MTProxy для Telegram, собранный вокруг Rust-ядра **telemt** (порт mtproto-proxy с поддержкой fake-TLS, v3.3.x). Проект даёт три вещи:
@@ -43,15 +60,17 @@ tls_domain = google.com (или любой из QUICK_DOMAINS)

 ```
 anten-ka/gotelegram_pro
-└── main          ← основной код и продакшен
+├── main          ← продакшен и дефолтная установка
+├── beta          ← следующая публичная сборка для проверки пользователями
+└── alpha         ← ранние личные сборки владельца
 ```

-**Правило коммитов:** изменения идут в `main` только после локальных проверок. Перед любым рискованным переносом или force-update создавай rollback tag/release для текущего состояния `main`.
+**Правило коммитов:** новые рискованные изменения сначала идут в `alpha`, затем после ручной проверки в `beta`. В `main` попадает только код, который можно считать установочным по умолчанию. Перед любым рискованным переносом или force-update создавай rollback tag/release для текущего состояния целевой ветки.

 **Инструменты для коммитов:**
 - Основной путь — обычный `git commit` + `git push` в нужную ветку после локальной проверки.
 - Если окружение не может пушить напрямую, используй GitHub REST API с PAT из переменной окружения `GOTELEGRAM_PAT`.
- Workflow через GitHub API: `POST git/blobs` для каждого файла → `POST git/trees` (с `base_tree` от текущего HEAD) → `POST git/commits` (parents=[текущий HEAD]) → `PATCH git/refs/heads/main` (sha=новый commit) → при необходимости `POST /releases`.
+- Workflow через GitHub API: `POST git/blobs` для каждого файла → `POST git/trees` (с `base_tree` от текущего HEAD) → `POST git/commits` (parents=[текущий HEAD]) → `PATCH git/refs/heads/<main|beta|alpha>` (sha=новый commit) → при необходимости `POST /releases`.
 - **Важно про `base_tree`:** при частичном обновлении (1-2 файла) ОБЯЗАТЕЛЬНО передавать `base_tree` — иначе дерево получится только из переданных файлов, и все остальные файлы пропадут из коммита. `base_tree` можно опускать только при коммите с полным набором файлов.

 ---
@@ -59,12 +78,13 @@ anten-ka/gotelegram_pro
 ## 3. Карта файлов

 ```
-install.sh                     главная точка входа, CLI-меню из 14 пунктов
+install.sh                     главная точка входа, CLI-меню из 5 разделов
 install_gotelegram_bot.sh      legacy-установщик бота (функционал продублирован в install.sh)
 bootstrap.sh                   установщик приватного репо через raw.githubusercontent.com с PAT
 templates_catalog.json         каталог 1801 шаблонов, 18 категорий, 4 источника (~460KB)
 DOCS_HUMAN.md                  документация для пользователя (этот каталог)
 DOCS_AI.md                     этот файл
+README.md                      короткая входная точка проекта

 lib/common.sh                  цвета, log_*, confirm, select_option, _valid_ip, config_get,
                               save_gotelegram_config, get_server_ip, run_with_spinner,
@@ -88,7 +108,12 @@ gotelegram-bot/bot.py          Telegram-бот (python-telegram-bot v21+)
 gotelegram-bot/config.example.env
 gotelegram-bot/requirements.txt
 gotelegram-bot/README.md
-gotelegram-bot/locales/*.json  99 ключей i18n для бота с per-user persistence
+gotelegram-bot/lang/*.json     i18n для бота с per-user persistence
+
+admin-web/server.py            backend локальной админки на Python stdlib
+admin-web/static/index.html    shell интерфейса админки
+admin-web/static/app.js        frontend логика, API calls, графики, таблицы
+admin-web/static/styles.css    responsive light/dark UI
 ```

 **Где что лежит на VPS после установки:**
@@ -362,12 +387,12 @@ Fallback: если по известным правилам index.html не на
 Ключевые моменты:
 - **Admin ID** — бот отвечает только пользователю с `ADMIN_TG_ID` из `.env`. Всё остальное игнорируется.
 - **safe_edit_message** — обёртка над `query.edit_message_text` + `query.edit_message_caption`, глотает `BadRequest: message is not modified`. Начиная с v2.4.2 принимает опциональный `disable_web_page_preview` — не забудь прокинуть его если показываешь ссылку-превью (раньше вызов с этим kwarg ловил TypeError в runtime). Используй её всегда вместо прямого вызова.
- **Language per-user** — файл `locales/users.json` хранит `{user_id: "ru"/"en"}`. При каждом сообщении бот читает язык пользователя и подставляет строку через `t(key, lang)`.
+- **Language per-user** — файл `/opt/gotelegram-bot/user_langs.json` хранит `{user_id: "ru"/"en"}`. При каждом сообщении бот читает язык пользователя и подставляет строку через `t(user_id, key)` / `tf(user_id, key, ...)`.
 - **QR-коды** — генерятся в `/tmp/gotelegram_qr_*.png`, отправляются как `InputFile`, удаляются в `finally`.
 - **Шаблон preview в HTML** — URL экранируется через `html.escape(url, quote=True)` (баг #11).
 - **Системные действия (v2.4.2+)** — бот реально умеет менять шаблон и домен маскировки. Хелпер `run_bot_action(action, **kwargs)` вызывает `subprocess.run(["/opt/gotelegram/install.sh", "--action=X", "--json", ...])` и парсит JSON. Два коллбэка: `cb_pro_confirm` (change-template) и `cb_lite_domain` (change-lite-domain). Оба обёрнуты в `async with _BOT_ACTION_LOCK` (глобальный `asyncio.Lock()`) — сериализуют параллельные callback'и внутри процесса бота. Входы валидируются ДО subprocess: `_TPL_ID_RE = r"^[A-Za-z0-9_-]{1,64}$"`, `_DOMAIN_RE` (RFC-like). Малформный ввод отвергается с понятным сообщением, не доходя до shell.
 - **Поле `template_id` в config.json** — канонический ключ для текущего шаблона. Раньше (до v2.4.2) бот читал `config['template']` и писал в него же в `handle_text_message`, но `save_gotelegram_config` всегда писал `template_id` → поле статуса никогда не отображалось. Используй только `template_id`.
- **Устанавливается** из меню `install.sh → 12) Telegram-бот → Установить`. Пользователь вводит BotFather token + свой Telegram ID, `.env` пишется в `/opt/gotelegram-bot/.env`.
+- **Устанавливается** из меню `install.sh → 4) Telegram-бот → Установить`. Пользователь вводит BotFather token + свой Telegram ID, `.env` пишется в `/opt/gotelegram-bot/.env`.
 - **Обновляется автоматически (v2.5.0+)** при повторном bootstrap/update: `auto_update_bot_if_possible` сравнивает новые файлы в `$SCRIPT_DIR/gotelegram-bot/` с установленными `/opt/gotelegram-bot/{bot.py,i18n.py,requirements.txt,lang/*.json}`. Если есть отличия и сервис уже установлен, вызывается `bot_install >/dev/null`, `.env` сохраняется, зависимости обновляются, systemd unit переписывается и `gotelegram-bot` перезапускается. Это закрывает сценарий 2.4.x → 2.5.0, где bootstrap обновлял `/opt/gotelegram/gotelegram-bot/`, но рабочий сервис продолжал запускать старый `/opt/gotelegram-bot/bot.py`.

 ### 11.1 Non-interactive action bridge (install.sh ↔ bot)
@@ -502,7 +527,7 @@ Traffic retention: обе CSV-истории хранятся максимум 3
   import os, base64, json, urllib.request, ssl
   TOKEN = os.environ["GOTELEGRAM_PAT"]
   REPO = "anten-ka/gotelegram_pro"
-   BRANCH = "main"
+   BRANCH = "main"  # или beta/alpha для соответствующей ветки
   API = f"https://api.github.com/repos/{REPO}"
   headers = {
       "Authorization": f"Bearer {TOKEN}",
@@ -621,7 +646,15 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:
 ## 16. Меню (install.sh)

 ```
-── Прокси ──
+Главный экран:
+ 1) submenu_proxy        (установка, статус, ссылка, share, restart, logs, change mode)
+ 2) submenu_stats        (show_traffic_stats, toggle_stats, install_stats_collector)
+ 3) submenu_manage       (backup, restore, update_telemt, website/SSL, remove, language)
+ 4) menu_bot             (install/start/stop/logs/change token/remove bot, installs admin web)
+ 5) submenu_about        (version info, promo)
+ 0) exit
+
+Раздел Proxy:
 1) menu_install         (Lite/Pro выбор, domain, template, certbot)
 2) menu_status          (telemt_status + show_proxy_info)
 3) menu_link            (ссылка + QR)
@@ -630,18 +663,13 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:
 6) menu_logs            (telemt_logs 40)
 7) menu_change_mode     (lite↔pro, смена шаблона, смена домена маскировки)

-── Управление ──
- 8) interactive_backup   (create_backup)
- 9) interactive_restore  (select_backup + restore_backup)
-10) update_telemt        (check_telemt_update → download → restart)
-11) menu_website         (nginx restart, certbot renew)
-
-── Бот и прочее ──
-12) menu_bot             (install_bot / start / stop / logs / change_token / remove)
-13) menu_remove          (только прокси / только бот / всё)
-14) menu_promo           (подарочные ссылки — маркетинг)
-
- 0) exit
+Раздел Management:
+ 1) interactive_backup   (create_backup)
+ 2) interactive_restore  (select_backup + restore_backup)
+ 3) update_telemt        (check_telemt_update → download → restart)
+ 4) menu_website         (nginx restart, certbot renew)
+ 5) menu_remove          (только прокси / только бот / всё)
+ 6) menu_language        (switch_language ru|en)
 ```

 Диспатчер в `install.sh` (`bot_action_dispatch`) принимает `--action=` для автоматизации из бота. Полный контракт описан в разделе 11.1.
@@ -705,7 +733,7 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:

 ## 20. Контрольные точки и инварианты

-Перед любым пушем в `main`:
+Перед любым пушем в `main`/`beta`/`alpha`:
 1. `bash -n install.sh lib/*.sh` — синтаксис bash ОК.
 2. Все новые `$()`-вызываемые функции пишут UI через `>&2`.
 3. Все пути к lib/ идут через `$SCRIPT_DIR/lib/...`, а `SCRIPT_DIR` — через `readlink -f`.
@@ -716,7 +744,7 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:

 После пуша:
 1. Подождать пока нужная ветка обновится (GitHub API мгновенно, raw кеш ~30 сек).
-2. На VPS: повторить bootstrap из ветки `main` с `GOTELEGRAM_PAT`; скрипт сам скачает файлы, обновит установленный бот/админку и покажет меню.
+2. На VPS: повторить bootstrap из целевой ветки с `GOTELEGRAM_PAT` и при необходимости `GOTELEGRAM_BRANCH=beta|alpha|main`; скрипт сам скачает файлы, обновит установленный бот/админку и покажет меню.
 3. `telemt_status` → running. `journalctl -u telemt` → нет ошибок. Ссылка открывается в Telegram-клиенте.

 ---