domovoy_bot/РАСПИСАНИЕ_ОТКЛЮЧЕНИЙ.md

# 📅 Расписание отключений — v1.4

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

---

## 📋 Описание

Система управления расписанием плановых отключений (вода, свет, отопление, газ, лифт). Админ создаёт события, бот напоминает за 1 час до начала, жильцы всегда в курсе отключений.

---

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

- ✅ Создание событий с типом, названием, временем
- ✅ 6 типов отключений (вода, свет, отопление, газ, лифт, общее)
- ✅ Inline-меню для выбора типа
- ✅ Пошаговое создание (тип → название → время → описание)
- ✅ Просмотр расписания командой `/график`
- ✅ Напоминание за 1 час до начала (авто)
- ✅ Удаление событий из расписания
- ✅ Emoji для каждого типа

---

## 📱 Команды

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

| Команда | Описание | Пример |
|---------|----------|--------|
| `/schedule_add` | Добавить событие в расписание | `/schedule_add` |
| `/schedule_del <ID>` | Удалить событие по ID | `/schedule_del 5` |

### Для всех:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/график` | Показать расписание отключений | `/график` |
| `/schedule` | Альтернатива `/график` | `/schedule` |

---

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

### Сценарий 1: Создание события (пошагово)

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

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

Выберите тип отключения:

1️⃣ 💧 Вода
2️⃣ ⚡ Электричество
3️⃣ 🔥 Отопление
4️⃣ 🔶 Газ
5️⃣ 🛗 Лифт
6️⃣ 📋 Общее

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

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

**4. Бот просит название:**
```
✅ Тип: 💧 Вода

Теперь отправьте название события:
Например: "Плановое отключение воды"
```

**5. Админ отправляет:**
```
Плановое отключение воды
```

**6. Бот просит время начала:**
```
✅ Название: Плановое отключение воды

Теперь отправьте дату и время НАЧАЛА в формате:
ДД.ММ.ГГГГ ЧЧ:ММ

Например: 27.02.2026 10:00
```

**7. Админ отправляет:**
```
27.02.2026 10:00
```

**8. Бот просит время окончания:**
```
✅ Начало: 27.02.2026 10:00

Теперь отправьте дату и время ОКОНЧАНИЯ:
ДД.ММ.ГГГГ ЧЧ:ММ
```

**9. Админ отправляет:**
```
27.02.2026 14:00
```

**10. Бот просит описание:**
```
✅ Окончание: 27.02.2026 14:00

Отправьте описание (необязательно) или нажмите "Пропустить":
[⏭️ Пропустить]
```

**11. Админ отправляет описание или пропускает:**
```
Будут отключены стояки с 1 по 10 этаж
```

**12. Бот подтверждает создание:**
```
✅ Событие добавлено в расписание!

💧 Вода — Плановое отключение воды

📅 Начало: 27.02.2026 10:00
📅 Окончание: 27.02.2026 14:00
⏱️ Длительность: 4.0 ч.
🔖 ID: 1

Для просмотра: /график
```

---

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

**Жилец:**
```
/график
```

**Бот:**
```
📅 Расписание отключений

1. 💧 Плановое отключение воды
   └─ Тип: Вода
   └─ Начало: 27.02.2026 10:00
   └─ Окончание: 27.02.2026 14:00
   └─ Длительность: 4.0 ч.
   └─ Описание: Будут отключены стояки с 1 по 10 этаж

2. ⚡ Ремонт трансформатора
   └─ Тип: Электричество
   └─ Начало: 28.02.2026 09:00
   └─ Окончание: 28.02.2026 17:00
   └─ Длительность: 8.0 ч.
```

---

### Сценарий 3: Напоминание за 1 час

**За 1 час до события (автоматически):**

**Бот пишет в чат:**
```
⏰ Напоминание: отключение через 1 час!

💧 Плановое отключение воды

📅 Начало: 27.02.2026 10:00
📅 Окончание: 27.02.2026 14:00
⏱️ Длительность: 4.0 ч.

Не забудьте сделать запасы!
```

---

### Сценарий 4: Удаление события

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

**Бот:**
```
✅ Событие "Плановое отключение воды" удалено из расписания
```

---

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

### Таблица `schedules`:
```sql
CREATE TABLE schedules (
    schedule_id INTEGER PRIMARY KEY AUTOINCREMENT,
    schedule_type TEXT NOT NULL,        -- water, electricity, heating...
    title TEXT NOT NULL,
    description TEXT,
    start_time TIMESTAMP NOT NULL,
    end_time TIMESTAMP NOT NULL,
    created_by BIGINT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    reminder_sent BOOLEAN DEFAULT 0,    -- Отправлено ли напоминание
    is_active BOOLEAN DEFAULT 1,
    FOREIGN KEY (created_by) REFERENCES users(user_id)
)
```

### Индексы:
- `ix_schedules_type` — по типу
- `ix_schedules_time` — по времени
- `ix_schedules_active` — по статусу

---

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

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

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

#### 2. Просмотр расписания
```bash
/график
```
- [ ] События отображаются
- [ ] Emoji правильные
- [ ] Длительность считается верно

#### 3. Напоминание
```bash
# Создать событие которое начнётся через 1-1.5 часа
# Подождать до срабатывания планировщика
```
- [ ] Напоминание пришло за 1 час
- [ ] `reminder_sent` установлен в True

#### 4. Удаление
```bash
# Админ:
/schedule_del <ID>
```
- [ ] Событие удалено (is_active=False)

---

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

| Файл | Изменения |
|------|-----------|
| `database/models.py` | Модель Schedule |
| `database/migrate_add_schedules.py` | Миграция БД |
| `handlers/schedule.py` | Хендлеры расписания |
| `keyboards/inline.py` | Клавиатуры для расписания |
| `services/scheduler.py` | Напоминания |
| `handlers/__init__.py` | Импорт schedule_router |
| `main.py` | Регистрация schedule_router |

---

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

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

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

2. **Посмотреть расписание:**
   ```
   /график
   ```

3. **Удалить событие:**
   ```
   /schedule_del 1
   ```

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

1. **Посмотреть расписание:**
   ```
   /график
   ```

2. **Получить напоминание:**
   - Автоматически за 1 час до начала

---

## 💡 Советы

### Типы отключений:

| Тип | Когда использовать |
|-----|-------------------|
| 💧 Вода | Отключение ХВС/ГВС |
| ⚡ Электричество | Ремонт сетей, трансформатора |
| 🔥 Отопление | Сезонное отключение, ремонт |
| 🔶 Газ | Профилактические работы |
| 🛗 Лифт | Ремонт лифта |
| 📋 Общее | Другие работы |

### Напоминания:

- Бот проверяет напоминания **каждый час**
- Напоминает **за 1 час** до начала
- Если событие создано меньше чем за 1 час — напоминание не отправляется

---

## 🔧 Отладка

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

SELECT schedule_id, schedule_type, title, start_time, end_time, reminder_sent
FROM schedules
WHERE is_active = 1
ORDER BY start_time;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i "напомин\|schedule"
```

---

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

| Было | Стало |
|------|-------|
| Объявления в чате | **Расписание в боте** |
| Забывают про отключения | **Напоминание за 1 час** |
| Нет истории | **Сохранение в БД** |
| Ручное напоминание | **Авто-напоминания** |

---

**Расписание отключений готово! 📅**

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