# TASKS.todo — تاریخچه + نقشه‌راه تا لانچ (به‌روز: 2025-09-17)

این فایل «تاریخچه کامل» و «برنامهٔ آینده تا لانچ» را نگه می‌دارد. اقلام قبلی حذف نمی‌شوند؛ اقلام تکمیل‌شده تیک می‌خورند و کنارشان تاریخ/یادداشت می‌آید. (مطابق درخواست، روی امنیت/سخت‌گیری‌های عملیاتی تمرکز نمی‌کنیم و نگاه محصول/بیزنس/مارکتینگ و UX/کپی‌رایتینگ را پررنگ می‌نویسیم.)

## A) تاریخچهٔ تسک‌های قبلی (Snapshot + وضعیت فعلی)

### Blockers / Infrastructure
- [ ] PHP ext-intl (Filament)
- [ ] Queue tables (`jobs`, `failed_jobs`) و راه‌اندازی worker
- [ ] Cron برای `schedule:run`
- [x] Route/Config/View cache پاکسازی دوره‌ای — 2025-09-17
- [x] ثبت route وبهوک تلگرام (`/api/telegram/webhook`) — 2025-09-17
- [x] ست‌کردن وبهوک واقعی تلگرام با secret — 2025-09-17

### Telegram Bot Core
- [x] Parsing & routing پیام/کالبک — 2025-09-17
- [x] آنبوردینگ (نقش → شهر → بودجه → فرکانس) + fallback متنی — 2025-09-17
- [ ] منوی اصلی داینامیک از DB (`menu_items`) (فعلاً سخت‌کد)
- [x] برابری عملکرد دکمه «🏠 منوی اصلی» با `/start` + نرمال‌سازی اموجی — 2025-09-20
- [x] Events: `Start`, `SelectCity` — 2025-09-17
- [ ] Event: `HelpOpen`
- [ ] Phone Gate (اختیاری)
- [ ] Channel Gate (اختیاری)

### RBAC & Admin
- [ ] جداول نقش‌ها (spatie/permission) و گارد پنل
- [ ] حفاظت admin endpoints

### AI (Responses API + Memory + RAG)
- [x] OpenAiProvider (timeout/retry) — 2025-09-17
- [ ] Memory: `chat_threads.previous_response_id` برای دیالوگ چندمرحله‌ای
- [ ] VectorStore attach/detach & status (RAG)
- [x] ثبت چت/رویداد برای HTTP (valuation) — 2025-09-17

### Payments (Zarinpal)
- [x] PaymentService create/verify (sandbox) — 2025-09-17
- [x] Verify ایدمپوتنت بر اساس `ref` — 2025-09-17
- [ ] ایندکس `payments.ref`
- [x] Event: `UpgradeClick`/`UpgradeSuccess` — 2025-09-17

### Ads Ingestion & Pipeline
- [x] MajidApiClient برای bama/divar — 2025-09-17
- [x] Jobs: درج خام در `ads_raw` — 2025-09-17
- [x] ScoreOpportunitiesJob: Normalize→Dedup→Median→Score→Persist — 2025-09-17
- [ ] لیست «آگهی‌های به‌قیمت» (paging) در ربات
- [x] Event: `ViewDeal` هنگام نمایش فرصت‌ها — 2025-09-17

### Push & CTR
- [ ] سگمنت/ارسال از طریق تلگراف
- [ ] ثبت sent/delivered/click برای CTR

### Saved Ads & Tickets
- [x] ذخیرهٔ ⭐ فرصت از تلگرام (opportunity) — 2025-09-17
- [ ] Saved Ads HTTP (external) + لیست/حذف با کاربر واقعی
- [ ] Tickets: ایجاد/فهرست کاربر، پاسخ ادمین (پل به تلگرام)

### Filament Admin
- [ ] راه‌اندازی پنل + منابع (Users/Plans/Payments/Opportunities/Featured/MenuItems/Settings/VectorStores/Experiments/Push/Tickets/Events)
- [ ] KPI widgets
- [ ] Settings (feature toggles & channels)

### Analytics / KPI / Quality Gates
- [ ] تکمیل رویدادها: `CallFromCard`, `ChecklistRun`, `PushOpen`, …
- [ ] گزارش روزانه + ویجت‌ها

### Testing (Pest/Feature)
- [ ] Webhook 200/401 + route list
- [ ] Payments verify idempotent + فعال‌سازی یک‌باره
- [ ] Saved Ads ownership + duplicate 409
- [ ] AI respond JSON/latency
- [ ] Ads pipeline fixture→opportunities

— این بخش، تاریخچه را نگه می‌دارد و با هر تحویل به‌روزرسانی می‌شود.

## B) نقشه‌راه تا لانچ (جزئیات کامل، محصول‌محور)

### 1) تلگرام — محصول‌سازی کامل ماژول‌ها
1.1 آنبوردینگ حرفه‌ای
- [ ] سافت‌نَویگیشن بین مراحل (Back/Restart) + خلاصهٔ انتخاب‌ها قبل از اتمام
- [ ] پیشنهاد شهرهای پرتکرار، 5 مورد پیشنهادی بالای صفحه
- [ ] بازخورد لحظه‌ای برای ورودی‌های مبهم (شهر/بودجه)

