Skip to main content
#P1519

POST /colleague/operation

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/colleague/operation V2ColleaguesController@operationColleague authWithJwt ایجاد، ویرایش یا حذف همکار با پردازش داده‌های مالی، عمومی و ارتباطی

منطق عملکرد تابع

تابع operationColleague نقطه اصلی مدیریت عملیات (CRUD) بر روی موجودیت colleague است. بسته به action موجود در دادهٔ ورودی، می‌تواند ایجاد، ویرایش، یا حذف داده را انجام دهد. این تابع علاوه بر جدول اصلی colleagues جداول کمکی colleague_additional و mapping_colleagues را نیز مدیریت می‌کند و پس از تغییر، کش Redis را به‌روزرسانی می‌کند.

  1. دریافت پارامترهای JSON از بدنه درخواست.
  2. بررسی مقدار فیلد action (create/update/delete).
  3. در صورت create → درج رکورد جدید در جدول اصلی و جداول ارتباطی.
  4. در صورت update → اعمال تغییرات در ردیف مشخص‌شده و ثبت تاریخ بروزرسانی.
  5. در صورت delete → حذف نرم (soft delete) رکورد همکار و غیرفعالسازی در Redis.
  6. به‌روزرسانی کش با job UpdateRedis برای شاخص colleague:{id}.
  7. بازگرداندن نتیجه همراه با وضعیت و زمان انجام عملیات.

پارامترهای ورودی

نام نوع محل الزامی توضیح
json string (JSON) Body بله اطلاعات کامل عملیات و پارامترها
action string Body بله یکی از مقادیر create، update، delete
id int Body خیر شناسه همکار (در حالت update یا delete لازم است)
office string Body در create الزامی نام تجاری یا دفتر همکار
financial_code string Body خیر کد مالیاتی/شناسه اقتصادی
type int Body خیر نوع همکار (۱: بستانکار، ۲: بدهکار، ۳: دوطرفه)
category int Body خیر دسته‌بندی همکار (شرکت، آژانس، هتل و...)
details object Body خیر اطلاعات تکمیلی در جدول colleague_additional

ساختار خروجی

{
  "status": true,
  "action": "update",
  "colleague_id": 142,
  "message": "colleague record updated successfully",
  "time": "2025-11-23T14:32:17+03:30"
}

نکات امنیتی

  • دسترسی فقط برای کاربران با سطح admin.colleague یا finance.manager مجاز است.
  • هر عملیات در جدول system_logs با فیلدهای user_id، action، object_id ثبت می‌شود.
  • ورودی JSON قبل از decode با json_last_error() کنترل می‌شود.

نکات عملکردی

  • در عملیات update فقط فیلدهای تغییر یافته در SQL تعریف می‌شود تا Lock کاهش یابد.
  • در insert رابطه‌ها به‌صورت batch با Query Builder درج می‌شوند.
  • Job اختصاصی UpdateRedis برای ریسک پایین Cache Miss ثبت می‌شود.

Dependencies

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use Carbon\Carbon;
  • use App\Jobs\UpdateRedis;
  • use App\Models\Colleague;
  • use App\Models\ColleagueAdditional;
  • use App\Models\MappingColleagues;

کدهای خطا

کد توضیح منبع
400 پارامترهای ضروری ارسال نشده‌اند Validation
401 توکن احراز هویت اعتبار ندارد Middleware
404 همکار مورد نظر یافت نشد Model Query
500 خطای داخلی پایگاه داده در زمان ثبت یا بروزرسانی DB Transaction

پیشنهادهای امنیتی

  • رمزنگاری فیلدهای حساس مانند کد اقتصادی قبل از ذخیره.
  • عدم اجازه update برای فیلد نقش مالی بدون سطح دسترسی super.finance.
  • سیاهه ممیزی قابل پیگیری با امضا دیجیتال (hash of payload) افزوده شود.

پیشنهادهای توسعه‌ای

  • اضافه کردن پشتیبانی از عملیات bulk (چندهمکار در یک درخواست).
  • افزودن تاریخچه تغییرات در جدول colleague_history.
  • افزودن event realtime برای Notification بخش مدیریت.

ممیزی و لاگ‌ها

  • ثبت در system_logs با event: ColleagueOperation
  • فیلدهای لاگ‌شده: user_id, colleague_id, action, payload_hash, timestamp
  • ارسال خلاصه فعالیت به Redis Channel: colleague:activity

جمع‌بندی

تابع operationColleague موتور اصلی و مرکزی CRUD همکاران در لایه API است. تمامی تغییرات ساختاری، مالی و ارتباطی در یک نقطه مجتمع شده‌اند تا تداخلی میان جداول colleagues و colleague_additional ایجاد نشود. این ساختار، در امتداد استاندارد داخلی «Enterprise V1.1»، پایه‌ای برای audit، cache و عملیات هم‌زمان فراهم می‌آورد.

Back to top