It's version 0.5

2025-10-29 21:46:06 +03:00
parent a71a7fbd0c
commit e56401bf1d
19 changed files with 582 additions and 7 deletions
@@ -0,0 +1,103 @@
+# MyFirstProgramm
+
+Лёгкий Telegram-бот на Python (aiogram + Playwright) для автоматической проверки и рассылки расписаний, а также набора аддонов.
+
+## Краткое описание
+Проект периодически проверяет расписание на сайте (через Playwright), делает скриншоты нужных фрагментов, вычисляет хеш (MD5) и отправляет/закрепляет изображение в целевых чатах Telegram только при изменении (чтобы не флудить чат). Также в `addons/` есть дополнительные модули (мини-приложения).
+
+## Структура (важные файлы/папки)
+- `main.py` — точка входа приложения (запуск бота).
+- `config.py` — конфигурация (переменные окружения).
+- `services/` — сервисы: `schedule_service.py`, `watcher_service.py` (логика слежки/хэшей).
+- `models/state.py` — in-memory состояние бота (кэши, last_clip_hash и т.д.).
+- `addons/` — набор дополнительных модулей (каждый аддон экспортирует `register` / `unregister`).
+- `requirements.txt` — зависимости.
+
+## Быстрый старт (локально)
+1. Установите зависимости (рекомендуется виртуальное окружение):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+2. Создайте `.env` (или экспортируйте переменные окружения):
+- `TELEGRAM_BOT_TOKEN` — токен бота
+- (опционально) `DEEPGRAM_API_KEY`, `ACCESS_TOKEN` — если используются аддоны
+
+Создайте файл `.env` рядом с `config.py`:
+
+```env
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+#DEEPGRAM_API_KEY=...
+#ACCESS_TOKEN=...
+```
+
+3. Запустите бота (пример):
+
+```bash
+python main.py
+```
+
+(В вашем окружении запуск может быть оформлен скриптом — например `./Desktop/my.sh`.)
+
+## Конфигурация
+Основные настройки находятся в `config.py`. Обратите внимание, что `Config` сейчас поднимает исключение, если `TELEGRAM_BOT_TOKEN` не задан.
+
+## Что изменилось (коротко)
+- Добавлена проверка MD5-хеша скриншота в `services/watcher_service.py` — теперь бот отправляет фото и закрепляет сообщение только при первом обнаружении и при изменениях.
+- Исправлен импорт в `addons/x_days_to/__init__.py` (модуль назывался `x_days_to.py`, вместо отсутствующего `handlers`).
+
+(Более полный список изменений — в `CHANGELOG.md`.)
+
+## Чек-лист готовности к релизу (private GitHub)
+Ниже — рекомендации и текущий статус (на основе быстрого статического анализа):
+
+- [ ] Тесты (unit/integration) — отсутствуют. Рекомендую добавить хотя бы базовые тесты для критичных сервисов (например мок ScheduleService и проверка логики хеширования).
+- [x] README (есть) — ✅
+- [x] CHANGELOG (есть) — ✅
+- [ ] Линт/статический анализ — есть предупреждения/ошибки (см. ниже). Нужно исправить перед релизом.
+- [ ] Безопасность/секреты — убедитесь, что `TELEGRAM_BOT_TOKEN` и другие ключи не коммитятся; добавьте `.env.example` и `.gitignore`.
+- [ ] CI — рекомендую GitHub Actions: lint (ruff), тесты (pytest), security scan.
+- [ ] Версионирование — добавьте `__version__` в `pyproject`/`setup.py` или тег релиза в Git.
+
+### Проблемы, найденные статически
+- `addons/send_message/handlers.py`: используется `aiohttp` без импорта (нужно `import aiohttp`). Это вызовет ошибку при импорте этого аддона.
+- Возможны другие runtime-ошибки — рекомендую прогнать `ruff check . --fix` и запустить бота в dev окружении.
+
+## Рекомендации перед релизом
+1. Исправить импорт/синтаксисные ошибки (см. `ruff` / `get_errors`).
+2. Добавить `.env.example` и `.gitignore` (включить `.venv/`, `storage/` с чувствительными файлами и логами).
+3. Добавить базовые тесты и настроить GitHub Actions (lint + tests).
+4. Решить поведение state-персистенции: `BotState` хранит состояние в памяти — после рестарта всё теряется. Если важно сохранять историю/фиксированный pinned_id — добавить simple JSON/SQLite storage.
+5. Проверить, что все аддоны регистрируют хендлеры корректно (в `x_days_to` ранее не было регистрации а-ля `@dp.message(...)` — возможно требуется доработить).
+
+## Как выпустить на приватный GitHub
+1. Создайте репозиторий и инициализируйте git:
+
+```bash
+git init
+git add .
+git commit -m "Initial commit"
+# создайте приватный репо в GitHub и затем
+git remote add origin git@github.com:yourorg/yourrepo.git
+git branch -M main
+git push -u origin main
+```
+
+2. Настройте GitHub Actions (workflow) для lint & tests.
+3. Добавьте релизный тег и changelog entry:
+
+```bash
+git tag -a v0.1.0 -m "Initial private release"
+git push origin v0.1.0
+```
+
+---
+
+Если хотите, я могу сразу:
+- добавить `.env.example` и `.gitignore`;
+- исправить `addons/send_message/handlers.py` (добавить импорт `aiohttp`) и/или добавить базовый тест для `watcher_service`.
+
+Скажите, что выполнить следующим шагом — добавлять `.env.example`/`.gitignore`, исправлять найденную ошибку или настроить CI (создать пример workflow).