📡 TelecomKz Analytics Mapper & Visual Simulator

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

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

---

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

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 и выполните:

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 ничего не вернёт.

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

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.

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

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

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

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

---

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

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