# PUT /v2/cartable/letters/step/{id}

<div class="api-docs" id="bkmrk-">  <div class="endpoint-section">  
</div></div>## Workflow Progression Logic

این متد یک مرحله خاص (`cartable\_letter\_steps`) از یک نامه را بروزرسانی می‌کند.   
**جادوی گردش کار:** اگر وضعیت ارسالی برابر با <span style="color: green; font-weight: bold;">3 (انجام شده)</span> باشد، سیستم به صورت خودکار پیکربندی "موضوع نامه" (`subject-&gt;steps`) را بررسی کرده و مرحله بعدی را در دیتابیس ایجاد می‌کند.

<div class="api-docs" id="bkmrk--1"><div class="endpoint-section">  
</div>  
---

  </div># Update Letter Step

تغییر وضعیت یک مرحله، ثبت توضیحات و (در صورت اتمام) ارجاع خودکار به مرحله بعد.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcartable%2Fle"><div class="endpoint-info"><div>**URL:** `/v2/cartable/letters/step/{id}`</div><div>**Method:** <span class="method-put">PUT</span></div><div>**Controller:** LetterController@updateLetterStep</div></div></div>### URL Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">id</td><td>Integer</td><td>(الزامی) شناسه رکورد مرحله در جدول `cartable_letter_steps`.</td></tr></tbody></table>

</div>### Body Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr-1"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">status</td><td>Integer</td><td>(الزامی) وضعیت جدید.   
`3` = انجام شده (Done) -&gt; **محرک مرحله بعدی**.  
سایر اعداد = صرفاً بروزرسانی وضعیت.</td></tr><tr><td dir="ltr">description</td><td>String</td><td>(اختیاری) توضیحات یا هامش روی این مرحله.</td></tr></tbody></table>

</div>### Logic Details (Backend)

<div class="api-docs" id="bkmrk-%D8%AB%D8%A8%D8%AA-%D8%B2%D9%85%D8%A7%D9%86-%D8%A7%D8%AA%D9%85%D8%A7%D9%85%3A-%D8%A7%DA%AF%D8%B1-">- **ثبت زمان اتمام:** اگر `status == 3` باشد، فیلد `done_at` با زمان فعلی پر می‌شود.
- **منطق ایجاد مرحله بعد:**
    1. سیستم `letter\_id` را پیدا کرده و از روی آن `subject\_id` را می‌یابد.
    2. آرایه JSON مراحل (`steps`) را از جدول `cartable\_subjects` می‌خواند.
    3. موقعیت فعلی را در آرایه پیدا کرده و اگر ایندکس بعدی (`index + 1`) وجود داشته باشد، یک رکورد جدید با وضعیت پیش‌فرض برای مرحله بعد ایجاد می‌کند.

</div>### Success Response

```json
{
    "payload": 1, // نشان دهنده موفقیت آمیز بودن عملیات (تعداد ردیف تغییر کرده)
    "meta": {
        "timestamp": 1733765000
    }
}
```

<div class="api-docs" id="bkmrk--2">---

</div>### Visual Logic Flow

<div class="api-docs" id="bkmrk-update-step-status-%E2%86%93"><div class="flowchart"><div class="flow-item">Update Step Status</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fffde7;">**Check: Is Status == 3?**</div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process" style="background-color: #e3f2fd;">**Fetch Workflow Config**  
(Find current step index in Subject's JSON)</div><div class="flow-arrow">↓</div><div class="flow-item-success">**Next Step Exists?**  
Insert new record into `cartable_letter_steps`</div></div></div>