# platform — control plane (SaaS-слой)

Зона записи сессии «Платформа». P0 собран 04.08 (скелет: HTTP · сессии · схема read-model ·
интерфейс ингеста); **активный промт — `docs/PLATFORM_SESSION_PROMPT.md`**, зонный журнал —
`docs/platform-PROGRESS.md` (весь прогресс зоны здесь, решение владельца 04.08), стек —
`docs/STACK_DECISIONS.md`.

Батарея зоны: `make check` (build · vet · fmt · lint · test -race). Тесты со схемой требуют
`TM_PLATFORM_TEST_DSN`; без него они пропускаются, и `check` называет пропуски вслух.

## ⚠ Git и зона (читать ДО первой строки кода)

**Платформенная сессия не коммитит — лендит оркестратор.** Канон — `../CLAUDE.md`, §Гардрейлы; продублировано здесь, потому что зона живёт своим онбордингом. Направление зоны (вход · деньги · стандарты · скорость) — `docs/PLATFORM_DIRECTION.md`; стандарты и критерии приёмки — `docs/ENGINEERING_STANDARDS.md`; дефекты и уязвимости — `docs/DEFECT_REGISTER.md` (каждая находка получает строку ДО закрытия).

1. **Писать только внутрь `platform/`.** Ничего за её пределами — ни `docs/`, ни `backend/`, ни `frontend/`, ни корневых файлов. Нужна правка вне зоны — пинг владельцу, её сделает оркестратор.
2. **Чужие незакоммиченные файлы в дереве не трогать**: параллельные сессии — норма.
3. **НИКАКИХ** `git add -A`, `reset --hard`, `amend`/`rebase`, перезаписи истории и `checkout` поверх грязного дерева.
4. ⚠ Ревью-гард модулей (D39.85): путь Go-модуля платформы **никогда** не вкладывать под путь движка — иначе он получит доступ к `backend/internal/*` по правилу префикса.

## Что здесь будет

Сервис между фронтом и движком перевода. Всё, что относится к ПОЛЬЗОВАТЕЛЯМ и не относится
к переводу:

- аутентификация и аккаунты (подписки и оплата — ПОСЛЕ MVP, решение владельца 02.08: в MVP
  оплаты нет и денежных полей в интерфейсе нет);
- библиотека книг: чья книга, права доступа, хранение исходников и экспортов;
- учёт токенов и денег **на пользователя** (сырьё уже считает движок: `request_log` +
  `internal/ledger`), потолки и гейт бюджета ДО старта задачи;
- очередь задач и запуск воркеров, статусы прогонов, ретраи;
- SSE-поток прогресса во фронт (⚠ денежные суммы на провод и на экран НЕ идут — D39.84; пользователь видит СТАТУС использования: процент и время сброса, П-5).

## Чего здесь НЕ будет

Перевода. Движок (`../backend/`) остаётся как есть: один процесс на книгу, свой SQLite под
эксклюзивным flock (`store.Open` — «один процесс владеет файлом проекта»). Платформа его
ЗАПУСКАЕТ как воркер, а не поглощает. Причина та же, по которой движок не ветвится по паре
языков: пользователи и квоты ничего не меняют в проводе запроса, значит им нечего делать в
кодовой базе, где каждый байт свёрнут в снапшот-хеш.

## Известное требование к движку (не забыть)

⚠ **Глобальный брокер конкурентности.** `pipeline/ratelimit.go` строит рейт-гарды НА ПРОГОН,
а лимит провайдера — на весь аккаунт. N параллельных пользователей = N независимых гардов
против общего лимита (в комментарии там зафиксировано: mistral валит ~48% вызовов под
параллелизмом). Воркер должен отпрашиваться у платформы перед вызовом. Это единственная
по-настоящему новая механика на стыке.

## Стек

Пины, даты релизов и обоснования — [`docs/STACK_DECISIONS.md`](docs/STACK_DECISIONS.md) (зонный,
live-сверка 04.08); общая записка по обоим новым сервисам — `../frontend/docs/STACK_DECISIONS.md` §5.

Коротко: Go 1.26.4 в `go.mod` (тулчейн сборки ≥1.26.5) · стандартный `net/http` + `ServeMux` без
роутер-библиотеки · PostgreSQL 18 · pgx v5.10.0 · goose v3.27.3 · очередь River v0.42.0 на том же
Postgres (запинена, ещё не подключена — П-3) · `govulncheck` отдельной целью.
**Redis не заводим нигде** — зафиксировано как архитектурное «нет».

Прогресс наружу — SSE, события **пушит воркер**, а не фронт опрашивает read-model.
Аутентификация — одна серверная сессия в Postgres, два способа предъявления: `__Host`-кука для
браузера и `Authorization: Bearer` для десктопа и CLI; эндпоинты про куки не знают ничего.