rf4-spotter/docs/PROJECT_AUDIT_2026-09-10.md

Полный аудит проекта RF4 Spotter — 10 сентября 2026

База: 13e04e6. Проверены: архитектура, backend, frontend, security, performance, testing, deployment, documentation.

---

1. Архитектура и высокоуровневый обзор

Стек

Слой	Технология	Статус
Proxy	Caddy 2.10	Production-ready, TLS завершение, Basic Auth на admin
Frontend	Astro 7 SSR (Node)	Сборка 0 errors, адаптивный дизайн
Backend	FastAPI + SQLAlchemy 2 + PostgreSQL 17	130 тестов, 1 skipped
Хранилище	PostgreSQL 17 + MinIO/S3	Volumes, backup/restore
CI	Gitea Actions	Python, Astro, Compose E2E, pip-audit
Scheduler	Official import + Community scheduler	Опциональный профиль

Оценка архитектуры: ✅ Хорошо (8/10)

• Чёткое разделение: Caddy → Astro SSR → FastAPI → Postgres/MinIO
• Нет точки отказа в виде единого контейнера
• Profiles в docker-compose для scheduler/importer
• Production compose отдельно от dev

---

2. Backend (FastAPI) — детальный разбор

2.1 main.py (~1100 строк) — 🔴 КРИТИЧЕСКАЯ ПРОБЛЕМА

Проблемы:

• Все endpoints в одном файле — нарушение SRP
• create_catch_report — 50+ строк бизнес-логики inline
• _check_rate_limit и _is_trusted_proxy — утилиты должны быть в отдельном модуле
• _admin, _spot_or_404, _report_source — общие функции смешаны с endpoints
• Нет APIRouter — всё на app.get/post

Рекомендация: Разделить на routes/ с APIRouter:

apps/api/app/routes/
  ├── activity.py      # /api/v1/activity, /spots/*
  ├── submissions.py   # catch-reports, screenshots
  ├── admin.py         # /admin/*
  ├── community.py     # observations, source-status
  ├── records.py       # /records, /imports
  └── catalog.py       # fishes, waterbodies, baits

2.2 activity.py — ⚠️ Есть риски при scale

Плюсы:

• Детерминированная формула, покрыта тестами
• Cap confidence для 1-2 игроков (A07)
• Exponential decay freshness (18h half-life)

Риски:

• Нет индекса на (spot_id, fish_id) — groups агрегирует в памяти
• При 10k+ approved reports за 72h — полный load + sort в памяти
• total = len(rows) — нет COUNT запроса, полная выборка для pagination

Рекомендация:

1. Добавить composite index: ix_catch_report_spot_fish_approved
2. Для activity endpoint — materialized view или pre-aggregation table
3. Для total — отдельный COUNT query вместо len(rows)

2.3 models.py — ✅ Хорошо структурирован

Плюсы:

• Чёткие enum для SourceType, ModerationStatus, ImportStatus
• Unique constraints на slug, external_id
• JSON поля для raw_payload, changes, provenance
• Foreign keys с relationships

Проблемы:

• source_external_id unique=True — конфликт при повторном импорте разных sources с одинаковым ID
• SubmissionAttempt — нет cleanup cron, растёт бесконечно (хотя есть cleanup в _check_rate_limit)
• ImportRecordEvent — нет индекса на (catch_report_id, created_at) для history query

2.4 importer.py — ✅ Хорошо, но есть edge cases

Плюсы:

• Advisory lock для cross-process mutex
• ETag/Last-Modified conditional requests
• Idempotent по external_id SHA-256
• A12: meaningful changes/provenance в ImportRecordEvent

Риски:

• html: str | None = None — тестовый параметр в production signature
• _unique_slug — N+1 query loop при коллизиях
• Нет retry policy для HTTP 5xx с exponential backoff

2.5 retention.py — ✅ Хорошо

Плюсы:

• Dry-run mode по умолчанию
• Configurable policy через RetentionPolicy
• Handles screenshots, payloads, moderation events
• Автоматический rejection pending reports по TTL

Проблемы:

• delete_object callback — должен быть injected, не passed per-call
• Нет bulk delete — loop по reports

2.6 scheduler.py vs community_scheduler.py — ⚠️ Дублирование

Оба используют pattern:

while True:
    try:
        run_due_import()
    except Exception:
        logger.exception(...)
    time.sleep(interval)

Рекомендация: Общий base class или use APScheduler/celery-beat

---

3. Frontend (Astro) — детальный разбор

