---
type: tech-risks
work_item_id: ET-014
title: "Технические риски — ET-014: Z-index фикс — terrain-popup уступает sheet'у"
version: 1
status: approved
created_at: 2026-06-04
authors:
  - "agent:architect"
---

# Технические риски — ET-014

Технические риски фикса z-index конфликта `#terrain-popup` ↔
`#sheet-gps-filters`. Бизнес-риски — в BRD §9 (R1..R3). Шкала:
вероятность (Н/С/В) × влияние (Н/С/В).

## R-T-1 — `closeTerrainPopup()` падает на ранней загрузке, когда DOM не готов

- **Описание:** Если по какому-то race condition `openSheet()`
  вызывается до того, как `#terrain-popup` / `#terrain-toggle` появятся
  в DOM, `getElementById` вернёт `null`. Helper защищён ранним возвратом
  (`if (!popup || popup.style.display === 'none') return;`), но если
  `btn` `null`, а `popup` есть — `btn.classList.remove` упадёт.
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - **Архитектурное решение (ADR-019 §«Решение»):** в helper'е
    проверка `if (btn) btn.classList.remove('active');`.
  - **DOM-инвариант:** `#terrain-popup` и `#terrain-toggle` — оба
    статически прописаны в `index.html` (строки ~43 и в `#map-controls-r`).
    Они существуют сразу после парсинга HTML, ещё до выполнения
    `app.js` (который грузится с `defer`). Реалистичная вероятность
    null — околонулевая.
  - **Acceptance гейт:** AC-09 (TC-UI-05) — все 5 sheet'ов открываются
    последовательно, helper срабатывает 5 раз без ошибок.

## R-T-2 — Двойной `removeEventListener` на `closeTerrainOnOutside`

- **Описание:** При сценарии «открыт popup → клик по ссылке
  Фильтры… → `openSheet(...)` вызвал `closeTerrainPopup()` →
  `removeEventListener` сработал» — а затем пользователь закрывает
  sheet и снова открывает popup, `addEventListener` повесит listener
  заново. Но если `closeTerrainOnOutside` был вызван иначе (например,
  через клик по карте в момент закрытия sheet'а — гипотетически), то
  оба removeEventListener'а отработают над одним и тем же handler'ом.
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - **DOM-спека:** `removeEventListener` на отсутствующий handler —
    no-op (silent). Никаких exception'ов.
  - **Архитектурное решение:** helper идемпотентен по построению:
    `if (popup.style.display === 'none') return;` — повторный вызов
    при уже закрытом popup'е выходит мгновенно, без вызовов `remove*`.

## R-T-3 — Регрессия открытия других sheet'ов (sheet-route и пр.)

- **Описание:** Изменение `openSheet` затрагивает 6 sheet'ов: route,
  recon, scenic, link, gpx, gps-filters. Если новый вызов
  `closeTerrainPopup()` имеет побочный эффект для случая «popup закрыт»,
  это сломает все 5 «здоровых» sheet'ов.
- **Вероятность / Влияние:** Н / С.
- **Митигация:**
  - **Архитектурное решение (ADR-019 §«Решение»):** helper строго
    no-op'ит при `popup.style.display === 'none'` (ранний выход первой
    строкой после null-check). При открытии sheet-route/recon/scenic/
    link/gpx popup гарантированно закрыт (нет UI-пути открыть его до
    клика на `#terrain-toggle`, который не задействован в этих
    сценариях).
  - **Acceptance гейт:** AC-09 (TC-UI-05) — открытие всех 5 «здоровых»
    sheet'ов через тулбар. **Обязательный гейт** перед merge.
  - **Sanity unit-тест (опциональный):** статический grep, что в
    `openSheet` ровно один вызов `closeTerrainPopup` (не два, не
    забытый).

## R-T-4 — `display:none` ломает положение popup'а после повторного открытия

- **Описание:** `toggleTerrainPopup()` использует `popup.style.display
  !== 'none'` для определения текущего состояния (`app.js:2775`). Если
  мы скрыли popup через `closeTerrainPopup()`, при следующем клике на
  `#terrain-toggle` функция правильно определит «закрыт» и откроется
  снова. Но если осталась inline `top/right`, popup появится в старой
  позиции — может быть некорректно при resize окна между открытиями.
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - **Архитектурное решение:** `toggleTerrainPopup()` (`app.js:2779-
    2786`) **каждый раз пересчитывает** `top` и `right` из
    `btn.getBoundingClientRect()` при открытии. Никакой stale-позиции
    не остаётся.
  - **Acceptance гейт:** AC-07, AC-08 — повторное открытие popup'а
    после закрытия sheet'а проверяется.

