#P1495
POST /financial/items
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/financial/items | V2CreditDebitController@financialItems | authWithJwt | دریافت ساختار و آیتمهای حساب مالی یک مؤلفه مشخص مانند دفتر، شرکت یا مرجع برای نمایش یا محاسبه درخت حسابداری. |
منطق عملکرد تابع
تابع financialItems وظیفه دارد بر اساس نوع حساب و شناسه دادهشده در درخواست (مثل نوع moeen یا preference)، آیتمهای مالی مرتبط را از جداول پایه حسابداری واکشی و سازماندهی کند. این دادهها معمولاً جهت ساخت نمای درختی حسابها (TreeView) در رابط کاربری استفاده میشوند.
در ابتدای اجرای تابع، مجموعه حسابهای سطح پایه از accounting_titles خوانده میشود؛ سپس بر اساس نوع ورودی (request->type)، شاخههای فعال یا غیرفعال علامتگذاری میگردند. هر آیتم دارای کلیدهایی مانند subset، locked و display است که در خروجی JSON تنظیم میشوند.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| type | string | Body | بله | نوع حساب مالی که باید آیتمهای آن واکشی شوند (مثلاً moen یا preference). |
| branch | integer | JWT/Header | بله | شناسه شعبهای که دادههایش باید فیلتر شود. |
| filters | object | Body | خیر | فیلتر اختیاری شامل وضعیت حساب یا سطح دسترسی. |
خروجی (Response)
{
"status": true,
"time": 1732287600,
"items": [
{
"id": 1,
"title": "داراییهای جاری",
"subset": true,
"locked": false,
"display": true
},
{
"id": 2,
"title": "بدهیهای جاری",
"subset": false,
"locked": false,
"display": true
}
]
}
نکات امنیتی
- احراز توکن JWT برای تعیین شعبه ضروری است.
- دسترسی به این API محدود به نقشهای دارای مجوز
financial.viewerیا بالاتر است. - هیچ دادهای از حسابهای غیرفعال یا قفل شده برای
non-adminبرگردانده نمیشود.
نکات عملکردی
- آیتمها از Redis کش شوند با کلید
financial:items:{branch}:{type}و مدت اعتبار 1800 s. - در صورت تغییر ساختار حساب، کش باید پاکسازی (invalidate) شود.
- زمان پاسخ کمتر از 200 ms در بار معمولی است.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Http\Controllers\StaticController;
- use Carbon\Carbon;
کدهای خطا
| کد | شرح خطا | منبع |
| 400 | نوع حساب نامعتبر یا فیلد type خالی است. | Validator |
| 403 | کاربر دسترسی مشاهده ندارد. | Middleware JWT |
| 500 | خطا در واکشی دادهها. | DB/Redis |
پیشنهادهای امنیتی
- استفاده از RBAC برای کنترل سطوح دسترسی view/edit.
- رمزگذاری خروجی آیتمها درون HTTPS جهت جلوگیری از تزریق داده.
- ثبت لاگ ممیزی در سطح Info برای هر درخواست.
پیشنهادهای بهبود
- افزودن قابلیت pagination برای آیتمهای حجیم حسابداری.
- پشتیبانی از جستجوی fuzzy روی نام آیتمها.
- افزودن شاخص version برای هر ساختار مالی جهت همگامسازی Frontend.
ممیزی و لاگها
- نوع لاگ:
FinancialItemsList. - فیلدها:
branch, type, operator_id. - سطح لاگ: Info.
- مدت نگهداری لاگ: ۳۰ روز.
جمعبندی
تابع financialItems یکی از نقاط مرکزی در ماژول مالی است که ساختار طبقهبندی حسابها را به شکل امن و سریع در اختیار رابط کاربری قرار میدهد. این تابع با ترکیب Redis Cache و درخت حسابداری پایگاه داده، عملکرد پایدار و انعطافپذیر ارائه میدهد.