# Техническое задание: Домовой бот для чата жильцов
## Дом на ~1000 квартир (~2000 жителей)

---

## 📋 1. ОБЩИЕ ПОЛОЖЕНИЯ

### 1.1 Назначение
Бот для Telegram-чата многоквартирного дома, выполняющий функции:
- Модерация и безопасность чата
- Информационная поддержка жильцов
- Юридическая помощь через AI (NotebookLM)
- Аналитика активности и выявление «шпионов»
- Сервисы взаимопомощи соседей

### 1.2 Целевая аудитория
- Собственники квартир (1000+)
- Арендаторы
- Члены семей (итого ~2000 человек)
- Возраст: от 18 до 80+ лет

---

## 🎯 2. ФУНКЦИОНАЛЬНЫЕ ТРЕБОВАНИЯ

### 2.1 Верификация и безопасность

| Функция | Описание | Приоритет |
|---------|----------|-----------|
| **Регистрация жильца** | Привязка Telegram ID к номеру квартиры + подтверждение (фото квитанции/код с доски) | 🔴 Высокий |
| **Премодерация входа** | Новый участник не видит чат, пока не пройдёт верификацию | 🔴 Высокий |
| **Детект мультиаккаунтов** | Выявление нескольких аккаунтов от одного человека (по поведению, времени активности) | 🟡 Средний |
| **Анти-спам** | Ограничение частоты сообщений, фильтрация ссылок | 🔴 Высокий |
| **Чёрный список** | Бан пользователей, автоматический бан при повторной регистрации | 🟡 Средний |
| **Тег «Не верифицирован»** | Визуальная маркировка в чате для непроверенных | 🟢 Низкий |

### 2.2 Информационные команды (меню)

**Формат:** Inline-кнопки + текстовые команды (кириллица!)

| Команда | Описание | Контент |
|---------|----------|---------|
| `/телефон` или кнопка «📞 Экстренные службы» | Телефоны служб | Текст + картинка |
| `/юрист` или кнопка «⚖️ Юридическая помощь» | AI-консультация через NotebookLM | Ссылка на ответ AI |
| `/сантехник` | Контакты проверенных мастеров | Список с рейтингом |
| `/участковый` | Контакты полиции | ФИО, телефон, приёмные часы |
| `/график` | Отключения воды, света, уборка | Календарь/таблица |
| `/объявление` | Последние новости дома | Последние 5 объявлений |
| `/продам` | Соседский маркетплейс | Ссылка на канал-витрину |
| `/помощь` | Список всех команд | Меню помощи |

### 2.3 AI-Юрист (NotebookLM интеграция)

**База знаний:**
- Конституция РФ
- Жилищный кодекс РФ
- Гражданский кодекс РФ (части 1, 2)
- КоАП РФ, УК РФ (релевантные статьи)
- **Договор управления вашего дома**
- Протоколы ОСС (общих собраний собственников)
- СанПиН, ГОСТы по ЖКХ
- Региональные нормативы (ваш субъект РФ)

**Сценарий работы:**
```
1. Жилец → /юрист → вводит вопрос
2. Бот → отправляет в NotebookLM API
3. NotebookLM → генерирует ответ со ссылками на законы
4. Бот → формирует ответ + шаблон документа (если нужно)
5. Жилец → получает в личку (или в чат, по настройке)
```

**Пример ответа:**
> «Согласно п. 4.2 Договора управления №XX от ДД.ММ.ГГГГ, УК обязана устранить протечку в течение 30 минут. 
> Статья 161 ЖК РФ подтверждает...
> 📎 [Скачать шаблон претензии в УК]»

### 2.4 Аналитика и экспорт

| Функция | Периодичность | Формат |
|---------|---------------|--------|
| **Экспорт чата** | Еженедельно (воскресенье 03:00) | JSON с ID пользователей |
| **Облако тегов тем** | Еженедельно | Текст: «лифты: 45%, парковка: 23%...» |
| **Рейтинг активности** | Ежемесячно | Топ-10 полезных / Топ-10 токсичных |
| **Детект «шпионов»** | Постоянно | Уведомление админу при аномалиях |
| **Статистика команд** | Ежемесячно | Какие команды популярны |