3.1 index.astro — ⚠️ Сложная логика в template

Проблемы:

• 50+ строк бизнес-логики в .astro файле
• Нет error boundary — catch all делает 503
• offset + items.length < totalItems — работает, но fragile при partial last page
• Нет optimistic UI / loading state

Рекомендация:

1. Вынести fetch logic в src/lib/fetchers.ts
2. Добавить isLoading state и skeleton UI
3. Error boundary per-section (filters, activity, signals)

3.2 Layout.astro — ✅ Хорошо

Плюсы:

• A08: errorPage prop для skip structuredData
• Canonical, OG, Twitter Card, JSON-LD
• robots/noindex для admin/error pages
• Skip link для accessibility

Минусы:

• 12 CSS imports — можно aggregate в global.css
• replaceAll("<", "\\u003c") — hack для JSON escaping

3.3 global.css (~1200 строк) — ⚠️ Все стили вместе

Проблемы:

• Все компоненты в одном файле — сложно navigate
• Нет CSS modules или scoped styles

Рекомендация:

• Разделить на components/, pages/, utilities/
• Astro scoped styles для компонентов

---

4. Security — ✅ В целом хорошо, есть улучшения

✅ Реализовано

Мера	Статус
Rate limiting (PostgreSQL advisory lock)	✅
Idempotency-Key header	✅ (A05)
HMAC client_hash вместо IP	✅
Screenshot validation (MIME, size, EXIF removal)	✅
Admin Bearer token + Caddy Basic Auth	✅
Security headers (HSTS, X-Frame-Deny, etc.)	✅
Production settings validation	✅
pip-audit в CI	✅

⚠️ Улучшения

Проблема	Приоритет
CORS origins — dev defaults localhost:4321, production требует HTTPS	Medium
ADMIN_TOKEN — default change-me-in-production в compose.yaml	High (docs)
X-Content-Type-Options — только на admin/catch-reports, не на всех	Low
Content-Security-Policy — отсутствует	Medium
Rate limit — 5 requests per 10 min, нет per-endpoint limits	Low
Screenshot upload — нет CSRF protection (POST без token)	Medium

---

5. Performance — ⚠️ Есть узкие места

5.1 Database

Проблемы:

• activity endpoint: full table scan + in-memory sort
• spot_detail: count_since — Python loop по reports
• public_spot_pages: 3-way JOIN + DISTINCT + offset pagination

Рекомендации — SQL индексы:

-- Добавить индексы
CREATE INDEX ix_catch_report_spot_fish_approved 
  ON catch_report(spot_id, fish_id, moderation_status, reported_at);

CREATE INDEX ix_catch_report_waterbody_approved_reported
  ON catch_report(waterbody_id, moderation_status, reported_at);

CREATE INDEX ix_catch_report_official_records 
  ON catch_report(source_type, caught_at, weight_g) 
  WHERE source_type = 'official_record';

5.2 Caching

Текущее:

• In-memory cache: 20s TTL, 128 keys, process-local
• public_cache.invalidate() на moderation/publish

Проблемы:

• Multi-process: каждый API worker имеет свой cache
• Нет cache warming на restart
• Community observations не кэшируются

Рекомендация: Redis или shared memory (SHM) для multi-process

5.3 Frontend

Плюсы:

• Astro SSR — no client JS for initial render
• fetchpriority="high" для hero image
• Reduced motion support

Улучшения:

• Нет lazy loading для нижеfold images
• Нет prefetch для /spots/[id]
• SignalFeed — нет intersection observer для "load more"

---

6. Testing — ✅ 130 passed, 1 skipped

✅ Хорошее покрытие

• API endpoints (test_api.py)
• Import idempotency (test_importer.py)
• Community CLI state/validation (test_community_cli.py)
• Readiness aggregation (test_readiness.py)
• Rate limit with Docker chain (test_rate_limit.py)

⚠️ Пропущенные сценарии

Тест	Приоритет
Retention cleanup — нет интеграционного теста	High
Screenshot validation — edge cases (PNG vs JPEG magic bytes)	Medium
Community scheduler retry backoff — 30min → 24h	Medium
Activity calculation — edge cases (0 players, all same player)	Low
Bootstrap E2E — test-production-bootstrap.sh не в CI	Medium
Astro accessibility — audit:axe есть, но нет automated checks	Low

---

7. Deployment & Operations

✅ Хорошее

• Compose production с healthchecks
• Backup/restore scripts
• Monitoring docs (disk, TLS, readiness)
• Data retention policy
• Preflight checks before deploy

