ba4676b0af
✅ Регистрация и верификация жильцов ✅ Рейтинг активности (уровни) ✅ Детект шпионов (Score 0-100) ✅ Анти-мат система (3 предупреждения → бан) ✅ Админ-панель с рассылкой ✅ Учёт квартир (несколько жильцов) ✅ Телефоны экстренных служб и мастеров ✅ Еженедельный экспорт JSON ✅ Прокси (socks5) для обхода РКН Бекап: backups/versions/v1.0_mvp_2026-02-26/ Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
310 lines
14 KiB
Markdown
310 lines
14 KiB
Markdown
# Техническое задание: Домовой бот для чата жильцов
|
||
## Дом на ~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
|
||
**Статус:** На согласовании
|