config: включение Telegram разведено с ключом доступа

- в секции [telegram] заведён обязательный ключ enabled: умолчания у него нет, файл без него негоден; bot_token стал только ключом доступа и при enabled = false не читается вовсе, а пустой при enabled = true роняет старт - выключенный вход даёт подъём одним входом без единого обращения к Telegram и записью INFO вместо прежнего WARN: это выбор владельца, а не отклонение - отказ разбора файла настроек больше не пересказывает toml — её ParseError несёт в тексте разбираемое значение, и оборванная строка секретного ключа уносила его в журнал; теперь называются путь, строка, столбец и последний ключ
2026-08-13 21:46:14 +03:00
parent 903941f587
commit cd57b68215
27 changed files with 1536 additions and 123 deletions
@@ -0,0 +1,113 @@
+## REMOVED Requirements
+
+### Requirement: Недоступный или незаданный вход Telegram не мешает подъёму
+
+**Reason**: Требование выводило намерение владельца из ключа доступа: пустой ключ
+означал разом и «вход выключен», и «ключа нет». Разведение этих двух значений
+меняет и премиссу требования — включённый вход без ключа теперь подъёму мешает,
+и прежнее имя стало неверным.
+
+**Migration**: Заменено требованием «Признак включения решает, поднимается ли
+вход Telegram». Прежние правила для включённого входа перенесены в него дословно;
+добавлены случай выключенного входа и случай включённого входа без ключа.
+
+## ADDED Requirements
+
+### Requirement: Признак включения решает, поднимается ли вход Telegram
+
+Намерение владельца SHALL объявляться отдельным признаком включения входа
+Telegram, а ключ доступа MUST означать только доступ. При выключенном входе
+сервис MUST подниматься без Telegram и MUST не смотреть на ключ доступа вовсе.
+При включённом входе пустой ключ MUST быть отказом старта: сообщение называет имя
+незаполненного ключа и MUST не нести его значения.
+
+Признак включения MUST быть в настройках задан. Умолчания у него нет: файл, где
+признака нет вовсе, негоден, и сервис MUST выходить с ошибкой настройки, назвав
+недостающий ключ. Умолчание здесь было бы угаданным намерением, а признак заведён
+затем, чтобы намерение объявляли: любое умолчание делает одну из двух ошибок
+тихой — либо бот молча пропадает, либо файл без признака молча работает.
+
+Выключенный вход MUST быть назван в журнале **ровно одной** записью уровня `INFO`
+при старте. Это выбор владельца, а не отклонение, и предупреждать о нём не о чем;
+предупреждение остаётся за тем, чего владелец не выбирал.
+
+При включённом входе сервис SHALL подниматься, когда вход поднять не удалось, и
+MUST продолжать работу оставшимся входом: приём по HTTP, опрос готовности и
+конвейер расшифровки работают в полном объёме. Неподнятый вход MUST быть назван в
+журнале **ровно одной** записью уровня `WARN` при старте — с причиной и без
+значения ключа.
+
+Исключение одно, и оно проходит по тому, **ответил ли Telegram**. Ответ «такого
+бота нет» — ошибка настройки: бот по этому ключу не появится ни от ожидания, ни
+от повтора, и старт MUST кончаться отказом. Сервис, молча потерявший бота после
+опечатки в ключе, перестаёт отвечать своим отправителям, и узнать об этом было бы
+неоткуда.
+
+Всё прочее — недоступность: сеть, DNS, авария Bot API, истёкший срок ожидания.
+Она MUST не влиять на подъём. Основной вход сервиса — не Telegram, и ронять его
+целиком из-за чужой аварии нельзя: перезапуск в такую минуту оставил бы без
+работы и приём по HTTP, и панель, и конвейер, которому Telegram не нужен вовсе.
+
+Ожидание при сборке MUST быть ограничено сроком. Без него недоступность
+неотличима от подъёма: обращение к Telegram стоит на пути старта, и молчащий
+собеседник останавливал бы его бессрочно — без записи, без порта и без пробы
+здоровья.
+
+Требование нормирует **наличие входа**, а не приём из него.
+
+#### Scenario: Вход выключен
+
+- **GIVEN** в настройках сервиса вход Telegram выключен
+- **WHEN** сервис запускается
+- **THEN** он поднимается и принимает записи по HTTP
+- **AND** конвейер расшифровки работает
+- **AND** бот не заведён, а в журнале ровно одна запись уровня `INFO` о том, что
+  вход выключен настройкой
+
+#### Scenario: Вход выключен, а ключ доступа задан
+
+- **GIVEN** в настройках сервиса вход Telegram выключен
+- **AND** ключ доступа при этом заполнен
+- **WHEN** сервис запускается
+- **THEN** он поднимается без Telegram, и бот не заводится
+- **AND** к Telegram не уходит ни одного обращения
+
+#### Scenario: Вход включён, а ключа доступа нет
+
+- **GIVEN** в настройках сервиса вход Telegram включён
+- **AND** ключ доступа пуст
+- **WHEN** сервис запускается
+- **THEN** старт кончается отказом
+- **AND** сообщение об отказе называет имя незаполненного ключа
+
+#### Scenario: Признака включения в настройках нет
+
+- **GIVEN** в настройках сервиса нет признака включения входа Telegram
+- **AND** ключ доступа заполнен и Telegram признаёт по нему бота
+- **WHEN** сервис запускается
+- **THEN** старт кончается отказом настройки
+- **AND** сообщение об отказе называет недостающий ключ
+
+#### Scenario: Вход включён и ключ годен
+
+- **GIVEN** в настройках сервиса вход Telegram включён
+- **AND** стоит ключ, по которому Telegram признаёт бота
+- **WHEN** сервис запускается
+- **THEN** он поднимается и работает обоими входами
+
+#### Scenario: Telegram не отвечает
+
+- **GIVEN** в настройках сервиса вход Telegram включён и ключ непуст
+- **AND** Telegram недоступен либо не отвечает дольше отведённого срока
+- **WHEN** сервис запускается
+- **THEN** он поднимается и принимает записи по HTTP
+- **AND** бот не заведён, а в журнале запись уровня `WARN` с причиной
+- **AND** запись не несёт значения ключа
+
+#### Scenario: Telegram ответил, что такого бота нет
+
+- **GIVEN** в настройках сервиса вход Telegram включён и ключ непуст
+- **AND** Telegram отвечает отказом на этот ключ
+- **WHEN** сервис запускается
+- **THEN** старт кончается отказом
+- **AND** ни журнал, ни текст отказа не несут значения ключа