# POST /colleagues/ledger-accounts

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td dir="ltr">POST</td><td dir="ltr">/api/v2/colleagues/ledger-accounts</td><td dir="ltr">V2ColleaguesController@colleagueLedgerAccounts</td><td dir="ltr">authWithJwt</td><td dir="rtl">دریافت فهرست حساب‌های معین، کل و تفصیلی مرتبط با هر همکار (Colleague) برای مقاصد گزارش‌گیری حسابداری.</td></tr></tbody></table>

</div>### منطق عملکرد تابع

تابع **colleagueLedgerAccounts** وظیفه دارد حساب‌های معین مرتبط با همکار مشخص را از ساختار حسابداری استخراج کند. این تابع معمولاً هنگام تهیه گزارش دفتر کل یا نمایش جزئیات مالی یک همکار فراخوانی می‌شود. عملکرد کلی:

<div id="bkmrk-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D8%B4%D9%86%D8%A7%D8%B3%D9%87%D9%94-%D9%87%D9%85%DA%A9%D8%A7%D8%B1-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">1. دریافت شناسهٔ همکار (`colleague_id`) از درخواست و بررسی صحت آن.
2. بازیابی حساب‌های معین (moeen) که در جداول `accounting_moeens` به همکار اشاره دارند.
3. اتصال به جداول `accounting_generals` و `accounting_groups` برای تکمیل سلسله‌مراتب حساب.
4. ساخت خروجی با ساختار سه‌سطحی (گروه – کل – معین) جهت نمایش در UI یا محاسبه.
5. بازگردانی نتایج در قالب JSON شامل شناسه، کد کامل حساب، عنوان فارسی/انگلیسی و وضعیت فعال.

</div>### پارامترهای ورودی

<div id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D9%85%D8%AD%D9%84-%D8%A7%D9%84%D8%B2%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 95%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>پارامتر</td><td>نوع</td><td>محل</td><td>الزامی</td><td>توضیح</td></tr><tr><td>colleague\_id</td><td>integer</td><td>Body</td><td>بله</td><td>شناسه داخلی همکار مورد نظر.</td></tr><tr><td>branch</td><td>string</td><td>Body</td><td>خیر</td><td>شناسه شعبه جهت فیلتر حساب‌ها.</td></tr><tr><td>include\_inactive</td><td>boolean</td><td>Body</td><td>خیر</td><td>اگر مقدار `true` باشد، حساب‌های غیرفعال نیز بازگردانده می‌شوند.</td></tr></tbody></table>

</div>### ساختار خروجی

```
[
  {
    "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"
    }
  }
]
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C-%D9%81%D9%82%D8%B7-%D8%A8%D8%B1%D8%A7%DB%8C-%DA%A9%D8%A7%D8%B1%D8%A8" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- دسترسی فقط برای کاربران احراز هویت شده با JWT معتبر مجاز است.
- در صورت وجود پارامتر branch، کاربران فقط به حساب‌های مربوط به شعبه خود دسترسی دارند.
- اطلاعات حساس حساب (مانند شماره شبا یا شناسه مالیاتی) در خروجی حذف می‌شود.

</div>### نکات عملکردی

<div id="bkmrk-%DA%A9%D9%88%D8%A6%D8%B1%DB%8C%E2%80%8C%D9%87%D8%A7-%D8%A8%D8%A7-%D8%A7%D8%B3%D8%AA%D9%81%D8%A7%D8%AF%D9%87-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- کوئری‌ها با استفاده از `leftJoin` بین سه جدول اصلی انجام می‌شود تا از N+1 Query جلوگیری شود.
- نتیجه با `collection()` و `map()` به فرمت خروجی تبدیل می‌شود.
- میانگین زمان پاسخ: زیر ۸۰ میلی‌ثانیه.

</div>### وابستگی‌ها

<div id="bkmrk-use-illuminate%5Csuppo" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Illuminate\\Support\\Facades\\DB;
- use App\\Http\\Controllers\\Functions;
- use App\\Models\\AccountingMoeen;
- use App\\Models\\Colleague;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-400-%D9%BE%D8%A7%D8%B1%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح</td><td>منبع</td></tr><tr><td>400</td><td>پارامتر colleague\_id ارسال نشده است.</td><td>Validation</td></tr><tr><td>404</td><td>هیچ حسابی برای همکار یافت نشد.</td><td>Query Result</td></tr><tr><td>500</td><td>خطای داخلی در پردازش داده‌ها یا joins.</td><td>DB Join Exception</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D8%A8%D9%87%D8%AA%D8%B1-%D8%A7%D8%B3%D8%AA-%D8%AE%D8%B1%D9%88%D8%AC%DB%8C-%D8%AA%D9%86%D9%87%D8%A7-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- بهتر است خروجی تنها شامل شناسه و عنوان بوده و کد کامل حساب به کاربران با سطح Manager نمایش داده شود.
- لاگ‌گیری از عملیات فیلتر بر اساس شعبه به‌منظور ردیابی دسترسی‌های غیرمجاز.

</div>### پیشنهادهای توسعه‌ای

<div id="bkmrk-%D8%A7%D9%85%DA%A9%D8%A7%D9%86-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- امکان افزودن پارامتر `type=moeen|general|group` برای فیلتر سطح نمایش.
- اتصال به کش Redis جهت کاهش بار پایگاه داده.
- افزودن نرخ به‌روزرسانی (RefreshDatetime) در خروجی مشابه مسیر colleaguesList.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%84%D8%A7%DA%AF%3A-ledgeraccou" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع لاگ: `LedgerAccountAccess`
- جزئیات ثبت‌شده: user\_id، colleague\_id، timestamp و تعداد حساب‌های یافته‌شده.
- سطح حساسیت: **Low to Medium**

</div>### جمع‌بندی

مسیر **/colleagues/ledger-accounts** یک نقطه کلیدی برای ارتباط بین سیستم مالی و سیستم حسابداری محسوب می‌شود. با استفاده از این Endpoint می‌توان تمام روابط حسابداری همکار را مرور کرد. کد بهینه‌سازی خوبی در join و تفکیک داده‌ها دارد، اما افزودن caching می‌تواند عملکرد را در محیط سازمانی بزرگ بهبود دهد.

<div id="bkmrk-colleague-ledger-accounts" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>