progcode/editorial/reviews/2027-09-draft.md

Редакторское ревью: сентябрь 2027

Пакет переписан как три самостоятельных технических материала про API-контракты. Исторические slug сохранены, но заголовки, excerpts, body и SVG рассказывают о HTTP-интерфейсах, JSON-валидации и code review API-diff.

Три содержательных прохода

editorial-2027-09-practice-mentor-series

1. Факты и пример: до — фиксированный literal о навыке и отсутствии наблюдения; после — validateCustomerResponse с обязательными id, revision, state, положительной и отрицательной ветками. Причина: пример должен проверять форму HTTP-ответа, а не редакционный статус.
2. Структура и голос: до — абстрактное рассуждение о развитии; после — проблема несовместимого ответа и стоимость rollback стоят в первых двух абзацах, затем идут таблица breaking changes, причина, действие и ограничение. Причина: читателю нужен инженерный маршрут.
3. Визуал и доступность: до — «карта навыка»; после — схема Endpoint → Форма → Потребитель с русскими <title> и <desc>, содержательными alt и caption. Причина: рисунок теперь объясняет границу API, а не внутренний процесс.

editorial-2027-09-mechanism-mentor-series

1. Факты и пример: до — evaluator для skill map; после — validateFilterInput, который показывает диапазон limit, enum state и безопасное значение по умолчанию. Причина: отделить JSON-форму от бизнес-инварианта и состояния.
2. Структура и голос: до — обещание карты уровня; после — три слоя валидации, матрица статусов 400/409/403, порядок проверки и явное ограничение JSON Schema. Причина: «valid» больше не скрывает различие между документом и операцией.
3. Визуал и доступность: до — practice/review matrix; после — матрица «форма → инвариант → состояние → право» с русскими title/desc и подписью. Причина: визуальный объект должен помогать выбрать класс ошибки.

editorial-2027-09-field-mentor-series

1. Факты и пример: до — hand-off самостоятельности; после — classifyApiChange, который различает удаление поля, новое required-поле и сужение enum. Причина: code review должен иметь наблюдаемое правило классификации diff.
2. Структура и голос: до — мета-описание передачи; после — маршрут от API-diff к consumer tests, compatibility matrix, expand/contract и rollback. Причина: действие и ограничение должны следовать из риска совместимости.
3. Визуал и доступность: до — петля назначения владельца; после — схема Diff → Класс риска → Потребители → Expand/switch/contract с веткой остановки. Причина: схема показывает обратимость миграции и читается на узком экране.

Источники и границы применения

• OpenAPI Specification 3.1.1, 24 октября 2024 года: структура HTTP-интерфейса; не доказывает runtime-ответ.
• JSON Schema Core 2020-12, draft 2020-12: форма JSON; не проверяет права и состояние базы.
• RFC 9110, июнь 2022 года: HTTP-методы, статусы и представления; не описывает конкретный сервис.

Проверки

• node --check scripts/upgrade-2027-09.mjs — PASS.
• node scripts/upgrade-2027-09.mjs --verify-fixture — PASS, 9/9.
• npm run audit:draft -- scripts/upgrade-2027-09.mjs — PASS, 6140 / 6119 / 6027 body chars по отчёту audit.
• npm run audit:articles -- editorial-2027-09-practice-mentor-series editorial-2027-09-mechanism-mentor-series editorial-2027-09-field-mentor-series — PASS.
• xmllint --noout и SVG safety scan — PASS для трёх существующих assets.
• Ручная проверка Sharp 375 px выполнена после общего рендера; обрезаний и наложений нет.