architect(ET-006): ADR-002/003, infra-requirements, data-requirements, tech-risks

docs/work-items/ET-006/10-tech-risks.md

@@ -0,0 +1,122 @@
+---
+type: tech-risks
+work_item_id: ET-006
+version: 1
+status: approved
+created_at: 2026-05-22
+authors:
+  - "agent:architect"
+---
+
+# Technical Risks — ET-006
+
+Технические риски этапа разработки. Бизнес-риски — в BRD §5.
+Шкала: вероятность / влияние ∈ {низк., сред., выс.}.
+
+## R-1 — Фриз UI при атомарном парсинге файла 50 МБ
+
+- **Вероятность:** сред. · **Влияние:** низк.
+- `DOMParser.parseFromString` нельзя разбить на чанки; для предельного
+  файла 50 МБ он блокирует основной поток на ~1–2 с (ADR-003).
+- **Митигация:** реалистичные GPX существенно меньше; 50 МБ — потолок
+  валидации, а не норма; чанковая конвертация DOM→GeoJSON снимает
+  доминирующую часть стоимости; CSS-индикатор анимируется композитором.
+- **Статус:** принят. Остаточный риск задокументирован в ADR-003.
+
+## R-2 — Рендеринг трека 500K точек на слабом GPU/мобильном
+
+- **Вероятность:** сред. · **Влияние:** сред.
+- BRD §3 **явно запрещает** упрощение (simplify) точек. Значит штатного
+  рычага снижения нагрузки на рендер нет.
+- **Митигация:** MapLibre оптимизирует GeoJSON line layers; единственная
+  доступная мера — принятие риска бизнесом (simplify вне scope).
+  Если на тестировании обнаружатся фризы pan/zoom — это повод для
+  отдельной задачи, а не для ET-006.
+- **Статус:** принят бизнесом (ограничение BRD).
+
+## R-3 — Исчерпание памяти при накоплении больших файлов
+
+- **Вероятность:** низк. · **Влияние:** сред.
+- TRZ REQ-F-07 не ограничивает число одновременных треков. Несколько
+  файлов по 50 МБ + транзиентные DOM-пики могут исчерпать память вкладки
+  на устройстве с 4 ГБ RAM.
+- **Митигация:** обнулять ссылку на DOM-документ сразу после конвертации
+  (освобождение ~150–300 МБ); не держать исходную строку файла после
+  парсинга. Реалистичный сценарий накопления десятков предельных файлов
+  маловероятен.
+- **Статус:** принят с рекомендацией по управлению памятью разработке.
+
+## R-4 — Дублирование обработчиков событий карты после `setStyle()`
+
+- **Вероятность:** выс. · **Влияние:** сред.
+- REQ-F-13: при смене стиля GPX-слои пересоздаются в `rebuildGpxOverlays()`.
+  Обработчики `map.on('click', layerId, fn)` / `mouseenter` / `mouseleave`
+  при повторной регистрации **накапливаются** — клик по треку начнёт
+  срабатывать многократно, утечка слушателей.
+- **Митигация (для разработки):** перед повторной регистрацией снимать
+  старые обработчики (`map.off(...)` с сохранёнными ссылками на функции)
+  либо регистрировать делегированный обработчик один раз по префиксу ID
+  слоя, а не по конкретному ID. Покрыть тестом I-07.
+- **Статус:** требует внимания на разработке.
+
+## R-5 — Варианты namespace в GPX-файлах
+
+- **Вероятность:** сред. · **Влияние:** низк.
+- При запросе элементов через `getElementsByTagNameNS` файл без `xmlns`
+  вернёт пусто; при запросе без namespace — наоборот, возможны коллизии.
+  TRZ требует работать с GPX и с namespace, и без (тест U-08).
+- **Митигация:** использовать namespace-агностичный обход — сопоставление
+  по `localName` элементов, а не по полному имени с namespace.
+- **Статус:** требует внимания на разработке.
+
+## R-6 — Невалидные координаты ломают `fitBounds`
+
+- **Вероятность:** низк. · **Влияние:** низк.
+- Точки `(0,0)`, NaN или координаты вне диапазона раздувают bbox и портят
+  автоцентрирование (REQ-F-06).
+- **Митигация:** валидировать `lat ∈ [-90,90]`, `lon ∈ [-180,180]`,
+  числовой тип; отбрасывать невалидные точки до построения bbox.
+- **Статус:** требует внимания на разработке.
+
+## R-7 — Z-order GPX-слоёв относительно маршрута OSRM
+
+- **Вероятность:** сред. · **Влияние:** низк.
+- REQ-F-04 / REQ-F-13 / AC-10: GPX-линии должны быть **ниже** активного
+  маршрута OSRM, но выше базовых слоёв — и сохранять этот порядок после
+  `setStyle()`. Маршрут (`route-line-*`) и GPX рисуются в разных функциях;
+  порядок их вызова в `rebuildMapOverlays()` определяет итоговый z-order.
+- **Митигация:** добавлять GPX line layer с явным `beforeId` — перед
+  слоями маршрута, если они есть; иначе поверх базовых. Не полагаться на
+  порядок вызовов в `rebuildMapOverlays()`. Покрыть тестом I-06.
+- **Статус:** требует внимания на разработке.
+
+## R-8 — Связность `gpx.js` ↔ `app.js` через глобали
+
+- **Вероятность:** низк. · **Влияние:** низк.
+- `gpx.js` зависит от глобалей `app.js` (`window._map`, `openSheet`,
+  `closeSheet`, `showToast`); `app.js` вызывает `rebuildGpxOverlays()`.
+- **Митигация:** контракт интеграции зафиксирован в ADR-002; вызов из
+  `app.js` защищён `typeof`; `gpx.js` подключается после `app.js`.
+- **Статус:** принят (контракт узкий и задокументирован).
+
+## R-9 — Отсутствует переиспользуемый `showToast`
+
+- **Вероятность:** низк. · **Влияние:** низк.
+- Сейчас есть только частный `showRulerToast()` / `#ruler-toast`.
+  ET-006 требует несколько разных сообщений об ошибках.
+- **Митигация:** обобщить toast до `showToast(message)` (ADR-002).
+- **Статус:** принят (мелкий шаред-утиль на этапе разработки).
+
+## Сводная таблица
+
+| ID | Риск | Вер. | Влияние | Статус |
+|----|------|------|---------|--------|
+| R-1 | Фриз при парсинге 50 МБ | сред. | низк. | принят |
+| R-2 | Рендеринг 500K точек | сред. | сред. | принят бизнесом |
+| R-3 | Память при накоплении файлов | низк. | сред. | принят + рекомендация |
+| R-4 | Дублирование обработчиков после setStyle | выс. | сред. | внимание разработки |
+| R-5 | Варианты namespace GPX | сред. | низк. | внимание разработки |
+| R-6 | Невалидные координаты в fitBounds | низк. | низк. | внимание разработки |
+| R-7 | Z-order относительно маршрута OSRM | сред. | низк. | внимание разработки |
+| R-8 | Связность gpx.js ↔ app.js | низк. | низк. | принят |
+| R-9 | Нет переиспользуемого showToast | низк. | низк. | принят |