**Структура JSON экспорта:**
```json
{
  "export_date": "2026-02-23T03:00:00+03:00",
  "chat_id": "-1001234567890",
  "messages": [
    {
      "message_id": 12345,
      "user_id": 987654321,
      "username": "@nickname",
      "first_name": "Иван",
      "last_name": "Иванов",
      "apartment": "45",
      "timestamp": "2026-02-22T14:30:00+03:00",
      "text": "У кого свет моргает?",
      "reply_to": null,
      "forward_from": null
    }
  ],
  "users": [
    {
      "user_id": 987654321,
      "username": "@nickname",
      "first_name": "Иван",
      "last_name": "Иванов",
      "apartment": "45",
      "verified": true,
      "join_date": "2025-06-15",
      "message_count": 342
    }
  ]
}
```

### 2.5 Соседские сервисы

| Сервис | Описание |
|--------|----------|
| **Маркетплейс** | Канал-витрина: `/продам диван 5000р` → пост в @dom_market |
| **Бронирование** | Колясочная, барбекю, гостевая парковка (календарь занятости) |
| **Взаимопомощь** | «Отдам котёнка», «Посажу ребёнка на час», «Нужна дрель» |
| **Рейтинг мастеров** | Сантехники/электрики с оценками от соседей |

### 2.6 Опросы и голосования

| Тип | Описание |
|-----|----------|
| **Быстрые опросы** | «За какой цвет покрасить подъезд?» (неофициально) |
| **Подготовка к ОСС** | Сбор мнений перед официальным голосованием |
| **Обратная связь** | «Оцените работу УК за месяц» |

---

## 🛠 3. ТЕХНИЧЕСКИЕ ТРЕБОВАНИЯ

### 3.1 Стек технологий

| Компонент | Рекомендуемое |
|-----------|---------------|
| **Язык** | Python 3.11+ |
| **Библиотека бота** | aiogram 3.x (асинхронная) |
| **База данных** | PostgreSQL / SQLite (для начала) |
| **Хранение файлов** | Локально / S3 / Google Drive |
| **NotebookLM API** | Google API (через сервисный аккаунт) |
| **Хостинг** | VPS (Timeweb, Selectel, Reg.ru) |
| **CI/CD** | GitHub Actions / GitLab CI |

### 3.2 Безопасность данных (ФЗ-152)

- [ ] Персональные данные (номера квартир, ID) хранятся только на сервере
- [ ] Доступ к базе — только у администратора (ты)
- [ ] В чат не выгружать таблицы с персональными данными
- [ ] Логирование доступа к базе данных
- [ ] Политика конфиденциальности (публичная оферта для жильцов)

### 3.3 Надёжность

- [ ] Автостарт при падении (systemd / Docker restart policy)
- [ ] Резервное копирование БД (ежедневно)
- [ ] Логирование ошибок (отправка критичных ошибок админу в личку)
- [ ] Rate limiting для API (чтобы Telegram не забанил)

---

## 📊 4. АРХИТЕКТУРА БАЗЫ ДАННЫХ

### Таблица `users`
```sql
CREATE TABLE users (
    user_id BIGINT PRIMARY KEY,
    username VARCHAR(255),
    first_name VARCHAR(255),
    last_name VARCHAR(255),
    apartment VARCHAR(10),
    phone VARCHAR(20),
    verified BOOLEAN DEFAULT FALSE,
    verification_date TIMESTAMP,
    join_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    message_count INTEGER DEFAULT 0,
    is_banned BOOLEAN DEFAULT FALSE,
    is_admin BOOLEAN DEFAULT FALSE,
    last_seen TIMESTAMP
);
```

### Таблица `messages`
```sql
CREATE TABLE messages (
    message_id BIGINT,
    user_id BIGINT REFERENCES users(user_id),
    chat_id BIGINT,
    text TEXT,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    reply_to_message_id BIGINT,
    PRIMARY KEY (message_id, chat_id)
);
```

