# Indexium — TODO / Roadmap

> Сервис: асинхронный событийный индексатор модов Minecraft поверх GitHub Releases CDN.
> Бэкенд не хранит тяжёлые артефакты, только метаданные + индексация + быстрый JSON API.

---

## Правила проекта (обязательно к соблюдению)

> Эти правила — не чекбоксы, а инварианты. Любой PR, нарушающий их, не принимается.

### 1. KISS — Keep It Simple, Stupid
- Выбирай самое простое решение, которое закрывает задачу. Никаких абстракций «на будущее» (YAGNI).
- Один модуль — одна ответственность. Если не можешь объяснить функцию в одном предложении — дроби.
- Предпочитай явный код неявной магии (никаких макросов ради макросов).

### 2. DRY — Don't Repeat Yourself
- Повтор >2 раз → выноси в функцию/модуль. Но не DRY ради DRY: дублирование лучше неправильной абстракции.
- Общие типы/утилиты — в `common`/`shared`, доменная логика — в своём модуле.

### 3. SOLID (применительно к Rust)
- **S** — один файл/модуль = одна причина для изменений (см. лимиты ниже).
- **O** — открыт для расширения через трейты, закрыт для модификации (feature-flag, а не `if` на типы).
- **L** — любой `impl Trait` должен заменять другой без поломки контракта.
- **I** — узкие трейты лучше жирных (`Readable`, `Validatable` вместо `GodService`).
- **D** — зависимость от абстракций (`PgPool` через `AppState`, а не глобаль).

### 4. Лимиты структуры (жёстко)
- **Макс 250 строк на файл** — если больше, дроби файл на подмодули.
- **Макс 4 файла на папку** — если больше, вводи подпапки по домену (`api/mods/`, `worker/parsers/`).
- Исключение: `mod.rs`/`lib.rs` не считаются, но должны быть тонкими реэкспортами.
- CI будет ругаться (`cargo clippy` + кастомный скрипт `scripts/check-limits.sh`).

### 5. Дополнительные инварианты
- **Чистота ошибок**: никаких `unwrap()`/`expect()` вне `main.rs` и тестов. Везде `Result` + `thiserror`/`anyhow`.
- **Типы вместо строк**: `Slug`, `GameVersion`, `Loader` — newtype, а не `String`.
- **Миграции только вперёд**: никаких `DROP` без ADR и бэкапа. Каждая миграция — идемпотентна (`IF NOT EXISTS`).
- **Логика без сайд-эффектов**: парсеры/валидаторы — чистые функции, I/O только на границах (handler/worker).
- **Документация рядом с кодом**: публичная функция без `///` — не готова к мерджу.
- **Тест на каждый баг**: регрессия покрывается тестом до фикса.

---

## Легенда статусов
- `[ ]` — не начато
- `[~]` — в процессе
- `[x]` — готово
- `[!]` — заблокировано / требует решения

---

## Phase 0 — Фундамент монорепо (Текущий приоритет)

- [x] Объединить `indexium-backend` + `indexium-frontend` в один git-монорепо (корень `/`)
- [x] Настроить корневой `.gitignore` + локальные `.gitignore`
- [x] Создать структуру `docs/` и заполнить базовую архитектуру
- [x] Создать `todo.md` и `README.md` в корне + прописать правила KISS/DRY/SOLID и лимиты файлов
- [x] Первая миграция `20260906000000_init_schema.sql` (mods, mod_versions, GIN индексы)
- [x] Базовый `src/main.rs` (Axum + SQLx + CORS + /health + миграции при старте)
- [x] Настройка `.env` / `.env.example` (DATABASE_URL, SERVER_PORT)
- [ ] Добавить `docker-compose.yml` (Postgres + Redis/Valkey) для локальной разработки
- [ ] Добавить `Makefile` / `justfile` с командами `dev`, `migrate`, `lint`, `test`
- [ ] Настроить CI (GitHub Actions): `cargo clippy + test`, `svelte-check`, `sqlx migrate check`
- [ ] Скрипт `scripts/check-limits.sh` — проверка 250 строк / 4 файла на папку

## Phase 1 — Backend Core (Rust / Axum)

