domovoy_bot/ДОСКА_ОБЪЯВЛЕНИЙ.md

# 📢 Доска объявлений (соседская) — v1.5

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

---

## 📋 Описание

Соседская доска объявлений — жильцы могут размещать объявления о продаже, покупке, отдаче вещей, поиске потерянного, услугах. Объявления публикуются в чате, хранятся 7 дней, затем автоматически удаляются.

---

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

- ✅ 6 категорий объявлений (продам, куплю, отдам, потеряно, нашлось, услуга)
- ✅ Пошаговое создание (категория → название → описание → цена → телефон)
- ✅ Публикация в общем чате
- ✅ Авто-удаление через 7 дней
- ✅ Просмотр всех активных объявлений
- ✅ Удаление своих объявлений
- ✅ Только для верифицированных жильцов
- ✅ Модерация для админов

---

## 📱 Команды

### Для всех верифицированных:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/ad` или `/объявление` | Создать объявление | `/ad` |
| `/ads` или `/доска` | Показать все объявления | `/ads` |
| `/ad_del <ID>` | Удалить своё объявление | `/ad_del 5` |

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

| Команда | Описание | Пример |
|---------|----------|--------|
| `/ads_moderate` | Объявления на модерации | `/ads_moderate` |
| `/ad_approve <ID>` | Подтвердить объявление | `/ad_approve 5` |

---

## 🎯 Категории объявлений

| № | Категория | Emoji | Когда использовать |
|---|-----------|-------|-------------------|
| 1 | 💰 Продам | 💰 | Продажа вещей, мебели, техники |
| 2 | 🛒 Куплю | 🛒 | Поиск вещей для покупки |
| 3 | 🎁 Отдам | 🎁 | Отдам даром, бесплатно |
| 4 | 😿 Потеряно | 😿 | Потеряны вещи, животные |
| 5 | 😺 Нашлось | 😺 | Нашлись вещи, животные |
| 6 | 🔧 Услуга | 🔧 | Предложение услуг |

---

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

### Сценарий 1: Создание объявления (продам)

**1. Жилец пишет:**
```
/ad
```

**2. Бот показывает меню:**
```
📢 Создание объявления

Выберите категорию:

1️⃣ 💰 Продам
2️⃣ 🛒 Куплю
3️⃣ 🎁 Отдам
4️⃣ 😿 Потеряно
5️⃣ 😺 Нашлось
6️⃣ 🔧 Услуга

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

**3. Жилец нажимает** `💰 Продам` **или отправляет** `1`

**4. Бот просит название:**
```
✅ Категория: 💰 Продам

Теперь отправьте название объявления:
Например: "Продам диван"
```

**5. Жилец отправляет:**
```
Продам диван угловой
```

**6. Бот просит описание:**
```
✅ Название: Продам диван угловой

Теперь отправьте описание:
Например: "Диван угловой, состояние хорошее, самовывоз"
```

**7. Жилец отправляет:**
```
Диван угловой, 2х спальный, состояние хорошее.
Есть небольшие следы использования.
Самовывоз с 5 этажа.
```

**8. Бот просит цену:**
```
✅ Описание принято

Укажите цену (в рублях) или отправьте "0" если бесплатно:
Например: 5000
```

**9. Жилец отправляет:**
```
5000
```

**10. Бот просит телефон:**
```
✅ Цена: 5000

Укажите контактный телефон или отправьте "пропустить":
Например: +7 (999) 123-45-67
```

**11. Жилец отправляет:**
```
+7 (999) 123-45-67
```

**12. Бот публикует объявление в чат:**
```
💰 Продам: Продам диван угловой

📝 Диван угловой, 2х спальный, состояние хорошее.
Есть небольшие следы использования.
Самовывоз с 5 этажа.

💰 Цена: 5000 ₽
📞 Телефон: +7 (999) 123-45-67

⏳ Действует до: 05.03.2026
🔖 ID: 1
```

**13. Жилец получает подтверждение:**
```
✅ Объявление опубликовано!

ID: 1
Действует до: 05.03.2026

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

---

### Сценарий 2: Просмотр всех объявлений

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

**Бот:**
```
📢 Доска объявлений

1. 💰 Продам: Продам диван угловой
   └─ Цена: 5000 ₽
   └─ Действует до: 05.03.2026
   └─ ID: 1

2. 🎁 Отдам: Отдам котёнка
   └─ Цена: Бесплатно
   └─ Действует до: 04.03.2026
   └─ ID: 2

3. 🔧 Услуга: Ремонт сантехники
   └─ Цена: 1000 ₽
   └─ Действует до: 03.03.2026
   └─ ID: 3

💡 Для создания: /ad
```

