#P1470
POST /api/v2/dashboard
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/dashboard |
V2BaseController@dashboard |
authWithJwt |
واکشی دادههای تحلیلی و وضعیت سرویسهای پایه برای صفحه داشبورد اپراتور |
منطق عملکرد تابع
تابع
dashboard دادههای اصلی سامانه (وضعیت ارتباط با سرویسهای وابسته، تعداد آیتمهای فعال، هشدارهای مرکزی و زمان آخرین همگامسازی) را جمعآوری و بازگردانی میکند:
- بررسی صحت اتصال با سرور مرکزی (hub یا service route) از طریق تابع اختصاصی اتصال.
- واکشی مقادیر و وضعیتهای کلیدی برای اپراتور فعلی.
- در صورت اتصال موفق: بازگرداندن تعداد آیتمهای فعال در فرمت
active.
- در صورت شکست اتصال یا خطای ارتباطی، برگرداندن پیام
Lack of connection with the central server.
- پوشش خطاهای Exception و بازگرداندن جزئیات آن در خروجی جهت بررسی سریع.
| نام فیلد |
نوع داده |
الزامی |
توضیح |
| branch |
integer |
بله |
شناسه شعبهٔ جاری برای بررسی وضعیت اتصال و سرویسهای فعال |
| operator_id |
integer |
خیر |
شناسه اپراتور برای ثبت یا تطبیق دادههای dashboard |
نمونه درخواست:
POST /api/v2/dashboard
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
{
"branch": 12
}
خروجی (Response)
| فیلد |
نوع داده |
توضیح |
| status |
boolean |
وضعیت کلی ارتباط (true = اتصال موفق) |
| time |
integer |
زمان UNIX درخواست |
| active |
integer |
تعداد آیتمهای فعال در سیستم مرکزی |
| data[] |
array |
دادههای حاصل از سرویس مرکزی در صورت اتصال موفق |
| message |
string |
پیام خطا در صورت قطع ارتباط |
نمونه پاسخ:
{
"status": true,
"time": 1732289412,
"active": 7,
"data": [{"service":"train","status":"OK"},{"service":"accommodation","status":"OK"}]
}
نکات امنیتی و کنترل دسترسی
- به واسطه
authWithJwt فقط کاربران تأیید شده JWT مجاز به مشاهده dashboard هستند.
- حاوی دادههای عملیاتی شعبه است، پس نباید برای کاربران خارج از محیط مدیریتی قابلدسترس باشد.
- فاقد رمزنگاری در پاسخ سرویس؛ در ارتباطات بینسرویس بهتر است از SSL داخلی استفاده شود.
- تابع سریع است ولی وابسته به latency ارتباط با سرور مرکزی.
- خطای موقت شبکه میتواند باعث تأخیر یا بازگشت پیام خطای "Lack of connection".
- پیشنهاد: پیادهسازی retry با backoff صعودی در صورت خطا برای نقطههای ارسال داده.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Http\Request;
- use Carbon\Carbon;
- use App\Helpers\Functions;
- use Exception;
کدهای خطا و پاسخهای Exception
| کد خطا |
شرح خطا |
منبع |
| 400 |
Database یا ارتباط ناموفق با سرویس مرکزی |
dashboard() |
| 1006 |
JWT غیر معتبر |
authWithJwt() |
| 500 |
Exception عمومی در runtime |
Exception handler |
پیشنهادهای امنیتی
- رمزنگاری دادههای آماری حساس با AES سمت سرور.
- محدودسازی مقدار بازگشتی برای جلوگیری از افشای وضعیت داخلی سرور.
- فیلتر خروجی بر اساس نقش کاربر (operator vs admin).
پیشنهادهای بهبود
- افزودن فیلد cache برای جلوگیری از خواندن مکرر در هر درخواست.
- افزودن latency tracker برای شناسایی نقاط ضعیف شبکه.
- نمایش شاخصهای uptime و CPU usage در نسخه بعدی.
ممیزی و لاگها
- در حال حاضر هیچ ممیزی برای ناکامی ارتباط ثبت نمیشود.
- پیشنهاد افزودن لاگ با نوع
DashboardConnectionFailed در جدول system_logs.
جمعبندی
تابع dashboard یکی از نقاط اصلی گزارش وضعیت سیستم است که ارتباط لحظهای و تعداد آیتمهای فعال را نمایش میدهد. ساختار خروجی به اندازه کافی خواناست؛ اما نبود ممیزی و کنترل سطح دسترسی، آن را در محیطهای production ناایمن میسازد. توصیه میشود role-based limitation و audit logging برای پایداری enterprise لحاظ گردد.