### 1.1 Инфраструктура
- [x] `config` — загрузка `.env` (DATABASE_URL, REDIS_URL, GITHUB_APP_ID, WEBHOOK_SECRET) — база в `main.rs` через `dotenvy`
- [x] `db` — пул `sqlx::PgPool`, миграции (`sqlx::migrate!`), health-check `/health`
- [x] `tracing` — структурированные логи (EnvFilter + fmt layer)
- [x] Axum роутер: `GET /health`, CORS (5173), TraceLayer

### 1.2 Схема БД (PostgreSQL + FTS + pg_trgm)
- [x] Миграция `20260906000000_init_schema.sql` — таблицы `mods`, `mod_versions` + `GIN (game_versions, loaders)`
- [ ] Миграция `002_fts` — `search_vector`, `pg_trgm`, триггер (см. `docs/database-schema.md`)
- [ ] Таблица `authors` + `webhook_deliveries` (идемпотентность)
- [ ] Сиды / фикстуры для локального дев-окружения

### 1.3 Webhook Ingestion API
- [ ] `POST /api/v1/webhooks/github` — проверка `X-Hub-Signature-256` (HMAC SHA-256)
- [ ] Валидация эвента `release.published` / `release.released`, идемпотентность по `delivery_id`
- [ ] Пуш задачи в очередь (Redis Streams) + ответ `202 Accepted` < 50ms
- [ ] Тест на replay-атаку и неверную подпись

### 1.4 Async Worker / Indexer
- [ ] Консьюмер очереди (tokio task)
- [ ] Скачивание через HTTP Range Request — чтение только ZIP central directory `.jar`
- [ ] Парсинг `fabric.mod.json` / `quilt.mod.json` / `neoforge.mods.toml` / `mcmod.info`
- [ ] Валидация: `mod_id`, `version`, `game_versions`, `loaders`, иконка
- [ ] SHA-256 сверка (если приложен `.sha256`), отбраковка битого артефакта
- [ ] Бейсик malware-скан: поиск `Runtime.exec`, `URLClassLoader`, сетевых вызовов в `<clinit>`
- [ ] Сохранение в `mod_versions`, инвалидация Redis-кэша

### 1.5 Public REST API (Read-Heavy, Cache-First)
- [ ] `GET /api/v1/mods?query=&gameVersion=&loader=&page=&limit=` — FTS + фильтры, кэш Redis 60s
- [ ] `GET /api/v1/mods/:slug` — карточка мода + список версий
- [ ] `GET /api/v1/mods/:slug/versions/:version` — детали версии + `download_url` (прямая CDN ссылка GitHub)
- [ ] Пагинация cursor/offset, ETag, `Cache-Control`
- [ ] Rate limiting (tower_governor / redis-cell)

### 1.6 Auth & Profiles (см. docs/auth-profiles.md, adr/004)
- [ ] GitHub OAuth 2.0 (read:user, user:email) + JWT httpOnly — вход для авторов (MVP)
- [ ] PAT `personal_access_tokens` (hash, scopes, expires) — `POST /auth/tokens` для CLI/лаунчеров (MVP)
- [ ] `POST /api/v1/mods/import` — импорт репозитория (проверка LICENSE + public + манифест)
- [ ] Профили `/u/:login`, `/org/:login` — кэш ISR, sponsors, verified badge, SVG `/v1/badges/:slug/*.svg` (MVP)
- [ ] Star/Follow `stars`, `follows` (с фильтром game_version/loader) — in-app уведомления (MVP-лайт)
- [ ] Device Flow RFC8628 (`/oauth/device/code` → `/activate`) — спроектировать, реализация Phase 2
- [ ] Discord linked_accounts + бот роли Verified Modder — Phase 2
- [ ] Установка Webhook'а через GitHub App API (автоматически) — миграция с OAuth на App в Phase 2

## Phase 2 — Frontend (SvelteKit) + Social

