Niken
103 lines
6.7 KiB
Markdown
103 lines
6.7 KiB
Markdown
# 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). |