141 lines
16 KiB
Markdown
141 lines
16 KiB
Markdown
# Промт: платформа-сессия P5 — `POST /books` (П-9) + стоп/резюм (PD-140) + наблюдаемость (П-11)
|
||
|
||
Ты — платформа-сессия TextMachine. Зона записи — **только `platform/`**; сессия НЕ коммитит —
|
||
дерево готовит и передаёт на лендинг оркестратору. Онбординг по `CLAUDE.md`; итоги, вопросы и
|
||
предложения на ратификацию — ТОЛЬКО зонный журнал `platform/docs/platform-PROGRESS.md`
|
||
(в `docs/PROGRESS.md` платформа не пишет). В дереве живут незакоммиченные файлы ЧУЖИХ зон —
|
||
полигон (`eval/*`, ЖИВОЙ платный прогон: ничего там не запускать) и, возможно, фронт
|
||
(`frontend/*`) и бэкенд; начни с `git status`, чужое не трогать. Чужой код ЧИТАТЬ для сверки
|
||
можно и нужно (норма D39.115 п.3), писать — нельзя. LLM-провайдеров пак не зовёт, $0.
|
||
|
||
> **Онбординг-блок (проблема).** Раннер P4 построен и принят (D39.123): транзиентные
|
||
> systemd-юниты, очередь River с холдом-до-спавна, реконсилятор, тейлер, пять ручек `/v0`.
|
||
> Но книги заводятся только дев-инструментом `tmplatformctl book add`, а единственная ручка
|
||
> контракта, которую P4 сознательно не взял, — `POST /books` (граница промта, П-9 зонного
|
||
> бэклога): это не «ещё один хендлер», а хранилище файла, статусы `uploading/parsing/rejected`
|
||
> (в схеме контракта есть, ни одним писателем не заполняются), каталог проекта движка и
|
||
> пер-маршрутный потолок тела (PD-72 закрывается ВМЕСТЕ с ручкой, не раньше). Вторая дыра:
|
||
> ручек стопа/резюма нет (PD-140, `Service.Stop` не подключён) — человек не может остановить
|
||
> прогон. Третья: наблюдаемости нет вовсе (П-11: ни метрик, ни трейсинга; глубина очереди и
|
||
> возраст холдов читаются только SQL-ем), и конфигурация из 27 env-переменных не печатается
|
||
> на старте (PD-114). Фронт ждёт `POST /books` для экрана загрузки S4 (Ф-26 его бэклога).
|
||
|
||
## Обязательное чтение до кода (порядок; читать, не грепать)
|
||
|
||
1. `platform/docs/platform-PROGRESS.md` — «Текущее состояние» + разделы P4 и дофикса целиком
|
||
(формы раннера: холд+прогон+попытка+очередь одной транзакцией · порядок `lockBook` ·
|
||
`MaxAttempts:1` · ExecStopPost-маркер · `IsTransient` · PD-158/PD-159) + пинги оркестратора
|
||
в хвосте (формы артефактов движка: манифест `tm-manifest-v2`, `unit.id` с тегом разреза).
|
||
2. `platform/BACKLOG.md` (П-9 дословно — это заказ) + `platform/docs/DEFECT_REGISTER.md`:
|
||
PD-72 · PD-140 · PD-152 · PD-153 · PD-113 · PD-114 · PD-115 · PD-122 · PD-162 · PD-165 ·
|
||
PD-169 — и все открытые строки по разу.
|
||
3. Контракт (канон): `docs/architecture/14-api-contract/openapi.yaml` — `POST /books` (multipart,
|
||
`BookIntake`), статусы `uploading/parsing/rejected/not_started`, `POST /runs/{id}/stop` /
|
||
`resume` (409 при неполной подписи банка), `503`-класс; компаньон-README §3.
|
||
4. `platform/docs/ENGINEERING_STANDARDS.md` (критерии приёмки зоны) + `STACK_DECISIONS.md`
|
||
(пины, linger-модель §15, рецепт стенда с живым PG без root, ставка §20).
|
||
5. Движок (read-only, для стыка): `backend/cmd/tmctl/main.go:30-52` (exit-контракт; SIGTERM
|
||
ловится и выходит кодом 1) · `tmctl manifest` ($0-команда, строит дерево до первого прогона,
|
||
первое касание создаёт БД проекта — D39.122) · D39.110 п.2(б) (потолки `book.yaml` платформа
|
||
НЕ правит).
|
||
|
||
По всем задачам — прогон в отчёте; **молча пропустить задачу нельзя**: сделано / диспозиция /
|
||
вопрос в журнал.
|
||
|
||
## Задачи
|
||
|
||
### 1. `POST /books` — загрузка книги (П-9; закрывает PD-72)
|
||
|
||
- Multipart-приём с **пер-маршрутным потолком тела** (отраслевой stdlib-путь прежде велосипеда:
|
||
`http.MaxBytesReader` и потоковый разбор, не буферизация всего в память) + тест потолка —
|
||
PD-72 закрывается этим же паком.
|
||
- **Хранилище:** куда ложится исходник, кто и когда его чистит при отказе разбора и при удалении
|
||
(смежно PD-162: удалённый каталог книги сегодня клинит прогон с открытым холдом — реши хотя бы
|
||
диспозицией); относительные пути и `StateDir`-дисциплина зоны в силе.
|
||
- **Статусы жизненного цикла:** `uploading → parsing → not_started | rejected` получают ПИСАТЕЛЕЙ;
|
||
разбор = вызов движка ($0-команда `tmctl manifest` — она и создаёт БД проекта); отказ разбора =
|
||
`rejected` с продуктовой причиной без протечки внутренностей (ПТ-33); read-model один — книга,
|
||
заведённая дев-интейком, и книга, загруженная ручкой, читаются одинаково.
|
||
- ⚠ **Развилка, ГЕЙЧЕНАЯ ратификацией: кто пишет `book.yaml` при интейке.** D39.110 п.2(б) —
|
||
«платформа `book.yaml` не правит» (контекст решения: потолок прогона не пишется в данные
|
||
движка). Создание НОВОГО каталога книги при аплоаде требует, чтобы кто-то положил стартовый
|
||
`book.yaml` (языки/жанр из `BookIntake`, потолки из деплой-шаблона). Спроектируй форму
|
||
(например: генерация из шаблона деплоя при интейке как отдельная операция, после которой файл
|
||
принадлежит оператору и платформа его больше не трогает), запиши варианты с ценой и **отправь
|
||
вопросом в журнал ДО стройки этой половины** — ратифицирует оркестратор. Остальное (приём,
|
||
потолок тела, хранилище, статусы, тесты) этой развилкой НЕ гейчено.
|
||
- `BookIntake.title` в спеке нет (черновик фронта ждёт ратификации) — поле НЕ выдумывать;
|
||
разбор даёт название, как даёт.
|
||
|
||
### 2. Стоп и резюм прогона (PD-140)
|
||
|
||
- Ручка стопа по контракту (точный путь и формы — ИЗ СПЕКИ, не отсюда): остановка юнита через
|
||
systemd (SIGTERM, graceful; движок дописывает чекпойнты и выходит), холд сеттлится штатным
|
||
реконсилятором.
|
||
- ⚠ Ограничение до эмиттера (строка 103 движка + 165): движок ловит SIGTERM и выходит кодом 1 ⇒
|
||
ExecStopPost-маркер честно скажет `exited/1`, и по одному маркеру стоп неотличим от аварии
|
||
(PD-152). **Кандидат-дизайн, оцени и предложи:** платформа ЗНАЕТ, что стоп её — записать
|
||
намерение стопа (строкой в Postgres той же транзакцией, что команда стопа) ДО SIGTERM и
|
||
классифицировать исход маркера по нему; это дискриминатор своей стороны, не гадание по
|
||
exit-коду. Если берёшь — пин на гонку «стоп против самостоятельного финиша». Различение
|
||
«потолок vs авария» остаётся за эмиттером — на него не замахиваться.
|
||
- `resume` по контракту (после банк-стопа — 409 при неполной подписи; после стопа — новый прогон
|
||
с остатком бюджета, механика перезапуска реконсилятора уже есть — переиспользовать, не
|
||
дублировать). Семантика денег прежняя: PD-158/PD-159 не трогать.
|
||
- Обе ручки — в аллоулисте форм контракта, wire-проверки в духе приёмки P4.
|
||
|
||
### 3. Наблюдаемость минимумом (П-11) + печать конфигурации (PD-114)
|
||
|
||
- Метрики зоны: глубина очереди · возраст самого старого открытого холда · число прогонов в
|
||
карантине · отставание тейлера · длительность/бюджет свипа (PD-169 смежно). Форму выбрать по
|
||
отраслевой практике с обоснованием и точным пином в `STACK_DECISIONS` (stdlib `expvar` против
|
||
prometheus-клиента — сравнить, решить, записать; PD-115: внешний эталон на ось наблюдаемости
|
||
назвать).
|
||
- Печать эффективной конфигурации на старте с редакцией секретов (PD-114 — задача уже
|
||
переформулирована ратификацией; деньги и argv в INFO по-прежнему не текут, PD-99).
|
||
|
||
### 4. Докс-минорка зоны: `DEFECT_REGISTER.md` секциями
|
||
|
||
Пинг оркестратора №16 (хвост зонного журнала): разложить реестр на секции (open по весу ·
|
||
accepted-risk · fixed по эрам паков), сохранив построчную форму `| PD-N | … |`;
|
||
`python3 docs/scripts/counts.py --check` обязан остаться зелёным (прогнать).
|
||
|
||
## Что НЕ делать
|
||
|
||
- Эскроу/`uncertain`/`closing` (строка 136 единого бэклога) — отдельный денежный промт; формулу
|
||
потолка (PD-158), SpendBound (PD-159) и ставку $0.03 не трогать.
|
||
- Эмиттер-сторону движка не строить и не ждать: тейлер уже умеет ждать файла; словарь `events.go`
|
||
не менять (движок ответит диффом со своей стороны).
|
||
- П-2 (брокер рейт-лимитов), платёжный провайдер, удаление аккаунта (PD-107 — гейт), счётчик
|
||
ревизии области (PD-122 — гейт «ручка удаления») — не в скоупе.
|
||
- Контракт не править: расхождение/нехватка — вопросом владельцу контракта через журнал
|
||
(прецедент 503/PD-112).
|
||
- Тесты и пины не подгонять под зелень (D39.121); `migrations.sha256` — только по правилам зоны.
|
||
- `git add`/`git commit` не делать — дерево передаёт на лендинг оркестратор.
|
||
|
||
## Отчёт и приёмка
|
||
|
||
- Батарея `make check` с живым PostgreSQL 18.4 под `-race`: 0 FAIL, линтер 0 issues, скипов 0,
|
||
`make vuln` чист; счётчик тестов — диффом `^func Test` исполнением, удалённых ноль.
|
||
- **Каждое новое свойство — с пином, каждый пин — с посадкой** (правило PD-83 зоны); посадки в
|
||
копии зоны вне репозитория, счёт «поймано/пережило» честно, пережившие не подчищать.
|
||
- **Живая проба на боевом бинаре** (фейковый движок как в P4): аплоад настоящего файла →
|
||
статусы `uploading/parsing/not_started` сменяются → книга видна в библиотеке и стартует прогон;
|
||
отказ разбора → `rejected` с продуктовой причиной; стоп живого прогона → юнит погашен, холд
|
||
сеттлится, статус по выбранному дизайну; метрики читаются; потолок тела отбивает большой файл
|
||
честным кодом ответа.
|
||
- Wire-сверка новых ручек с каноном спеки (форма ответов/ошибок problem+json, аллоулист полей).
|
||
- **Мандат самопроверки:** ревью ИСПОЛНЕНИЕМ + адверсариальное ревью диффа (author≠reviewer);
|
||
после тяжёлого ревью — записка-план «ID → статус → улика» (D39.121). Клеймы — с командой рядом;
|
||
перед сдачей перечитать последний абзац отчёта; комплектность против промта — механически.
|
||
- **Предметные оси самопроверки** (D39.120): (1) индустриальный первоисточник/stdlib прежде
|
||
велосипеда (multipart, метрики — назвать эталон); (2) деньги: ни один новый путь не создаёт
|
||
и не освобождает холд мимо ратифицированных форм; (3) жизненный цикл: каждая ветка нового
|
||
статуса достижима и покрыта (недостижимая ветка = дефект, класс PD-117…121).
|
||
- **Канал вопросов — зонный журнал, и у сессии есть право оспорить ПОСЫЛКУ** (D39.47 п.4):
|
||
замер или чтение кода, бьющие по основанию задачи (не по исполнению), обязывают остановиться
|
||
и поднять вопрос — а не выдать формально требуемый артефакт; тихая интерпретация запрещена.
|
||
- **Самоверификация интервально, не одним прогоном в конце:** после каждой задачи — сверка
|
||
с промтом и прогон гейтов; красное чинится до перехода к следующей.
|
||
- Отчёт — разделом в `platform-PROGRESS.md`: таблица задач · развилка book.yaml вопросом ·
|
||
дизайн стопа · закрытые/заведённые PD-строки. Реестр и счёт — скриптом, не руками.
|