domovoy_bot/НАПОМИНАНИЯ_О_ПЛАТЕЖАХ.md

# 💳 Напоминания о платежах ЖКХ — v1.6

**Версия:** v1.6
**Дата:** 26 февраля 2026 г.
**Статус:** ✅ Реализовано

---

## 📋 Описание

Система напоминаний о платежах за коммунальные услуги. Админ создаёт напоминания о платежах, бот автоматически рассылает напоминания 5-го и 9-го числа каждого месяца, жильцы всегда в курсе сроков оплаты.

---

## 🎯 Возможности

- ✅ 8 типов платежей (электроэнергия, вода, отопление, газ, содержание жилья, мусор, интернет, другое)
- ✅ Пошаговое создание напоминаний
- ✅ Авто-рассылка 5-го и 9-го числа в 09:00
- ✅ Ссылки на оплату (Госуслуги, Сбербанк, Тинькофф)
- ✅ Просмотр всех платежей
- ✅ Удаление напоминаний
- ✅ Ежемесячные повторяющиеся платежи

---

## 📱 Команды

### Для администраторов:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/payment_add` | Добавить напоминание о платеже | `/payment_add` |
| `/payment_del <ID>` | Удалить напоминание по ID | `/payment_del 5` |
| `/payments`, `/платежи` | Показать все напоминания | `/payments` |

### Для всех:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/payments`, `/платежи` | Показать все напоминания | `/payments` |

---

## 🎯 Типы платежей

| № | Тип | Emoji | Описание |
|---|-----|-------|----------|
| 1 | ⚡ Электроэнергия | ⚡ | Оплата за свет |
| 2 | 💧 Вода | 💧 | ХВС, ГВС, водоотведение |
| 3 | 🔥 Отопление | 🔥 | Отопительный сезон |
| 4 | 🔶 Газ | 🔶 | Газоснабжение |
| 5 | 🏠 Содержание жилья | 🏠 | Содержание и ремонт |
| 6 | 🗑️ Вывоз мусора | 🗑️ | ТКО, мусор |
| 7 | 📡 Интернет | 📡 | Домашний интернет |
| 8 | 📋 Другое | 📋 | Прочие платежи |

---

## 🎯 Сценарии использования

### Сценарий 1: Создание напоминания

**1. Админ пишет:**
```
/payment_add
```

**2. Бот показывает меню:**
```
💳 Добавление напоминания о платеже

Выберите тип платежа:

1️⃣ ⚡ Электроэнергия
2️⃣ 💧 Вода
3️⃣ 🔥 Отопление
4️⃣ 🔶 Газ
5️⃣ 🏠 Содержание жилья
6️⃣ 🗑️ Вывоз мусора
7️⃣ 📡 Интернет
8️⃣ 📋 Другое

Или отправьте номер типа (1-8):
[кнопки с типами]
```

**3. Админ нажимает** `💧 Вода` **или отправляет** `2`

**4-8. Пошаговый ввод:**
- Название: `Квартплата за воду`
- Сумма: `1500`
- Дата оплаты: `10` (ежемесячно до 10 числа)
- Описание: `ХВС, ГВС, водоотведение`

**9. Бот подтверждает:**
```
✅ Напоминание о платеже добавлено!

💧 Вода — Квартплата за воду

💰 Сумма: 1500 ₽
📅 Срок оплаты: 10 число каждого месяца
🔖 ID: 1

Для просмотра: /payments
```

---

### Сценарий 2: Просмотр платежей

**Жилец или админ:**
```
/payments
```

**Бот:**
```
💳 Напоминания о платежах ЖКХ

1. Квартплата за воду
   └─ Сумма: 1500 ₽
   └─ Срок: 10 число
   └─ Осталось дней: 5

2. Электроэнергия
   └─ Сумма: 800 ₽
   └─ Срок: 15 число
   └─ Осталось дней: 10

3. Интернет
   └─ Сумма: Переменная
   └─ Срок: 25 число
   └─ Осталось дней: 20

💡 Для добавления: /payment_add
```

---

### Сценарий 3: Авто-напоминание (5 число)

**5-го числа в 09:00 (автоматически):**

**Бот пишет в чат:**
```
⏰ Напоминание об оплате ЖКХ!

Сегодня 5 число. Не забудьте оплатить:

✅ Квартплата за воду
   └─ Срок: 10 число (осталось 5 дн.)
   └─ Сумма: 1500 ₽

✅ Электроэнергия
   └─ Срок: 15 число (осталось 10 дн.)
   └─ Сумма: 800 ₽

💳 Ссылки на оплату:
• [Госуслуги ЖКХ](https://www.gosuslugi.ru/category/payments/zhkh)
• [Сбербанк Онлайн](https://www.sberbank.ru/ru/person/payments/zhkh)
• [Тинькофф ЖКХ](https://www.tinkoff.ru/payments/zhkh)

_Оплатить можно через Госуслуги, Сбербанк или Тинькофф_
```