## R-T-5 — Marker-dialog/search-panel/ruler-info регрессии при правке `openSheet`

- **Описание:** `#marker-dialog` (z=500), `#search-panel` (z=600),
  `#ruler-info` (z=600) не относятся к `.bottom-sheet`. Они открываются
  не через `openSheet`, а через свои обработчики
  (`tb-marker`/`tb-search`/`tb-ruler`). Если наша правка случайно
  затронула общий код пути этих виджетов — регрессия.
- **Вероятность / Влияние:** Н / С.
- **Митигация:**
  - **Архитектурное решение (ADR-019 §«Что НЕ меняется»):** правка
    локализована **только** в `openSheet` (вызывается только для
    `.bottom-sheet`). z-index стек не трогается → marker-dialog,
    search-panel, ruler-info остаются на своих местах в стеке.
  - **Acceptance гейт:** AC-10, AC-11, AC-12 (TC-UI-08 + ручные
    проверки search-panel и ruler-info).
  - **REQ-NF-03:** прямое отражение этого риска в TRZ.

## R-T-6 — Старый клиент в кэше браузера получает старый багованный app.js

- **Описание:** Пользователь с открытой вкладкой неделю назад имеет
  закэшированный старый `app.js` без `closeTerrainPopup`. Service
  worker — не настроен в MVP. До reload браузер не дёрнет свежий код.
- **Вероятность / Влияние:** С / Н.
- **Митигация:**
  - **Архитектурное решение:** `src/web/index.html` грузит `app.js`
    напрямую. nginx + стандартный `Cache-Control` на `*.js`
    (не immutable). При reload браузер делает conditional GET → 200
    (свежий) или 304.
  - **Backwards compat:** старый кэшированный клиент с багом
    продолжает работать в багованном режиме, никаких 4xx/5xx нет.
    Никакого hard-reload не требуется — обычный F5 / pull-to-refresh
    подхватит fix.
  - **Долгосрочная митигация:** PWA / SW (PH-9) введёт правильную
    инвалидацию.

## R-T-7 — Пользователь ожидает «возврат к panel слоёв» после закрытия sheet'а

- **Описание:** BRD R2 явно описан: «пользователь может удивиться, что
  панель слоёв сама закрылась». После закрытия фильтров пользователь
  оказывается на карте, а не в panel слоёв. Кому-то это может показаться
  «прыжок UX».
- **Вероятность / Влияние:** С / Н.
- **Митигация:**
  - **Архитектурное решение (ADR-019 §A):** BRD R2 разрешает такое
    поведение: «панель слоёв — точка входа в фильтры, после закрытия
    фильтров пользователь возвращается к карте». Это решение оператора,
    зафиксировано в BRD.
  - **UX-нота для test-report:** оператор фиксирует свои наблюдения
    в `13-test-report.md`.
  - **Fallback (если оператор передумает):** в `closeAllSheets` /
    `closeSheet('sheet-gps-filters')` дополнительно перезапускать
    `toggleTerrainPopup` — но это **существенное** расширение scope и
    требует отдельной задачи (ET-014.1 или новый work-item).

## R-T-8 — Свайп фильтров вниз — popup не возвращается

- **Описание:** Та же концептуальная проблема, что R-T-7, но через
  жест свайпа. Пользователь свайпом закрывает sheet, видит карту, а не
  panel слоёв.
- **Вероятность / Влияние:** С / Н.
- **Митигация:**
  - Та же что R-T-7: BRD R2 это разрешает.
  - **Acceptance гейт:** AC-03 включает чекбоксы внутри sheet'а; свайп
    не тестируется отдельно (он = клик `✕` поведенчески).

## R-T-9 — В будущем кто-то откроет sheet с явным намерением «не закрывать popup»

- **Описание:** Пока такого сценария нет (BRD §8 допускает, что
  единственная точка входа в `sheet-gps-filters` из popup'а — это
  «Фильтры…»). Но если завтра появится «открыть мини-фильтр из popup'а,
  оставив popup открытым», текущее общее правило `openSheet → closeTerrainPopup`
  заблокирует такой сценарий.
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - **Архитектурное решение (ADR-019 §«Технический долг» TD-2):**
    при появлении такого сценария — расширение
    `openSheet(id, opts)` объектом опций с флагом `keepPopup: true`.
    Сейчас — YAGNI.

