# POST /api/v2/trade/item/edit

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" style="margin: 15px auto; width: 96%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td style="direction: ltr; text-align: left;">POST</td><td style="direction: ltr; text-align: left;">/api/v2/trade/item/edit</td><td style="direction: ltr; text-align: left;">V2TradeController@editItemTrade</td><td style="direction: ltr; text-align: left;">authWithJwt</td><td style="direction: rtl; text-align: right;">ویرایش آیتم خاص در فاکتور (فاکتوری آنلاین یا آفلاین) براساس نوع خدمت</td></tr></tbody></table>

</div>### منطق عملکرد

<div id="bkmrk-%D9%85%D8%AA%D8%AF-%D8%A7%D9%85%DA%A9%D8%A7%D9%86-%D9%88%DB%8C%D8%B1%D8%A7%DB%8C%D8%B4-%D8%AC%D8%B2%D8%A6" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- متد امکان ویرایش جزئیات هر آیتم فاکتور را بسته به نوع `action` (online, route, hotel, visa, service, ...) فراهم می‌کند.
- اگر فیلد `created` وجود نداشته باشد، نوع و جزئیات آیتم تشخیص داده و فیلد `details` ساخته می‌شود.
- بر اساس `edit_all` مشخص می‌کند که آیا باید تمام آیتم‌های مشابه فاکتور به‌روزرسانی شوند یا فقط آیتم موردنظر.
- در صورت وجود `created`، قبل از تغییر تاریخ، بسته بودن دوره مالی بررسی می‌شود (بر اساس تنظیم `END_OF_FINANCIAL_PERIOD_CLOSING_ACCOUNTS`).
- تمام تغییرات به کمک `SystemLog::dispatch` ثبت‌شده و کش Redis مربوط به آیتم حذف می‌شود.
- در صورت ویرایش همه آیتم‌ها، تمام کلیدهای cache مربوطه `reference_item:*:information:title:fa` پاک می‌شوند.

</div>### ورودی‌ها

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%81%DB%8C%D9%84%D8%AF-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%B6%D8%B1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" style="margin: 15px auto; width: 97%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام فیلد</td><td>نوع داده</td><td>ضروری</td><td>توضیح</td></tr><tr><td>item\_id</td><td>int</td><td>بله</td><td>شناسه آیتم فاکتور جهت ویرایش</td></tr><tr><td>action</td><td>string</td><td>بله</td><td>نوع آیتم (online, route, visa, hotel, service, ...)</td></tr><tr><td>edit\_all</td><td>bool</td><td>خیر</td><td>در صورت true، تمام آیتم‌های مشابه در فاکتور ویرایش می‌شوند</td></tr><tr><td>provider</td><td>object | null</td><td>خیر</td><td>تامین‌کننده خدمت</td></tr><tr><td>buy</td><td>int</td><td>خیر</td><td>مبلغ خرید (قیمت پایه از تأمین‌کننده)</td></tr><tr><td>sell</td><td>int</td><td>خیر</td><td>مبلغ فروش نهایی</td></tr><tr><td>failure\_bill</td><td>bool</td><td>خیر</td><td>پرچم مشخص‌کننده وجود فاکتور معیوب</td></tr><tr><td>created</td><td>YYYYMM</td><td>خیر</td><td>برای تغییر تاریخ ایجاد آیتم فاکتور (در حالت ویژه)</td></tr><tr><td>passenger</td><td>object</td><td>خیر</td><td>اطلاعات مسافر، شامل شناسه و تاریخ تولد (در بلیت‌ها)</td></tr><tr><td>currency</td><td>object</td><td>خیر</td><td>واحد ارزی، ضریب تبدیل، و مبلغ تبدیل‌شده</td></tr><tr><td>online|route|hotel|visa|insurance|service</td><td>object</td><td>در حالت خاص</td><td>جزئیات آیتم بر حسب نوع خدمت</td></tr></tbody></table>