---

### Сценарий 3: Удаление своего объявления

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

**Бот:**
```
✅ Объявление "Продам диван угловой" удалено
```

**Объявление удаляется из чата и базы.**

---

### Сценарий 4: Объявление с модерацией

**Если включена модерация:**

1. Объявление создаётся но не публикуется
2. Админ получает уведомление
3. Админ: `/ads_moderate` — показывает неподтверждённые
4. Админ: `/ad_approve 1` — подтверждает
5. Объявление публикуется в чат

---

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

### Таблица `ads`:
```sql
CREATE TABLE ads (
    ad_id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id BIGINT NOT NULL,
    category TEXT NOT NULL,         -- sell, buy, give, lost, found, service
    title TEXT NOT NULL,
    description TEXT,
    price INTEGER,                  -- Цена в рублях
    phone TEXT,                     -- Контактный телефон
    message_id BIGINT,              -- ID сообщения в чате
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    expires_at TIMESTAMP,           -- Дата истечения (через 7 дней)
    is_active BOOLEAN DEFAULT 1,
    is_moderated BOOLEAN DEFAULT 0, -- Проверено админом
    FOREIGN KEY (user_id) REFERENCES users(user_id)
)
```

### Индексы:
- `ix_ads_category` — по категории
- `ix_ads_active` — по статусу
- `ix_ads_created_at` — по дате создания

---

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

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

#### 1. Создание объявления
```bash
# С верифицированного аккаунта:
/ad
# Выбрать категорию, название, описание, цену, телефон
```
- [ ] Меню категорий отображается
- [ ] Пошаговый ввод работает
- [ ] Объявление опубликовано в чат
- [ ] Сохранено в БД

#### 2. Проверка верификации
```bash
# С неверифицированного аккаунта:
/ad
```
- [ ] Бот отвечает "Только для верифицированных"

#### 3. Просмотр объявлений
```bash
/ads
```
- [ ] Объявления отображаются
- [ ] Emoji правильные
- [ ] Срок действия указан

#### 4. Удаление объявления
```bash
# Админ или автор:
/ad_del 1
```
- [ ] Объявление удалено
- [ ] Сообщение в чате удалено

#### 5. Авто-удаление
```bash
# Подождать 7 дней (или изменить expires_at в БД)
```
- [ ] Объявление деактивировано автоматически

---

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

| Файл | Изменения |
|------|-----------|
| `database/models.py` | Модель Ad |
| `database/migrate_add_ads.py` | Миграция БД |
| `handlers/ads.py` | Хендлеры объявлений |
| `keyboards/inline.py` | Клавиатуры для объявлений |
| `services/scheduler.py` | Авто-удаление |
| `handlers/__init__.py` | Импорт ads_router |
| `main.py` | Регистрация ads_router |

---

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

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

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

2. **Посмотреть все объявления:**
   ```
   /ads
   ```

3. **Удалить своё объявление:**
   ```
   /ad_del 1
   ```

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

1. **Проверить объявления на модерации:**
   ```
   /ads_moderate
   ```

2. **Подтвердить объявление:**
   ```
   /ad_approve 1
   ```

3. **Удалить любое объявление:**
   ```
   /ad_del 1
   ```

---

## 💡 Советы

### Правила размещения:

✅ **Разрешено:**
- Продажа личных вещей
- Отдача даром
- Поиск потерянного
- Предложение услуг соседям

❌ **Запрещено:**
- Реклама магазинов
- Спам, мошенничество
- Недвижимость (не относится к дому)
- Услуги сторонних компаний

### Срок действия:

- **7 дней** — стандартный срок
- После истечения — авто-удаление
- Можно создать новое объявление

### Цена:

- Указывайте реальную цену
- "0" или "бесплатно" — для бесплатных вещей
- "Договорная" — в описании

---

## 🔧 Отладка

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

SELECT ad_id, category, title, price, created_at, expires_at, is_active
FROM ads
ORDER BY created_at DESC LIMIT 10;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i "объявлен\|ads"
```

### Авто-удаление (тест):
```bash
# В БД установить expires_at на вчера:
UPDATE ads SET expires_at=datetime('now', '-1 day') WHERE ad_id=1;

# Запустить очистку:
# (на следующее утро в 04:00 или вручную через scheduler)
```

---

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

| Было | Стало |
|------|-------|
| Объявления в словах | **Структурированные объявления** |
| Забывают про объявления | **Авто-удаление через 7 дней** |
| Нет категорий | **6 категорий с emoji** |
| Не видно телефон | **Телефон в объявлении** |
| Нет модерации | **Модерация для админов** |

---

**Доска объявлений готова! 📢**

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