MapMil/README.md

MapMil Platform (ЦП → ЦА → ПИ)

Единая платформа на базе MapMil (ЦА — аналитика) и SocialParser (ЦП — парсинг).

Архитектура

flowchart LR
  CA[ЦА Analytics Center]
  CP[ЦП Parsing Center]
  PI[ПИ External Consumers]

  CA -->|jobs via Redis| CP
  CP -->|POST /internal/ingest| CA
  CA -->|GET /api/v1/events| PI

Центр	Контейнеры	Назначение
ЦА	ca-db, ca-api, ca-frontend	PostgreSQL, ingest API, карта, distribution API
ЦП	cp-workers	Парсинг Telegram (код из SocialParser)
Общее	redis	Очередь заданий ЦА → ЦП

Структура monorepo

MapMil/
├── centers/
│   ├── analytics/
│   │   ├── api/          # CA backend (FastAPI + PostgreSQL)
│   │   └── frontend/     # CA admin UI (Vue + Leaflet)
│   └── parsing/
│       └── workers/      # CP workers (Telethon)
├── contracts/            # Shared schemas (ingest, jobs)
├── data/                 # telegram.session (symlink → SocialParser)
├── docker-compose.yml
└── .env                  # TELEGRAM_* из SocialParser

Быстрый старт

1. Скопируйте .env из SocialParser (или создайте из .env.example):

cp ../SocialParser/.env .env

2. Убедитесь, что сессия Telegram доступна:

ls -la data/telegram.session
# symlink → ../SocialParser/data/telegram.session

3. Запуск:

docker compose up --build

4. Откройте UI: http://localhost:8080

Admin UI

Веб-интерфейс ЦА доступен по тем же адресу. Навигация в шапке:

Раздел	Путь	Описание
Карта	/	Интерактивная карта с объектами, таймлайном и CRUD. Поддерживает ?eventId= для перехода к событию
Парсеры	/parsers	Создание заданий Telegram-парсинга, таблица статусов с автообновлением (5 с), повтор failed-заданий
События	/events	Фильтрация, пагинация, просмотр деталей, ссылка «На карте» для событий с координатами
Аналитика	/analytics	KPI-карточки, график динамики ingest за 30 дней, топ населённых пунктов и регионов
ПИ	/consumers	CRUD подписчиков distribution API, ротация ключей, тест среза через /api/v1/events

Сохранение Telegram-сессии

Важно: существующий файл сессии не удаляется и не пересоздаётся.

• Оригинал: SocialParser/data/telegram.session
• В репозитории MapMil: data/telegram.session — симлинк для локальной разработки
• В Docker cp-workers: каталог ../SocialParser/data монтируется как /data (read-write; Telethon обновляет SQLite-сессию)
• Путь в контейнере: /data/telegram.session
• Переменные из .env: TELEGRAM_API_ID, TELEGRAM_API_HASH, TELEGRAM_SESSION_PATH=/data/telegram.session

Симлинк не работает внутри Docker — compose монтирует каталог SocialParser/data целиком.

Файл сессии и .env добавлены в .gitignore и не коммитятся.

API

Карта (совместимость MapMil)

Метод	Путь	Описание
GET	/api/health	Health check
GET	/api/objects	Объекты на карте (включая события с координатами)
POST	/api/objects	Создать объект вручную

ЦА Admin

Метод	Путь	Описание
POST	/admin/jobs	Создать задание парсинга (ставится в Redis)
GET	/admin/jobs	Список заданий
POST	/admin/jobs/{id}/retry	Повторить failed-задание
GET	/admin/events	События с фильтрами ({ items, total })
GET	/admin/analytics/summary	KPI-сводка
GET	/admin/analytics/timeline?days=	Динамика ingest по дням
GET	/admin/analytics/top-localities?limit=	Топ населённых пунктов
GET	/admin/analytics/top-regions?limit=	Топ регионов
GET	/admin/consumers	Список подписчиков ПИ
POST	/admin/consumers	Создать подписчика ПИ
PATCH	/admin/consumers/{id}	Обновить подписчика
POST	/admin/consumers/{id}/rotate-key	Сменить API-ключ

Пример задания Telegram:

curl -X POST http://localhost:8080/admin/jobs \
  -H 'Content-Type: application/json' \
  -d '{"source_type":"telegram","source_config":{"channel":"creamy_caprice","limit":50}}'

ЦП → ЦА (internal)

Метод	Путь	Описание
POST	/internal/ingest	Приём batch событий (заголовок X-Internal-Token)

ПИ Distribution API

Метод	Путь	Описание
GET	/api/v1/events	События с фильтром по API-ключу

Тестовый consumer test-pi создаётся при старте с ключом из TEST_PI_API_KEY (по умолчанию test-pi-api-key-change-me):

curl http://localhost:8080/api/v1/events \
  -H 'Authorization: Bearer test-pi-api-key-change-me'

Поток данных

1. Аналитик создаёт задание: POST /admin/jobs
2. ca-api ставит задание в Redis (cp:jobs)
3. cp-workers забирает задание, парсит Telegram через существующую сессию
4. Результаты отправляются в POST /internal/ingest
5. События с координатами автоматически появляются на карте как MapObject
6. Внешние ПИ получают отфильтрованный срез через /api/v1/events

Миграция EventRecord → Event

SocialParser	CA Event
event	description / title
date (dd.mm.yy)	event_date
geolocation	latitude, longitude
locality	locality, region
source_url	source_url
—	source_type = "telegram"

Остановка

docker compose down

Данные PostgreSQL сохраняются в volume pgdata.

Legacy

Старые каталоги backend/ и frontend/ в корне оставлены для справки; активная разработка — в centers/.