139 lines
16 KiB
Markdown
139 lines
16 KiB
Markdown
# Промт: сессия БАТЧ 0.3.0 — ломающая правка контракта API v0 по принятому ревью (строка 183)
|
||
|
||
> Выдан оркестратором №17 16.08.2026 по ратификации D39.138 (приёмка контракт-ревью research/28;
|
||
> решения владельца 16.08 — его §8). Исполняет ОТДЕЛЬНАЯ сессия со своим онбордингом (норма D39.120 п.2).
|
||
> Запуск — по слову владельца.
|
||
|
||
## 0. Какую проблему ты решаешь и что решит твой результат
|
||
|
||
Проект — SaaS-перевод книг: движок (Go, `backend/`) ↔ платформа (control plane, `platform/`) ↔
|
||
веб-фронт (`frontend/`). Между фронтом и платформой стоит ратифицированный контракт **API v0**
|
||
(OpenAPI 3.1). Он рос точечными правками 0.2.0→0.2.3 под давлением строек, и целостного ревью не
|
||
имел. 15–16.08 отдельная сессия провела такое ревью (`docs/research/28-contract-review.md` — ПРИНЯТ,
|
||
D39.138): ядро контракта здорово, дефекты сосредоточены там, где контракт писался вперёд без
|
||
потребителя — ошибки, поток, экспорт, замечания, глава. Владелец разобрал доклад вопрос-за-вопросом
|
||
и принял решения (§8 отчёта); оркестратор ратифицировал их нотой **D39.138 п.2**.
|
||
|
||
Твоя работа — **исполнить эти решения правкой спеки**: батч 0.3.0. Момент дешёвый и не повторится:
|
||
**платформа не отвечает на 8 операций из 16** (сервера за ними нет вовсе, а фронт заморожен и живёт
|
||
на моках), поэтому правка их формы сегодня стоит только правки документа. Сразу после тебя платформа строит читающую
|
||
поверхность (пак P7) **по твоей спеке** — каждый пропущенный тобой дефект она отольёт в код, миграции
|
||
и воркер, где он подорожает на порядок. Отнесись к каждой форме ответственно: этот документ — закон
|
||
для трёх зон.
|
||
|
||
## 1. Зона и git (читать ДО первой правки)
|
||
|
||
**Ты не коммитишь — лендит оркестратор.** Твоя зона записи — РОВНО три файла:
|
||
1. `docs/architecture/14-api-contract/openapi.yaml` — нормативная спека (канон);
|
||
2. `docs/architecture/14-api-contract/README.md` — компаньон (правится ВМЕСТЕ со спекой, §5 ниже);
|
||
3. `docs/archive/reports/CONTRACT_BATCH_0.3.0_REPORT.md` — твой отчёт (новый файл).
|
||
|
||
Всё остальное — read-only: код трёх зон читать можно и нужно, править нельзя. **Зеркало
|
||
`frontend/docs/api-contract/openapi.yaml` НЕ трогать** — зона фронта заморожена (D39.136 п.2), зеркало
|
||
синхронизируют лендинг и первое касание зоны; временное расхождение канона и зеркала — известное
|
||
состояние, не дефект (ратифицируется при лендинге). Чужие незакоммиченные файлы в дереве (живой
|
||
полигон: `eval/`, `docs/experiments/`, `docs/POLYGON_*`) не трогать. `.env` не читать. Никаких
|
||
`git add`/`commit`/`reset`/`checkout` — дерево остаётся как есть, git трогает только оркестратор.
|
||
|
||
## 2. Что читать (карта, ≤5 позиций; порядок важен)
|
||
|
||
1. **`docs/research/28-contract-review.md` — ЦЕЛИКОМ, это носитель твоего задания.** Состав и порядок
|
||
батча — §5 · что резать — §5а · транспорт/сеть — §5б · решения владельца — §8 · форма модели
|
||
ошибок — §8 п.4 и §8а · инструкции лендинга — §8б. ⚠ Ревью-шапка приёмки в голове файла несёт
|
||
ПОПРАВКИ (важнейшая: К-10 закрывается «НЕ строить» — пофазность у главы на провод не выносить,
|
||
это следствие Б-0) — читать тело через неё.
|
||
2. **D39.138 п.2 (живой `docs/architecture/05-decisions-log.md`, с хвоста)** — ратификация решений.
|
||
При расхождении формулировок research/28 и ноты побеждает НОТА.
|
||
3. **Канон 0.2.3 + компаньон** (`docs/architecture/14-api-contract/`) — целиком, до правок: ты обязан
|
||
знать, что ломаешь и почему оно было таким (у половины форм есть записанные обоснования — их
|
||
судьба решается, а не игнорируется).
|
||
4. Код трёх зон — по мере нужды, read-only. `file:line`-якоря отчёта research/28 — отправные точки,
|
||
**код первичен**: перед тем как записать в спеку факт о поведении сервера/клиента, открой место
|
||
и перепроверь (якоря могли уплыть).
|
||
5. `CLAUDE.md` (корень) — гардрейлы проекта; `docs/glossary.md` — жаргон.
|
||
|
||
## 3. Ратифицировано — делай РОВНО так (отступление = пинг владельцу, не тихая девиация)
|
||
|
||
Состав и порядок — **research/28 §5** (здесь не пересказывается — не дублировать носитель).
|
||
Несущие рамки из D39.138 п.2, которые обязаны выжить в любой твоей редакции:
|
||
|
||
- **Порядок исполнения не косметика:** Б-1 (модель ошибок) — ПЕРВОЙ: от словаря кодов зависят
|
||
формулировки Б-2/Б-3/Б-8/Б-14а/§8а.
|
||
- **Б-0:** конвейер уходит с провода. `Progress` → один счётчик до ближайшей остановки, знаменатель —
|
||
КУПЛЕННЫЙ объём (после подписи банка полоса заново); `finalizing` снять из словарей (устная фраза
|
||
владельца, не норма — §8 п.15); `verify_bank` → `stop_for_signing` без упоминания следующей фазы;
|
||
`TermOrigin`/`TermStatus` с провода снять; `Unit` описать без «edit unit» и «1.9 на главу»;
|
||
из ВСЕХ описаний вычистить конвейерные слова — описания компилируются в JSDoc клиента.
|
||
- **Б-1 — вариант B (§8 п.4 + §8а):** машинный `code` (двухуровневый: стабильный корневой +
|
||
расширяемый вложенный) + `request_id` (значение на сервере уже есть); `title`/`detail` —
|
||
developer-facing, клиент НЕ показывает; серверная локализованная фраза — отдельным полем ТОЛЬКО
|
||
для неперечислимых причин; `errors[]` с указателем поля для валидации. Два класса конкретности:
|
||
класс 1 (детерминированные — вход/счёт) — конкретика максимальная; класс 2 (модельные — прескрин /
|
||
отказ провайдера / фильтр) — ОДИН грубый код на весь класс, без вариации между попытками (К-9:
|
||
`rejected` + грубый код, 12-й статус НЕ заводить).
|
||
- **Жанр — выкинуть** из `BookIntake` и `Book` (Б-23; остальные половины удаления — строка 184, не твои).
|
||
- **Экспорт остаётся** и получает состояние отказа (Б-4: `state` вместо булева `ready`, `failure_code`,
|
||
`expires_at`, эхо формата, правило доступа к ссылке — ПТ-34).
|
||
- **Б-19:** запрет клиентской служебной метки «Глава {n}» СНЯТЬ (противоречит решению владельца 09.08 —
|
||
это ратифицировано); а вот `title_raw`/`kind`/структурная версия — ВЫБОР ТВОЙ из двух названных форм
|
||
(заложить формой сейчас ЛИБО явно передать дизайн-паку 161 с записью в компаньоне) — аргументируй.
|
||
- **Версия = 0.3.0**, обычный ломающий минор; право ломать в 0.x — весь бета-период (§8 п.17).
|
||
- **НЕ заводить в батч:** `POST /books/{id}/parts` (строка 185, дизайн — пак 161) · историю прогонов
|
||
(в МВП не нужна) · двухшаговую загрузку · ленту изменений структуры · поиск/фильтр · «грубую группу
|
||
статуса» — всё это записывается в компаньон НАПРАВЛЕНИЯМИ с номерами строк бэклога (дисциплина Б-21).
|
||
- **Гейт на утечку конвейера** (тест по образцу языкового) — фронт-половина, тебе НЕ строить; в
|
||
компаньон записать само правило «на проводе нет имён стадий/волн и движковых словарей» как
|
||
ревью-вопрос каждой правки.
|
||
|
||
## 4. Реши сам и аргументируй в отчёте
|
||
|
||
Точные имена полей и значений словаря кодов (класс 1 — из реальных причин `fail()` платформы, читай
|
||
код) · формы схем (пять конвертов списков на `allOf` — §5а «слить формально») · состав и глубина
|
||
резки §5а (мёртвые поля/кадры — с обоснованием на каждое) · как записать семантику сжатия и условных
|
||
чтений (шаги 1–2 §5б — В спеку, не в зонный док) · формулировки всех описаний. Совет-приор (опровергается
|
||
аргументом): для правил, которые OpenAPI не выражает (межполевые инварианты, условная обязательность),
|
||
образец уже есть в спеке — `BankDecision.dst` через `if/then` плюс прозу; помни улику К-11: генераторы
|
||
`if/then` игнорируют, значит правило обязано жить и словами для клиента.
|
||
|
||
## 5. Компаньон — ВМЕСТЕ со спекой (не после)
|
||
|
||
(а) Снять опровергнутые утверждения: ответ §5 «добавлена волна → фронт не правится» (опровергнут
|
||
исполнением, Б-0) · «канала банка нет» §3 против собственной строки 267 (Б-7а) · resume-абзац
|
||
(Б-7а п.4: лечение «новый прогон с бОльшим потолком» существует). (б) Завести таблицу
|
||
«чтение → источник → строка бэклога» и правило «предупреждение о недостроенном несёт номер строки»
|
||
(Б-21). (в) Обновить провенанс-классы ✓/◆/○ под 0.3.0. (г) Приложение А (карта «код → фраза»):
|
||
структуру перевести на словарь кодов Б-1, СЛОВА не заполнять — фразы пишет владелец (строка 148).
|
||
(д) Генезис-прозу из спеки (история ратификаций, апологии RFC — §5а называет места) переносить в
|
||
компаньон, не удалять.
|
||
|
||
## 6. Мандат самопроверки — исполнением, не заявлением
|
||
|
||
1. **Линт (форма проверена исполнением 16.08):** `cd frontend && npx spectral lint
|
||
../docs/architecture/14-api-contract/openapi.yaml --ruleset .spectral.yaml --fail-severity=warn`
|
||
— exit 0 (предупреждение валит так же, как ошибка). Читать/запускать фронт-тулинг можно,
|
||
писать в зону фронта — нет.
|
||
2. **Записка-план по §5** (норма D39.121): каждый пункт §5 research/28 (включая однострочники и §5а)
|
||
получает строку «исполнено, где / отказ, почему» — сдача = все ID с диспозицией; это же —
|
||
скелет твоего отчёта. Комплектность против заказа — механически, не по памяти.
|
||
3. **Предметные оси** (право снять/добавить свою — с аргументом): (а) «второй клиент» — сгенерируй
|
||
мысленно (или реально) клиента по своей схеме: не указывает ли она нарушить собственную прозу
|
||
(класс PD-172: порядок свойств `BookIntake` указывал класть файл вторым); (б) анти-утечка — греп
|
||
финальной спеки по словарю конвейера (draft/edit/wave/stage/mined/ruby/finalizing и что найдёшь
|
||
сам); (в) каждое «оставить как есть» в спорном месте несёт записанный контраргумент (анти-инерция).
|
||
4. **Заявление = команда:** каждое числовое/категорическое утверждение отчёта — с командой, которой
|
||
получено; приёмка их пере-ранит.
|
||
5. Несогласие с ратифицированным решением — СТОП по этому пункту и пинг через владельца с аргументом;
|
||
у тебя есть право сказать «этого делать не надо» — но не право молча сделать иначе.
|
||
|
||
## 7. Эхо-протокол старта
|
||
|
||
Первый деливерабл — ≤10 строк: «что я понял: скоуп / инварианты / чего НЕ делаю». Расхождение чинится
|
||
на минуте пять, не на приёмке.
|
||
|
||
## 8. Сдача
|
||
|
||
Отчёт `docs/archive/reports/CONTRACT_BATCH_0.3.0_REPORT.md`: записка-план §6.2 с диспозициями ·
|
||
спорные формы с вариантами и твоим выбором · **obstacle reporting — что НЕ удалось/не сделано и
|
||
почему (обязательная секция)** · дифф-сводка «было → стало» по операциям. Без саги. Дерево оставить
|
||
незакоммиченным. Вопросы и конфликты промта с кодом/доками — пинг оркестратору через владельца,
|
||
НЕ интерпретация.
|