revise June and August 2019 articles

editorial/reviews/2019-06-draft.md

@@ -0,0 +1,127 @@
+# Июнь 2019 — тройное ревью чернового пакета П16 «Контракт REST API»
+
+Статус: **принят в публикационный слой 31 июля 2026 года**. Registry
+накладывает три ревизии по стабильным slug и сохраняет дату и автора базового
+архива:
+
+- <code>editorial-2019-06-practice-rest-api</code>;
+- <code>editorial-2019-06-mechanism-rest-api</code>;
+- <code>editorial-2019-06-field-rest-api</code>.
+
+Созданы только:
+
+- <code>web/scripts/upgrade-2019-06.mjs</code>;
+- <code>web/public/assets/editorial/2019/rest-api-contract-map-2019.svg</code>;
+- <code>web/public/assets/editorial/2019/rest-api-response-matrix-2019.svg</code>;
+- <code>web/public/assets/editorial/2019/rest-api-contract-fixture-2019.svg</code>;
+- этот файл.
+
+Модуль экспортирует ровно три ревизии. В ревизиях нет <code>date</code> и
+<code>author</code>: это исторические поля исходных публикаций, а не черновика.
+При вызове с <code>--print-revisions</code> stdout содержит только JSON.
+Отдельный <code>--run-fixture</code> запускает локальную проверку заранее
+заданных объектов ответа; он не делает HTTP-запрос, не запускает сервер и не
+является проверкой production.
+
+## Проход 1. Факты и техника — пройдено
+
+| Утверждение или решение | Первичный источник | Проверенная граница |
+| --- | --- | --- |
+| HTTP-код и представление ответа — часть результата операции | [IETF RFC 7231, раздел 6](https://www.rfc-editor.org/rfc/rfc7231#section-6) | В текст не введён флаг ошибки внутри 200 как замена HTTP-статуса |
+| Problem detail содержит type, title, status, detail, instance; расширения принадлежат API | [IETF RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) | <code>errors</code> помечен как project extension, а не как универсальное поле стандарта |
+| OpenAPI 3.0.2 описывает operation, responses, content и schema | [OpenAPI 3.0.2](https://spec.openapis.org/oas/v3.0.2.html) | Версия существовала в 2019 году; не использованы более поздние возможности |
+| required-property и nullable-value — разные условия | [OpenAPI 3.0.2, Schema Object](https://spec.openapis.org/oas/v3.0.2.html#schema-object) | <code>page.nextCursor</code> обязателен и допускает null; <code>customer</code> либо отсутствует, либо является объектом |
+| HTTP не навязывает конкретную pagination форму | [IETF RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) | cursor и object page названы проектным выбором; Link header назван альтернативой, а не проигнорирован |
+
+Учебные snippets и fixture не ссылаются на настоящий сервис, токен, URL
+production или якобы выполненный сетевой сценарий. В CLI с
+<code>--run-fixture</code> есть три локальных case:
+
+1. 200 / JSON с последней страницей и явным <code>nextCursor: null</code>;
+2. 400 / problem+json с <code>invalid_cursor</code>;
+3. отрицательный 200 / JSON без <code>nextCursor</code>, который обязан быть
+   отклонён.
+
+Итог первого прохода: технические утверждения привязаны к HTTP, RFC 7807 и
+исторически уместному OpenAPI 3.0.2; тест не объявлен серверным или
+production-доказательством.
+
+## Проход 2. Редактура и голос М2 — пройдено
+
+| Проверка | Практика | Механизм | Полевой разбор |
+| --- | --- | --- | --- |
+| Ранняя постановка симптома и цены | Падение, неверная страница и спор слоёв | Тихая поломка при семантически другом JSON | UI не знает, как трактовать распарсенный ответ |
+| Рабочая цепочка | Симптом → причина → контракт → fixture → действие | Симптом → Operation/Responses/Schema → совместимость | Симптом → cases → fixture → запрос к стенду |
+| Техническая речь | Статус, media type, cursor, optional field | HTTP, OpenAPI 3.0.2, required, nullable | Response objects, negative case, headers, body |
+| Объём основного текста | Подтверждается draft gate | Подтверждается draft gate | Подтверждается draft gate |
+
+Голос соответствует М2 / 2019: автор уже связывает frontend, backend и HTTP,
+но не имитирует инструменты и практики 2027 года. Текст не обещает
+«универсальный REST», не называет обычный JSON доказательством успеха и не
+подменяет конкретные условия общими оценками. В каждой статье есть не менее
+пяти смысловых разделов, доступная таблица, код, порядок действий, визуал,
+источники и ограничения.
+
+Итог второго прохода: три текста держат прагматичный формат «симптом →
+причина → проверка → действие» и не раздувают тему за счёт общих вступлений.
+
+## Проход 3. Визуал и выпускная дисциплина — пройдено для автономного пакета
+
+| Артефакт | Назначение | Проверка доступности и выпуска |
+| --- | --- | --- |
+| <code>rest-api-contract-map-2019.svg</code> | Вход операции и развилка 200/400 | Есть title, desc, содержательный alt, подпись; SVG без script |
+| <code>rest-api-response-matrix-2019.svg</code> | Связь Operation, Responses и Schema | Есть title, desc, содержательный alt, подпись; SVG без script |
+| <code>rest-api-contract-fixture-2019.svg</code> | Граница локальной fixture и сетевой проверки | Есть title, desc, содержательный alt, подпись; SVG без script |
+
+### Выполненные проверки
+
+~~~text
+node --check web/scripts/upgrade-2019-06.mjs
+cd web && npm run audit:draft -- scripts/upgrade-2019-06.mjs
+node web/scripts/upgrade-2019-06.mjs --run-fixture
+xmllint --noout \
+  web/public/assets/editorial/2019/rest-api-contract-map-2019.svg \
+  web/public/assets/editorial/2019/rest-api-response-matrix-2019.svg \
+  web/public/assets/editorial/2019/rest-api-contract-fixture-2019.svg
+~~~
+
+Результат 31 июля 2026 года:
+
+- <code>node --check</code> — код 0;
+- draft gate — три PASS: практика 9 266, механизм 10 792, полевой разбор
+  10 300 знаков основного текста;
+- <code>--run-fixture</code> — три PASS: финальная 200-страница с
+  <code>nextCursor: null</code>, 400 problem detail с
+  <code>invalid_cursor</code> и обязательное отклонение 200 без
+  <code>nextCursor</code>;
+- <code>xmllint --noout</code> — код 0 для трёх SVG;
+- проверка завершающих пробелов не нашла совпадений.
+
+SVG дополнительно прочитаны как выпускные артефакты: у каждого есть
+самодостаточные <code>title</code> и <code>desc</code>, все блоки, стрелки и
+подписи размещены внутри viewBox 900×760. У первой схемы длинная итоговая
+подпись разбита на две строки. CSS статьи выводит figure-image по ширине
+контейнера, а таблицы имеют горизонтальную прокрутку. Это статическая
+проверка разметки и геометрии; в журнал не приписывается вымышленный
+browser-render, server run или production build. Перед публикацией основной
+редактор должен отдельно
+подключить ревизии к registry, повторить strict audit вместе с архивом,
+построить production-сайт и проверить реальные страницы на широком и узком
+экране, сохранив исходные дату и автора.
+
+После подключения registry основной редактор повторил strict audit: все три
+slug прошли объём 9 266 / 10 792 / 10 300 знаков, figure, таблицы, код,
+маршруты и источники. <code>npm run build</code> завершился с кодом 0 и
+сгенерировал 374 статические страницы.
+
+Выпусковой вердикт: **принят к публикации**. <code>articles.json</code> не
+менялся; registry заменяет только редакционные поля по стабильному slug.
+
+### Независимый мобильный preflight
+
+Основной редактор отдельно отрендерил все три SVG через Sharp на ширине 720 и
+375 px. Первый вариант не обрезался, но его подписи были слишком мелкими при
+375 px. Все три схемы заменены на вертикальные композиции с короткими
+подписями; повторный рендер подтвердил читаемые главные метки, отсутствие
+обрезания и горизонтального overflow. Это проверка SVG-артефактов, а не
+заявление о browser-render или сетевом production-тесте.