# 🎨 ПІКЕР ВІЗУАЛІЗАЦІЙ — як звіт може виглядати

> **Для замовника:** обери, **яким виглядом** показувати кожен блок. Не вигадуй з нуля — бери готове:
> кожен патерн уже працює в якомусь нашому звіті, тож він точно збереться і виглядатиме як решта.
> **Формат фіксації в ТЗ:** `блок · патерн · як у <звіт> · що на осях/у колонках`.
>
> Інвентар зроблено по коду `web-analytics/static/*.html` + довідникам зовнішніх джерел.
> Обсяг: **30 bar · 22 line · 5 doughnut · 1 box** графіків, теплокарти в 28 звітах, drill-down у 13.

---

## 📊 KPI та зведення

| Патерн | Що це | Коли брати | Як у звіті |
|---|---|---|---|
| **KPI-картки** | Ряд плиток: назва · велике число · підпис. Δ-семафор (🟢/🟡/🔴) | Головні цифри «одним поглядом» угорі | скрізь: `operational`, `weekly`, `merchant-out-in` |
| **KPI + Δ до попереднього** | Те саме + зміна до минулого періоду | Треба бачити динаміку, а не лише рівень | `weekly`, `main-dashboard` |
| **Зони/тири** | Бал → зона `High / Mid / Low` кольором | Порівнювати сутності одним числом | `scoreboard` (≥56 / 34–55 / ≤33), `affiliate-tier` |
| **Банер-алерти** | Смуга вгорі: `⚠️ N сутностей за порогом` + перелік, клік → скрол | Коли треба **привернути увагу**, а не змусити шукати | `capacity`, `merchant-out-in` |

## 📋 Таблиці

| Патерн | Що це | Коли брати | Як у звіті |
|---|---|---|---|
| **Проста таблиця + сортування** | Клік по заголовку сортує | База для будь-якого переліку | усі звіти |
| **Drill-down** | Клік по рядку розгортає дітей (мерчант → кабінети) | Є ієрархія; ⚠️ метрики рахуються **на кожному рівні** | `merchant-out-in`, `trader-detailed`, 13 звітів |
| **Кольорові пігулки** | Значення у бейджі, колір за порогом | Показник із «нормою» (CR, %, конверсія) | `merchant-out-in` (🟢<90 🟡90–100 🔴>100) |
| **Sticky-заголовок** | Шапка й перша колонка не їдуть при скролі | Широка/довга таблиця | 36 звітів |
| **Широкий борд** | Десятки колонок, горизонтальний скрол, групи колонок | Операційний контроль, «усе в одному» | BAM (~107 колонок) |
| **Коридор норми** | Колонка `P25–P75` + позначка виходу за межі | Треба відрізнити «інакше» від «аномально» | `merchant-out-in` |

## 📈 Часові ряди

| Патерн | Що це | Коли брати | Як у звіті |
|---|---|---|---|
| **Лінія по днях** | Класичний тренд | Динаміка за період | `operational`, `churn`, `weekly` |
| **Стовпчики по днях/годинах** | Обсяги | Порівняння дискретних періодів | 30 графіків у наших звітах |
| **Стек-стовпчики** | Розбивка всередині періоду (за категорією) | Показати **структуру**, не лише суму | 17 звітів, напр. втрати за категоріями |
| **Лінія + baseline-коридор** | Факт + пунктирні `P75 / Median / P25` | Видно, чи поточне значення в межах норми | `capacity` |
| **Медіана + смуга P25–P75** | Тренд когорти зі смугою розкиду | Показати «типове» й розкид одночасно | `churn` (когортний тренд) |
| **Факт + прогноз** | Історія + прогнозна лінія (+MAPE) | Планування | `THC`, `lab.dsfrogboard` (forecast) |
| **Погодинний профіль** | 24 точки — доба | Планування змін, пікові години | `trader-hourly-calculator` |

## 🔲 Матриці та теплокарти

