#P1810

GET /b2c/v1/ledger-account

ledger-account CreditDebitController

این اندپوینت برای واکشی حساب کل دفتر همکار (colleague) در سیستم مالی B2C به‌کار می‌رود و از داده‌های تجمیع‌شده در Redis و خروجی متد ColleaguesController::colleagueLedgerAccounts استفاده می‌کند تا هم جزئیات صورت‌حساب‌ها (ledger items) و هم مانده‌ی کل حساب را برگرداند.

Endpoint Information

URL: /b2c/v1/ledger-account

Method: GET

Controller: CreditDebitController@ledgerAccount

Middleware: authWithJwt

Dependencies: ColleaguesController@colleagueLedgerAccounts, Redis, Morilog\Jalali\Jalalian

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

نام	نوع	الزامی	توضیح
operator (JWT)	object	✅	حاوی اطلاعات کاربر احراز شده، خصوصاً `colleague_id`
branch	integer	✅	شناسه دفتر یا شعبه کاربر

منطق پردازشی (Flowchart)

📥 ۱. دریافت درخواست و استخراج شناسه همکار از JWT (operator->colleague_id)

↓

⚙️ ۲. ساخت پیش‌فرض‌های JSON جستجو (فیلتر زمانی و پارامترهای گزارش):

from = یک ماه قبل به تاریخ شمسی (با Jalalian::now()->subMonths(1))
to = تاریخ امروز
status = "0"
lbalance = false

↓

🧩 ۳. تزریق داده‌ی JSON تولیدشده در $request['json'] و $request['id'] سپس ایجاد نمونه از ColleaguesController و فراخوانی متد colleagueLedgerAccounts() برای واکشی جزئیات تراکنش‌ها.

↓

🗄️ ۴. واکشی مانده کلی حساب از Redis با کلید: colleagues:general_billing:all{colleague_id} در صورت موجود بودن داده، پارس آن با json_decode().

↓

بررسی وجود داده در Redis:

✅ اگر موجود بود → ساخت آرایه شامل debit, credit, balance, diagnosis, documents از داده Redis
❌ اگر نبود → مقادیر صفر پیش‌فرض تنظیم می‌شود

↓

✅ ۵. ساخت پاسخ JSON شامل لیست آیتم‌های دفتر کل و جزئیات موجودی: { items, payload, meta.timestamp }

ساختار خروجی JSON

پاسخ موفق

{
  "items": [
    {
      "serial_id": "1404-22",
      "datetime": "1404/09/01 00:00:00",
      "credit": 500000,
      "debit": 0,
      "description": { "html": "واریز بابت فاکتور #22", "text": "واریز بابت فاکتور #22" },
      "details": { "type": { "title": "دریافت نقدی" } }
    }
  ],
  "payload": {
    "debit": 1250000,
    "credit": 500000,
    "balance": -750000,
    "diagnosis": "بدهکار",
    "documents": 17
  },
  "meta": { "timestamp": 1733768901 }
}

پاسخ بدون داده

{
  "items": [],
  "payload": {
    "debit": 0,
    "credit": 0,
    "balance": 0,
    "diagnosis": 0,
    "documents": 0
  },
  "meta": { "timestamp": 1733768903 }
}

نکات فنی و باگ‌های شناسایی‌شده

اگر Redis کلید colleagues:general_billing:all{id} را نداشته باشد، پاسخ همواره با موجودی صفر ست می‌شود؛ بهتر است در این حالت سرویس colleagueLedgerAccounts برای جمع‌آوری داده‌ی جدید اجرا شود.
در نسخه فعلی، فیلد زمان‌ها و فرمت تاریخی بر اساس تاریخ شمسی با Morilog\Jalali تنظیم شده اما در سطح پایگاه داده (Carbon) تاریخ میلادی ذخیره می‌شود — نیاز به تطبیق هنگام sort در کلاینت دارد.
پاسخ دارای آرایه‌ای از آیتم‌های Ledger است که به‌صورت مستقیم از کنترلر همکار (`colleagueLedgerAccounts`) گرفته می‌شوند؛ در صورت تغییر ساختار آن متد، این خروجی نیز باید به‌روزرسانی شود.
بازگشت داده درون `meta.timestamp` با time() انجام می‌شود (یونیکس تایم).