# 📡 TelecomKz Analytics Mapper & Visual Simulator

Интерактивный симулятор мобильного приложения **Казахтелеком (TelecomKz**, `kz.telecom.app`**)**
для продуктового маппинга экранов, кнопок и метрик Amplitude / ClickHouse.

👉 Подробности архитектуры — в [PROJECT_DOCUMENTATION.md](PROJECT_DOCUMENTATION.md).

---

## ⚡ Быстрый старт

```bash
npm install
py -m pip install opencv-python numpy pillow websockets requests
npm run dev
```

Откройте **http://localhost:5173**.

Требования: Node.js 18+, Python 3.10+, Android-смартфон с включённой отладкой по USB
и **открытым на переднем плане** приложением TelecomKz.

Приложение работает и без телефона: экраны и разметка читаются из
`public/data/telecomkz_app_map.json`, а панель сверху честно показывает
«Телефон не подключен».

---

## 🧭 Что нужно понимать про данные

Два разных признака достоверности, оба видны в интерфейсе.

**1. Источник метрик** (`metrics.json` → поле `source`)

| Значение | Что означает |
|---|---|
| `clickhouse` | Числа выгружены из ClickHouse через `tools/fetch_clickhouse.py`. |
| `demo` | **Демонстрационные значения.** Это не аналитика. |

В репозитории по умолчанию лежит `demo`. Чтобы получить реальные метрики,
скопируйте `.env.example` в `.env`, укажите `CLICKHOUSE_HOST` и выполните:

```bash
py tools/fetch_clickhouse.py --days 30
```

Хотспот, ключа которого нет в каталоге, **не получает метрик вообще** — в тултипе
пишется «Нет данных». Ноль вместо этого читался бы как «на кнопку никто не нажимает».

**2. Достоверность ключа события** (`keyConfidence` у каждого хотспота)

| Значение | Что означает |
|---|---|
| `observed` | Ключ перехвачен в момент отправки из приложения. **Только это — настоящий ключ.** |
| `dom-attribute` | Взят из атрибута `data-event` / `data-analytics` в DOM. |
| `manual` | Задан аналитиком вручную. |
| `rule` | Выведен из подписи кнопки по таблице `EVENT_RULES`. Не проверен. |
| `guessed` | Транслитерирован из подписи, правило не сработало. Не проверен. |

⚠️ Ключи вида `PAYMENTS_CLICK` в поставляемой разметке имеют статус `rule` — это
**соглашение этого проекта, а не ключи приложения**. Реальные ключи, снятые с живого
приложения, выглядят иначе: `HOMEPAGEPAYMENTS`, `OPENWINDOWPAYMENT`. Пока ключ не
переведён в `observed`, join с ClickHouse ничего не вернёт.

Снять настоящие ключи:

```bash
py tools/monitor_live_events.py --seconds 120 --map main_dashboard
```

Потыкайте кнопки на телефоне — каждый пойманный ключ запишется в разметку
со статусом `observed`.

---

## 🛠 Инструменты

| Скрипт | Назначение |
|---|---|
| `tools/telecom_cdp.py` | Общее ядро: ADB, поиск сокета WebView, CDP-клиент, геометрия экрана. |
| `tools/capture_screen.py` | Снимок экрана со сшивкой всей прокрутки + разметка хотспотов. |
| `tools/live_auto_recorder.py` | Быстрая пересборка хотспотов одного экрана по живому DOM. |
| `tools/monitor_live_events.py` | Перехват реальных событий аналитики в момент нажатия. |
| `tools/crawl_and_map_all.py` | Автообход разделов с захватом экранов и событий. |
| `tools/fetch_clickhouse.py` | Выгрузка метрик из ClickHouse. |
| `tools/map_screen_controls.py` | Обход всех кнопок экрана: снятие реальных ключей + захват экранов, куда они ведут. |
| `tools/reclassify_hotspots.py` | Пересчёт ключей, дедупликация и чистка мёртвых ссылок без телефона. |
| `tools/rename_screen.py` | Переименование снятого экрана вместе с файлами и ссылками. |
| `tools/inspect_page.py` | Диагностика WebView (Amplitude, мосты, Vue, storage). |
| `tools/device_status.py` | Проверка «телефон + WebView доступны». |

Скрипты в `tools/legacy/` не используются — см. `tools/legacy/README.md`.

---

## 🗺️ Экраны и режимы съёмки

| Экран | Маршрут / поверхность | Команда |
|---|---|---|
| Главный | `/` | `py tools/capture_screen.py main_dashboard` |
| Мои услуги | `/services` | `py tools/capture_screen.py services_screen` |
| Трафик | `/detalization` | `py tools/capture_screen.py traffic_screen` |
| Платежи | `/payments` | `py tools/capture_screen.py payments_screen` |
| Заявки | `/appeals` | `py tools/capture_screen.py orders_screen` |
| Боковое меню | `/` (оверлей) | `py tools/capture_screen.py side_menu --no-scroll` |
| Музыка | нативный экран | `py tools/capture_screen.py music_screen --native` |

* `--no-scroll` — для оверлеев: прокрутка закрывает боковое меню.
* `--native` — для экранов без WebView: разметка берётся из `uiautomator`.

Полный обход экрана (ключи + экраны назначения одним проходом):

```bash
py tools/map_screen_controls.py payments_screen --via "Платежи" --capture-new
```

Инструмент сам возвращается назад **внутри WebView** (`history.back()`), а не
аппаратной кнопкой: та закрывает приложение и вызывает запрос пин-кода.

Съёмка **не стирает** подтверждённые (`observed`) ключи — они переносятся по подписи
элемента. Пересъём безопасен.

---

## 🌟 Возможности

- Мокап смартфона с прокруткой длинных экранов и переходами между разделами.
- Тултипы с метриками Amplitude/ClickHouse и явной пометкой источника.
- Тепловая карта кликов; зоны без измерений остаются серыми, а не «холодными».
- Редактор разметки с сохранением **на диск** (`Сохранить разметку на диск`),
  а не только выгрузкой файла.
- Захват экрана с телефона: сшивка ведётся по реальному смещению прокрутки, поэтому
  координаты хотспотов совпадают с картинкой пиксель в пиксель.
- Чтение DOM WebView через Chrome DevTools Protocol и нативной разметки через
  `uiautomator` — границы тулбара и таб-бара измеряются, а не задаются константами.