⚠️ Улучшения

Проблема	Решение
Нет blue-green/canary	Добавить rolling update в deploy script
Database migration rollback	Нет test-rollback в bootstrap
Log rotation — Docker json-file, 10MB × 5	OK, но нет centralized logging
No distributed tracing	Добавить OpenTelemetry для request_id propagation
No metrics export	Нет Prometheus metrics (request count, latency, error rate)

---

8. Documentation

✅ Хорошее

• README.md — comprehensive (150+ строк)
• docs/ — recovery plans, audit reports, roadmap
• deploy/README.md — production steps
• data-policy.md, retention, monitoring

⚠️ Улучшения

Проблема	Решение
API documentation — FastAPI auto-docs, но нет OpenAPI spec file	Добавить openapi.json в repo
Data model ER diagram	Добавить визуальную схему
Architecture decision records (ADR)	Для key decisions (Astro vs Next, in-memory cache, etc.)
Runbook for incidents	Что делать при Postgres full, MinIO down, etc.

---

9. Код-стиль и maintainability

✅ Хорошее

• Type hints everywhere
• from __future__ import annotations
• Pydantic v2 models
• Alembic migrations

⚠️ Улучшения

Проблема	Пример
Long lines	create_catch_report — 70+ char lines
Magic numbers	55 * min(1, weighted / 12) — вынести константы
Inline SQL	text("SELECT pg_try_advisory_lock(:key)") — вынести в constants
Duplicate URL patterns	"/api/v1/admin/" repeated in middleware and endpoints

---

10. Приоритизированный список улучшений

🔴 High Priority (блокирующие/рисковые)

1. Разделить main.py на routers — SRP, testability, reviewability
2. Добавить database indexes — spot_id + fish_id + moderation_status, source_type + official_records
3. Retention integration test — verify cleanup works end-to-end
4. Screenshot CSRF protection — form submission без CSRF token
5. Bootstrap E2E в CI — test-production-bootstrap.sh должен run на push

🟡 Medium Priority (улучшения)

6. Shared cache (Redis) — вместо in-memory для multi-process
7. Content-Security-Policy header — добавить base-uri, script-src
8. Error boundaries в Astro — per-section error handling
9. Materialized view для activity — pre-aggregation вместо in-memory sort
10. OpenAPI spec export — openapi.json в repo + swagger UI
11. Metrics export (Prometheus) — request latency, error rate, queue depth
12. Screenshot validation test — magic bytes, MIME mismatch

🟢 Low Priority (косметика/технический долг)

13. CSS modularization — split global.css into components
14. Extract constants — 55, 25, 20, 12, 6, 3 → named constants
15. Scheduler base class — DRY для official + community scheduler
16. Prefetch links — /spots/[id] prefetch на hover
17. ADR documentation — record architecture decisions
18. Incident runbook — playbooks для common failures

---

Итоговая оценка

Категория	Оценка	Комментарий
Архитектура	8/10	Чистое разделение, но main.py — god object
Безопасность	7.5/10	Хорошие основы, нужно CSP + CSRF
Производительность	6.5/10	Indexes + caching critical для scale
Тестирование	8/10	130 tests, но пропущены retention + bootstrap
Deploy/Ops	7.5/10	Good compose, no metrics/tracing
Документация	8.5/10	Comprehensive README, missing runbook
Code Quality	7.5/10	Type hints, но long files + magic numbers

Общий балл: 7.6/10 — крепкий проект с хорошими основами, требует refactor main.py и database indexes для production scale.

---

История ревизий

Дата	Автор	Изменения
2026-09-10	AI	Полный аудит: архитектура, backend, frontend, security, performance, testing, deploy, docs
2026-09-08	(предыдущий)	Базовый аудит UI/UX, T01/T02 fixes

---

Что делать дальше (рекомендации)

Немедленно (до продакшена)

1. Разделить main.py на routers (минимум 3 файла)
2. Создать и применить SQL индексы
3. Добавить retention integration test
4. Добавить CSRF token для screenshot upload
5. Добавить test-production-bootstrap.sh в CI workflow

В течение спринта

6. Внедрить Redis для shared caching
7. Добавить CSP headers
8. Вынести fetch logic из index.astro в fetchers.ts
9. Добавить OpenAPI spec export
10. Написать incident runbook

По возможности

11. Materialized view для activity
12. Prometheus metrics
13. CSS modularization
14. ADR documentation
15. Scheduler base class