- [ ] Дизайн-система: Tailwind / UnoCSS + токены
- [ ] Страницы: `/` (поиск + фильтры), `/mod/[slug]`, `/mods/import`, `/u/[login]`, `/org/[login]`, `/activate` (device flow)
- [ ] Компоненты: `ModCard`, `VersionTable`, `SearchBar`, `LoaderBadge`, `ProfileHeader`, `SponsorsBar`
- [ ] Клиент API (`src/lib/api.ts`) — типизированные fetch-обёртки
- [ ] SSR + кэширование, skeletons, error boundaries
- [ ] SEO / OpenGraph для карточек модов
- [ ] **Collections / Modlists** `collections`, `collection_stars` + экспорт `?format=prism|packwiz` (Phase 2 хит)
- [ ] **Activity Feed** — лента по подпискам (releases + collections + stars)
- [ ] **Org/Teams** — `/org/:login` агрегатор, `role=maintainer`
- [ ] **Геймификация** — `badges` (Early Adopter, Bug Hunter, Veteran) + Showcase SVG

## Phase 3 — Поиск, качество данных и аналитика (см. docs/analytics.md, adr/005)

- [ ] PostgreSQL FTS (`to_tsvector` + `ts_rank`) по `name`, `summary`, `README`
- [ ] `pg_trgm` для неточных совпадений / опечаток
- [ ] Опционально: `pgvector` для семантического поиска по описанию (эмбеддинги README)
- [ ] Админ-панель / ручная модерация, флаг `verified` / `suspicious`
- [ ] **Indexium Analytics (bStats аналог):**
  - [ ] Миграция `20260907000000_telemetry.sql` (`mod_telemetry_pings`, `mod_daily_stats`, `analytics_salts`)
  - [ ] `POST /api/v1/analytics/submit` (gzip, валидация, daily_salt hash, Redis 1/15мин, без IP)
  - [ ] Крон агрегация `COUNT(DISTINCT server_hash)` → `mod_daily_stats` + TTL 30д
  - [ ] `GET /mods/:slug/analytics?range=30d` + `GET /badges/:slug/servers.svg` + `sort=active_servers`
  - [ ] Легковесный Java/Kotlin SDK `dev.indexium:analytics` (MIT, SimplePie, opt-out флаг)

## Phase 4 — Надёжность и ограничения GitHub

- [ ] GitHub App Install token — 5k-12.5k RPH вместо 60 RPH анонимных
- [ ] Прямые редиректы на `objects.githubusercontent.com` — не проксировать трафик
- [ ] Retry + exponential backoff, DLQ для воркера
- [ ] Метрики: Prometheus / `tracing` + Grafana, алерты на lag очереди

## Phase 5 — Деплой и эксплуатации

- [ ] Dockerfile multi-stage для backend (distroless / alpine)
- [ ] Dockerfile для frontend (adapter-node / adapter-static)
- [ ] `docker-compose.prod.yml` / Fly.io / Railway / Hetzner
- [ ] Бэкапы Postgres (PITR), миграции в CI
- [ ] Документация деплоя (`docs/deployment.md`)

## Phase 6 — Расширения (Backlog)

- [ ] Поддержка CurseForge / Modrinth как доп. источников (опционально)
- [ ] Webhooks для лаунчеров (подписка на обновления мода)
- [ ] CLI для авторов (`indexium publish`)
- [x] Аналитика рантайма — аналог bStats (спроектирована, см. docs/analytics.md) → реализация в Phase 3
- [ ] Аналитика скачиваний (агрегация без хранения персоналки)

---

## Ближайшие 3 шага (Next Actions)

1. `docker-compose.yml` + первая миграция SQL
2. `POST /webhooks/github` с HMAC-проверкой и заглушкой очереди (in-memory channel)
3. `GET /mods` — мок-данные из БД + подключение фронта

---

## Как отмечать прогресс

- При завершении задачи ставь `[x]` и добавляй ссылку на PR/коммит: `[x] Задача (#12)`
- Если задача блочится — ставь `[!]` и опиши блокер в комментарии ниже.

## Блокеры / Вопросы

- [ ] Выбрать окончательно очередь: `Redis Streams` vs `NATS JetStream` vs `pg-queue` на старте?
  - Рекомендация: стартовать с `Redis` (уже нужен как кэш) → мигрировать на NATS если нужен strict ordering.
- [ ] Где хостить Postgres на старте — Supabase / Neon / self-hosted?