5cb347a44b
Rebuilt the capture and mapping pipeline after an audit found the simulator's data could not be trusted: * Hotspot coordinates never matched the screenshots. Capture now scrolls the page over CDP and pastes each frame at the measured scrollY, so image pixels and DOM coordinates share one grid by construction. * Metrics were synthesised (1200 + n*410) and presented as analytics. Numbers are now attached only when the catalog has a matching row; metrics.json carries a `source` label and the UI says "no data" instead of showing zeros. * Event interception hooked a connector bridge that never fires. The app posts to api.amplitude.com using the legacy form-urlencoded v1 API; the hook now reads event_type off the wire. 36 keys are verified as `observed`. * All device access moved into tools/telecom_cdp.py: dynamic WebView socket discovery (the PID was hardcoded), id-matched CDP, measured native geometry. * Editor edits can now be saved to disk; API failures no longer report success from a stale result file; screenId is no longer interpolated into a shell. Screens went from 7 (with fabricated markup) to 32, all verified: image height equals map height, no out-of-bounds hotspots, no dead links. The id_card screenshot has been manually redacted - it showed a national ID. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
136 lines
7.9 KiB
Markdown
136 lines
7.9 KiB
Markdown
# 📡 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` — границы тулбара и таб-бара измеряются, а не задаются константами.
|