Спека: настраиваемые напоминалки для админов
This commit is contained in:
Kenik
@@ -0,0 +1,121 @@
|
||||
# Настраиваемые напоминалки для админов — дизайн
|
||||
|
||||
Дата: 2026-09-02
|
||||
|
||||
## Проблема
|
||||
|
||||
Админам нужно, чтобы бот сам напоминал о разовых или периодических событиях (например,
|
||||
об окончании аренды домена/сервера): дата и время, текст, кому из админов отправить,
|
||||
периодичность (разово / каждую неделю / каждый месяц / каждый год).
|
||||
|
||||
## Права доступа
|
||||
|
||||
Создавать, просматривать и удалять напоминания может **любой админ** (из `ADMIN_IDS`
|
||||
или добавленный в рантайме, см. `_is_admin` в [bot.py](../../../bot.py)). Список
|
||||
напоминаний — общий для всех админов (как общая доска задач), отдельного разграничения
|
||||
«моё / чужое» нет.
|
||||
|
||||
## Хранение данных
|
||||
|
||||
Новая таблица SQLite `reminders` (создаётся в `Database._init_db()` в
|
||||
[database.py](../../../database.py), по образцу существующих `admins`/`custom_faq`):
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS reminders (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
text TEXT NOT NULL,
|
||||
remind_at TEXT NOT NULL, -- "YYYY-MM-DD HH:MM:SS", исходное (якорное) время
|
||||
next_at TEXT NOT NULL, -- "YYYY-MM-DD HH:MM:SS", следующее срабатывание
|
||||
recurrence TEXT NOT NULL, -- 'once' | 'weekly' | 'monthly' | 'yearly'
|
||||
recipients TEXT NOT NULL, -- JSON: список vk_id, либо строка "all"
|
||||
created_by INTEGER NOT NULL,
|
||||
created_at TEXT NOT NULL,
|
||||
active INTEGER NOT NULL DEFAULT 1
|
||||
);
|
||||
```
|
||||
|
||||
`remind_at` — неизменное якорное время первого срабатывания (день месяца/год для
|
||||
пересчёта периодов), `next_at` — то, что реально проверяет планировщик и что двигается
|
||||
вперёд после каждой отправки.
|
||||
|
||||
CRUD-методы в `Database` (по аналогии с `add_admin`/`remove_admin`/`get_admins`):
|
||||
`add_reminder(...)`, `get_active_reminders()`, `get_due_reminders(now_str)`,
|
||||
`update_reminder_next_at(id, next_at)`, `deactivate_reminder(id)`, `delete_reminder(id)`.
|
||||
|
||||
## Планировщик
|
||||
|
||||
Отдельный фоновый поток `threading.Thread(target=self._reminders_loop, daemon=True)`,
|
||||
запускается в `run()` рядом с уже существующими фоновыми потоками (прогрев медиа,
|
||||
рассылка). Цикл:
|
||||
|
||||
```
|
||||
while True:
|
||||
now = datetime.now() # локальное серверное время, как везде в проекте (без TZ-логики)
|
||||
for r in db.get_due_reminders(now):
|
||||
отправить текст всем recipients (self.send_message)
|
||||
if r.recurrence == 'once':
|
||||
db.deactivate_reminder(r.id)
|
||||
else:
|
||||
next_at = compute_next(r.remind_at, r.recurrence, after=now)
|
||||
db.update_reminder_next_at(r.id, next_at)
|
||||
time.sleep(60)
|
||||
```
|
||||
|
||||
`compute_next` считает **следующее срабатывание строго после now**, отталкиваясь от
|
||||
якорной даты `remind_at` (а не от предыдущего `next_at`) — так периодичность не
|
||||
дрейфует из-за клампинга коротких месяцев:
|
||||
|
||||
- `weekly`: `remind_at + 7*N дней`, ближайшее значение `> now`;
|
||||
- `monthly`: тот же день месяца, что и в `remind_at`; если в целевом месяце такого дня
|
||||
нет — последний день этого месяца (31.01 → 28/29.02 → 31.03, а не 28.03);
|
||||
- `yearly`: тот же день/месяц; 29 февраля в невисокосный год → 28 февраля.
|
||||
|
||||
**Пропуск при простое бота**: если бот был выключен и время срабатывания уже прошло —
|
||||
при первом же тике после старта напоминание досылается один раз, после чего сразу
|
||||
пересчитывается следующее *будущее* срабатывание (не досылается «пачка» пропущенных
|
||||
периодов).
|
||||
|
||||
## UI — мастер в админ-панели
|
||||
|
||||
Новая кнопка «⏰ Напоминалки» в `get_admin_keyboard` ([keyboards.py](../../../keyboards.py)).
|
||||
|
||||
**Список** (`_send_reminders_admin`): для каждого активного напоминания — id, дата
|
||||
следующего срабатывания, периодичность, текст (обрезанный превью), получатели.
|
||||
Плюс инструкция: «напоминалка добавить» / «напоминалка удалить <id>».
|
||||
|
||||
**Добавление** — пошаговый мастер состояний (по образцу `ADMIN_FAQ_ADD` в
|
||||
[bot.py](../../../bot.py)):
|
||||
|
||||
1. `ADMIN_REMINDER_DATE` — ввод `ДД.ММ.ГГГГ ЧЧ:ММ`, валидация формата и что дата не в
|
||||
прошлом;
|
||||
2. `ADMIN_REMINDER_TEXT` — текст напоминания;
|
||||
3. `ADMIN_REMINDER_RECIPIENTS` — нумерованный список текущих админов + пункт
|
||||
«0 — все админы»; можно ввести несколько номеров через запятую (например «1,3»);
|
||||
4. `ADMIN_REMINDER_PERIOD` — кнопки «Разово / Каждую неделю / Каждый месяц / Каждый год»;
|
||||
5. подтверждение и запись в БД (`add_reminder`), возврат к списку напоминаний.
|
||||
|
||||
Отмена мастера на любом шаге — существующим паттерном («отмена»/кнопка отмены →
|
||||
`get_cancel_admin_keyboard`).
|
||||
|
||||
**Удаление** — по id, текстовой командой «напоминалка удалить <id>», как удаление
|
||||
админа (`db.delete_reminder`).
|
||||
|
||||
**Сознательное упрощение (YAGNI)**: редактирования существующего напоминания нет —
|
||||
только добавить/удалить, как сейчас устроено управление списком админов. Чтобы
|
||||
поправить напоминание — удалить и создать заново.
|
||||
|
||||
## Изменяемые файлы
|
||||
|
||||
- [database.py](../../../database.py) — таблица `reminders` + CRUD-методы.
|
||||
- [bot.py](../../../bot.py) — мастер `ADMIN_REMINDER_*`, обработчики команд, фоновый
|
||||
поток-планировщик, запуск потока в `run()`.
|
||||
- [keyboards.py](../../../keyboards.py) — кнопка «⏰ Напоминалки» в админ-клавиатуре,
|
||||
клавиатура выбора периодичности.
|
||||
|
||||
## Тестирование
|
||||
|
||||
Юнит-тесты в `tests/` (по образцу `tests/test_database.py`):
|
||||
- CRUD напоминаний в БД;
|
||||
- расчёт `compute_next` для всех 3 периодичностей, включая крайние случаи (31 число,
|
||||
29 февраля);
|
||||
- логика «пропущенного» напоминания при простое (одна отправка + пересчёт в будущее).
|
||||
Reference in New Issue
Block a user