GET /v2/account-history/all-daily

Route Info 

 

 

 

 

 Method 

 Endpoint 

 Controller 

 Middleware 

 

 

 GET 

 /v2/account-history/all-daily 

 AccountHistoryController@getAllDailyBalances 

 authWithJwt 

 

 

 

 

 شرح عملکرد (Functionality) 

 این API برای دریافت یکجای تمام سوابق روزانه یک سال خاص استفاده می‌شود (مثلاً برای رسم نمودار تغییرات موجودی در طول سال). 

 

 

 عملکرد دسته‌ای (Batch): به جای درخواست‌های متعدد، تمام کلیدهای کش مربوط به یک سال را اسکن و بازیابی می‌کند. 

 مرتب‌سازی: داده‌ها به صورت خودکار بر اساس تاریخ (Date) مرتب می‌شوند (Sort Ascending). 

 بدون محاسبه: این متد فقط خواندنی است و محاسبه‌ای انجام نمی‌دهد. فقط داده‌هایی که قبلاً محاسبه و کش شده‌اند را برمی‌گرداند. 

 

 

 ورودی (Query Parameters) 

 ?colleague_id=108&year=1403

 

 قوانین اعتبارسنجی (Validation Rules) 

 

 

 colleague_id: الزامی | integer | موجود در جدول colleagues . 

 year: الزامی | integer | بازه 1300 تا 1500. 

 

 

 منطق اجرا (Execution Logic) 

 

 

 اعتبارسنجی ورودی‌ها (بازگشت 400 در صورت خطا). 

 ساخت الگوی جستجو در Redis: DAILY_BALANCE_KEY{colleagueId}:{year}:* . 

 استفاده از دستور Redis::keys برای یافتن تمام کلیدهای منطبق. 

 حلقه روی کلیدها:

 

 دریافت مقدار (`Redis::get`) و دیکود کردن JSON. 

 

 

 ذخیره نتایج در آرایه با کلید تاریخ (برای دسترسی سریع‌تر در فرانت‌اند). 

 مرتب‌سازی آرایه بر اساس کلید (تاریخ) با تابع ksort . 

 بازگشت داده‌ها (حتی اگر لیست خالی باشد، آرایه خالی برمی‌گردد و خطای 404 نداریم). 

 

 

 پاسخ موفق (200 OK) 

 توجه کنید که کلیدهای آبجکت payload همان تاریخ‌ها هستند. 

 {

 "payload": {

 "1403-01-01": {

 "credit": 0,

 "debit": 100000,

 "balance": -100000,

 "date": "1403-01-01"

 },

 "1403-01-02": {

 "credit": 50000,

 "debit": 0,

 "balance": -50000,

 "date": "1403-01-02"

 },

 "1403-05-20": {

 "credit": 200000,

 "debit": 0,

 "balance": 150000,

 "date": "1403-05-20"

 }

 },

 "meta": {

 "colleague_id": 108,

 "year": 1403,

 "total_days": 3,

 "cached": true,

 "timestamp": "2025-12-01T16:15:00+03:30"

 }

}

 

 

 پاسخ‌های خطا (Error Responses) 

 خطای اعتبارسنجی (400) 

 {

 "error": {

 "code": "VALIDATION_ERROR",

 "message": "The year must be between 1300 and 1500."

 },

 "meta": { ... }

}

 

 خطای سرور (500) 

 {

 "error": {

 "code": "INTERNAL_ERROR",

 "message": "Redis connection failed"

 },

 "meta": { ... }

}

 

 

 توضیحات فنی (Meta) 

 

 

 Redis Pattern: استفاده از Wildcard ( * ) در انتهای کلید. 

 Performance: این کوئری ممکن است روی دیتابیس‌های ردیس بسیار حجیم (میلیون‌ها کلید) کمی کند باشد، اما در اسکیل فعلی قابل قبول است. 

 خروجی به صورت Dictionary (Map) است، نه آرایه ساده؛ تا دسترسی به یک تاریخ خاص در کلاینت (Client-Side) راحت‌تر باشد (O(1)).