---

# VK бот "Бюро находок"

Python-бот для сообщества VK, который принимает объявления о найденных вещах, отправляет их на модерацию, публикует на стене сообщества и помогает безопасно связать нашедшего с владельцем через бота.

## Что уже реализовано

- пользовательский сценарий: `/start` -> создание объявления -> превью -> отправка на модерацию
- пошаговый сбор данных: описание, место, дата/время, фото
- модерация в личных сообщениях сообщества:
  - `✅ Принять`
  - `⚠️ Изменить`
  - `❌ Отклонить`
- редактирование модератором текста, места, даты и фотографии
- публикация объявления на стене сообщества VK
- уведомления автору о публикации, изменении и отклонении
- список своих объявлений
- закрытие объявления автором
- базовый запрос на связь с автором через бота без мгновенного раскрытия контактов
- запуск в Docker
- хранение данных в SQLite

## Архитектура

- `app/__main__.py` - точка входа
- `app/bot.py` - основной цикл бота и обработчики сценариев
- `app/db.py` - инициализация SQLite
- `app/repository.py` - доступ к данным
- `app/keyboards.py` - VK-клавиатуры
- `app/config.py` - переменные окружения

## Ограничения и адаптация под VK

В вашем описании исходный сценарий был рассчитан на Telegram. Для VK пришлось адаптировать несколько вещей:

- публикация происходит на стене сообщества VK, а не в Telegram-канале
- кнопка "Связаться с нашедшим" под постом стены технически не такая гибкая, как в Telegram, поэтому используется безопасный сценарий:
  - человек пишет боту `связаться 12`
  - бот отправляет запрос автору объявления
  - только после согласия автора бот раскрывает профили друг другу
- роль администратора сейчас управляется через текстовые команды в чате с ботом:
  - `добавить модератора 123456`
  - `удалить модератора 123456`
  - `статистика`

## Настройка VK

Нужно создать сообщество и включить:

1. Сообщения сообщества
2. Callback API / Long Poll API для бота
3. Доступ к сообщениям и стене

Токен сообщества должен иметь права минимум на:

- `messages`
- `wall`
- `photos`
- `docs` при необходимости

## Переменные окружения

Скопируйте `.env.example` в `.env` и заполните:

```env
VK_GROUP_TOKEN=your_group_token
VK_GROUP_ID=123456789
VK_COMMUNITY_SCREEN_NAME=club123456789
DATABASE_PATH=/app/data/lost_and_found.sqlite3
MODERATOR_IDS=12345678,87654321
ADMIN_IDS=12345678
LOG_LEVEL=INFO
```

## Запуск в Docker

```bash
docker compose up --build -d
```

Логи:

```bash
docker compose logs -f
```

Остановка:

```bash
docker compose down
```

## Локальный запуск без Docker

```bash
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python -m app
```

Для Windows PowerShell:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m app
```

## Как работает сценарий

### Пользователь

1. Нажимает `➕ Подать объявление`
2. Вводит описание
3. Отправляет место текстом или геолокацией
4. Указывает дату и время
5. Отправляет фото
6. Получает превью и нажимает `✅ Опубликовать`

### Модератор

1. Получает карточку объявления
2. Выбирает одно из действий:
   - принять
   - изменить
   - отклонить
3. При редактировании бот публикует уже исправленную версию

### Потерявший

1. Видит пост на стене
2. Пишет боту `связаться ID`
3. Ждет согласия автора объявления на обмен контактами

## Что имеет смысл улучшить следующим шагом

- полноценная валидация даты и времени
- отдельная таблица аудита действий модераторов
- автозакрытие старых объявлений
- веб-панель администратора
- повторная публикация при редактировании уже существующего поста вместо создания нового
- более строгая защита персональных данных и журнал согласий