</div>```
{
  "item_id": 205,
  "action": "online",
  "edit_all": false,
  "online": { "type": "aircraft", "flight_number": "W5-1155", "original_ticket_no": "774221", "date_time_path": "2025-11-21 13:20" },
  "buy": 8800000,
  "sell": 9400000,
  "currency": { "unit": "IRR", "exchange": 1, "amount": 9400000 },
  "provider": { "id": 2 }
}
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### ساختار &lt;details&gt; بر اساس action

<div id="bkmrk-online.aircraft%3A-%D8%B4%D8%A7%D9%85" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- **online.aircraft:** شامل datetime، flight\_number، original\_ticket\_no
- **route.aircraft:** شامل origin, destination, datetime\_departure, flight\_no, ticket\_no, baggage و غیره
- **hotel:** شامل login, logout, room\_type, room\_rate, roommate, transfer, ...
- **online.train:** شامل service, passenger.age\_title, origin، destination، datetime و اطلاعات مالی
- **online.accommodation:** شامل accommodation id، rate، check\_in/out، room\_type، roommate
- **visa / insurance / service:** شامل اطلاعات پایه، تاریخ صدور/انقضا و فایل پیوست

</div>### خروجی

<div id="bkmrk-%D9%81%DB%8C%D9%84%D8%AF-%D9%86%D9%88%D8%B9-%D8%B4%D8%B1%D8%AD-status-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" style="margin: 15px auto; width: 97%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>فیلد</td><td>نوع</td><td>شرح</td></tr><tr><td>status</td><td>bool</td><td>نتیجه نهایی عملیات</td></tr><tr><td>time</td><td>int</td><td>مهر زمانی سیستم</td></tr><tr><td>code</td><td>int|null</td><td>کد خطا در صورت وجود</td></tr><tr><td>message</td><td>string|null</td><td>توضیح خطا</td></tr></tbody></table>

</div>```
{
  "status": true,
  "time": 1732022461
}
```

<div id="bkmrk--2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-5002-%D8%A2%DB%8C%D8%AA" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" style="margin: 15px auto; width: 90%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح</td><td>منبع</td></tr><tr><td>5002</td><td>آیتم فاکتور یافت نشد</td><td>در صورت نبود item\_id معتبر</td></tr><tr><td>5003</td><td>خطا در اجرای تراکنش/پایگاه داده</td><td>catch(Exception)</td></tr><tr><td>5007</td><td>تلاش برای ویرایش تاریخ در دوره مالی بسته‌شده</td><td>ولیدیشن تاریخی</td></tr></tbody></table>

</div>### اثرات جانبی

<div id="bkmrk-%D8%AF%D8%B1-%D8%B5%D9%88%D8%B1%D8%AA-%D9%88%DB%8C%D8%B1%D8%A7%DB%8C%D8%B4-%D9%85%D9%88%D9%81%D9%82%D8%8C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- در صورت ویرایش موفق، Cache Redis برای آیتم مربوطه حذف می‌شود.
- در صورت `edit_all` = true، کش تمام آیتم‌های factor نیز حذف می‌گردد.
- SystemLog شامل لاگ کامل تغییرات (data diff) و اطلاعات اپراتور ثبت می‌شود.

</div>### امنیت

<div id="bkmrk-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%D8%A7%D8%B2-%D8%B7%D8%B1%DB%8C%D9%82-jwt-%D8%A7%D9%84" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- احراز از طریق JWT الزامی است (`authWithJwt`).
- تغییر تاریخ تنها در صورت بسته نبودن دوره مالی ممکن است.
- دسترسی فقط برای اپراتورهای معتبر مجاز است.

</div>### کارایی

<div id="bkmrk-%D8%B9%D9%85%D9%84%DB%8C%D8%A7%D8%AA-%DA%A9%D8%A7%D9%85%D9%84%D8%A7%D9%8B-db-tra" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- عملیات کاملاً DB transaction-safe نیست اما atomic روی سطر واحد اجرا می‌شود.
- dispatch لاگ با delay در صف `snailJob` انجام می‌شود تا latency پاسخ کاهش یابد.
- در حالت `edit_all`، بروزرسانی گروهی ممکن است تا 0.3s افزایش زمان پاسخ داشته باشد.

</div>### وابستگی‌ها

<div id="bkmrk-use-carbon%5C%5Ccarbon%3B-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Carbon\\\\Carbon;
- use Morilog\\\\Jalali\\\\Jalalian;
- use Illuminate\\\\Support\\\\Facades\\\\DB;
- use Illuminate\\\\Support\\\\Facades\\\\Redis;
- use App\\\\Helpers\\\\Functions;
- use App\\\\Jobs\\\\SystemLog;

</div>### پیشنهادهای بهبود

<div id="bkmrk-%D8%A7%D8%B3%D8%AA%D8%A7%D9%86%D8%AF%D8%A7%D8%B1%D8%AF%D8%B3%D8%A7%D8%B2%DB%8C-%D8%B3%D8%A7%D8%AE%D8%AA%D8%A7%D8%B1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- استانداردسازی ساختار `details` برای همه `action`ها در قالب Schema واحد.
- افزودن محدودکننده validation برای واحدهای پولی و نرخ تبدیل.
- بررسی امکان atomic transaction کامل هنگام ویرایش گروهی.

</div>### جمع‌بندی

متد **editItemTrade** نقطه‌ی کنترل جزئیات دقیق فاکتور است؛ برای هر نوع خدمت (از بلیت هواپیما تا ویزا و بیمه) جزئیات را بازسازی و در پایگاه داده به‌روزرسانی می‌کند. از نظر معماری با `editTrade` تفاوت دارد چون روی آیتم واحد تمرکز دارد و لاگینگ دقیق row-level را اعمال می‌کند. این ترکیب بین **دقت، سرعت و قابلیت audit** تعادل مطلوبی ایجاد کرده است.

<div id="bkmrk-root" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>