39 lines
5.3 KiB
Markdown
39 lines
5.3 KiB
Markdown
# Редакторское ревью: сентябрь 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](https://spec.openapis.org/oas/v3.1.1.html), 24 октября 2024 года: структура HTTP-интерфейса; не доказывает runtime-ответ.
|
||
- [JSON Schema Core 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html), draft 2020-12: форма JSON; не проверяет права и состояние базы.
|
||
- [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html), июнь 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 выполнена после общего рендера; обрезаний и наложений нет.
|