| Патерн | Що це | Коли брати | Як у звіті |
|---|---|---|---|
| **Матриця день × година** | Клітинки = інтенсивність кольором | Шукати регулярні провали/піки | `operational` (Matrix) |
| **Теплокарта сутність × година** | Рядок = банк/трейдер, колонка = година IST | Де і коли активність | eye-of-god: `Активні счета` (банк×година), `Автоматика` |
| **Теплокарта сума × година** | Рядок = сумовий бенд, колонка = година | Швидкість/конверсія по «вартості» заявки | eye-of-god: `Heatmap` P90 виплат |
| **Матриця сутність × сутність** | Напр. афіліат × суб-афіліат | Перетини, покриття | `affiliate-weekly` (subaff-matrix) |

## 📉 Розподіли й воронки

| Патерн | Що це | Коли брати | Як у звіті |
|---|---|---|---|
| **Гістограма-бакети** | Стовпчики за діапазонами | Розподіл часу/сум | eye-of-god: `0-10м · 10-20м · … · >12год` |
| **Воронка втрат** | Етапи з відсівом на кожному | Де саме губимо | eye-of-god: `Воронка` (cc_true/false, r_auto), 14 звітів |
| **Кільце (doughnut)** | Частки цілого | 3–6 категорій, не більше | 5 графіків |
| **Box-plot** | Квартилі + викиди | Порівняти розкид між групами | 1 звіт |
| **Сумові бенди** | Розбивка по діапазонах сум | Де концентрується обсяг | `capacity` (покриття по бендах) |

## 🚦 Сигнали та статуси

| Патерн | Що це | Коли брати | Як у звіті |
|---|---|---|---|
| **Δ-семафор** | Зелений/жовтий/червоний за напрямком зміни | Скрізь, де є порівняння | усі звіти |
| **Бейдж-причина в рядку** | `⛔ Alert −40%` замість голого числа | Пояснити, **чому** сутність позначена | `affiliate-tier` |
| **Статус-бейджі** | `ok / warning / critical` | Моніторинг стану | `hermes-load-monitor` |
| **Прапорець аномалії** | `⚠️ вище/нижче норми` + підсвітка рядка | Самонормований поріг (вихід за коридор) | `merchant-out-in` |
| **Фільтр «лише аномальні»** | Тумблер, ховає нормальні рядки | Довгий список, треба лише проблемні | `merchant-out-in` |

## 🌐 Що дає КОЖНЕ джерело (аудит покриття)

> Патерни вище зібрані переважно з наших звітів. Нижче — **що можна підглянути в кожного джерела**,
> щоб не винаходити своє. ⚠️ Це референси **вигляду**, а не готові компоненти: реалізуємо у своєму стилі.

| Джерело | Візуали, які там є | Що варто запозичити |
|---|---|---|
| **CH `hermes`** | — **UI немає**, це шар даних | нічого; звідси беруться **числа**, не вигляд |
| 🥇 **reports.halleg** (наші) | KPI-картки · Δ-семафор · матриця день×година · drill-down · зони/тири · Legend · Hour-to-Hour · sticky-таблиці | **база за замовчуванням** — новий звіт має виглядати як решта |
| **supportzones** | **Conversion by hours** — таблиця `Година · Total · Success · Failure · CR% · Sender CR%` з **порогом-підсвіткою** · **CR по хвилинах** (пульс за останні години) · розбивка по статусах із `% від усіх` · майстер-таблиця провайдерів (~120 полів) · банк-акаунти за балансом | **поріг як підсвітка рядка** (нижче N% — червоним) · **пульс по хвилинах** для «зараз» · статус-розбивка з часткою |
| **eye-of-god** | теплокарта **банк×година** · теплокарта **сума×година** (P90 виплат) · воронка втрат по етапах · гістограма-бакети швидкості (`0-10м…>12год`) · вкладки-секції в сайдбарі (ТРАФІК/САППОРТ/OPERATIONS) · «Вигрузити всі таблиці в Excel» | **теплокарти з двома осями** · **бакет-гістограми** для часу · **групування вкладок у секції**, коли звіт великий |
| **BAM** (`/bam/`) | борд на **~138 колонок** зі sticky-шапкою · вкладки `dashboard · bonuses · sales-index · audit · admin · guide` · CR-бакети (`<1k / 1-5k / 5-10k / ≥10k`) · downtime-timeline · пороги-алерти | **бакетування сутностей за обсягом** (сегменти замість одного середнього) · **timeline простоїв** · вкладка `guide` — довідка всередині борда |
| **lab.dsfrogboard** | ліквідність (inline-таблиці `l0–l9`) · **прогноз + MAPE** · диспути-лічильники · «дії» | **прогнозна лінія з оцінкою точності** — коли планують, а не констатують |
| **OPS** (`‹зовнішня панель›`) | `exc-dashboard` — таблиця по мерчантах `Total · Success · **Topup INR**` за період | компактна **зведена таблиця по сутностях** без графіків, коли треба «швидко звірити» |

