111 lines
12 KiB
Markdown
111 lines
12 KiB
Markdown
> ⚠ **ПРОМТ ОТРАБОТАН — исторический, не задание.** По нему прошли три сессии: P0 (скелет, принят
|
||
> D39.107), P1 (вход OIDC, кредитный леджер, админ-CLI, деплой-юнит) и P2 (очередь приёмки P1 +
|
||
> два своих ревью). **P1+P2 приняты и залендены приёмкой №15 — D39.109.** Состояние зоны, решения
|
||
> и открытые дефекты: `platform-PROGRESS.md` (раздел «Ратификация приёмкой P2») + `DEFECT_REGISTER.md`
|
||
> (живые строки — PD-6, PD-23, PD-43, PD-45, PD-60/61, PD-72 и PD-79…PD-107). Следующий промт зоны
|
||
> (реконсилятор · тейлер журнала · транзиентные юниты прогона) выдаётся по слову владельца —
|
||
> D39.107 п.3(3). Ниже — текст, по которому работали; исполнять его заново не нужно.
|
||
|
||
# Промт: платформа-сессия P0 — стек, скелет, дизайн-ответы контракту
|
||
|
||
Ты — первая платформенная сессия TextMachine. **Зона записи — только `platform/`.** `backend/`,
|
||
`frontend/`, `docs/`, `eval/` — read-only; расхождения и вопросы — в ЗОННЫЙ журнал
|
||
`platform/docs/platform-PROGRESS.md` (решение владельца 04.08: весь прогресс зоны — там,
|
||
в `docs/PROGRESS.md` платформа не пишет). **Сессия не коммитит — лендит оркестратор**: дерево
|
||
доводится до зелёного и передаётся. Git-канон — `CLAUDE.md` §Гардрейлы (никаких `git add -A`,
|
||
`reset --hard`, перезаписи истории; чужие незакоммиченные файлы не трогать).
|
||
|
||
> Промт написан оркестратором №12 (D39.100). Ратифицирует правки — он же.
|
||
> Вся документация проекта ведётся ИИ-сессиями и может ошибаться: несущие утверждения
|
||
> проверяй по коду/спеке сам, находки расхождений — в журнал зоны.
|
||
|
||
## Что за продукт и где твоё место
|
||
|
||
TextMachine — SaaS издательского художественного перевода больших текстов (zh/ja/en→ru)
|
||
мультиагентным LLM-пайплайном. **Движок** (`backend/`) — Go-CLI `tmctl`: процесс-на-прогон,
|
||
свой SQLite на книгу, никакого сервера внутри (ратифицировано D39.81/D39.85 — HTTP в движок
|
||
не тащить). **Фронт** (`frontend/`) — SPA ридер-IDE, работает на моках, ждёт живой API.
|
||
**Ты — control plane между ними**: пользователи · сессии · очередь · воркер, супервайзящий
|
||
процессы tmctl · материализация статуса в Postgres · HTTP/SSE для фронта.
|
||
|
||
## Обязательное чтение ДО кода (порядок; жаргон — docs/glossary.md)
|
||
|
||
1. Корневой `CLAUDE.md` — канон целей и гардрейлы (⚠ `.env` не читать НИКОГДА).
|
||
2. `docs/research/23-engine-platform-seam.md` — ратифицированный шов движок↔платформа
|
||
(D39.85) — приоритетный канон зоны: NDJSON-поток событий движка → идемпотентный апсерт
|
||
`(run_id, seq)` в Postgres (Reporting Database) → SSE фронту из Postgres; ре-синк на
|
||
обрыве — `tmctl status --json`; **анти-паттерны запрещены**: живой SQLite движка не
|
||
читать · event-sourcing/реплей истории не строить · read-пакет из ядра не выносить.
|
||
3. `docs/architecture/14-api-contract/` — **ратифицированный контракт API v0** (D39.99):
|
||
`openapi.yaml` — нормативная поверхность, которую ты обязан отдать; `README.md` —
|
||
провенанс каждого решения и открытые К-вопросы. Твои: **К-4** (ревизия чтений: одна
|
||
сквозная или пер-ресурсная) · **К-7** (пагинация: 2284 главы / 1200 терминов) ·
|
||
**К-12** (завершение экспорта: пуш событием или опрос).
|
||
4. `platform/BACKLOG.md` — П-1..П-5: твой зонный трекер (аутентификация П-1 ратифицирована
|
||
D39.84 + `frontend/docs/STACK_DECISIONS.md` §5: ОДНА серверная сессия в Postgres,
|
||
`__Host`-кука браузеру · `Bearer` десктопу/CLI · principal создаётся ТОЛЬКО в middleware ·
|
||
CSRF только на cookie-пути).
|
||
5. `frontend/docs/STACK_DECISIONS.md` §5 — транспорт-решения фронта (SSE-дисциплина,
|
||
heartbeat ~20 c, `Last-Event-ID`, отказ от WebSocket) — твой контрагент по проводу.
|
||
6. Grep по D-номерам в `docs/architecture/05-decisions-log.md`: D39.81 · D39.84 · D39.85 ·
|
||
D39.99 · D39.100 (целиком файл НЕ читать).
|
||
|
||
## Скоуп P0 — фундамент, и ни шагом дальше
|
||
|
||
1. **Стек с live-сверкой** (версии по памяти не называть — проверять live; пины точными
|
||
числами, таблицей в зонный док `platform/docs/STACK_DECISIONS.md` с датами релизов и
|
||
«зачем нам»): Go (та же мажорная линия, что у движка — сверься с `backend/go.mod`),
|
||
Postgres, HTTP-роутер/библиотеки (предложи минимум, stdlib-first — ратифицирует
|
||
оркестратор), River (очередь, уже назван П-3/STACK §5 — пин подтверди). Библиотеки сам
|
||
не ратифицируешь — таблица уходит оркестратору при передаче.
|
||
2. **Layout модуля.** ⚠ Ревью-гард D39.85: путь Go-модуля платформы **никогда** не
|
||
вкладывать под путь движка — иначе доступ к `backend/internal/*` по правилу префикса.
|
||
Отдельный `platform/go.mod` уже заведён — наполни. ⚠ Корневой `go.work` (мандат D39.85)
|
||
НЕ создавай — корень вне твоей зоны, его заведёт оркестратор при лендинге.
|
||
3. **Скелет, который компилируется и поднимается**: HTTP-сервер + `/healthz` · каркас
|
||
session-auth по П-1 (схема Postgres + middleware, без UI регистрации) · драфт схемы
|
||
read-model под контракт (books/runs/chapters/units/bank/notes/events + ревизии) ·
|
||
интерфейс NDJSON-ингест воркера (супервизия процесса tmctl, апсерт `(run_id, seq)`,
|
||
ре-синк `status --json`) — интерфейс и типы, живой прогон НЕ нужен: **NDJSON-эмиттер
|
||
в движке ещё НЕ построен** (строка 103 единого бэклога) — формы событий проектируй по
|
||
словарю research/23 §7 и контракту §6, из tmctl потока сегодня не получить.
|
||
4. **Зонная батарея**: свой `check` (build · vet · lint · test) одной командой; пины
|
||
линтера точные. Образец дисциплины — `backend/Makefile` (агрегатная цель там зовётся `battery`) и фронтовый `npm run check`.
|
||
5. **Дизайн-ответы К-4 · К-7 · К-12 + форма П-5** (API лимитов/использования + оповещение
|
||
«перевод остановлен: лимиты исчерпаны», D39.100/ПТ-35; суммы денег на провод НЕ идут —
|
||
статус использования, не доллары). Каждый ответ — ПРЕДЛОЖЕНИЕ с обоснованием в зонном
|
||
журнале; ратифицирует оркестратор, спеку правит фронт-сессия после ратификации.
|
||
|
||
**Не в скоупе:** П-2 (брокер рейт-лимитов — гейт «до второго пользователя») · стройка
|
||
очереди П-3 целиком (дизайн-заметки можно) · деплой/TLS/домены · UI чего угодно ·
|
||
любые вызовы LLM-провайдеров. Бюджет сессии $0.
|
||
|
||
## Жёсткие ограничения
|
||
|
||
- Движок не править и не форкать; `tmctl` дёргать можно только read-only командами и только
|
||
в интеграционных пробах ($0); живой SQLite движка не открывать.
|
||
- Деньги: суммы/цены не попадают в API-ответы (канон D39.84); в логи уровня INFO — тоже
|
||
(норма ЭТОГО промта, не D-лога); лимиты-СТАТУС — П-5, отдельная поверхность.
|
||
- ПТ-34: ни один байт пользовательского перевода — на индексируемый URL (`X-Robots-Tag`,
|
||
`Cache-Control: no-store` уже в контракте — соблюсти в реализации).
|
||
- Пары/языки: платформа языко-агностична; никакой логики по конкретной паре/книге.
|
||
|
||
## Как работать
|
||
|
||
1. **Ревью исполнением — мандат проекта (решение владельца 12.07):** каждый деливерабл
|
||
проверяется запуском (сервер поднялся и ответил · тест сработал · линт чист), не чтением.
|
||
2. **Адверсариальная самопроверка перед финишем** (author≠reviewer): пройди по своим
|
||
решениям с установкой опровергать; особо — схему read-model против спеки контракта
|
||
(каждое поле ответа API обязано иметь источник в схеме или в артефакте шва).
|
||
3. Спорное с каноном / новое продуктовое — НЕ решать: вопрос в зонный журнал, работу
|
||
продолжать там, где вопроса не требуется.
|
||
4. Комментарии в коде — «почему», не «что»; файлы малые; stdlib-first.
|
||
|
||
## Готово — это когда
|
||
|
||
- Дерево компилируется, зонная батарея зелёная, `/healthz` отвечает живым запуском.
|
||
- `platform/docs/STACK_DECISIONS.md` — пины live-сверены, таблица полная.
|
||
- Дизайн-ответы К-4/К-7/К-12/П-5 лежат в `platform/docs/platform-PROGRESS.md` с обоснованиями.
|
||
- Журнал зоны обновлён: что построено · что предложено · что спрошено; BACKLOG-строки
|
||
получили диспозиции.
|
||
- Ничего не закоммичено — дерево передано оркестратору.
|