Toornaa
/
CRM
1
0
انشعاب 0
کد مسائل درخواست‌های ادغام بسته‌ها عنوان پروژه‌ها انتشارها ویکی فعالیت
CRM/docs/P1_TASKS_AND_CALL_NOTES_FA.md

5.3 KiB
خام پیوند همیشگی سرزنش تاریخچه

راهنمای فنی P1: Task و تاریخچه یادداشت تماس

دامنه پیاده‌سازی

P1 یک Task عمومی و polymorphic برای lead، contact، company، deal، call و campaign اضافه می‌کند. نام کلاس PHP هیچ‌وقت از ورودی API پذیرفته نمی‌شود و alias امن در سرور resolve می‌شود. این فاز همچنین یادداشت چندتایی تماس، reminderهای idempotent، notification دارای read_at، audit قبل/بعد و حفظ تاریخی شماره تماس را پوشش می‌دهد.

مدل داده

  • tasks: موضوع، توضیحات، taskable_type/id، مسئول/تخصیص‌دهنده/سازنده، اولویت، وضعیت، موعد، شروع/تکمیل/یادآوری، parent، تخمین، visibility، version و soft delete.
  • notes: تاریخچه polymorphic با type، visibility، pin، زمان ویرایش، source_key یکتا و soft delete. user_id برای حفظ تاریخچه پس از حذف کاربر nullable و nullOnDelete است.
  • internal_notifications: زمان خواندن و کلید idempotency یکتا.
  • activity_logs: snapshotهای redacted قبل/بعد و request ID.
  • contact_phones: soft delete؛ تماس‌های تاریخی شماره حذف‌شده را با withTrashed بازیابی می‌کنند.

وضعیت‌های Task عبارت‌اند از open، in_progress، done و cancelled. مسیرهای مجاز lifecycle در سرویس دامنه کنترل می‌شوند و تمام mutationها version را افزایش می‌دهند. ویرایش با version قدیمی پاسخ استاندارد 409 VERSION_CONFLICT می‌دهد.

API اصلی

  • GET/POST /api/tasks و GET/PATCH/DELETE /api/tasks/{id}
  • POST /api/tasks/{id}/assign|start|complete|reopen|cancel
  • POST /api/tasks/bulk-assign و POST /api/tasks/bulk-complete (اتمیک)
  • GET /api/users/assignable?context=task&search=... (فقط کاربران active و مجاز؛ حداکثر ۲۰ نتیجه)
  • GET/POST /api/calls/{call}/notes
  • PATCH/DELETE /api/notes/{note} و POST /api/notes/{note}/pin|unpin
  • GET /api/notifications، PATCH /api/notifications/read-all و PATCH /api/notifications/{id}/read

فهرست Task فیلترهای status، priority، assignee، creator، بازه موعد، overdue، entity، search، sort و pagination را می‌پذیرد. پاسخ‌های جدید envelope استاندارد data/meta/links/message دارند.

مجوز و scope

مجوزهای مستقل view own/team/all، create، assign/reassign، edit own/team، delete، complete، bulk، مدیریت note و pin تعریف شده‌اند. Policy و scope سرور منبع حقیقت‌اند:

  • Admin تمام Taskهای سازمان و کاربران فعال را می‌بیند.
  • Supervisor فقط Task و کاربران تیم خودش (به‌علاوه خودش) را مدیریت می‌کند.
  • Agent فقط Taskهای خود را می‌بیند و نمی‌تواند Task را به کاربر دیگر تخصیص دهد.
  • visibility خصوصی فقط برای مشارکت‌کننده مجاز است و IDOR با 403 بسته می‌شود.

مهاجرت و backfill

قبل از استقرار backup بگیرید، سپس:

cd backend
php artisan migrate --force
php artisan permissions:sync-defaults
php artisan call-notes:backfill

migration و فرمان backfill از source_key=legacy_call:{id} استفاده می‌کنند؛ اجرای تکراری Note دوم نمی‌سازد. calls.notes حذف یا بازنویسی نمی‌شود و فقط به‌عنوان legacy read-only باقی می‌ماند. Noteهای نتیجه تماس جدید مستقیماً به تاریخچه افزوده می‌شوند.

Scheduler و صف

Scheduler هر ۱۵ دقیقه reminderهای Task و Follow-up را بررسی می‌کند. Taskهای done/cancelled اعلان نمی‌گیرند و idempotency key از تکرار reminder/overdue جلوگیری می‌کند.

php artisan schedule:work
php artisan queue:work

در production این دو process را با Supervisor/systemd یا سرویس مشابه پایدار کنید.

Rollback

برای بازگشت سه migration P1 در آخرین batch:

php artisan migrate:rollback --step=3 --force

Rollback جدول Task و ستون‌های افزوده را حذف می‌کند و Noteهای backfillشده با کلید legacy پاک می‌شوند؛ متن اصلی در calls.notes باقی است. تغییر notes.user_id به nullable/nullOnDelete عمداً به cascade قدیمی برنمی‌گردد تا تاریخچه با حذف کاربر از بین نرود. در production rollback را فقط همراه backup و بررسی batch اجرا کنید.

کنترل کیفیت

cd backend
php artisan test

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

تست‌های Feature، ماتریس نقش و IDOR، lifecycle و conflict، bulk transaction، note و visibility، backfill، notification/reminder و شماره تاریخی را پوشش می‌دهند. E2E مسیر ایجاد و تخصیص Task توسط Supervisor را در مرورگر پوشش می‌دهد.