domovoy_bot/КАЛЕНДАРЬ_СОБЫТИЙ.md

# 📅 Календарь событий дома — v1.14

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

---

## 📋 Описание

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

---

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

- ✅ Создание событий (собрания, субботники, праздники, спорт, детское)
- ✅ Запись на участие (/join)
- ✅ Отписка от события (/leave)
- ✅ Просмотр предстоящих событий
- ✅ Мои события
- ✅ Список участников
- ✅ Отмена события админом
- ✅ Авто-напоминания за 24 часа

---

## 📱 Команды

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

| Команда | Описание | Пример |
|---------|----------|--------|
| `/event_add` | Создать событие | `/event_add` |
| `/participants <ID>` | Участники события | `/participants 5` |
| `/event_cancel <ID>` | Отменить событие | `/event_cancel 5` |

### Для всех:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/events` | Предстоящие события | `/events` |
| `/join <ID>` | Записаться на событие | `/join 5` |
| `/leave <ID>` | Отписаться от события | `/leave 5` |
| `/my_events` | Мои события | `/my_events` |

---

## 🎯 Типы событий

| Тип | Emoji | Описание |
|-----|-------|----------|
| **meeting** | 📋 | Собрание, встреча |
| **subbotnik** | 🧹 | Субботник |
| **holiday** | 🎉 | Праздник |
| **sport** | ⚽ | Спортивное событие |
| **kids** | 🎈 | Детское событие |
| **general** | 📅 | Общее событие |

---

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

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

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

**2. Бот просит название:**
```
📅 Создание события

Отправьте название события:
Например: "Общее собрание жильцов"
```

**3. Админ отправляет:**
```
Общее собрание жильцов
```

**4-7. Пошаговый ввод:**
- Дата: `01.03.2026 19:00`
- Место: `Холл 1 этажа`
- Описание: `Обсуждение вопросов капремонта`

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

📅 Общее собрание жильцов
🗓️ 01.03.2026 19:00
📍 Холл 1 этажа
🔖 ID: 1

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

---

### Сценарий 2: Запись на событие

**Жилец:**
```
/join 1
```

**Бот:**
```
✅ Вы записались на событие!

📅 Общее собрание жильцов
🗓️ 01.03.2026 19:00
👥 Участников: 5
```

---

### Сценарий 3: Просмотр событий

**Жилец:**
```
/events
```

**Бот:**
```
📅 Предстоящие события

📋 Общее собрание жильцов
   └─ 01.03.2026 19:00
   └─ 📍 Холл 1 этажа
   └─ 🔖 ID: 1

🧹 Субботник во дворе
   └─ 15.03.2026 10:00
   └─ 📍 Детская площадка
   └─ 🔖 ID: 2

💡 Для участия: /join <ID>
```

---

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

**Жилец:**
```
/my_events
```

**Бот:**
```
📅 Ваши события

📋 Общее собрание жильцов
   └─ 01.03.2026 19:00
   └─ 📍 Холл 1 этажа

🧹 Субботник во дворе
   └─ 15.03.2026 10:00
   └─ 📍 Детская площадка
```

---

### Сценарий 5: Участники события (админ)

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

**Бот:**
```
👥 Участники: Общее собрание жильцов

Всего: 5

• Иван Иванов (кв. 45)
• Петр Петров (кв. 88)
• Анна Сидорова (кв. 12)
• Мария Козлова (кв. 100)
• Василий Смирнов (кв. 50)
```

---

### Сценарий 6: Напоминание о событии

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

**Бот пишет в чат:**
```
⏰ Напоминание о событии!

📅 Общее собрание жильцов
🗓️ 01.03.2026 19:00
📍 Холл 1 этажа

Не забудьте принять участие!
```

---

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

### Таблица `events`:
```sql
CREATE TABLE events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    description TEXT,
    event_type TEXT DEFAULT 'general',
    event_date TIMESTAMP NOT NULL,
    location TEXT,
    created_by BIGINT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT 1,
    reminder_sent BOOLEAN DEFAULT 0
)
```

### Таблица `event_participants`:
```sql
CREATE TABLE event_participants (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    event_id INTEGER NOT NULL,
    user_id BIGINT NOT NULL,
    joined_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (event_id) REFERENCES events(id),
    FOREIGN KEY (user_id) REFERENCES users(user_id)
)
```

---

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

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

#### 1. Создание события
```bash
# Админ:
/event_add
# Ввести название, дату, место, описание
```
- [ ] Событие создано
- [ ] ID присвоен
- [ ] В БД сохранено

#### 2. Запись на событие
```bash
/join 1
```
- [ ] Запись успешна
- [ ] Участник добавлен

#### 3. Просмотр событий
```bash
/events
```
- [ ] События отображаются
- [ ] Дата и место указаны

#### 4. Мои события
```bash
/my_events
```
- [ ] Записанные события показаны

#### 5. Участники
```bash
/participants 1
```
- [ ] Список участников показан

#### 6. Напоминание
```bash
# Подождать до 24 часов до события
```
- [ ] Напоминание пришло в чат

---

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

| Файл | Изменения |
|------|-----------|
| `database/models.py` | Модели Event, EventParticipant |
| `database/migrate_add_events.py` | Миграция БД |
| `services/events.py` | Сервис событий |
| `handlers/events.py` | Хендлеры событий |
| `services/scheduler.py` | Напоминания о событиях |
| `handlers/__init__.py` | Импорт events_router |
| `main.py` | Регистрация events_router |

---

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

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

1. **Создать событие:**
   ```
   /event_add
   ```

2. **Посмотреть участников:**
   ```
   /participants 1
   ```

3. **Отменить событие:**
   ```
   /event_cancel 1
   ```

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

1. **Посмотреть события:**
   ```
   /events
   ```

2. **Записаться:**
   ```
   /join 1
   ```

3. **Мои события:**
   ```
   /my_events
   ```

4. **Отписаться:**
   ```
   /leave 1
   ```

---

## 💡 Советы

### Типы событий:

- **meeting** — собрания жильцов
- **subbotnik** — субботники, уборки
- **holiday** — праздники (Новый год, 8 марта)
- **sport** — футбол, волейбол во дворе
- **kids** — детские мероприятия
- **general** — остальное

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

- Отправляются **за 24 часа** до события
- **Один раз** на событие
- В **общий чат**

### Отмена события:

- Админ может отменить событие
- Событие помечается `is_active=False`
- Участники не удаляются

---

## 🔧 Отладка

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

SELECT id, title, event_date, location, is_active
FROM events
ORDER BY event_date;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i "событ\|event"
```

---

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

| Было | Стало |
|------|-------|
| События в чате забываются | **Календарь событий** |
| Не видно кто придёт | **Запись на участие** |
| Забывают про события | **Авто-напоминания** |
| Нет списка участников | **/participants** |

---

**Календарь событий готов! 📅**

**v1.14 — ФИНАЛЬНАЯ ВЕРСИЯ ПЕРЕД v2.0!** 🎉