## R-T-10 — `eslint` падает на новой функции из-за code style

- **Описание:** Если в проекте настроен `eslint` с правилами на
  `prefer-const`, `func-style`, `no-implicit-globals` — новая
  `function closeTerrainPopup()` может не пройти конкретные правила
  стиля.
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - **Архитектурное решение:** другие helper'ы в `app.js`
    (`openSheet`, `closeSheet`, `closeAllSheets`, `closeTerrainOnOutside`)
    объявлены через `function name()` без проблем — значит, eslint
    их пропускает.
  - **Acceptance гейт:** `make lint` зелёный (часть DoD).

## R-T-11 — Playwright TC-UI-* нестабильны на test-среде из-за тайминга

- **Описание:** TC-UI-01..TC-UI-08 используют фиксированные `wait`
  (300-600 мс) после кликов. На загруженной test-среде анимация
  открытия sheet'а (`transition: transform 0.3s`) может не успеть
  завершиться, скриншот будет «полу-открытым».
- **Вероятность / Влияние:** С / Н.
- **Митигация:**
  - **Архитектурное решение:** TC-UI-* — операторские, не CI-blocking
    (см. `04b-ui-test-cases.md`). Оператор делает финальную приёмку.
  - **Tuning:** если CI-прогон нестабилен — поднимать wait'ы до 800 мс
    (мажорная анимация = 300 мс + слабая retry).
  - **Это вне scope ADR-019.**

## R-T-12 — В будущем z-index у `#sheet-backdrop` или `.bottom-sheet` поднимут до >500 без знания о ADR-019

- **Описание:** Кто-то решит «давайте сделаем sheets z=510» (Вариант B),
  не зная, что мы выбрали Вариант A. Тогда правка не сломает ничего
  (она лишь подкрепит fix), но логика становится двойной: и popup
  закрывается, и z-index хитрый. Сложнее понимать систему.
- **Вероятность / Влияние:** С / Н.
- **Митигация:**
  - **Архитектурное решение (ADR-019 §«Альтернативы»):** Вариант B
    зафиксирован как отклонённый. Если кто-то будет менять z-index,
    он прочитает ADR-индекс и увидит запись.
  - **Прецедент:** комментарий в коде `app.js`:
    `// ET-014: terrain-popup yields to any opening sheet (see ADR-019).`

## R-T-13 — Десктоп: после закрытия фильтров пользователь не видит ни popup'а, ни фильтров, ни panel слоёв

- **Описание:** На desktop backdrop скрыт media-query
  (`app.css:543: #sheet-backdrop { display: none; }`). Sheet
  занимает слева ~380 px. После закрытия sheet'а пользователь видит
  чистую карту. Никаких «фантомных» элементов — но и контекста, где
  он только что был, нет.
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - **Архитектурное решение:** это **специально** так — BRD §3
    «после закрытия пользователь возвращается к карте». На desktop
    нет визуальной потери (карта всегда видна, sheet был сбоку).
  - **Acceptance гейт:** AC-02, AC-04.

## R-T-14 — Регрессия повторного открытия popup'а с уже выставленной inline-позицией

- **Описание:** При закрытии через `closeTerrainPopup()` мы выставляем
  `popup.style.display = 'none'`, но не сбрасываем `popup.style.top` и
  `popup.style.right`. При следующем открытии через `toggleTerrainPopup`
  значения top/right пересчитываются, поэтому стейл не страшен. Но
  если кто-то в будущем добавит ветку «открыть popup без
  пересчёта позиции» — может сработать на остатках.
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - **Архитектурное решение:** `toggleTerrainPopup` (`app.js:2779-
    2786`) безусловно пересчитывает `top`/`right` при каждом открытии.
  - **Тест:** AC-08 (TC-UI-07) — popup закрывается кликом вне, потом
    открывается заново; проверка визуальной корректности.

## R-T-15 — Сценарий «открыть фильтры, прокрутить sheet вниз и обратно к popup»

