# POST /v2/manual-document/list

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

<div id="bkmrk-method-endpoint-cont" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;"><table border="1" style="width: 100%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f4f4f4; font-weight: bold;"><td style="padding: 10px;">Method</td><td style="padding: 10px;">Endpoint</td><td style="padding: 10px;">Controller</td></tr><tr><td style="direction: ltr; padding: 10px;">POST</td><td style="direction: ltr; padding: 10px;">/v2/manual-document/list</td><td style="direction: ltr; padding: 10px;">AccountingController@listManualDocument</td></tr></tbody></table>

</div>### شرح عملکرد (Functionality)

این مسیر برای **لیست‌گیری، جستجو، فیلتر و صفحه‌بندی** اسناد دستی در جدول `manual_documents` استفاده می‌شود. عملکرد متد به صورت زیر است:

<div id="bkmrk-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%88%D8%B1%D9%88%D8%AF%DB%8C-json-%D8%A7%D8%B2" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;">- دریافت ورودی JSON از کلید `json` شامل تنظیمات صفحه‌بندی و فیلتر.
- محاسبه مقدار `start` بر اساس مقدار فعلی و طول (length).
- اجرای کوئری با شروط: 
    - فیلتر تاریخ بین `from` و `to`
    - فیلتر براساس سال
    - فیلتر شماره سند (from\_document / to\_document)
    - فیلتر بر اساس branch
- بارگذاری گزارش تراز سند از Redis: 
    - `documents:balance_report:{id}`
- در صورت نبود داده در Redis، فراخوانی `getManualDocumentDetails()`.
- ساخت خروجی استاندارد شامل: 
    - serial و system\_serial
    - title و description
    - status فارسی
    - تراز مالی (financial)

</div>### پارامترهای ورودی (JSON Body)

**Body Parameter:** کل ورودی در فیلد `json` ارسال می‌شود

```
{
  "start": 0,
  "length": 20,
  "draw": 1,
  "search": {
    "from": "1403-01-01",
    "to": "1403-01-30",
    "year": "",
    "from_document": "",
    "to_document": ""
  }
}
```

<div id="bkmrk-start%3A-%D9%86%D9%82%D8%B7%D9%87-%D8%B4%D8%B1%D9%88%D8%B9-%D8%B5%D9%81%D8%AD" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;">- **start**: نقطه شروع صفحه‌بندی
- **length**: تعداد آیتم در هر صفحه
- **draw**: شماره درخواست (برای DataTables)
- **search.from / search.to**: بازه تاریخی
- **search.year**: فیلتر سال
- **from\_document / to\_document**: بازه شماره سند (با تبدیل داخلی -1000)

</div>### خروجی موفق (Success Response)

```
{
  "status": true,
  "time": 1718450000,
  "draw": 1,
  "recordsTotal": 152,
  "recordsFiltered": 20,
  "data": [
    {
      "serial": 3125,
      "system_serial": 125,
      "type": "manual",
      "title": "سند شماره 3125 | 1403/01/25 | دستی - توضیحات",
      "date": "14030125",
      "manual_serial": false,
      "sub_serial": false,
      "description": "توضیحات سند",
      "status": "تائید نهایی",
      "financial": {
        "debit_financial_past": 0,
        "credit_financial_past": 0,
        "debit_start_period": 0,
        "credit_start_period": 0,
        "debit_during_period": 1500000,
        "credit_during_period": 900000,
        "debit_balance": 600000,
        "credit_balance": 0
      }
    }
  ]
}
```

<div id="bkmrk--1" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;"></div>### خروجی خطا (Error Response)

در صورت بروز خطای دیتابیس یا Exception:

```
{
  "status": false,
  "time": 1718450000,
  "code": 5005,
  "message": "SQL error message...",
  "trace": [ ... ]
}
```

<div id="bkmrk--2" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;"></div>### نکات داخلی (Internal Logic Notes)

<div id="bkmrk-%D8%B4%D9%85%D8%A7%D8%B1%D9%87-%D8%B3%D9%86%D8%AF-%D8%AE%D8%B1%D9%88%D8%AC%DB%8C-%3D-se" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;">- شماره سند خروجی = `serial + 1000`
- تاریخ خروجی به صورت `YYYYMMDD` در فیلد date
- عنوان سند از طریق `getManualDocumentTitle()` ساخته می‌شود
- گزارش تراز مالی سند در Redis با کلید `documents:balance_report:{id}`
- بازه صفحه = `currentPage = start / length`

</div>