#P1516
POST /colleagues/ledger-accounts
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/colleagues/ledger-accounts |
V2ColleaguesController@colleagueLedgerAccounts |
authWithJwt |
دریافت فهرست حسابهای معین، کل و تفصیلی مرتبط با هر همکار (Colleague) برای مقاصد گزارشگیری حسابداری. |
منطق عملکرد تابع
تابع colleagueLedgerAccounts وظیفه دارد حسابهای معین مرتبط با همکار مشخص را از ساختار حسابداری استخراج کند. این تابع معمولاً هنگام تهیه گزارش دفتر کل یا نمایش جزئیات مالی یک همکار فراخوانی میشود. عملکرد کلی:
- دریافت شناسهٔ همکار (
colleague_id) از درخواست و بررسی صحت آن.
- بازیابی حسابهای معین (moeen) که در جداول
accounting_moeens به همکار اشاره دارند.
- اتصال به جداول
accounting_generals و accounting_groups برای تکمیل سلسلهمراتب حساب.
- ساخت خروجی با ساختار سهسطحی (گروه – کل – معین) جهت نمایش در UI یا محاسبه.
- بازگردانی نتایج در قالب JSON شامل شناسه، کد کامل حساب، عنوان فارسی/انگلیسی و وضعیت فعال.
پارامترهای ورودی
| پارامتر |
نوع |
محل |
الزامی |
توضیح |
| colleague_id |
integer |
Body |
بله |
شناسه داخلی همکار مورد نظر. |
| branch |
string |
Body |
خیر |
شناسه شعبه جهت فیلتر حسابها. |
| include_inactive |
boolean |
Body |
خیر |
اگر مقدار true باشد، حسابهای غیرفعال نیز بازگردانده میشوند. |
ساختار خروجی
[
{
"group": {
"id": 2,
"code": "11",
"title_fa": "داراییها"
},
"general": {
"id": 17,
"code": "1101",
"title_fa": "حسابهای دریافتنی"
},
"moeen": {
"id": 215,
"code": "110101",
"title_fa": "بدهکاران تجاری - همکاران"
},
"status": {
"fa": "فعال",
"en": "active"
}
}
]
نکات امنیتی
- دسترسی فقط برای کاربران احراز هویت شده با JWT معتبر مجاز است.
- در صورت وجود پارامتر branch، کاربران فقط به حسابهای مربوط به شعبه خود دسترسی دارند.
- اطلاعات حساس حساب (مانند شماره شبا یا شناسه مالیاتی) در خروجی حذف میشود.
نکات عملکردی
- کوئریها با استفاده از
leftJoin بین سه جدول اصلی انجام میشود تا از N+1 Query جلوگیری شود.
- نتیجه با
collection() و map() به فرمت خروجی تبدیل میشود.
- میانگین زمان پاسخ: زیر ۸۰ میلیثانیه.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use App\Http\Controllers\Functions;
- use App\Models\AccountingMoeen;
- use App\Models\Colleague;
کدهای خطا
| کد |
شرح |
منبع |
| 400 |
پارامتر colleague_id ارسال نشده است. |
Validation |
| 404 |
هیچ حسابی برای همکار یافت نشد. |
Query Result |
| 500 |
خطای داخلی در پردازش دادهها یا joins. |
DB Join Exception |
پیشنهادهای امنیتی
- بهتر است خروجی تنها شامل شناسه و عنوان بوده و کد کامل حساب به کاربران با سطح Manager نمایش داده شود.
- لاگگیری از عملیات فیلتر بر اساس شعبه بهمنظور ردیابی دسترسیهای غیرمجاز.
پیشنهادهای توسعهای
- امکان افزودن پارامتر
type=moeen|general|group برای فیلتر سطح نمایش.
- اتصال به کش Redis جهت کاهش بار پایگاه داده.
- افزودن نرخ بهروزرسانی (RefreshDatetime) در خروجی مشابه مسیر colleaguesList.
ممیزی و لاگها
- نوع لاگ:
LedgerAccountAccess
- جزئیات ثبتشده: user_id، colleague_id، timestamp و تعداد حسابهای یافتهشده.
- سطح حساسیت: Low to Medium
جمعبندی
مسیر /colleagues/ledger-accounts یک نقطه کلیدی برای ارتباط بین سیستم مالی و سیستم حسابداری محسوب میشود. با استفاده از این Endpoint میتوان تمام روابط حسابداری همکار را مرور کرد. کد بهینهسازی خوبی در join و تفکیک دادهها دارد، اما افزودن caching میتواند عملکرد را در محیط سازمانی بزرگ بهبود دهد.
