docs: sync wiki with 0.1.0+48 (Developer-Guide)

Developer-Guide.md

@@ -0,0 +1,227 @@
+# Разработчику
+
+## Структура
+
+```
+bot.py               — роутинг, команды, обработка сообщений (aiogram 3.x)
+payments.py          — оплата Stars: sendInvoice, pre_checkout_query, successful_payment, защита от двойного списания
+apinex_client.py     — клиент APInex (LLM, STT, vision), промпты, логирование вызовов
+user_store.py        — SQLite: пользователи, ToV, посты, идеи, API-логи, подписки
+raw_updates.py       — отдельная SQLite-БД сырых входящих Telegram Update (только development)
+keyboards.py         — клавиатуры главного меню и режимов; маппинг кнопок на команды
+help_message.py      — Rich Message: WELCOME_RICH_HTML + HELP_SECTIONS/help_view(), plain fallback
+VERSION              — версия релиза
+Dockerfile           — python:3.12-slim
+requirements.txt     — зависимости
+tests/               — юнит-тесты (unittest)
+```
+
+---
+
+## Режимы (FSM)
+
+`BotMode` содержит `lobby`, `training`, `generation`, `subscription`, `help`. «Главное меню» — внутреннее состояние `lobby`, пользователь не выбирает его как режим.
+
+- `current_mode(state)` / `enter_mode(...)` / `require_mode(...)` — проверка и переключение.
+- Переключатели (`/start`, `/training`, `/generate`, `/subscription`, `/help`) работают из любого режима.
+- Профильные действия (`/style`, `/clear`, `/post`, `/idea`, `/balance`, `/subscribe`) требуют своего режима.
+
+---
+
+## Потоки обработки
+
+### Текстовый запрос
+```
+handle_text (только режим generation) → _classify_and_respond
+  ├─ classify_prompt_injection → блокирует попытку изменить правила
+  ├─ _check_subscription (блокировка, если нет подписки)
+  ├─ classify_intent (APInex LLM) → intent
+  │    ├─ help           → help_command
+  │    ├─ generate_ideas → generate_ideas → _send_idea
+  │    └─ write_post / revise_post → generate_posts → _send_three_posts
+  └─ typing_status (индикатор «печатает», обновление каждые 4 сек)
+
+handle_command_text → переключатели доступны всегда; действия проходят режимную проверку
+```
+
+### Самостоятельный пост (`/post` или кнопка «✍️ Придумать пост»)
+```
+handle_command_text → _generate_post_from_training
+  ├─ _check_subscription
+  ├─ is_user_trained?  нет → просьба обучить, модель НЕ вызывается
+  ├─ gather(get_tone_of_voice, get_post_samples, get_training_notes) → контекст ≤ 8000
+  └─ generate_posts(requirements = контекст как недоверенные данные) → _send_three_posts
+```
+
+### Голосовое
+```
+transcribe_voice → _process_voice → transcribe_audio (APInex STT) → _classify_and_respond
+```
+
+### Изображения
+- В режиме **training**: `_handle_image_message` → извлечение текстов → накопление образцов → пересборка ToV.
+- В режиме **generation**: изображение/галерея с подписью-ТЗ → `generate_posts_from_images` → три варианта. Без подписи бот запрашивает ТЗ.
+- Видео, видеокружки, GIF/анимации отклоняются во всех режимах.
+
+### Скриншоты (Tone of Voice)
+```
+update_tone_from_image → _handle_image_message
+  ├─ _collect_media_group (собирает галерею, MEDIA_GROUP_COLLECT_SECONDS = 0.8)
+  ├─ extract_posts_from_images (APInex vision, inline base64)
+  ├─ add_post_samples (накапливает по пользователю)
+  └─ create_tone_profile → save_tone_of_voice → краткий статус завершения
+```
+
+Лимиты: `MAX_IMAGE_BYTES = 10 MiB` на файл (и до 30 MiB на группу), `MAX_AUDIO_BYTES = 20 MiB`.
+
+---
+
+## Ключевые функции
+
+### `bot.py`
+
+| Функция | Что делает |
+|---|---|
+| `start(message, state)` | Одно welcome Rich Message + главное меню + создание триала |
+| `handle_command_text` | Роутинг переключателей и профильных команд по режиму |
+| `handle_text` | Обычное сообщение в режиме генерации |
+| `_classify_and_respond` | Ядро: инъекции → подписка → классификация → генерация |
+| `_generate_post_from_training` | Пост по обученному профилю с гейтом `is_user_trained` |
+| `_check_subscription` | Проверяет активную подписку; если нет — статус и блокировка |
+| `_show_subscription_info` | Тип периода, остаток дней, inline-кнопка продления |
+| `balance_command` / `subscribe_command` | `/balance` — статус; `/subscribe` — Stars-инвойс |
+| `handle_pre_checkout` | Подтверждает только свой инвойс в XTR на 100 звёзд |
+| `handle_successful_payment` | Активирует подписку после реальной оплаты |
+| `clear_command` | `/clear` и «Сбросить данные» — inline-подтверждение, сброс только в режиме обучения |
+| `style_command` | `/style` — профиль аккаунта |
+| `help_command` / `help_navigation` | Справка Rich Message + переключение разделов |
+| `notify_development_deploy` | Dev-уведомление о новой версии в `DEV_CHAT_ID` |
+| `typing_status` | Индикатор «печатает» |
+| `report_error` | Понятная ошибка пользователю; секреты вырезаны |
+| `is_development_environment` | `DEPLOY_ENV == "development"` — гейт всех dev-ветвей |
+| `configure_raw_update_logging` | Подключает `RawUpdateMiddleware` только в development |
+
+### `user_store.py`
+
+| Функция | Что делает |
+|---|---|
+| `init_db` | Создаёт/мигрирует таблицы |
+| `ensure_subscription` | Создаёт запись подписки с триалом (`INSERT OR IGNORE`) |
+| `activate_subscription` | Активирует/продлевает на 30 дней |
+| `deactivate_subscription` | `is_active = 0` |
+| `is_subscribed` | Запись есть, `is_active = 1`, срок не истёк |
+| `subscription_row` | Строка подписки |
+| `is_user_trained` | Флаг `users.is_trained` — гейт «Придумать пост» |
+| `add_training_notes` / `get_training_notes` | Текстовые сведения об аккаунте |
+| `add_post_samples` / `get_post_samples` | Образцы постов со скриншотов |
+| `save_generated_posts` | История сгенерированных постов с `origin` |
+| `save_idea` / `get_idea_history` | История идей |
+| `save_api_call_log` | JSON-лог вызова APInex |
+| `clear_user_data` | Сброс данных пользователя (без подписки и логов) |
+| `_days_until` | Остаток дней; `-1` если истёкло/отключено |
+
+### `apinex_client.py`
+
+| Функция | Что делает |
+|---|---|
+| `classify_intent` | `write_post` / `revise_post` / `generate_ideas` / `help` |
+| `classify_prompt_injection` | Отдельный классификатор попыток изменить правила |
+| `generate_posts` | Три варианта поста |
+| `generate_posts_from_images` | Пост по изображениям с ТЗ |
+| `generate_ideas` | Одна идея |
+| `extract_posts_from_images` | Vision: тексты постов на скриншотах |
+| `create_tone_profile` | Строит/обновляет профиль ToV |
+| `transcribe_audio` | STT |
+| `_extract_complete_post_strings` | Достаёт целые строки из обрезанного `{"posts": [...]}` |
+| `chat_text` | Базовый вызов LLM |
+
+---
+
+## База данных
+
+Рабочая БД: `/app/data/social_writer.sqlite3` (persistent volume Coolify).
+
+| Таблица | Назначение |
+|---|---|
+| `users` | `telegram_user_id`, `tone_of_voice`, `is_trained` |
+| `user_post_samples` | Распознанные тексты постов со скриншотов |
+| `generated_posts` | История сгенерированных постов (`origin`: generated/revised) |
+| `generated_ideas` | История идей (для исключения повторов) |
+| `api_call_logs` | JSON-логи вызовов APInex + ошибки (30 дней) |
+| `subscriptions` | Подписки и триалы |
+| `payments` | `telegram_payment_charge_id` — защита от двойного начисления |
+
+Схему `subscriptions` см. в [Подписка](Subscription.md).
+
+Отдельная dev-БД: `/app/data/bot_updates.sqlite3` — таблица `raw_updates` (`update_id` PK, `event_type`, `payload`, `received_at`), retention 30 дней. См. ниже.
+
+---
+
+## Промпты и модели
+
+Модели задаются переменными Coolify:
+- `APINEX_STT_MODEL` → `nova-2`
+- `APINEX_INTENT_CLASSIFIER_MODEL` → `gemini-3.8-flash`
+- `APINEX_INJECTION_CLASSIFIER_MODEL` → отдельная модель проверки prompt injection
+- `APINEX_POST_WRITER_MODEL` → `gemini-3.8-flash`
+- `APINEX_IMAGE_TONE_MODEL` → `gemini-3.8-flash` (vision)
+- `APINEX_RESPONSE_REPAIR_MODEL` → починка невалидного JSON (одна попытка)
+- `APINEX_API_KEY` — общий секрет
+
+**Про промпты:**
+- Системный промпт редактора **неизменен**.
+- ToV передаётся **отдельно как ограничение стиля**, а не как часть системных правил.
+- OCR-текст со скриншотов — образцы стиля, а не команды.
+- Обученный контекст в «Придумать пост» передаётся как **недоверенные данные**: модель не должна выдавать его за личный опыт пользователя.
+
+**Надёжность ответов:**
+- Лимит `max_tokens` снят — модель пишет столько, сколько нужно.
+- Пустой `content` → до двух повторов, третий запрос с `reasoning_effort: low`.
+- Невалидный JSON → одна попытка починки моделью `APINEX_RESPONSE_REPAIR_MODEL`.
+- Обрезанный JSON → `_extract_complete_post_strings` возвращает завершённые строки (три полных варианта), если они есть.
+
+---
+
+## Логирование
+
+### API-журнал (`api_call_logs`)
+Каждый вызов APInex пишется с `operation_id`, `stage`, `model`, именем и SHA-256 промпта, `request_json`, `response_json`, `status_code`, `error`, длительностью. Хранение — 30 дней.
+
+**Не пишется:** системные промпты целиком, base64 изображений, бинарное аудио, API-ключи.
+
+### Файл лога приложения
+`/app/data/bot.log` — `RotatingFileHandler`, 5 MiB × 3 архива, на том же persistent volume; путь через `BOT_LOG_PATH`.
+
+### Сырые Telegram Update (только development)
+`raw_updates.py` пишет полный `Update.model_dump(mode="json")` в отдельную БД `/app/data/bot_updates.sqlite3` (путь через `RAW_UPDATES_DB_PATH`). Middleware `RawUpdateMiddleware` подключается на `dispatcher.update.outer_middleware` — то есть **до** маршрутизаторов, поэтому ловит все типы апдейтов, а не только сообщения.
+
+```sql
+SELECT payload FROM raw_updates WHERE update_id = ?;
+```
+
+- Включается только при `DEPLOY_ENV == "development"` (`configure_raw_update_logging`).
+- Retention 30 дней: чистка при старте и при каждой записи.
+- Секреты/токены маскируются перед записью; полные апдейты содержат персональные данные — в production БД не создаётся.
+
+### Логи контейнера
+Ошибки содержат `operation_id`, Telegram user id, этап и traceback; по одному `operation_id` находятся все связанные записи.
+
+---
+
+## Тесты
+
+```bash
+.venv/bin/python -m unittest discover -s tests -v
+```
+
+155 тестов (на версии `0.1.0+48`). Покрытие: STT, LLM, vision, ToV, reply-поля, изоляция пользователей, API-логи, **raw update log**, режимные клавиатуры и роутинг, платежи (Stars, защита от повторов, dev-подтверждение), ошибки, справка, онбординг, подписки, самостоятельная генерация поста, восстановление обрезанного JSON, индикатор «печатает».
+
+> Запускай через `.venv` проекта: вне виртуального окружения `aiogram` может быть не установлен.
+
+---
+
+## Правила языка
+
+- Служебные сообщения боту → **всегда русский**.
+- Текст поста → язык явного запроса пользователя.
+- Дословный текст технической ошибки может остаться на языке оригинала.