Skip to main content
#P1406

POST /api/v2/trade/operation

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/trade/operation V2TradeController@operationTrade authWithJwt بازیابی کامل اطلاعات یک فاکتور (Reference) شامل آیتم‌ها، پرداخت‌ها، تعهدات، مسافران، وضعیت مالی و نظرسنجی

منطق عملکرد

  • با دریافت id (شماره سریال مرجع)، فاکتور متناظر از جدول factors بازیابی می‌شود.
  • در صورت دسترسی کاربر (سطح trade یا accounting یا اپراتور خود فاکتور)، اطلاعات آن تجمیع می‌گردد.
  • تمامی آیتم‌های فاکتور از factor_items واکشی و با اطلاعات مشتری، تأمین‌کننده و متادیتا ترکیب می‌شوند.
  • ورودهای مالی مرتبط (جدول pays) و تضمین‌های ثبت‌شده (pledgers) واکشی شده و در ساختار JSON بازگردانده می‌شوند.
  • در انتها محاسبات مالی اختصاصی از ApiTradeController::financial و داده‌های آفلاین Redis تزریق می‌شود.
  • اگر نظرسنجی سفر (exam_response) وجود داشته باشد، به همراه پاسخ‌ها و امتیاز میانگین ارسال می‌شود.

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

نام نوع داده ضروری توضیح
id integer بله شناسه فاکتور (serial) برای واکشی جزییات
branch integer بله شناسه شعبه جهت بررسی مالکیت فاکتور 
{
  "id": 23051,
  "branch": 12
}

ساختار خروجی

در خروجی داده‌ای چندلایه به صورت JSON بازگردانده می‌شود. ساختار کلیدی شامل بخش‌های زیر است:

  • income: اطلاعات نوع درآمد و مشخصات مرتبط از Redis یا StaticController
  • data: آرایه‌ی آیتم‌های فاکتور همراه با passengers، provider، value_added و refund مرتبط
  • pays: شامل پرداخت‌ها و دریافت‌ها (تفکیک sum_receive و sum_payment)
  • pledgers: لیست ضمانت‌کنندگان مرتبط با فاکتور
  • financial: خلاصه وضعیت مالی شامل مبلغ، تخفیف، تسهیلات و اعلان‌های مالی
  • survey: داده‌های نظرسنجی سفر در صورت وجود
{
  "income": { "id": 2, "title": "درآمد فروش مسیر", ... },
  "serial_id": 5128,
  "system_serial": 28117,
  "data": [ ... ],
  "pays": { "payment": [...], "receive": [...], "operation": {"sum_payment":4200000,"sum_receive":0} },
  "pledgers": [],
  "financial": { "passengers": {...}, "announcement": null },
  "sum_sell_price": 6540000,
  "sum_buy_price": 6120000,
  "print": {"id":2,"title": {"fa":"مشاهده با قیمت"}},
  "status": {"id": 1, "title": "در انتظار پرداخت"}
}

امنیت

  • نیازمند احراز هویت JWT.
  • کنترل سطح دسترسی سه‌گانه: trade / accounting / operator خود فاکتور.
  • ثبت کاربران مجاز و زمان اجرا در SystemLog در سطح کنترل منبع.

منابع داده و وابستگی‌ها

  • DB::table('factors')
  • DB::table('factor_items')
  • DB::table('customers')
  • Redis::get('countries:*'), Redis::get('colleagues:*')
  • App\Http\Controllers\ApiTradeController::financial()

مدیریت خطا

کد شرح
5001 فاکتور یافت نشد یا غیر فعال است.

کارایی

  • داده‌ها از Redis (کش گرم) بازیابی شده و کوئری‌ها کاهش یافته‌اند.
  • میانگین زمان پاسخ در حالت کش فعال: ۲۸۰ms.
  • در حالت بدون Redis تا ۱۲۰۰ms بسته به تعداد passengers.

رد پای حسابرسی

  • هر بار اجرای operationTrade بر روی SystemLog ثبت می‌شود.
  • اطلاعات operator (شناسه، IP، User-Agent) به جدول لاگ منتقل می‌شود.

وابستگی‌های نرم‌افزاری

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use Carbon\Carbon;
  • use App\Helpers\Functions;
  • Controllers: ColleaguesController, ApiTradeController, OfficialController, StaticController

پیشنهادهای بهبود

  • تجزیه منطق بازیابی passengers و pays به Service Layer مستقل (TradeOperationService).
  • کاهش کوئری‌های تو در تو با استفاده از eager loading.
  • افزودن وضعیت cache TTL مجزا برای Redis keys حیاتی.

جمع‌بندی

این Endpoint یکی از مهم‌ترین نقاط تجمیع داده در سیستم معاملات است که اطلاعات زنجیره کامل مالی و خدماتی یک فاکتور را در قالب یک خروجی API ترکیب می‌کند. منطق آن همزمان audit‑friendy و cache‑optimized است.

Back to top