# CRM

سامانه CRM با بک‌اند Laravel 12 و فرانت‌اند React/Vite. مجوزها در بک‌اند منبع حقیقت هستند و رابط کاربری نیز از همان permissionهای کاربر برای نمایش مسیرها و عملیات استفاده می‌کند.

## اجرای محلی در ویندوز

پیش‌نیازها: PHP 8.2 یا جدیدتر، Composer، Node.js و npm.

```powershell
cd backend
composer install
Copy-Item .env.example .env
php artisan key:generate
php artisan migrate --seed

cd ..\frontend
npm install
```

سپس از ریشه پروژه `run-project.bat` را اجرا کنید. بک‌اند روی `http://127.0.0.1:8887` و فرانت‌اند روی `http://127.0.0.1:8886` بالا می‌آیند. Vite درخواست‌های `/api`، `/sanctum` و `/storage` را به بک‌اند proxy می‌کند.

اگر پروژه را بدون فایل bat اجرا می‌کنید، مقادیر `APP_URL`، `FRONTEND_URL`، `SANCTUM_STATEFUL_DOMAINS` و `CORS_ALLOWED_ORIGINS` را متناسب با میزبان و پورت‌های خود تنظیم کنید.

## عملیات پس از استقرار

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

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

برای reminderهای Follow-up و Task باید scheduler لاراول فعال باشد. در سرور، `php artisan schedule:run` را هر دقیقه اجرا کنید؛ برای اجرای دائمی در محیط توسعه می‌توان از `php artisan schedule:work` استفاده کرد. Task reminder به صف ارسال می‌شود، پس در production یک `php artisan queue:work` تحت process manager نیز اجرا کنید.

پس از استقرار P1، تبدیل idempotent یادداشت‌های قدیمی تماس را هم اجرا کنید (migration نیز همین تبدیل را انجام می‌دهد و تکرار فرمان امن است):

```powershell
php artisan call-notes:backfill
```

مرکز کارها در مسیر `/tasks` قرار دارد و Task را می‌توان به Lead، Contact، Company، Deal، Call یا Campaign متصل کرد. جزئیات schema، API، مجوزها و rollback در [راهنمای P1](docs/P1_TASKS_AND_CALL_NOTES_FA.md) آمده است.

فاز P2 برد چندپایپ‌لاین فرصت‌ها، workspace فروش، جست‌وجوی سراسری، نماهای ذخیره‌شده، scoring/SLA، اتوماسیون محدود، فیلدهای سفارشی و گزارش عملیات را اضافه می‌کند. داشبورد نقش‌محور در `/` صفحه پیش‌فرض باقی می‌ماند. جزئیات API، مجوزها، scheduler و rollback در [راهنمای P2](docs/P2_PROFESSIONAL_CRM_FA.md) آمده است.

پایش دستی SLA (اجرای تکراری امن است):

```powershell
cd backend
php artisan sla:monitor
```

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

```powershell
cd backend
php artisan test
composer audit

cd ..\frontend
npm run lint
npm run test:run
npm run build
npm run test:e2e
npm audit --audit-level=high
```

برای فایل‌های PHP تغییرکرده نیز `vendor\bin\pint --test <files>` را اجرا کنید. CI تست‌های بک‌اند را روی SQLite، MySQL و PostgreSQL و lint، unit test، build و E2E فرانت‌اند را اجرا می‌کند.

## انتشار امن

ابتدا همه تغییرات مورد انتشار را commit کنید و مطمئن شوید working tree تمیز است. سپس:

```powershell
.\scripts\package-release.ps1
```

اسکریپت فقط فایل‌های tracked در commit فعلی را archive می‌کند، مسیرهای حساس/وابستگی‌ها را رد می‌کند و در صورت مشاهده الگوی secret متوقف می‌شود. خروجی پیش‌فرض `artifacts/crm-release.zip` است. فایل‌های `.env`، دیتابیس محلی، `vendor`، `node_modules`، log و build محلی وارد بسته نمی‌شوند.

قبل از انتشار واقعی، secretهای محیط مقصد را خارج از Git نگه دارید و اگر قبلاً جایی افشا شده‌اند آن‌ها را در سرویس مربوطه rotate کنید. سپس cacheهای production را با `php artisan optimize` بسازید.

## Rollback

قبل از migrate از دیتابیس نسخه پشتیبان بگیرید. برای برگشت آخرین batch:

```powershell
cd backend
php artisan migrate:rollback --step=1 --force
```

مهاجرت نرمال‌سازی Sales Script داده‌های رابطه‌ای قدیمی را به کلیدهای canonical در `campaigns` و `products` منتقل می‌کند؛ بنابراین rollback تولیدی باید همراه با backup و برنامه بازیابی داده انجام شود.

در rollback مهاجرت تاریخچه تماس، Noteهای تولیدشده با `source_key=legacy_call:*` حذف می‌شوند ولی ستون قدیمی `calls.notes` دست‌نخورده است. nullable شدن `notes.user_id` و رفتار `nullOnDelete` عمداً برگشت داده نمی‌شود تا حذف کاربر باعث نابودی تاریخچه نشود؛ برای rollback تولیدی P1 راهنمای بالا و backup الزامی است.