1.2 ماژول ارزش‌گذاری (قیمت‌یار)
- [ ] اتصال مستقیم پیام کاربر به AI با الگوی متن کوتاه فارسی (بدون راه‌اندازی دستی)
- [ ] حافظهٔ رشته (thread) per user/module با `previous_response_id`
- [ ] کارت خروجی: بازه/Anchor/اعتماد + 2–4 دلیل کوتاه + دکمه‌های داخلی (تحلیل قیمت/⭐ ذخیره/تمرین/بازدید) بدون CTA تماس
- [ ] مدیریت ابهام: درخواست اطلاعات تکمیلی با نمونهٔ صحیح

1.3 تمرین مذاکره
- [ ] سناریوهای آماده (مودب/قاطع/حقوقی)
- [ ] Q&A هدایت‌گر + پلن 3مرحله‌ای؛ پاسخ کوتاه و عمل‌محور

1.4 سؤالات کارشناسی + بازدید ۳ دقیقه‌ای
- [ ] پاسخ بولتی کوتاه؛ چک‌لیست خرید/فروش → Risk Map + قدم بعدی

1.5 حقوقی
- [ ] پاسخ‌های کوتاه با دیسکلیمر ثابت؛ درخواست شفاف‌سازی اگر داده ناکافی بود

1.6 راهنما (Help)
- [ ] معرفی مختصر قابلیت‌ها + لینک‌های عمیق به ماژول‌ها

1.7 حساب من
- [ ] نمایش نقش/شهر/فرکانس/اشتراک؛ امکان تغییر شهر/فرکانس؛ نمایش وضعیت اشتراک

1.8 پشتیبانی (Tickets)
- [ ] ایجاد/فهرست تیکت در تلگرام؛ اعلان به ادمین؛ پاسخ ادمین در چت

1.9 منوی داینامیک
- [ ] لود از DB (MenuItems) + ترتیب/عنوان/نمایش‌پذیری؛ ادیت آنی از پنل

### 2) تبلیغ‌ها و فرصت‌ها
- [ ] زمان‌بندی کشیدن داده (Bama/Divar) هر 15–30 دقیقه
- [ ] پروموشن خودکار به `reviewed` بر اساس آستانه‌های اسکور + ادیت انسانی از پنل
- [ ] TTL 72ساعت؛ آرشیو اقلام قدیمی
- [ ] لیست «به‌قیمت» با صفحه‌بندی، لینک مستقیم، ⭐ ذخیره (external/opportunity)

### 3) پرداخت و پلن‌ها
- [ ] نمایش وضعیت اشتراک در «حساب من» + CTA ارتقا
- [ ] اتصال Entitlements به ویژگی‌ها (کوتاهای ماهانه/روزانه)
- [ ] ثبت تراکنش‌ها با خلاصهٔ قابل‌فهم برای ادمین (بدون ورود به مباحث امنیتی)

### 4) Saved Ads و پشتیبانی (HTTP + Telegram)
- [ ] Saved Ads: ذخیرهٔ external (bama/divar) با dedup per user؛ لیست/حذف امن با نگاشت کاربر تلگرام
- [ ] Tickets: API + تلگرام؛ وضعیت، timestamps، آخرین پاسخ ادمین

### 5) Push و کمپین
- [ ] تعریف سگمنت‌ها (نقش/شهر/بودجه/فرکانس)
- [ ] زمان‌بندی/ارسال؛ ثبت delivered/open/click؛ CTR 7روز
- [ ] ابزار شبیه‌سازی کلیک/باز شدن پیام (برای QA داخلی)

### 6) پنل ادمین (Filament)
- [ ] Resources: Users, Plans, Subscriptions, Payments, Opportunities, FeaturedAds, MenuItems, Settings, VectorStores, VectorFiles, Experiments, PushCampaigns, PushLogs, Tickets, Events
- [ ] Dashboard: کارت‌های KPI (CTR, Saved%, D1, Payments)
- [ ] Settings: toggles (phone/channel) و فهرست کانال‌ها؛ ابزار تست عضویت/وبهوک/ارسال پیام نمونه

### 7) کپی‌رایتینگ و UX
- [ ] بازنویسی همهٔ پیام‌ها به لحن کوتاه/روشن/عمل‌محور؛ حذف کلیهٔ پیام‌های «در حال توسعه است»
- [ ] برای هر ماژول: پیام ورودی نمونه + پیام‌های خطای راهنما + CTA روشن
- [ ] دکمه‌ها: 2–4 مورد، متن کوتاه و دقیق، ایموجی معنادار

### 8) آنالیتیکس و KPI
- [ ] تکمیل رخدادها: `PriceCheck` (تلگرام), `PushOpen`, `CallFromCard`, `ChecklistRun`, `ReferralJoin`, …
- [ ] گزارش روزانه (تلگرام/ایمیل) با: p80 AI, CTR, Saved%, D1, Payments, خطاهای مهم
- [ ] ویجت‌های ادمین همگام با گزارش

### 9) QA و تست‌ها
- [ ] Acceptance Sheet: چک‌لیست‌های سبز نهایی
- [ ] تست‌های خودکار: webhook, payments, ads, saved ads, AI, tickets, push simulate

— این نقشه‌راه با هر تحویل و اسپرینت به‌روزرسانی می‌شود.
