PATCH /v2/charter/financial/completion

Charter: Finalize Completion Financial Report

این اندپوینت برای نهایی‌سازی (Finalization) گزارش مالی تکمیلی یک چارتر طراحی شده است. پس از اینکه یک چارتر به پایان می‌رسد و تمام داده‌های فروش و هزینه‌ها مشخص می‌شود، این اندپوینت فراخوانی می‌شود تا یک "اسنپ‌شات" (Snapshot) از وضعیت مالی نهایی (شامل سود، زیان، هزینه سوخت‌شده و...) تهیه و آن را در پایگاه داده ثبت کند. این عمل معادل "بستن گزارش مالی" برای آن چارتر است و معمولاً پس از آن، امکان تغییر در رزروها یا داده‌های مالی مرتبط با آن چارتر محدود یا مسدود می‌شود.

Request Overview

Access Control

Request Body

برای مشخص کردن اینکه کدام چارتر باید نهایی شود، شناسه اصلی آن باید در بدنه درخواست ارسال گردد.

Example Request

{
  "main_id": 451
}

Logic Details

نکته مهم: کد ارائه شده صرفاً یک ساختار اولیه است. منطق واقعی این اندپوینت بسیار پیچیده‌تر بوده و شامل مراحل زیر خواهد بود:

Response Structure

پاسخ موفق

یک پاسخ موفق به این معنی است که گزارش مالی با موفقیت تولید و بایگانی شده است. طبق استاندارد REST، برای عملیات PATCH یا PUT که منجر به به‌روزرسانی موفقی شده اما بدنه پاسخی برای برگرداندن ندارد، از کد وضعیت 204 استفاده می‌شود.

پاسخ‌های خطا

خطاهای مختلفی ممکن است در این فرآیند رخ دهد:

PHP Implementation

کد زیر یک ساختار اولیه برای این اندپوینت است. منطق اصلی که در بخش "Logic Details" تشریح شد، باید در بلوک try پیاده‌سازی شود.

public function setCompletionFinancialCharter(Request $request)
{
    // Validate that 'main_id' exists in the request body.
    $validated = $request->validate([
        'main_id' => 'required|integer|exists:charter_main,id',
    ]);

    $mainId = $validated['main_id'];

    try {
        // 1. Check if the charter is already finalized.
        $charter = DB::table('charter_main')->where('id', $mainId)->first();
        if ($charter->finalized_at) {
            return response()->json([
                "message" => "Financial report for this charter has already been finalized."
            ], 409); // 409 Conflict
        }

        // 2. Generate the financial completion report data internally.
        // This would call the same logic as the getCompletionFinancialCharter() method.
        $reportData = $this->generateFinancialData($mainId); // Hypothetical internal method

        // 3. Store the snapshot.
        DB::table('charter_financial_snapshots')->insert([
            'charter_main_id' => $mainId,
            'snapshot_data' => json_encode($reportData),
            'finalized_by' => auth()->id(), // Get user ID from JWT
            'created_at' => now(),
            'updated_at' => now()
        ]);

        // 4. Update the main charter record to mark it as finalized.
        DB::table('charter_main')->where('id', $mainId)->update([
            'finalized_at' => now()
        ]);

        // 5. Return success response.
        return response('', 204);

    } catch (Exception $exception) {
        return response()->json([
            "message" => $exception->getMessage(),
            "trace" => $exception->getTrace()
        ], 400);
    }
}