enduro-trails/docs/work-items/ET-013/12-review.md

type, work_item_id, verdict, version, created_at, updated_at, authors, related

type	work_item_id	verdict	version	created_at	updated_at	authors	related
review	ET-013	APPROVED	18	2026-06-04	2026-06-07	agent:reviewer	ET-013:trz ET-013:adr-017 ET-013:acceptance-criteria ET-013:test-report

Review ET-013 — Перепады высот на z9-z11 (re-run #18)

Re-run #18 (независимая сверка.) Перечитаны TRZ (02-trz.md), AC (03-acceptance-criteria.md), ADR-017, CLAUDE.md. Построчно сверена реализация в рабочем дереве с REQ-F-01..F-21 и решениями ADR-017. Unit-тесты исполнены локально.

Состояние ветки: фича ET-013 уже смержена в main и задеплоена. git diff main...HEAD затрагивает только docs (12-review.md, 13-test-report.md) — кодовая часть в рабочем дереве идентична merged/deployed-состоянию (commits 5be81f9 feat + 099669d whitelist-fix). Нового кода для ревью нет; повторно подтверждаю корректность merged-кода непосредственным чтением файлов и прогоном unit-тестов.

TL;DR

• Branch: feature/ET-013-z9-z11-z8 (фича в main; в ветке — docs).
• Scope: zoom-aware paint hillshade/TRI на z9-z11, понижение UI-минзума hillshade z10→z9, обратно-совместимое расширение applyTerrainLayer, расширение backend-whitelist на tri.
• P0/P1 findings: нет.
• Вердикт: APPROVED.

Соответствие ТЗ (проверено по коду)

REQ	Требование	Статус
F-01/11	updateHillshadeAvailability: zoom < 9 (app.js:3425)	✅ старый < 10 отсутствует в теле функции
F-02	hillshade minzoom=9, paint=HILLSHADE_PAINT (app.js:2825)	✅
F-03	TRI minzoom=5/maxzoom=15, paint=TRI_PAINT (app.js:2826)	✅ minzoom не тронут
F-04	applyTerrainLayer(opacityOrPaint) (app.js:3371-3414)	✅ number→legacy(linear) / object as-is, paint: paint в addLayer
F-05/06/07	HILLSHADE_PAINT opacity 9:0.65→10:0.60→11:0.55→12:0.50→14:0.40; contrast 9:0.40→10:0.35→11:0.30→12:0.15→14:0.00; nearest (app.js:2734-2752)	✅ stops точно по TRZ/ADR
F-08/09	TRI_PAINT opacity z5:0.55,z7:0.65,z8:0.70 (регрессия),z9:0.80,пик z10-z11:0.85,z12:0.75,z15:0.70; nearest (app.js:2755-2768)	✅ stops точно
F-10	hint «Зум 9+» (index.html:60)	✅
F-12	контракт onTerrainCheckbox, persistence localStorage, .active	✅ без изменений сигнатуры/логики
F-13/14	unit-тесты (Вариант B, Python-парсер) + регрессии	✅ 17/17 PASS локально (0.03 s)
F-15	integration smoke z9 (test_terrain_z9_tiles.py) с skipif	✅ присутствует, whitelist/404-регрессии работают без данных
F-18	API контракт /terrain/{layer}/{z}/{x}/{y}.png, Cache-Control: public, max-age=31536000, immutable (main.py:1252-1264)	✅ контракт сохранён
F-19	style.json/style-dark.json/app.css/config не тронуты	✅

Соответствие ADR-017

• Реализация точно следует P-A (frontend paint-калибровка): zoom-aware paint через interpolate ['linear'] ['zoom'], 0 перегенерации тайлов, 0 новых слоёв/источников/endpoint'ов. ✅
• O-B (linear-stops), C-A (contrast только hillshade), R-A (nearest глобально), U-A (UI-порог z9 + source.minzoom=9), A-A (обратно-совместимая сигнатура), M-A (константы рядом с TERRAIN_BASE_URL в app.js) — все соблюдены. ✅
• Отклонённые «жирные» альтернативы (z-factor 2.5, raster-dem, theme-specific paint) корректно вынесены в follow-up (TD-1..TD-5). ✅

Findings

#	Severity	Файл	Описание	Статус
N-1	P3 (info)	src/api/main.py:1252	TRZ §2 декларировал backend «без изменений», но в whitelist добавлен tri (("hypso","hillshade","tri"), commit 099669d). Это необходимый багфикс: в dev-режиме (FastAPI без nginx) запросы /terrain/tri/... иначе возвращали бы 404 «Unknown layer». Контракт endpoint'а (URL-шаблон, коды ответа, Cache-Control: immutable, отсутствие новых query/headers) не нарушен → REQ-F-18 соблюдён. Покрыто integration-регрессией test_known_terrain_layer_accepted_by_whitelist (parametrize по hypso/hillshade/tri) + парным test_unknown_terrain_layer_returns_404. Документировано в docstring endpoint'а. Не дефект.	Принято.

Качество кода

• applyTerrainLayer расширен обратно-совместимо; ветвление typeof opacityOrPaint === 'number' собирает legacy-paint (raster-opacity + linear) либо пробрасывает object as-is. JSDoc/коммент на месте.
• HILLSHADE_PAINT/TRI_PAINT вынесены рядом с TERRAIN_BASE_URL с пояснением логики stops; конфигурируемость через env/config справедливо отвергнута (калибровка живёт в коде, ADR-017 M-A).
• Дублирования, необработанных ошибок, мёртвого кода не выявлено.

Качество тестов

• Unit (17): opacity/contrast stops + монотонность, nearest, регрессия z8=0.70, пик z9-z11≥0.80, обратная совместимость applyTerrainLayer (number→linear legacy / object as-is), порог zoom < 9 (+ отсутствие zoom < 10), текст hint «Зум 9+», число call-site, привязка paint-константы и minzoom к каждому слою. Парсер устойчив к пробелам/переносам. 17/17 PASS локально.
• Integration: TestClient против src.api.main:app; тайло-зависимые кейсы параметризованы по слоям (hillshade/tri) и зумам (9/10/11), skipped при отсутствии PH-6 данных; whitelist/404/Cache-Control — регрессии работают всегда (без локальных PNG). Адекватно.

Замечание по статусу тестирования (вне content-review)

Test Report фиксирует blocker на AC-19/REQ-F-20 §1: на test-среде отсутствуют нарезанные z9-тайлы hillshade (PH-6 data). Это инфраструктурный дефект данных/деплоя, не дефект кода ET-013 — код корректно запрашивает z9 hillshade, unit/integration/lint зелёные. Разблокировка — зона Деплой/Инфра (догенерить data/terrain/hillshade/9/*

• повторный AC-19/Playwright), не Review. Кодовых P0/P1 не порождает.

Вердикт

Нет P0/P1. Реализация полностью соответствует TRZ и ADR-017, тесты адекватны и зелёные (17/17). APPROVED.