ehsan-dashboards/dashboards/old_hermes/HANDOFF_EKEEPA_FIELD_DASHBOARD.md

73 lines
7.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# سند هندآف: داشبورد میدانی جذب و پروپوزال اکیپا (Ekeepa Field Dashboard)
**تاریخ ایجاد:** سه‌شنبه ۳۱ شهریور ۱۴۰۵ (2026-09-22)
**دامنه زنده:** [https://ekeepa.zebellkhan.com/field/](https://ekeepa.zebellkhan.com/field/)
**رمز عبور ذخیره‌سازی روی سرور:** `ekipa-field-1405`
---
## ۱. هدف جلسه بعدی (Goal of next session)
- دریافت بازخورد اولین مراجعه میدانی نماینده به مجموعه‌داران با این داشبورد.
- در صورت درخواست، اتصال خودکار بک‌اند سینک به ربات تلگرام (با Bot Token و Chat ID کاربر) برای ارسال مستقیم اعلان‌ها بدون نیاز به مرورگر.
- پایش لاگ‌های حسابرسی ثبت‌شده در `sync_audit.db` سرور.
---
## ۲. وضعیت فعلی (State of Play)
### الف. انجام‌شده و تأییدشده (Done & Verified)
1. **داشبورد تک‌فایل HTML (موبایل‌محور و واکنش‌گرا):**
- طراحی بر اساس استانداردهای بصری (Vazirmatn، پالت تیره بنفش و طلایی، RTL).
- بدون وابستگی به فایل خارجی برای تصاویر (تمام تصاویر به‌صورت WebP Base64 ادغام شده‌اند).
2. **تفکیک ۶ تب عملیاتی:**
- **راهنمای نماینده:** کارمزد پایه ۱۳٪، پکیج تست ۲ هفته‌ای رایگان در بدو ورود، پاسخ کوبنده به عدم تمایل به درگاه‌های اقساطی (افت ۲۰ تا ۳۰ درصدی فروش جوانان)، مقایسه رقبا، ۴ خط قرمز و کارت مرجع سریع.
- **پروپوزال مشتری:** درگاه‌های اقساطی و کیف پول‌ها (اسنپ‌پی، تارا، دیجی‌پی، اوانو، اوزون، سلفیت)، تسویه منظم اول و ۱۵ هر ماه، نمایش ۳ اسکرین‌شات از پنل مالی، پکیج طلایی (۲۵٪) و نقره‌ای (۲۰٪) با قاعده سقف ۶۰ میلیون تومان فروش (مازاد رایگان)، نمایش تخفیف لحظه‌آخری، پیشنهادات ویژه با تگ VIP، گالری ۳تایی تگ «مورد تأیید تیم اکیپا»، قابلیت چاپ و ذخیره PDF.
- **ویس بلاگ:** ۱۴ سؤال مصاحبه میدانی بدون اسپویل، چک‌لیست نکات مثبت و منفی، راهنمای ضبط ویس.
- **ارزیابی کیفی و وریفای:** ۵ معیار ستاره‌ای (پازل، سناریو، دکور، ایمنی، پرسنل)، اعطای خودکار وریفای در صورت نمره حداقل ۴ در همه ابعاد، گالری ۳تایی نمایش تگ.
- **گزارش‌ها:** فهرست گزارش‌های ثبت‌شده با امکان ارسال خلاصه به تلگرام (تصویر بزرگ نمونه گزارش به درخواست کاربر حذف شد).
- **پیشرفت جذب (CRM):** پایپ‌لاین ثبت مجموعه‌ها با ۵ وضعیت، ذخیره‌سازی، خروجی CSV و گزارش متنی جامع به تلگرام.
3. **تفکیک صحیح تصاویر ارسالی کاربر:**
- تصاویر سفید (۳ عدد) -> پنل مالی شفاف و زنده در پروپوزال.
- تصاویر تیره/بنفش (۳ عدد) -> گالری تگ «مورد تأیید تیم اکیپا» در پروپوزال و ارزیابی.
4. **سینک چنددستگاهی واقعی (Cross-Device Sync):**
- بک‌اند پایتون (`api_server.py`) روی پورت `8097` میزبان.
- پروکسی معکوس در `ekeepa-dashboard-nginx` روی مسیر `/field/api/`.
- ذخیره‌سازی پایدار در `/data/dashboards/ekeepa/field/state.json` و ثبت لاگ در SQLite `sync_audit.db`.
- حل باگ مقایسه زمان رشته‌ای با استفاده از شمارنده نسخه ترتیبی (`rev`).
- سرویس سیستمی `ekeepa-field-api.service` با راه‌اندازی خودکار پس از ریبوت فعال و تست شد.
- تست انتها به انتهای Playwright با دو کانتکست مجزا (موبایل و دسکتاپ) با موفقیت پاس شد.
### ب. موارد در جریان / بالقوه (In Flight / Next)
- اتصال اختیاری به بات تلگرام برای ارسال خودکار نوتیفیکیشن بک‌اند به جای URL Share.
- افزودن قابلیت جستجو و فیلتر در لیدهای CRM در صورت افزایش تعداد مجموعه‌ها.
---
## ۳. تصمیم‌های اتخاذشده (Decisions Log)
- **روش ذخیره‌سازی:** هیبریدی (Local-First + Server Sync). در نبود اینترنت، داده در LocalStorage می‌ماند؛ در زمان اتصال و زدن دکمه ذخیره، با رمز روی سرور ثبت می‌شود.
- **احراز هویت ذخیره:** هدر `X-Field-Pass: ekipa-field-1405`؛ خواندن اطلاعات باز است اما هرگونه بازنویسی به رمز نیاز دارد.
- **چیدمان گالری بج:** در موبایل ۱ ستونی (عرض کامل تصویر) و در تبلت/دسکتاپ ۳ ستونی.
- **حذف عکس گزارش از تب گزارش‌ها:** بنا به تأکید کاربر برای تمیزی و تمرکز روی داده‌های متنی.
---
## ۴. مهارت‌های پیشنهادی برای جلسه بعدی (Suggested Skills)
1. `coolify-server-access` — برای بررسی سلامت سرور میزبان و مدیریت کانتینرها.
2. `ecosystem-secrets-reference` — برای دسترسی به توکن‌ها و کلیدهای تلگرام در صورت توسعه بات.
3. `static-dashboard-operations` — برای اصلاح یا انتشار نسخه‌های بعدی داشبوردهای استاتیک اکیپا.
---
## ۵. آدرس‌ها، فایل‌ها و ابزارهای مرتبط (Artifacts)
| مورد | مسیر / URL | توضیحات |
|---|---|---|
| **دامنه زنده داشبورد** | `https://ekeepa.zebellkhan.com/field/` | دسترسی عمومی، تست‌شده با کد ۲۰۰ |
| **اندپوینت سلامت API** | `https://ekeepa.zebellkhan.com/field/api/health` | بازگشت `{status: ok}` |
| **سورس HTML اصلی** | `/workspace/ekeepa_field_dashboard.html` | نسخه محلی آماده توسعه |
| **اسکریپت تولیدکننده** | `/workspace/build_dash.py` | ساخت مجدد HTML و امبد تصاویر |
| **سرور سینک** | `/workspace/field_api_server.py` | کد بک‌اند پایتون پورت ۸۰۹۷ |
| **تست E2E سینک** | `/workspace/e2e_sync_test.py` | سناریوی تست Playwright روی دامنه زنده |
| **مسیر روی سرور میزبان** | `/data/dashboards/ekeepa/field/` | فایل‌های مستقرشده روی هیتزنر |
| **سرویس لینوکس سرور** | `ekeepa-field-api.service` | مدیریت پردازش بک‌اند با systemd |
| **فایل پیکربندی Nginx** | کانتینر `ekeepa-dashboard-nginx` -> `/etc/nginx/conf.d/default.conf` | هدایت `/field/api/` به `10.0.1.1:8097` |