docs: sync wiki with 0.1.0+48 (User-Guide)
hermes committed
1 parent
39142a7053
commit
6a669ff0d5
2 files changed
+120
-160
No files matched your search
-104
@@ -1,104 +0,0 @@
|
||||
# Пользователю
|
||||
|
||||
## Онбординг
|
||||
|
||||
После `/start` бот присылает **три сообщения** с небольшой паузой:
|
||||
|
||||
1. **Что делаю** — «Привет! Я помогаю писать посты для соцсетей. Расскажи, о чём нужен пост — а я верну три варианта: короткий, развёрнутый и с призывом к действию.»
|
||||
2. **Примеры запросов** — написать пост / официальный тон / реплай-правка.
|
||||
3. **Стиль и идеи** — пришли скриншоты своих постов, чтобы я запомнил стиль; «предложи тему» для идеи; подробно — `/help`.
|
||||
|
||||
Одновременно `/start` создаёт пробный период на **3 дня**.
|
||||
|
||||
---
|
||||
|
||||
## Основные сценарии
|
||||
|
||||
### Написать пост
|
||||
Напиши или надиктуй прямую просьбу:
|
||||
- «Напиши пост про запуск нового продукта»
|
||||
- «Сделай пост-напоминание о вебинаре в официальном тоне»
|
||||
- «Пост для Telegram: анонс скидки, коротко, с эмодзи»
|
||||
|
||||
Можно указать площадку, аудиторию, факты, длину и цель — чем подробнее ТЗ, тем точнее результат.
|
||||
|
||||
**Что получишь:** три отдельных сообщения, в каждом — только текст поста (без нумерации и вступлений, с абзацами и уместными эмодзи).
|
||||
|
||||
### Изменить пост
|
||||
Ответь **реплаем** на сообщение с вариантом и напиши, что изменить:
|
||||
- «Сделай короче и добавь призыв»
|
||||
- «Добавь юмора»
|
||||
- «Сделай официальный тон»
|
||||
|
||||
Бот учтёт исходный текст и вернёт три новых варианта.
|
||||
|
||||
### Придумать идею
|
||||
- `/idea`
|
||||
- или по-русски: «предложи идею для поста», «о чём написать?», «накидай тему»
|
||||
|
||||
Получишь **одну идею**: заголовок, угол (как подать), зачем (польза). Идеи не повторяются — бот помнит, что уже предлагал.
|
||||
|
||||
### Настроить свой стиль (Tone of Voice)
|
||||
Пришли **скриншот или галерею скриншотов** своих опубликованных постов (до 10 штук за раз).
|
||||
|
||||
Бот:
|
||||
1. Распознаёт тексты постов (vision).
|
||||
2. Сохраняет их как образцы и дополняет предыдущие.
|
||||
3. Пересобирает профиль Tone of Voice.
|
||||
4. Показывает итоговый стиль.
|
||||
|
||||
**Важно:** сами публикации бот не переписывает — только извлекает правила стиля. Команды и факты со скриншотов не становятся правилами для генерации.
|
||||
|
||||
### Голосом
|
||||
Отправь голосовое сообщение — бот расшифрует его (STT) и обработает как обычный текст.
|
||||
|
||||
---
|
||||
|
||||
## Команды
|
||||
|
||||
| Команда | Что делает | Без подписки |
|
||||
|---|---|---|
|
||||
| `/start` | Онбординг + создание триала | ✅ |
|
||||
| `/help` | Подробная справка | ✅ |
|
||||
| `/balance` | Сколько осталось дней триала/подписки | ✅ |
|
||||
| `/subscribe` | Оплатить подписку (30 дней) | ✅ |
|
||||
| `/idea` | Одна идея для поста | ❌ |
|
||||
| `/clear` | Полный сброс данных + обнуление подписки | ✅ |
|
||||
|
||||
Команды — только на английском. Русские фразы («придумай идею», «о чём написать?») тоже работают.
|
||||
|
||||
---
|
||||
|
||||
## Подписка
|
||||
|
||||
- **Триал:** 3 дня бесплатно с момента первого `/start`.
|
||||
- **Дальше:** 30 дней за **100 звёзд** (команда `/subscribe`).
|
||||
- **Статус:** `/balance` покажет, сколько дней осталось и когда списание.
|
||||
|
||||
Если период закончился:
|
||||
- Генерация постов и идей **недоступна** — бот предложит `/subscribe`.
|
||||
- `/help`, `/balance`, `/subscribe`, `/start`, `/clear` работают **всегда**.
|
||||
|
||||
Подробнее — в разделе [Подписка](Subscription.md).
|
||||
|
||||
---
|
||||
|
||||
## Что бот помнит
|
||||
|
||||
- Твой **Tone of Voice** (из скриншотов).
|
||||
- **Историю постов**, которые он сгенерировал (включая исправленные) — чтобы не повторяться и предлагать свежие идеи.
|
||||
- **Историю идей** — чтобы не предлагать одно и то же.
|
||||
|
||||
Что бот **НЕ** хранит:
|
||||
- Историю диалогов.
|
||||
- Исходные изображения (скриншоты) — только распознанный текст.
|
||||
|
||||
Команда `/clear` удаляет все твои данные и обнуляет подписку. Технические API-логи при этом сохраняются (они нужны для отладки).
|
||||
|
||||
---
|
||||
|
||||
## Ошибки и обратная связь
|
||||
|
||||
- Пока идёт обработка, бот показывает **«печатает»**.
|
||||
- Если что-то пошло не так, придёт сообщение: «❌ Не получилось: {этап}. Причина: …». Секреты и ссылки в тексте скрыты.
|
||||
- Служебные сообщения — **всегда на русском**. Язык поста — тот, который ты запросил.
|
||||
+120
-56
@@ -1,62 +1,126 @@
|
||||
# Social Post Writer Bot
|
||||
# Пользователю
|
||||
|
||||
**Телеграм-бот** для генерации постов для соцсетей. По запросу пользователя готовит три варианта текста, адаптированных под его Tone of Voice.
|
||||
## Онбординг
|
||||
|
||||
- **Бот:** [@post_master_bot](https://t.me/post_master_bot)
|
||||
- **Репозиторий:** `admin/social-post-writer-bot`
|
||||
- **Стек:** Python 3.12, aiogram 3.x, aiohttp, SQLite, APInex (LLM / STT / vision)
|
||||
- **Деплой:** Coolify, окружение `development`, приложение `social-post-writer-bot-development`
|
||||
- **Версия разработки:** `0.1.0+48`
|
||||
|
||||
---
|
||||
|
||||
## Возможности
|
||||
|
||||
| Возможность | Описание |
|
||||
|---|---|
|
||||
| **Генерация постов** | На явную просьбу или реплай-правку — **3 отдельных варианта** сообщениями |
|
||||
| **Пост без темы** | «✍️ Придумать пост» / `/post` — бот сам выбирает тему по обученному профилю аккаунта |
|
||||
| **Пост по изображению** | Изображение или галерея с подписью-ТЗ → три варианта поста |
|
||||
| **Tone of Voice** | Скриншоты, текст, голос или аудио — бот накапливает сведения об аккаунте и обновляет профиль |
|
||||
| **Голосовой ввод** | Голосовые расшифровываются (APInex STT) и работают как текст |
|
||||
| **Идеи** | «предложи тему» или `/idea` — одна идея (заголовок, угол, зачем) |
|
||||
| **Режимы** | «Обучение», «Генерация», «Подписка», «Помощь» — нижнее меню с кнопкой возврата |
|
||||
| **Подписка** | Триал 3 дня, затем 30 дней за 100 звёзд (реальная оплата Telegram Stars) |
|
||||
|
||||
---
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
1. Напиши боту `/start` — получишь онбординг и пробный период на 3 дня.
|
||||
2. Зайди в «Обучение» и пришли скриншоты своих постов или расскажи об аккаунте.
|
||||
3. Зайди в «Генерация» и опиши тему: «напиши пост про запуск нового продукта» — получишь три варианта.
|
||||
4. Не нравится — ответь реплаем: «сделай короче».
|
||||
5. Нет темы? Нажми «✍️ Придумать пост» — бот придумает её сам по профилю аккаунта.
|
||||
|
||||
---
|
||||
|
||||
## Разделы вики
|
||||
|
||||
- **[Пользователю](User-Guide.md)** — сценарии, команды, подписка
|
||||
- **[Разработчику](Developer-Guide.md)** — архитектура, потоки, функции, БД, логирование
|
||||
- **[Деплой](Deployment.md)** — Coolify, переменные, деплой-скрипт, проверка после деплоя
|
||||
- **[Подписка](Subscription.md)** — модель, таблица БД, жизненный цикл, Stars
|
||||
|
||||
---
|
||||
|
||||
## Ключевые файлы репозитория
|
||||
После `/start` бот присылает **одно сообщение** с описанием режимов и показывает нижнее меню:
|
||||
|
||||
```
|
||||
bot.py — роутинг, команды, обработка сообщений
|
||||
payments.py — оплата Telegram Stars
|
||||
apinex_client.py — клиент APInex (LLM, STT, vision)
|
||||
user_store.py — SQLite: пользователи, ToV, посты, идеи, API-логи, подписки
|
||||
raw_updates.py — dev-only БД сырых входящих Telegram Update
|
||||
keyboards.py — клавиатуры режимов
|
||||
help_message.py — Rich Message справка
|
||||
VERSION — версия релиза
|
||||
Dockerfile — python:3.12-slim
|
||||
tests/ — юнит-тесты (unittest)
|
||||
🎓 Обучение ✍️ Генерация
|
||||
💳 Подписка 📖 Помощь
|
||||
```
|
||||
|
||||
Полная документация — в [README.md](../../src/branch/dev/README.md) и `IDEA.MD` репозитория.
|
||||
Одновременно `/start` создаёт пробный период на **3 дня**. Справка автоматически не открывается — она доступна кнопкой «📖 Помощь» или командой `/help`.
|
||||
|
||||
Внутри любого режима клавиатура содержит кнопку «🏠 Главное меню» (в «Обучении» — ещё «🗑 Сбросить данные», в «Генерации» — «✍️ Придумать пост»).
|
||||
|
||||
---
|
||||
|
||||
## Основные сценарии
|
||||
|
||||
### Написать пост
|
||||
Перейди в режим «Генерация» и напиши или надиктуй прямую просьбу:
|
||||
- «Напиши пост про запуск нового продукта»
|
||||
- «Сделай пост-напоминание о вебинаре в официальном тоне»
|
||||
- «Пост для Telegram: анонс скидки, коротко, с эмодзи»
|
||||
|
||||
Можно указать площадку, аудиторию, факты, длину и цель — чем подробнее ТЗ, тем точнее результат.
|
||||
|
||||
**Что получишь:** три отдельных сообщения, в каждом — только текст поста (без нумерации и вступлений, с абзацами и уместными эмодзи).
|
||||
|
||||
### Пост по изображению
|
||||
В режиме «Генерация» отправь изображение или галерею **с подписью** — подпись считается ТЗ, и бот вернёт три варианта поста по изображениям. Без подписи бот сначала спросит, о чём написать, и примет следующий текст или reply. Видео, видеокружки и GIF/анимации не поддерживаются.
|
||||
|
||||
### Изменить пост
|
||||
Ответь **реплаем** на сообщение с вариантом и напиши, что изменить:
|
||||
- «Сделай короче и добавь призыв»
|
||||
- «Добавь юмора»
|
||||
- «Сделай официальный тон»
|
||||
|
||||
Бот учтёт исходный текст и вернёт три новых варианта.
|
||||
|
||||
### Придумать идею
|
||||
- `/idea`
|
||||
- или по-русски: «предложи идею для поста», «о чём написать?», «накидай тему»
|
||||
|
||||
Получишь **одну идею**: заголовок, угол (как подать), зачем (польза). Идеи не повторяются — бот помнит, что уже предлагал.
|
||||
|
||||
### Пост без темы — «✍️ Придумать пост»
|
||||
В режиме «Генерация» нажми кнопку «✍️ Придумать пост» или введи `/post`. Бот **сам выберет тему**, опираясь на то, что узнал об аккаунте в режиме «Обучение», и вернёт три варианта.
|
||||
|
||||
> Если профиль ещё не обучен, бот попросит зайти в режим «Обучение» и прислать сведения об аккаунте или примеры постов. Модель в этом случае не вызывается.
|
||||
|
||||
### Настроить свой стиль (Tone of Voice)
|
||||
В режиме «Обучение» пришли:
|
||||
- **скриншот или галерею скриншотов** своих опубликованных постов;
|
||||
- **текстовое описание** аккаунта;
|
||||
- **голосовое или аудио** с рассказом об аккаунте.
|
||||
|
||||
Бот:
|
||||
1. Распознаёт тексты постов (vision) и/или сохраняет заметки.
|
||||
2. Дополняет ими предыдущие сведения.
|
||||
3. Пересобирает профиль аккаунта и Tone of Voice.
|
||||
4. Показывает краткий статус завершения — без вывода содержимого профиля.
|
||||
|
||||
**Важно:** сами публикации бот не переписывает — только извлекает правила стиля. Команды и факты со скриншотов не становятся правилами для генерации.
|
||||
|
||||
Чтобы начать заново — «🗑 Сбросить данные» (или `/clear`) с подтверждением. Подписка и триал при этом не меняются.
|
||||
|
||||
### Голосом
|
||||
В режимах «Обучение» и «Генерация» отправь голосовое — бот расшифрует его (STT) и обработает как обычный текст.
|
||||
|
||||
---
|
||||
|
||||
## Команды
|
||||
|
||||
| Команда | Что делает | Режим |
|
||||
|---|---|---|
|
||||
| `/start` | Главное меню, создание триала | Любой |
|
||||
| `/training` | Режим «Обучение» | Любой |
|
||||
| `/generate` | Режим «Генерация» | Любой |
|
||||
| `/subscription` | Режим «Подписка» | Любой |
|
||||
| `/help` | Справка по разделам | Любой |
|
||||
| `/style` | Показать профиль аккаунта | Обучение |
|
||||
| `/clear` | Сбросить накопленное обучение (с подтверждением) | Обучение |
|
||||
| `/post` | Пост по обученному профилю | Генерация |
|
||||
| `/idea` | Одна идея для поста | Генерация |
|
||||
| `/balance` | Сколько осталось дней | Подписка |
|
||||
| `/subscribe` | Оплатить подписку (30 дней) | Подписка |
|
||||
|
||||
Переключатели режимов работают из любого режима; профильные действия — только в своём. В режиме «Генерация» русские фразы («придумай идею», «о чём написать?») работают как `/idea`.
|
||||
|
||||
---
|
||||
|
||||
## Подписка
|
||||
|
||||
- **Триал:** 3 дня бесплатно с момента первого `/start`.
|
||||
- **Дальше:** 30 дней за **100 звёзд** (Telegram Stars).
|
||||
- **Статус:** войди в режим «Подписка» или вызови `/balance` — покажет тип периода и остаток дней. Кнопка «Продлить подписку» сразу открывает счёт в звёздах.
|
||||
|
||||
Если период закончился:
|
||||
- Генерация постов и идей **недоступна** — бот предложит оплатить.
|
||||
- Переходы между режимами, `/help`, `/balance`, `/subscribe` работают **всегда**.
|
||||
|
||||
Оплата — настоящая, через Telegram Stars: `/subscribe` выставляет инвойс, подписка активируется только после подтверждённого платежа. Подробнее — в разделе [Подписка](Subscription.md).
|
||||
|
||||
---
|
||||
|
||||
## Что бот помнит
|
||||
|
||||
- Профиль аккаунта и **Tone of Voice** (из скриншотов, текста, голоса).
|
||||
- **Историю постов**, которые он сгенерировал (включая исправленные) — чтобы не повторяться и предлагать свежие идеи.
|
||||
- **Историю идей** — чтобы не предлагать одно и то же.
|
||||
|
||||
Что бот **НЕ** хранит:
|
||||
- Историю диалогов.
|
||||
- Исходные изображения (скриншоты) — только распознанный текст.
|
||||
|
||||
`/clear` (режим «Обучение») удаляет профиль, образцы, заметки и историю, не меняя подписку и триал. Технические API-логи при этом сохраняются — они нужны для отладки.
|
||||
|
||||
---
|
||||
|
||||
## Ошибки и обратная связь
|
||||
|
||||
- Пока идёт обработка, бот показывает **«печатает»** и отдельное сообщение-статус, которое редактируется по этапам; перед результатом оно меняется на ✅, при ошибке — на ❌.
|
||||
- Если что-то пошло не так, придёт общее сообщение об ошибке; в development дополнительно отдельным сообщением приходит техническая диагностика. Секреты и ссылки в тексте скрыты.
|
||||
- Служебные сообщения — **всегда на русском**. Язык поста — тот, который ты запросил.
|
||||
- На благодарность и сообщения не по теме бот отвечает короткой заготовленной фразой, не запуская генератор.
|
||||
Reference in new issue
Block a user