# راهنمای فاز P2 — CRM حرفه‌ای

این فاز قابلیت‌های حرفه‌ای فروش را روی پایه امن P0/P1 اضافه می‌کند. داشبوردهای نقش‌محور حذف یا جایگزین نشده‌اند و مسیر `/` همچنان پس از ورود، داشبورد مجاز کاربر را نمایش می‌دهد.

## قابلیت‌های تحویل‌شده

- داشبورد: حفظ داشبوردهای Admin/Supervisor/Agent، refresh دستی و دوره‌ای، loading و error/retry واقعی، و ترجیحات شخصی ویجت‌ها.
- فرصت فروش: چند پایپ‌لاین و چند مرحله، برد کانبان، مجموع ارزش مرحله، ارزش وزنی، workspace جزئیات، تاریخچه مرحله، بستن موفق/ناموفق با دلیل و مبلغ نهایی، و optimistic locking با `version`.
- بهره‌وری: جست‌وجوی سراسری scopeشده برای Lead/Deal/Company/Contact/Call، نماهای ذخیره‌شده private/team/public، و ترجیحات اعلان و داشبورد.
- هوشمندی: امتیازدهی deterministic لید با breakdown و سطح cold/warm/hot، SLA برای اولین تماس، پیگیری و فرصت راکد، تشخیص idempotent و اعلان قابل mute.
- پیکربندی: اتوماسیون محدود و قابل audit برای ایجاد Task، اعلان و تغییر اولویت لید؛ triggerهای واقعی `lead_created`، `lead_scored`، `deal_stage_changed` و `sla_breached`؛ سقف اجرا و event key ضدتکرار.
- فیلد سفارشی: تعریف فیلد برای Lead/Deal/Company/Contact با نوع‌های متنی، عددی، تاریخ، boolean و انتخابی؛ ذخیره typed و indexپذیر و کنترل visibility نقش.
- کیفیت و اسکریپت: strengths/improvement areas، acknowledgement کارشناس و پاسخ او، metadata اسکریپت شامل category/source/questions/disclosures/template و جست‌وجوی سروری.
- گزارش و اعلان: گزارش عملیات فروش شامل pipeline/forecast/won/SLA/task، فیلتر اعلان خوانده‌نشده و لینک ترجیحات.

## مسیرهای UI

- `/` داشبورد نقش‌محور و صفحه پیش‌فرض
- `/deals` برد فرصت‌ها
- `/deals/{id}` workspace فرصت و تاریخچه مرحله
- `/operations` مرکز SLA، اتوماسیون، فیلد سفارشی و ترجیحات
- `/reports` تب «عملیات فروش و SLA»
- `/sales-scripts` اسکریپت‌های توسعه‌یافته
- `/quality-reviews` ارزیابی و acknowledgement

جست‌وجوی سراسری در Header با `Ctrl+K` در دسترس است.

## APIهای اصلی

| حوزه | Endpointهای اصلی |
|---|---|
| Pipeline | `GET /api/pipelines`, `POST /api/pipelines`, `GET /api/pipelines/{id}/board`, `PATCH /api/deals/{id}/stage` |
| Search/View | `GET /api/global-search`, `GET/POST/DELETE /api/saved-views` |
| Preferences | `GET/PUT /api/workspace-preferences` |
| Scoring/SLA | `POST /api/leads/{id}/score`, `POST /api/leads/bulk-score`, `GET/POST /api/sla-rules`, `POST /api/sla/detect`, `PATCH /api/sla-breaches/{id}/resolve` |
| Automation | `GET/POST /api/automations`, `POST /api/automations/{id}/run`, `GET /api/automation-runs` |
| Custom fields | `GET/POST /api/custom-fields`, `GET/PUT /api/custom-field-values/{type}/{id}` |
| QA | `POST /api/quality-reviews/{id}/acknowledge` |
| Reports | `GET /api/reports/operations` |

تمام endpointهای رکوردی مجوز و scope مالک/تیم را در backend اعمال می‌کنند. مخفی‌کردن کنترل در UI جایگزین authorization سرور نیست.

## مجوزهای جدید

`view_pipelines`, `manage_pipelines`, `move_deals`, `close_deals`, `manage_saved_views`, `share_team_views`, `use_global_search`, `score_leads`, `view_sla`, `manage_sla`, `manage_automations`, `view_automation_logs`, `manage_custom_fields`, `acknowledge_quality_reviews`, `manage_dashboard_preferences`, `manage_notification_preferences`.

بعد از deploy این فرمان را اجرا کنید تا permissionهای جدید ساخته و نقش‌های پیش‌فرض همگام شوند:

```powershell
php artisan permissions:sync-defaults
```

## Scheduler و عملیات

پایش SLA هر ۱۵ دقیقه در scheduler ثبت شده و از `withoutOverlapping` و event key یکتا استفاده می‌کند. اجرای دستی و idempotent:

```powershell
php artisan sla:monitor
```

در production اجرای `php artisan schedule:run` در هر دقیقه الزامی است. اعلان SLA ترجیح `notification_type=sla` را رعایت می‌کند.

## مهاجرت و rollback

پنج migration این فاز با prefixهای `030000` تا `034000` به‌ترتیب pipeline، preferences، scoring/SLA، automation/custom fields و QA/scripts را ایجاد می‌کنند.

پیش از migration از دیتابیس backup بگیرید:

```powershell
php artisan migrate --force
php artisan permissions:sync-defaults
```

برای rollback کامل P2 در محیط کنترل‌شده، آخرین پنج migration را برگردانید:

```powershell
php artisan migrate:rollback --step=5 --force
```

Rollback جدول‌ها و ستون‌های P2 را حذف می‌کند؛ در production بازیابی داده‌های pipeline/history/custom fields باید از backup انجام شود. ابتدا روی staging تمرین شود.

## کنترل کیفیت

```powershell
cd backend
php artisan test
vendor\bin\pint --test

cd ..\frontend
npm run lint
npm run test:run
npm run build
npm run test:e2e
```

تست `ProfessionalCrmP2Test` scope تیم، بستن فرصت و version conflict، audit، search/view/preferences، scoring/SLA، idempotency اتوماسیون، typed custom field و acknowledgement QA را پوشش می‌دهد. تست کامپوننت rollback کانبان و خطای جست‌وجو و Playwright مسیر جست‌وجو تا جابه‌جایی فرصت را پوشش می‌دهند.

## محدودیت‌های عمدی

Automation یک DSL محدود است و PHP/SQL دلخواه اجرا نمی‌کند. actionهای مجاز فقط `create_task`، `notify` و `set_lead_priority` هستند. برای افزودن action جدید، validation، authorization، audit و تست idempotency هم‌زمان توسعه داده شوند.