# PATCH /v2/charter/financial/completion

# Charter: Finalize Completion Financial Report

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

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcharter%2Ffin"><div class="endpoint-info"><div>**URL:** `/v2/charter/financial/completion`</div><div>**Method:** <span class="method-patch">PATCH</span></div><div>**Controller:** CharterController@setCompletionFinancialCharter</div><div>**Middleware Stack:** authWithJwt</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C-%D9%85%D8%B9%D8%AA%D8%A8%D8%B1-jwt-%28%D8%AA%D9%88">- دسترسی معتبر JWT
- (توصیه می‌شود) دسترسی مبتنی بر نقش (Role-Based Access) فقط برای مدیران مالی یا ادمین‌های سیستم.

</div>## Request Body

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

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>main\_id</td><td>integer</td><td>**(الزامی)** شناسه اصلی چارتر (`main_id`) که گزارش مالی آن باید نهایی و ثبت شود.</td></tr></tbody></table>

</div>#### Example Request

```json
{
  "main_id": 451
}
```

<div class="api-docs" id="bkmrk--1"></div>## Logic Details

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

<div class="api-docs" id="bkmrk-%D8%A7%D8%B9%D8%AA%D8%A8%D8%A7%D8%B1%D8%B3%D9%86%D8%AC%DB%8C-%D9%88%D8%B1%D9%88%D8%AF%DB%8C%3A-%D8%B3%DB%8C">1. **اعتبارسنجی ورودی:** سیستم بررسی می‌کند که `main_id` در بدنه درخواست وجود داشته و معتبر است.
2. **بررسی وضعیت چارتر:**
    - ابتدا چارتر با `main_id` مشخص شده از پایگاه داده واکشی می‌شود.
    - سیستم بررسی می‌کند که آیا این چارتر قبلاً نهایی شده است یا خیر (مثلاً با چک کردن یک فیلد `finalized_at` در جدول اصلی چارتر). اگر قبلاً نهایی شده باشد، خطای `409 Conflict` بازگردانده می‌شود تا از ثبت مجدد جلوگیری شود.
3. **تولید داده‌های گزارش:**
    - سیستم به صورت داخلی منطق اندپوینت `GET /v2/charter/financial/completion` را فراخوانی می‌کند تا گزارش مالی کامل و تحلیلی (شامل `profit`, `burned`, `paid` و ...) را برای `main_id` مورد نظر تولید کند.
4. **ذخیره‌سازی اسنپ‌شات (Snapshot):**
    - کل شیء گزارش تولید شده (که خروجی اندپوینت GET است) به فرمت JSON تبدیل می‌شود.
    - این رشته JSON در یک جدول جدید و اختصاصی به نام `charter_financial_snapshots` یا مشابه آن، به همراه `main_id`، شناسه کاربری که عملیات را انجام داده (`finalized_by`)، و تاریخ/زمان فعلی (`finalized_at`) ذخیره می‌شود. این کار تضمین می‌کند که یک نسخه بایگانی‌شده و غیرقابل تغییر از گزارش نهایی همیشه در دسترس است.
5. **به‌روزرسانی وضعیت چارتر اصلی:**
    - پس از ذخیره موفقیت‌آمیز اسنپ‌شات، رکورد مربوط به چارتر در جدول اصلی (مثلاً `charter_main`) به‌روزرسانی شده و فیلد `finalized_at` آن با تاریخ و زمان فعلی پر می‌شود. این کار به عنوان یک پرچم (flag) عمل کرده و از نهایی‌سازی مجدد جلوگیری می‌کند.
6. **پاسخ نهایی:** در صورت موفقیت تمام مراحل، یک پاسخ `204 No Content` بازگردانده می‌شود که به کلاینت اعلام می‌کند عملیات با موفقیت انجام شده است.

</div>## Response Structure

### پاسخ موفق

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

<div class="api-docs" id="bkmrk-status-code%3A-204-no-">- **Status Code:** `204 No Content`
- **Body:** (Empty)

</div>### پاسخ‌های خطا

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

<div class="api-docs" id="bkmrk-status-code%3A-400-bad">- **Status Code:** `400 Bad Request`  
    **دلیل:** فیلد `main_id` در بدنه درخواست ارسال نشده یا نوع داده آن صحیح نیست.  
    ```json
    {
      "message": "The main id field is required."
    }
    ```
- **Status Code:** `404 Not Found`  
    **دلیل:** چارتری با `main_id` ارسال شده در سیستم وجود ندارد.  
    ```json
    {
      "message": "Charter not found."
    }
    ```
- **Status Code:** `409 Conflict`  
    **دلیل:** این گزارش مالی قبلاً نهایی شده است و امکان نهایی‌سازی مجدد وجود ندارد.  
    ```json
    {
      "message": "Financial report for this charter has already been finalized."
    }
    ```

</div>## PHP Implementation

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

```php

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);
    }
}
  
```