CRM/README.md

CRM

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

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

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

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، ماتریس مجوز نقش‌های پیش‌فرض را همگام کنید:

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 نیز همین تبدیل را انجام می‌دهد و تکرار فرمان امن است):

php artisan call-notes:backfill

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

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

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

cd backend
php artisan sla:monitor

کنترل کیفیت

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 تمیز است. سپس:

.\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:

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 الزامی است.