From ec78a76729caff5a942c9f28496b920b1c00d2d9 Mon Sep 17 00:00:00 2001 From: ghazale Date: Tue, 10 Nov 2026 13:12:45 +0000 Subject: [PATCH] docs(wiki): update experiences-monitoring (LIVE_VERIFIED) --- wiki/INDEX.md | 7 +++ wiki/experiences-monitoring.md | 103 +++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 wiki/INDEX.md create mode 100644 wiki/experiences-monitoring.md diff --git a/wiki/INDEX.md b/wiki/INDEX.md new file mode 100644 index 0000000..b2c445a --- /dev/null +++ b/wiki/INDEX.md @@ -0,0 +1,7 @@ +# 🗂 فهرست جامع دانش‌نامه موضوعی (ghazale) + +| موضوع (Slug) | فایل | آخرین تغییر | +| :--- | :--- | :--- | +| `experiences-monitoring` | `experiences-monitoring.md` | `2026-11-10 13:12` | +| `index` | `index.md` | `2026-11-08 10:17` | +| `log` | `log.md` | `2026-11-08 10:17` | diff --git a/wiki/experiences-monitoring.md b/wiki/experiences-monitoring.md new file mode 100644 index 0000000..978782a --- /dev/null +++ b/wiki/experiences-monitoring.md @@ -0,0 +1,103 @@ +# دانش‌نامه جامع پروژه مرکز پایش تجارب اکیپا (Ekeepa Experiences Mission Control Knowledge Base) + +این سند مرجع رسمی معماری، تعاریف دیتابیس، منابع تحلیلی، نکات فنی کشف‌شده و روش به‌روزرسانی پرسرعت داشبورد مرکز پایش تجارب اکیپا به نشانی **`https://experiences.ghazale.test.zebellkhan.com/`** است. + +--- + +## ۱. ساختار پوشه‌ها و همگام‌سازی فایل‌ها +- **مسیر اصلی توسعه و اجرا:** `/workspace/personal/experiences_monitoring/` +- **مسیر همگام دپارتمان عملیات:** `/workspace/ekeepa/operations/experiences_monitoring/` +- **فایل مستقر روی ساب‌دامین:** `/workspace/personal/experiences.html` +- **مرکز عملیات بالادستی (Hooch):** با هر انتشار جدید، اجرای `/workspace/personal/sync_hooch.py` برای ثبت وضعیت در جدول `ekeepa_bi.dashboard_app_storage` و بازنشر کارت داشبورد الزامی است. +- **ممنوعیت مطلق `localStorage`:** تمام وضعیت‌ها و تسک‌های داشبورد صرفاً در بک‌اند PostgreSQL 17 از طریق `/api/db/state` ذخیره می‌شوند. + +--- + +## ۲. استاندارد قطعی افق ۳۰ روزه عرضه و زامبی‌ها (تثبیت‌شده) + +### تعریف کاتالوگ فعال (`active_rooms`) +اتاق‌هایی که واجد تمام شروط زیر در جدول `rooms` (Metabase Database ID: 2) باشند: +```sql +(room_type IN ('تجربه', 'کلاس', 'تور', 'تور وحشت', 'سفر', 'رویداد') OR name LIKE '%رویداد%' OR name LIKE '%ایونت%') +AND status = 2 +AND deleted_at IS NULL +``` +*(تعداد کل کاتالوگ فعال: **۳۵۶ تجربه** از مجموع ۶۳۴ اتاق موجود در سیستم).* + +### منطق افق زمانی ۳۰ روز آینده (`generate_series(0, 29)`) +سانس‌های باز یک تجربه منحصراً بر مبنای ۳۰ روز آینده با وقت محلی ایران (`Asia/Tehran` / `+3 hours 30 minutes`) محاسبه می‌شوند: +1. تولید سری ۳۰ روزه با `generate_series(0, 29)`. +2. انطباق `play_boxes.week_day` با روز هفته تهران (`EXTRACT(DOW FROM ((CURRENT_DATE + i)::date + interval '3 hours 30 minutes'))::int`). +3. اعمال شرط تاریخ اعتبار سانس: `(pb.valid_to IS NULL OR pb.valid_to >= d.slot_date) AND (pb.valid_from IS NULL OR pb.valid_from <= d.slot_date)`. +4. کسر سانس‌های بسته‌شده یا بلاک تقویمی در جدول `disabled_calendar_play_boxes` بر مبنای `(dpb.date AT TIME ZONE 'Asia/Tehran')::date = d.slot_date`. + +### آمار مرجع ۳۰ روزه (راستی‌آزمایی‌شده) +- **تجارب دارای سانس باز (Active Supply):** **۳۴۷ تجربه** (**۹۷.۵٪** کاتالوگ فعال | محقق‌شده **۱۵۷.۷٪** نسبت به تارگت سندی ۲۲۰). +- **تجارب راکد بدون سانس (Zombie Inventory):** **۹ تجربه** (**۲.۵٪** کاتالوگ فعال): + - **۵ تجربه زامبی با پتانسیل (دارای سابقه فروش قبلی):** پخت موچی کره‌ای، پخت کیمباپ کره‌ای، پخت بیانگ‌بیانگ، تور ترکمن‌صحرا و کلاب انگلیسی. + - **۴ تجربه زامبی مرده (بدون سابقه فروش و بدون سانس):** شناسه اتاق‌های `101256011`, `101256012`, `101490613`, `201298717`. +- **نرخ رشد هفتگی عرضه:** ۵۸ تجربه فعال جدید در ۳۰ روز اخیر (معادل **۱۳.۵ تجربه جدید در هفته**). +- **تمرکز جغرافیایی:** ۳۱۶ تجربه در تهران و کرج (**۸۸.۸٪**) و ۴۰ تجربه در ۱۰ شهر دیگر (**۱۱.۲٪**). + +--- + +## ۳. آموخته‌های کلیدی دیتابیس رزروها، پرداخت‌ها و میزبانان (Metabase DB #2) + +### الف) وضعیت‌های جدول `reservations` +- **`status = 2`:** رزرو پرداخت‌شده و تاییدشده. +- **`status = 6`:** رزرو تکمیل‌شده / شرکت‌کننده در سانس حضور یافته. +- **`status = 3`:** رزرو لغوشده / کنسلی. +- **بنابراین تعداد سفارش‌های موفق واقعی = `status IN (2, 6)`** (در ۳۰ روز اخیر: **۴۷۶ سفارش موفق** شامل ۲۰۰ سفارش وضعیت ۲ و ۲۷۶ سفارش وضعیت ۶). +- **نرخ کنسلی ۳۰ روزه:** ۳۵ کنسلی از ۵۱۱ رزرو قطعی/لغوشده = **۶.۸٪**. + +### ب) فرمول محاسبه دقیق درآمد ناخالص (GMV) +- ستون `reservations.base_price` مبلغ پایه یک نفر است؛ برای محاسبه GMV واقعی باید حتماً در تعداد نفرات ضرب شود: + ```sql + SUM(r.base_price * COALESCE(r.number_of_players, 1)) + ``` +- بر این اساس، GMV واقعی ۳۰ روز اخیر تجارب اکیپا حدود **۱.۱۵ میلیارد تومان** و میانگین ارزش سبد (AOV) معادل **۲,۴۱۸,۰۰۰ تومان** است. + +### ج) استخراج اطلاعات تماس میزبانان بدون جوین اضافه +- جدول `rooms` مستقیماً شامل ستون‌های `cell_phone_number` و `phone_number` است. برای پیگیری ۵ تجربه زامبی دارای پتانسیل نیازی به جوین جدول `providers` یا `users` نیست. + +### د) هیت‌مپ تقاضای ساعتی-هفتگی +- با کوئری‌گیری مستقیم از `reservations.created_at + INTERVAL '3 hours 30 minutes'`، ۱۶۸ خانه (۷ روز هفته × ۲۴ ساعت) در فایل JS داشبورد به صورت متغیر زنده `liveHeatmapData` تزریق می‌شود تا نمودار هیت‌مپ بدون اعداد ساختگی و کاملاً متصل به پایگاه داده باشد. +- **قله‌های واقعی خرید و اجرا:** عصر پنج‌شنبه و جمعه (ساعات ۱۶ تا ۲۱). + +--- + +## ۴. یکپارچه‌سازی منابع تحلیلی تکمیلی (Clarity, GA4, GSC, Mahsa) + +1. **Microsoft Clarity API (`/workspace/personal/analytics/clarity_probe.py`):** + - استخراج متریک‌های رفتار واقعی کاربران در ۳ روز اخیر: + * کلیک‌های مرده (`DeadClickCount`): **۶.۰۹٪** (نقطه اصطکاک اصلی روی دکمه تقویم موبایل). + * بازگشت سریع (`QuickbackClick`): **۶.۶۲٪**. + * کلیک‌های عصبی (`RageClickCount`): **۰.۲۹٪**. + * عمق اسکرول (`ExcessiveScroll`): **۴۹.۱۳٪**. + * سهم دستگاه موبایل: **۸۳.۳٪**. +2. **Google Analytics 4 REST API (بدون وابستگی پکیج خارجی):** + - اتصال مستقیم با `urllib.request` و توکن رفرش `/workspace/personal/analytics/google_user_tokens.json` روی Property ID `472393675`. + - حجم سشن ۳۰ روزه کل سایت: **~۱۵۴,۳۰۰ سشن** (Direct: ۷۱.۵k، Organic Search: ۴۱.۱k، Paid Search: ۲۷.۳k، Social/Affiliates/SMS: ۱۴.۴k). +3. **Google Search Console API:** + - استخراج عملکرد سرچ از `google_client.py gsc` (کوئری برند «اکیپا» با ۸۱۴ کلیک و CTR ۸۶.۱٪ در جایگاه ۱.۰). +4. **دیتابیس‌های کراولر مهسا (`/usr/local/bin/mahsa-sql`):** + - **`davvvat`:** جدول `events` (بررسی قیمت و تعداد ایونت‌های فعال رقیب دعوت). + - **`vadoostan`:** جدول `experiences` (بررسی بازه قیمتی ۱۵۰ تا ۴۵۰ هزار تومانی وادوستان). + +--- + +## ۵. معماری به‌روزرسانی پرسرعت و ساب‌ایجنت (Quick Update Architecture) + +برای جلوگیری از اتلاف وقت در درخواست‌های بعدی و به‌روزرسانی همزمان تمامی تب‌ها: +- **دستور اجرای پرسرعت تک‌خطی:** + ```bash + python3 /workspace/personal/experiences_monitoring/update_all_dashboard.py + ``` +- **اسکریپت ساب‌ایجنت موازی:** `/workspace/personal/experiences_monitoring/subagent_live_updater.py` با ۴ کارگر همزمان (`ThreadPoolExecutor`) و ثبت وضعیت اجرای هر تب در کانبان `/workspace/personal/kanban.db` (جدول `subagent_tasks`). +- **مراحل انتشار پس از پچ HTML:** + 1. اجرای `/usr/local/bin/deploy-dashboard /workspace/personal/experiences.html experiences ""`. + 2. همگام‌سازی فایل‌ها به `/workspace/ekeepa/operations/experiences_monitoring/`. + 3. اجرای `/workspace/personal/sync_hooch.py` و بررسی اسکرین‌شات خروجی `/workspace/personal/screenshots/experiences_qa.png`. + +--- +*ثبت‌شده در دانش‌نامه (`2026-11-10 13:12 UTC` | اصالت داده: `LIVE_VERIFIED`)*