ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadminandClaude Fable 5 f59b6d128f docs(generator): issue 09 и 10 дооформлены до ready-for-agent

- Зачем:
  - закрыть последний шаг триажа: без Acceptance criteria и способа приёмки
    задачи нельзя передавать Codex на исполнение.
- Что:
  - issue 09: причина уточнена по коду (расходится источник фактуры — донор
    против seed_click_id, а не индекс), зафиксировано решение хранить донора
    в state, критерии расширены полями location (referer, utm) по итогам ревью.
  - issue 10: приёмка по скриншотам playwright-cli с определением «читаемо»,
    поправлена длительность пересборки (6 часов по умолчанию, не 2 суток),
    отмечено, что legacy world_map, похоже, не умеет легенду и tooltip.
  - handoff триажа дополнен сдвигами в понимании и итогом тройного ревью.
- Проверка:
  - утверждения по коду сверены с generation.py, runtime.py, state.py и
    sql/ddl/dds/30_dds.sql двумя независимыми ревью-агентами.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-04 17:04:18 +03:00

7.6 KiB

Raw Blame History

Status: ready-for-agent

Гео-карта на дашборде нечитаема

Parent

.scratch/generator-model-time-startup-history/PRD.md (раздел «Финальная ручная приёмка»: если панелей не хватает для просмотра — отдельная задача на панель).

Что нашли

На финальной ручной приёмке (шаг 2 спеки) виджет «🌍 Geography Map» показывает что-то, но прочитать нельзя:

нет всплывающих подсказок (tooltip) — навёл на страну, значения не видно;
нет легенды и подписи шкалы — непонятно, что кодирует цвет и в каких единицах;
цветовая шкала неочевидна — подсвечено мало стран, остальное пусто.

График рисуется, но непонятно, что именно он показывает.

Две разные причины (не путать)

Читаемость визуализации (эта задача). Сделать так, чтобы у графика были tooltip, легенда и подпись метрики/единиц и понятная цветовая шкала — либо настройкой текущего чарта, либо заменой карты (choropleth — карта, где страна закрашена по значению) на более читаемую форму, например топ-N стран столбцами, потому что распределение сильно разрежено. Важно: сейчас это legacy-виз world_map (superset/create_dashboard.py:149-164), и у него, судя по параметрам, легенда и tooltip вообще не настраиваются — скорее всего, основной путь именно смена типа визуализации, а не подкрутка текущего. Возможности виз-типов уточнить по актуальной документации Superset через Context7 (правило AGENTS.md) и зафиксировать выбор.
Перекос гео-данных (отдельно). Сама гео-фактура (значения стран в событиях) берётся из статического сида (geo_by_click_id), и на приёмке распределение стран оказалось сильно перекошенным — закрашено мало стран. Опора на чужой сид — осознанно временная (ADR-0006: своя гео-фактура — отдельный будущий шаг); лечится это генерацией гео, а не настройкой чарта. Здесь не решаем, только отмечаем как смежную причину.

Acceptance criteria

У гео-графика есть tooltip со значением по стране (на выбранном типе визуализации — карте или замене).
Есть легенда и подпись: какая метрика и в каких единицах кодируется (для текущей метрики COUNT(*) честный ответ — «событий, штук»).
Выбранный тип визуализации читаем на текущем (разреженном) распределении; выбор типа (оставить карту или заменить) зафиксирован с коротким «почему».
Зафиксировано, что перекошенное распределение стран — свойство гео-фактуры из сида (своя генерация гео — отдельный шаг по ADR-0006), а не настройки чарта.
Приёмка пройдена по скриншотам (см. «Как принимать» ниже), скриншот «после» приложен к итогам задачи.

Как принимать (дописано 2026-07-04)

Проверка визуальная, через скриншоты playwright-cli (так уже делали в спеке редизайна дашборда docs/specs/2026-06-06-superset-dashboard-redesign.md):

Скриншоты «до» и «после»: кадр виджета целиком, плюс кадр с наведением курсора на закрашенную страну / столбец (виден tooltip).
«Читаемо» значит: по кадру виджета целиком (без обращения к SQL и коду чарта) можно ответить на три вопроса — какая метрика показана, в каких единицах, у какой страны значение больше. Если по кадру ответить нельзя — не принято.
Tooltip — по отдельному кадру с наведением: видно название страны и значение метрики. Кадр с tooltip в headless-прогоне может стабильно не ловиться (tooltip следует за курсором); тогда допустим другой способ показать tooltip (например, короткая запись экрана) — согласовать с человеком, молча не ослаблять.

Состояние стенда: стенд не трогали с 2026-06-14 и он мог умереть. Это нормально: полная пересборка (make generated-history-analytics) заново генерирует backfill. По умолчанию она даёт 6 часов модельной истории (GEN_MODEL_T_END в scripts/run_generated_history_analytics.sh) — для приёмки читаемости этого достаточно. Если нужен вид как на исходной находке (2 суток), переопределить GEN_MODEL_T_END на T0+2 суток при запуске; профиль «2 суток одной командой» — это ещё не сделанная задача 11, здесь её не делать. Портативный артефакт (задача 07) для этой задачи не нужен и не блокирует её.

Notes

Всплыло на просмотре дашборда на данных генерации (2 суток backfill).
Смежные документы: superset/create_dashboard.py (определение чарта), docs/SUPERSET_DASHBOARD.md — при смене типа визуализации обновить в этом же изменении.
Возможно, стоит расширить до общего прохода по читаемости дашборда (легенды и подсказки у других виджетов), но базово задача — про гео-карту. Если проход делается, он не должен раздувать задачу: заметил — запиши отдельным issue.
Рекомендуемый режим ревью по coordinator-loop: обычный (риска для state и данных нет, правка ограничена определением чарта и документацией).

7.6 KiB Raw Blame History