---

### Сценарий 4: Удаление напоминания

**Админ:**
```
/payment_del 1
```

**Бот:**
```
✅ Напоминание "Квартплата за воду" удалено
```

---

## 🗄️ База данных

### Таблица `payment_reminders`:
```sql
CREATE TABLE payment_reminders (
    reminder_id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    amount INTEGER,              -- Сумма в рублях
    due_date TIMESTAMP NOT NULL, -- Дата оплаты
    description TEXT,
    payment_link TEXT,           -- Ссылка на оплату
    is_recurring BOOLEAN DEFAULT 1,  -- Ежемесячный
    created_by BIGINT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT 1,
    last_reminder_sent TIMESTAMP,
    FOREIGN KEY (created_by) REFERENCES users(user_id)
)
```

### Индексы:
- `ix_payment_reminders_due_date` — по дате
- `ix_payment_reminders_active` — по статусу

---

## 🧪 Тестирование

### Чек-лист проверки:

#### 1. Создание напоминания
```bash
# Админ:
/payment_add
# Выбрать тип, название, сумму, дату, описание
```
- [ ] Меню типов отображается
- [ ] Пошаговый ввод работает
- [ ] Напоминание сохранено в БД

#### 2. Просмотр платежей
```bash
/payments
```
- [ ] Напоминания отображаются
- [ ] Сумма указана верно
- [ ] Дней до срока считается правильно

#### 3. Удаление
```bash
# Админ:
/payment_del 1
```
- [ ] Напоминание удалено (is_active=False)

#### 4. Авто-напоминание
```bash
# Установить в БД last_reminder_sent на вчера
# Или подождать 5 или 9 число
```
- [ ] Напоминание приходит в 09:00
- [ ] Ссылки на оплату отображаются

---

## 📁 Изменённые файлы

| Файл | Изменения |
|------|-----------|
| `database/models.py` | Модель PaymentReminder |
| `database/migrate_add_payment_reminders.py` | Миграция БД |
| `handlers/payments.py` | Хендлеры платежей |
| `keyboards/inline.py` | Клавиатуры для платежей |
| `services/scheduler.py` | Авто-напоминания |
| `data/payment_links.json` | Ссылки на оплату |
| `handlers/__init__.py` | Импорт payments_router |
| `main.py` | Регистрация payments_router |

---

## 🚀 Как использовать

### Для админа:

1. **Добавить напоминание:**
   ```
   /payment_add
   ```
   Далее следуй инструкциям бота.

2. **Посмотреть все платежи:**
   ```
   /payments
   ```

3. **Удалить напоминание:**
   ```
   /payment_del 1
   ```

### Для жильца:

1. **Посмотреть напоминания:**
   ```
   /payments
   ```

2. **Получить напоминание:**
   - Автоматически 5-го и 9-го числа в 09:00

---

## 💡 Советы

### Когда настраивать:

- **Сумма:** Указывайте среднюю сумму за месяц
- **Дата:** Дата до которой нужно оплатить
- **Описание:** Что входит в платёж (например "ХВС, ГВС, водоотведение")

### Ссылки на оплату:

Отредактируйте `data/payment_links.json`:
```json
{
  "payment_links": [
    {
      "name": "Ваш банк",
      "url": "https://ссылка-на-оплату",
      "description": "Описание"
    }
  ]
}
```

### Дни напоминаний:

По умолчанию: **5 и 9 число**

Измените в `data/payment_links.json`:
```json
{
  "default_reminder_days": [3, 7]  // 3 и 7 число
}
```

---

## 🔧 Отладка

### Посмотреть напоминания в БД:
```bash
cd /home/matrixhasyou/domovoy_bot
source venv/bin/activate
sqlite3 database/domovoy.db

SELECT reminder_id, title, amount, due_date, is_active
FROM payment_reminders
ORDER BY due_date;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i "платеж\|payment"
```

### Тест напоминания:
```bash
# В БД установить текущую дату на 5 число
# Или вызвать функцию вручную через Python
```

---

## ✅ Преимущества

| Было | Стало |
|------|-------|
| Забывают про оплату | **Напоминания 5 и 9 числа** |
| Нет ссылок на оплату | **Ссылки в сообщении** |
| Ручное напоминание | **Авто-рассылка** |
| Не видно список | **/payments — все платежи** |

---

**Напоминания о платежах готовы! 💳**

*Следующий шаг: тестирование на тестовой группе и фиксация версии v1.6*