domovoy_bot/TECHNICAL_SPECIFICATION.md

Техническое задание: Домовой бот для чата жильцов

Дом на ~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 экспорта:

{
  "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

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

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 (юридические запросы)

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 (мастера, контакты)

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
Статус: На согласовании