222 lines
11 KiB
Markdown
222 lines
11 KiB
Markdown
---
|
||
type: review
|
||
work_item_id: ET-014
|
||
verdict: APPROVED
|
||
version: 1
|
||
---
|
||
|
||
# Review ET-014 — Z-index конфликт terrain-popup vs sheet-gps-filters
|
||
|
||
**Branch:** `feature/ET-014-ui-z-index`
|
||
**Commit:** `39348f6 fix(ui): terrain-popup закрывается при открытии bottom-sheet (ET-014)`
|
||
**Reviewer:** agent:reviewer
|
||
**Date:** 2026-06-04
|
||
|
||
## TL;DR
|
||
|
||
Реализация **полностью соответствует** ADR-019 (Вариант A): новый
|
||
helper `closeTerrainPopup()` + один вызов первой строкой в `openSheet()`
|
||
после null-check. CSS / HTML / backend не затронуты. 8 JS unit-тестов
|
||
+ 9 Python (статика + node `--test` wrapper) — **все зелёные**.
|
||
Z-stack `marker-dialog` (500), `search-panel` (600), `ruler-info` (600),
|
||
`.bottom-sheet` (400), `#sheet-backdrop` (390), `.terrain-popup` (500)
|
||
без изменений — статический тест это гарантирует.
|
||
|
||
P0/P1 не выявлено. Два P2/P3 нита (см. ниже) не блокируют приёмку.
|
||
|
||
## Проверенные оси
|
||
|
||
| Ось | Статус | Комментарий |
|
||
|-----|--------|-------------|
|
||
| Соответствие ТЗ (REQ-F-01..07, REQ-NF-01..05) | ✅ | Все требования закрыты, см. ниже |
|
||
| Соответствие ADR-019 | ✅ | Реализация байт-в-байт совпадает с §Решение |
|
||
| Качество кода | ✅ | Стиль файла, комменты, маркеры блока, ссылки на ADR |
|
||
| Качество тестов | ✅ | 8 поведенческих + 5 статических + 1 wrapper |
|
||
|
||
### Соответствие ТЗ (02-trz.md → src/web/app.js)
|
||
|
||
| Требование | Покрыто | Где |
|
||
|------------|---------|-----|
|
||
| REQ-F-01 (sheet не перекрыт popup'ом) | ✅ | `closeTerrainPopup()` в `openSheet()`; AC-01/02 ⇒ TC-E-01/02 |
|
||
| REQ-F-02 (`.active` снимается с `#terrain-toggle`) | ✅ | `btn.classList.remove('active')` в helper; covered by TC-U-02 |
|
||
| REQ-F-03 (закрытие фильтров → возврат к карте) | ✅ | `closeSheet`/`closeAllSheets` не тронуты, ведут себя как раньше |
|
||
| REQ-F-04 (повторное открытие стабильно) | ✅ | unit test `REQ-F-04` |
|
||
| REQ-F-05 (terrain-popup для прочих сценариев — без регрессии) | ✅ | `toggleTerrainPopup`/`closeTerrainOnOutside` не изменены (app.js:2787, 2815) |
|
||
| REQ-F-06 (другие sheets — без регрессии) | ✅ | unit test `REQ-F-06`: для них `closeTerrainPopup` — no-op |
|
||
| REQ-F-07 (свет/тёмная тема) | ✅ | Логика чисто JS, тема-агностична |
|
||
| REQ-NF-01 (backend не трогаем) | ✅ | diff пуст в `src/api/` |
|
||
| REQ-NF-02 (нет тяжёлых обработчиков) | ✅ | helper O(1), вызывается 1 раз на `openSheet` |
|
||
| REQ-NF-03 (marker-dialog/search-panel/ruler-info без регрессии) | ✅ | статический тест `test_z_index_stack_unchanged_for_affected_widgets` |
|
||
| REQ-NF-04 (PWA) | ✅ | n/a, JS-логика не зависит от display-mode |
|
||
| REQ-NF-05 (mobile + desktop) | ✅ | n/a, viewport-агностично |
|
||
|
||
### Соответствие ADR-019
|
||
|
||
ADR §Решение/1 — функция:
|
||
```js
|
||
function closeTerrainPopup() {
|
||
const popup = document.getElementById('terrain-popup');
|
||
const btn = document.getElementById('terrain-toggle');
|
||
if (!popup || popup.style.display === 'none') return;
|
||
popup.style.display = 'none';
|
||
if (btn) btn.classList.remove('active');
|
||
document.removeEventListener('click', closeTerrainOnOutside);
|
||
}
|
||
```
|
||
**Реализация — байт-в-байт совпадает** (`src/web/app.js:211-218`).
|
||
|
||
ADR §Решение/2 — вызов первой строкой после null-check:
|
||
```js
|
||
function openSheet(id) {
|
||
const sheet = document.getElementById(id);
|
||
if (!sheet) return;
|
||
closeTerrainPopup(); // ← вставлено
|
||
document.querySelectorAll('.bottom-sheet.open').forEach(...);
|
||
...
|
||
}
|
||
```
|
||
**Реализация — точно** (`src/web/app.js:220-232`). Порядок проверен статическим
|
||
тестом `test_open_sheet_calls_close_terrain_popup_first` (null-check →
|
||
closeTerrainPopup → closeSheet → classList.add).
|
||
|
||
ADR §Решение/3 (`closeTerrainOnOutside` не меняется) — подтверждено, `app.js:2815`
|
||
без изменений. ADR §Решение/4 (`togglePublicTracksFiltersSheet` не меняется) —
|
||
подтверждено статическим тестом `test_gps_tracks_js_not_touched_by_et014`.
|
||
|
||
### Качество кода
|
||
|
||
Положительное:
|
||
- Блок обрамлён маркерами `// >>> ET-014 sheet-popup yield block` / `<<<` —
|
||
делает блок переиспользуемым для JS unit-тестов через `Function()` факторинг
|
||
(тот же приём, что в ET-007 `base_layer.test.js`, прецедент закреплён).
|
||
- Комментарий в `openSheet()` ссылается на ADR-019 — следующий читатель
|
||
кода не будет гадать, зачем эта строка.
|
||
- Helper не имеет побочных эффектов сверх документированных в ADR.
|
||
- Стиль (отступы, кавычки, naming) повторяет окружающий код.
|
||
|
||
Замечания: см. P2/P3 ниже.
|
||
|
||
### Качество тестов
|
||
|
||
`tests/unit/sheet_popup.test.js` (8 node `--test` кейсов):
|
||
1. TC-U-02 — popup закрывается, `.active` снимается ✓
|
||
2. REQ-F-04 — повторное открытие стабильно ✓
|
||
3. REQ-F-06 — для других sheets helper срабатывает (no-op) ✓
|
||
4. closeTerrainPopup — no-op если popup уже скрыт ✓
|
||
5. closeTerrainPopup — отписывает `closeTerrainOnOutside` ✓
|
||
6. closeTerrainPopup — безопасен при отсутствии `#terrain-popup` ✓
|
||
7. openSheet — ранний выход если sheet не найден ✓
|
||
8. openSheet — закрывает другие sheets через `closeSheet` ✓
|
||
|
||
`tests/unit/test_sheet_popup.py` (9 pytest-кейсов):
|
||
- 5 статических (маркеры, helper-в-блоке, порядок вызовов в openSheet,
|
||
z-stack неизменён, gps_tracks.js не тронут)
|
||
- 1 wrapper (запускает node-тесты)
|
||
- 2 на `index.html` / порядок-once
|
||
|
||
**Все 17 тестов проходят локально**:
|
||
```
|
||
node --test: pass 8, fail 0 (73 ms)
|
||
pytest: 9 passed (0.11 s)
|
||
```
|
||
|
||
E2E (TC-E-01..06, TC-UI-01..08) — Playwright-инфра в репо отсутствует;
|
||
Python-файл явно документирует skip и поведенчески покрывает суть через
|
||
JS unit-тесты. Это валидное решение для текущего CI (matched ADR-017 / ET-013
|
||
precedent).
|
||
|
||
## Findings
|
||
|
||
### P0 (blocker)
|
||
|
||
Нет.
|
||
|
||
### P1 (must-fix)
|
||
|
||
Нет.
|
||
|
||
### P2 (should-fix)
|
||
|
||
**F-1 [P2] — Отсутствует запись в CHANGELOG.md под `[Unreleased]`.**
|
||
|
||
В проекте есть устойчивая конвенция: ET-008/009/010/012/013 — все имеют
|
||
`Added`/`Changed`/`Fixed` записи в CHANGELOG под `[Unreleased]` с
|
||
`Refs: ET-XXX`. У ET-014 — нет. Хотя CLAUDE.md не делает это явным
|
||
требованием, проектная конвенция говорит «обновлять». Deployer / следующий
|
||
агент, формирующий тег, не увидит изменение и не сможет включить его в
|
||
release-note.
|
||
|
||
Рекомендация: добавить под `### Fixed` (новая категория, корректная для
|
||
bug-fix) что-то вроде:
|
||
|
||
```
|
||
### Fixed
|
||
- ET-014: Панель «Фильтры публичных треков» (#sheet-gps-filters)
|
||
больше не открывается под панелью слоёв (#terrain-popup).
|
||
При открытии любого .bottom-sheet через openSheet() popup
|
||
принудительно закрывается (helper closeTerrainPopup в src/web/app.js).
|
||
Z-index стек (.bottom-sheet=400, .terrain-popup=500, #marker-dialog=500,
|
||
#search-panel=600, #ruler-info=600) не изменён — нулевой риск регрессии
|
||
стека. ADR-019. Refs: ET-014.
|
||
```
|
||
|
||
Severity P2 (не блокирует merge, но желательно поправить до деплоя).
|
||
|
||
### P3 (nice-to-have)
|
||
|
||
**F-2 [P3] — TD-1 из ADR-019 не закрыт (опционально).**
|
||
|
||
ADR-019 §Технический долг/TD-1 предлагает DRY-рефакторинг
|
||
`closeTerrainOnOutside` на вызов нового `closeTerrainPopup()`:
|
||
|
||
```js
|
||
// Сейчас (src/web/app.js:2815):
|
||
function closeTerrainOnOutside(e) {
|
||
const popup = document.getElementById('terrain-popup');
|
||
const btn = document.getElementById('terrain-toggle');
|
||
if (!popup.contains(e.target) && e.target !== btn && !btn.contains(e.target)) {
|
||
popup.style.display = 'none';
|
||
btn.classList.remove('active');
|
||
document.removeEventListener('click', closeTerrainOnOutside);
|
||
}
|
||
}
|
||
|
||
// Можно (тело сжимается до 5 строк):
|
||
function closeTerrainOnOutside(e) {
|
||
const popup = document.getElementById('terrain-popup');
|
||
const btn = document.getElementById('terrain-toggle');
|
||
if (!popup || !btn) return;
|
||
if (!popup.contains(e.target) && e.target !== btn && !btn.contains(e.target)) {
|
||
closeTerrainPopup();
|
||
}
|
||
}
|
||
```
|
||
|
||
ADR явно помечает это как opt-in cleanup («обязательного требования нет»).
|
||
Не блокирует ET-014. Можно сделать отдельным fix-up коммитом сейчас или в
|
||
будущем work-item. **Не делать в рамках review-loop** — попадёт под общее
|
||
правило «reviewer не правит код».
|
||
|
||
## Definition of Done (по 03-acceptance-criteria.md)
|
||
|
||
| DoD-item | Статус |
|
||
|----------|--------|
|
||
| AC-01..14 на test-среде | ⏳ Owner-verify (e2e не автоматизирован, см. выше) |
|
||
| `make test` зелёный | ✅ Локально pytest + node --test зелёные; CI должен подтвердить |
|
||
| `make lint` зелёный | ⏳ Не проверил локально (нет make), CI проверит |
|
||
| Playwright UI tests | ⏳ Не запускаются автоматически (нет инфры в репо) — задокументировано |
|
||
| Owner approve по скриншотам AC-01/02/14 | ⏳ Owner-step |
|
||
|
||
Технически Developer закрыл всё что должен. Остальное — этапы CI / Owner.
|
||
|
||
## Вердикт
|
||
|
||
**APPROVED.**
|
||
|
||
Нет P0/P1. Реализация точно соответствует ADR-019. Тесты покрывают
|
||
поведение и стат-инварианты. Два P2/P3 нита (CHANGELOG, опциональный
|
||
DRY-рефакторинг `closeTerrainOnOutside`) не блокируют merge.
|
||
|
||
Рекомендация перед деплоем: закрыть F-1 (CHANGELOG entry). F-2 — на
|
||
усмотрение Owner / Developer (можно отложить).
|