#P1556

POST /api/v2/tasks/category/operation

Route Info

Method	Endpoint	Controller	Middleware
POST	/api/v2/tasks/category/operation	OfficialController@operationTasksCategory	authWithJwt

منطق دقیق عملکرد (Code Logic)

این متد عملیات CRUD را به صورت تجمیعی و با استفاده از Query Builder (نه Eloquent Model) مدیریت می‌کند. مراحل اجرا به ترتیب:

استخراج داده‌ها: متغیر data$ از ورودی request->data$ پر می‌شود (نکته: اگر این پارامتر ارسال نشود، در خطوط بعدی ارور PHP دریافت خواهید کرد).
بررسی Action: بر اساس مقدار فیلد action یکی از سه بلوک زیر اجرا می‌شود:
- store:
  - یک رکورد در جدول tasks_categories درج می‌شود.
  - فیلد branch از ریکوئست، user از شناسه اپراتور لاگین شده، و title/color/icon از آرایه data خوانده می‌شوند.
  - شناسه رکورد درج شده (Insert ID) گرفته می‌شود اما در خروجی برگردانده نمی‌شود.
- update:
  - رکورد جدول tasks_categories که id آن برابر با request->id$ است آپدیت می‌شود.
  - هیچ شرط دیگری (مثل بررسی شعبه) در کوئری وجود ندارد.
- delete:
  - ابتدا رکورد اصلی از جدول tasks_categories حذف می‌شود.
  - سپس تمام idهای جدول tasks_items که مربوط به این دسته هستند (where('category', $request->id)) استخراج می‌شوند.
  - سپس تمام رکوردهای tasks_items مربوطه حذف می‌شوند.
  - در نهایت تمام رکوردهای جدول tasks_notes که مربوط به تسک‌های استخراج شده هستند حذف می‌شوند (حذف دستی ارتباطات).
پاسخ: در صورت موفقیت آرایه‌ای شامل وضعیت و زمان سرور برمی‌گرداند.

ساختار ورودی مورد انتظار

سیستم انتظار دارد ورودی‌ها دقیقاً به این شکل ارسال شوند (در غیر این صورت وارد بلوک catch می‌شود):

POST /api/v2/tasks/category/operation
Authorization: Bearer <JWT>

{
  "action": "store",      // الزامی: store | update | delete
  "id": 10,               // الزامی برای update و delete
  "branch": 1001,         // الزامی (معمولا توسط کلاینت یا میدل‌ور ست می‌شود)
  "data": {               // الزامی (حتی برای delete باید ارسال شود وگرنه کد کرش می‌کند)
      "title": "جلسات",    // الزامی برای store و update
      "color": "#ffffff", // الزامی برای store و update
      "icon": "fa-user"   // الزامی برای store و update
  }
}

خروجی واقعی

موفقیت آمیز:

{
  "status": true,
  "time": 1732037000
}

در صورت بروز خطا (Exception):
شامل متن دقیق خطای PHP و Stack Trace کامل برای دیباگ.

{
  "status": false,
  "time": 1732037005,
  "message": "Trying to access array offset on value of type null", // مثال اگر data ارسال نشود
  "trace": [...]
}

عملیات دیتابیس (Direct DB Manipulation)

این متد مستقیماً با جداول زیر درگیر است:

tasks_categories (Insert, Update, Delete)
tasks_items (Select, Delete)
tasks_notes (Delete)

نکات فنی و خطاهای محتمل

وابستگی به آرایه data: در خط اول متد $data = $request->data اجرا می‌شود. اگر کلاینت پارامتر data را نفرستد، کد متوقف نمی‌شود اما در خطوط بعدی (مثلا $data['title']) خطا می‌دهد.
حذف بدون Transaction: عملیات حذف در ۳ مرحله انجام می‌شود. اگر در مرحله حذف tasks_items خطایی رخ دهد، دسته‌بندی حذف شده اما نوت‌ها باقی می‌مانند (Partial Delete Risk).
عدم بررسی مالکیت (Ownership): کوئری‌های Update و Delete فقط id را چک می‌کنند. این یعنی کد اجازه می‌دهد دسته‌بندی متعلق به یک شعبه دیگر، توسط کاربری در شعبه متفاوت ویرایش شود (صرفاً با داشتن ID).