Photo Map Service � ������������ ������ ���������� ���� �� ������������� ����� (EXIF GPS)
Go to file
kimi e253907796
All checks were successful
ci / test (push) Successful in 1m37s
ci: retrigger after sonar hotspot review
2026-11-14 02:56:58 +04:00
.gitea/workflows ci: poll Quality Gate up to 5 min (async CE on slow IO) 2026-11-13 13:32:22 +04:00
app ui: default map center Saratov + browser geolocation when permitted 2026-11-14 02:51:34 +04:00
demo_photos iter 4: integration tests on real PostgreSQL, Allure reporting, deploy manifests 2026-11-10 16:28:52 +04:00
deploy deploy: photos host dir via env (PHOTOS_HOST_DIR) 2026-11-10 20:15:26 +04:00
docs/wiki docs: project documentation for Wiki.js (main, architecture, api, cicd, operations) 2026-11-14 01:44:25 +04:00
scripts iter 4: integration tests on real PostgreSQL, Allure reporting, deploy manifests 2026-11-10 16:28:52 +04:00
tests feat: background scan (202 + polling /api/scans/{id}, 409 on parallel, stale-job cleanup), 19 tests 2026-11-10 21:38:01 +04:00
.gitignore chore: unignore artifacts, gitignore allure-results 2026-11-10 17:01:11 +04:00
allure-results.zip ci: fix allure publish (files[] + generate-report) 2026-11-10 17:00:21 +04:00
Dockerfile MVP iter 1: FastAPI skeleton, models, CI (pytest + SonarQube + ntfy) 2026-11-10 15:19:39 +04:00
README.md feat: background scan (202 + polling /api/scans/{id}, 409 on parallel, stale-job cleanup), 19 tests 2026-11-10 21:38:01 +04:00
requirements-dev.txt iter 4: integration tests on real PostgreSQL, Allure reporting, deploy manifests 2026-11-10 16:28:52 +04:00
requirements.txt MVP iter 1: FastAPI skeleton, models, CI (pytest + SonarQube + ntfy) 2026-11-10 15:19:39 +04:00
sonar-project.properties MVP iter 1: FastAPI skeleton, models, CI (pytest + SonarQube + ntfy) 2026-11-10 15:19:39 +04:00

Photo Map Service

Веб-сервис для визуализации личной библиотеки фотографий на интерактивной карте. Сканирует файловую систему (NAS / локальный диск), извлекает GPS-координаты и метаданные из EXIF, сохраняет в PostgreSQL и отображает точки на карте.

Архитектура

┌─ разработчик ─┐   push    ┌──────────────┐        ┌────────────┐
│  git / IDE    ├──────────►│ Gitea :3000  ├───────►│ act_runner │
└───────────────┘           └──────────────┘        └─────┬──────┘
                                                          │ job-контейнер
        CI: pytest (unit + интеграция на реальном PG) ◄───┘
          → Allure :5050 → SonarQube :9090 Quality Gate → ntfy :8090

┌─ docker network devstack_devnet (VM 192.168.2.112) ──────────┐
│  photomap :8000 ──► PostgreSQL 16 (база `photomap`)          │
│     │                                                         │
│     └── читает /photos (RO) ── библиотека фото на NAS         │
│     └── пишет /data/thumbnails ── кэш миниатюр                │
└───────────────────────────────────────────────────────────────┘

Ключевые решения:

  • FastAPI — OpenAPI-документация (/docs) из коробки: контракт API всегда актуален, по нему удобно писать тесты.
  • Отдельная БД в общем PostgreSQL — принцип devstack «одна СУБД, изолированные базы». Координаты — float8 + B-tree: выборки по прямоугольнику карты (bbox) этого достаточно, PostGIS не нужен.
  • Библиотека фото монтируется read-only — сервис физически не может испортить пользовательские файлы.
  • Инкрементальное сканирование по (path, mtime) — повторный прогон не перечитывает неизменённые файлы.
  • Ленивые миниатюры — генерируются при первом запросе и кэшируются на диске; сканирование остаётся быстрым.
  • Фоновое сканирование — POST /api/scan отвечает 202 сразу, фронт поллит /api/scans/{id}; счётчики коммитятся каждые 25 файлов. Параллельный запуск отклоняется (409); зависшие после рестарта прогоны помечаются failed при старте.
  • Bbox-запросы — фронт получает только точки видимой области, карта не деградирует при росте библиотеки.
  • Фронтенд без сборки — Leaflet + markercluster завендорены, сервис полностью автономен в LAN (кроме тайлов OSM).

API

Метод Путь Назначение
GET /api/health liveness
GET /api/health/db readiness (проверка БД)
GET /api/photos?min_lat=…&max_lat=…&min_lon=…&max_lon=… точки в bbox
GET /api/photos/{id} карточка фото
GET /api/photos/{id}/thumbnail миниатюра (ленивая генерация)
GET /api/photos/{id}/file оригинал
POST /api/scan запустить сканирование (202 Accepted, фон)
GET /api/scans история сканирований
GET /api/scans/{id} статус/прогресс (поллинг раз в секунду)

Структура

app/
  main.py       — FastAPI-приложение, эндпоинты
  config.py     — настройки из env (12-factor)
  db.py         — SQLAlchemy (ленивая инициализация движка)
  models.py     — ORM: Photo, ScanJob
  exif_utils.py — парсинг EXIF (exifread, без декодирования пикселей)
  scanner.py    — инкрементальный сканер библиотеки
  thumbnails.py — ленивая генерация миниатюр (Pillow)
  static/       — карта (Leaflet, завендорен)
tests/
  test_health.py      — smoke-контракты API (SQLite)
  test_scanner.py     — сканер на реальных EXIF-файлах (piexif)
  test_thumbnails.py  — миниатюры и отдача файлов
  test_integration.py — настоящий PostgreSQL (в CI; локально skip)
deploy/           — docker-compose.yml для VM (+ .env.example)
scripts/          — генератор демо-библиотеки с GPS EXIF

CI (Gitea Actions)

push → pytest (unit + интеграция на реальном PostgreSQL) → Allure → SonarQube Scan → Quality Gate → ntfy

Секреты репозитория: SONAR_TOKEN, SONAR_HOST_URL, PHOTOMAP_TEST_DATABASE_URL, NTFY_TOPIC.

Деплой на NAS

cd /volume1/docker/photomap
cp deploy/.env.example .env   # заполнить пароль БД
sudo docker-compose --env-file .env up -d --build

Сервис: http://192.168.2.112:8000 (карта), http://192.168.2.112:8000/docs (API).

Локальная разработка

pip install -r requirements.txt -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000
pytest --cov=app -q