> 📌 **Кейс-нагадування:** саме з OPS-таблиці ми взяли колонку `Topup INR` → звірка **5/5** → і це стало
> формулою входу для Exchange. Тобто чужий борд іноді дає не лише вигляд, а й **сенс метрики**.

## 🧩 Обовʼязкові елементи скелета (не патерн — правило)

- **Вкладки-періоди** (1/7/14/30) або **календар з–по** — один механізм, не два.
- **Слайсери**: Affiliate · Manager · Status · Group · Trader + «Clear all».
- **Валюта ₹/$** — конвертація показу, **не** фільтр даних.
- **Legend** угорі (під фільтрами) + **tooltip на кожній колонці** з формулою **і числами рядка**.
- **Hour-to-Hour ★** — чесне порівняння неповного періоду.
- **LastRefresh + Update**, експорт в Excel (числа — числовим форматом).

---

## Як обирати (коротко)

| Питання замовника | Патерн |
|---|---|
| «Скільки всього?» | KPI-картки |
| «Як змінюється?» | лінія / стовпчики по днях |
| «З чого складається?» | стек-стовпчики або кільце |
| «Коли саме?» | погодинний профіль або матриця день×година |
| «Хто відхиляється?» | таблиця + коридор + прапорець аномалії + банер |
| «Де губимо?» | воронка втрат |
| «Це нормально чи ні?» | baseline-коридор P25–P75 |
| «Хто кращий?» | зони/тири або сортована таблиця з пігулками |

---

## 🖼️ Макет (HTML без бекенду) — шаблон-заготовка

Перед ТЗ показуємо, **як це виглядатиме**. Мінімальний каркас, який лишається в нашому стилі:

```html
<div style="background:#0f1117;color:#e4e6ef;font-family:'Segoe UI',system-ui;padding:16px 20px">
  <div style="background:rgba(245,158,11,.12);border:1px solid #f59e0b;border-radius:8px;
              padding:10px 16px;margin-bottom:14px;font-size:.85rem">
    🖼️ <b>МАКЕТ</b> · дані вигадані · бекенду немає · це лише вигляд
  </div>
  <!-- KPI-ряд -->
  <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px">
    <div style="background:#181c25;border:1px solid #272d3d;border-radius:10px;padding:14px">
      <div style="font-size:.64rem;color:#7b8094;text-transform:uppercase">Назва KPI</div>
      <div style="font-size:1.45rem;font-weight:700">₹1.2M</div>
    </div>
  </div>
  <!-- далі: таблиця / графік / матриця з 3–6 рядками вигаданих даних -->
</div>
```

**Правила макета:**
- **синтетичні** дані, 3–6 рядків — досить, щоб побачити структуру;
- плашка «МАКЕТ» **не прибирається**;
- кольори як у звітах: фон `#0f1117` · картка `#181c25` · рамка `#272d3d` · акцент `#6366f1` ·
  🟢 `#22c55e` · 🟡 `#f59e0b` · 🔴 `#ef4444`;
- якщо для блока є 2 доречні патерни — показати **обидва поруч**;
- інтерактив імітувати не треба, достатньо статики;
- ⚠️ макет **не про цифри** — він лише про вигляд і порядок блоків.