---
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 (можно отложить).
