docs(wiki): update experiences-monitoring (LIVE_VERIFIED)

This commit is contained in:
ghazale 2026-11-10 13:12:45 +00:00
parent e911af873a
commit ec78a76729
2 changed files with 110 additions and 0 deletions

7
wiki/INDEX.md Normal file
View file

@ -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` |

View file

@ -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 "<commit>"`.
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`)*