- **Описание:** Пользователь открыл фильтры, popup закрылся. Если бы
  popup остался в DOM-tree «фоном» (например, при z-index решении),
  можно было бы свайпом или ESC вернуться к нему. После
  ET-014 этого пути нет.
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - **Архитектурное решение:** этот сценарий не был доступен и до
    ET-014 (popup `display:block` не позволял прокрутить «к
    popup'у» — он и так был видим). UX не теряет ничего.

## R-T-16 — Service worker в будущем (PH-9) перехватит `app.js`

- **Описание:** Когда PH-9 (PWA) введёт SW, он начнёт кэшировать
  `app.js` в Cache Storage. Деплой ET-014 потребует cache-busting
  стратегии (`?v=`, hash в имени файла или `clients.claim()`+
  `skipWaiting()` в SW).
- **Вероятность / Влияние:** Н / Н.
- **Митигация:**
  - PH-9 — отдельный work-item. К моменту его реализации ET-014 уже
    давно в test/prod, новый SW при первой установке возьмёт свежий
    `app.js`. Никаких специальных действий для ET-014 не нужно.

## Сводная таблица

| #     | Риск                                                              | Вер | Влиян | Митигация (тип)                                    |
|-------|--------------------------------------------------------------------|-----|-------|----------------------------------------------------|
| R-T-1 | `closeTerrainPopup` падает на ранней DOM-загрузке                  | Н   | Н     | null-check в helper; DOM-инвариант; AC-09          |
| R-T-2 | Двойной `removeEventListener`                                       | Н   | Н     | DOM-спека = no-op; идемпотентность helper'а        |
| R-T-3 | Регрессия открытия 5 «здоровых» sheet'ов                            | Н   | С     | Ранний выход no-op; AC-09 = обязательный гейт      |
| R-T-4 | Stale `top/right` у popup'а после reopen                            | Н   | Н     | `toggleTerrainPopup` пересчитывает каждый раз; AC-07 |
| R-T-5 | Marker-dialog/search-panel/ruler-info регрессия                     | Н   | С     | Локализация правки; AC-10/AC-11/AC-12 = REQ-NF-03  |
| R-T-6 | Закэшированный старый `app.js` у пользователей                      | С   | Н     | Conditional GET (If-Modified-Since); backwards compat |
| R-T-7 | UX-удивление «panel слоёв сама закрылась»                           | С   | Н     | BRD R2 разрешает; test-report фиксирует            |
| R-T-8 | Свайп вниз — popup не возвращается                                  | С   | Н     | То же что R-T-7                                    |
| R-T-9 | Будущий сценарий «открыть sheet, не закрывая popup»                 | Н   | Н     | YAGNI; TD-2 в ADR-019                              |
| R-T-10| `eslint` падает на новой функции                                    | Н   | Н     | Существующий стиль `function name()` принят        |
| R-T-11| Playwright TC-UI нестабильны по таймингу                            | С   | Н     | Операторская приёмка; tuning wait'ов               |
| R-T-12| Будущий developer не знает про ADR-019, поднимет z-index            | С   | Н     | ADR в индексе; комментарий в коде                  |
| R-T-13| Desktop: пустая карта после закрытия — нет контекста                | Н   | Н     | Specified by BRD §3                                |
| R-T-14| Stale inline-позиция popup'а                                        | Н   | Н     | Пересчёт в `toggleTerrainPopup` каждый раз         |
| R-T-15| «Возврат к popup'у» через свайп невозможен                          | Н   | Н     | Сценарий не существовал и раньше                   |
| R-T-16| PH-9 (SW) перехватит `app.js`                                       | Н   | Н     | Не задача ET-014; SW при первой установке свежий   |

## Связанные документы

- `01-brd.md` §4 BR-01..BR-06, §9 R1..R3 (бизнес-риски пересекаются)
- `02-trz.md` §2.1 REQ-F-01..REQ-F-07, §2.2 REQ-NF-01..REQ-NF-05, §3 (варианты)
- `03-acceptance-criteria.md` AC-01..AC-14 (все гейты)
- `04b-ui-test-cases.md` TC-UI-01..TC-UI-08
- `06-adr/ADR-019-terrain-popup-yields-to-sheet.md` §«Решение», §«Последствия», §«Технический долг»
- `07-infra-requirements.md` §6 (deploy procedure), §7 (мониторинг)
- `08-data-requirements.md`
- `docs/work-items/ET-013/10-tech-risks.md` — образец «calibration risks» документа (наследие)