### Таблица `requests` (юридические запросы)
```sql
CREATE TABLE requests (
    request_id SERIAL PRIMARY KEY,
    user_id BIGINT REFERENCES users(user_id),
    question TEXT,
    answer TEXT,
    notebooklm_response JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    status VARCHAR(50) DEFAULT 'pending'
);
```

### Таблица `services` (мастера, контакты)
```sql
CREATE TABLE services (
    service_id SERIAL PRIMARY KEY,
    name VARCHAR(255),
    category VARCHAR(100),
    phone VARCHAR(20),
    rating DECIMAL(3,2) DEFAULT 0,
    reviews_count INTEGER DEFAULT 0,
    verified_by_admin BOOLEAN DEFAULT FALSE
);
```

---

## 🚀 5. ДОРОЖНАЯ КАРТА (ROADMAP)

### Этап 1: MVP (2-3 недели)
- [ ] Базовый бот с командами `/старт`, `/помощь`, `/телефон`
- [ ] Регистрация пользователей (привязка к квартире)
- [ ] Экспорт чата в JSON (еженедельно)
- [ ] Админ-панель (просмотр базы жильцов)

### Этап 2: Безопасность (2 недели)
- [ ] Премодерация новых участников
- [ ] Детект мультиаккаунтов
- [ ] Анти-спам фильтры

### Этап 3: AI-Юрист (3-4 недели)
- [ ] Интеграция с NotebookLM API
- [ ] Загрузка нормативной базы
- [ ] Тестирование ответов на типовых вопросах

### Этап 4: Соседские сервисы (3 недели)
- [ ] Маркетплейс (канал-витрина)
- [ ] Бронирование ресурсов
- [ ] Рейтинг мастеров

### Этап 5: Аналитика (2 недели)
- [ ] Облако тегов тем
- [ ] Рейтинг активности
- [ ] Дашборд для админа (Grafana / веб-интерфейс)

---

## ❓ 6. ОТКРЫТЫЕ ВОПРОСЫ

1. **Модерация контента:** Блокировать ли мат/оскорбления автоматически? (AI-модерация / чёрный список слов)
2. **Анонимные жалобы:** Давать ли возможность жаловаться на соседей анонимно?
3. **Платные услуги:** Будет ли интеграция с платежом (квартплата, взносы)?
4. **Видеонаблюдение:** Интеграция с камерами подъезда/двора?
5. **Умный дом:** Датчики протечек, шума, качества воздуха (общедомовые)?

---

## 📎 7. ПРИЛОЖЕНИЯ

### 7.1 Список экстренных телефонов (шаблон)
```
🚑 Скорая: 103, 112
🔥 Пожарные: 101, 112
👮 Полиция: 102, 112
⛽ Газовая служба: 104
💧 Аварийная водоканал: +7 (XXX) XXX-XX-XX
🔌 Аварийная электросети: +7 (XXX) XXX-XX-XX
🏢 Диспетчер УК: +7 (XXX) XXX-XX-XX (круглосуточно)
👨‍⚖️ Участковый: Иванов И.И. +7 (XXX) XXX-XX-XX
```

### 7.2 Примеры юридических запросов для тестирования AI
- «Соседи сверху залили, что делать?»
- «УК не убирает подъезд, куда жаловаться?»
- «Можно ли курить на балконе?»
- «Как оспорить решение ОСС?»
- «Платить ли за капремонт, если дом новый?»

---

## 📝 8. КРИТЕРИИ ПРИЁМКИ

- [ ] Бот отвечает на все команды из раздела 2.2
- [ ] Экспорт JSON формируется корректно, содержит ID пользователей
- [ ] Верификация работает (неверифицированные помечаются)
- [ ] AI-юрист выдаёт ответы со ссылками на законы
- [ ] База данных хранит пользователей с привязкой к квартирам
- [ ] Бот работает стабильно 7 дней без падений

---

**Версия ТЗ:** 1.0  
**Дата:** 23.02.2026  
**Статус:** На согласовании