Added Docs

2026-09-12 17:02:12 +03:30
parent ed9ef3bac3
commit 401ad6a143
7 changed files with 979 additions and 2 deletions
--- a/docs/report-api-frontend-fa.md
+++ b/docs/report-api-frontend-fa.md
@@ -0,0 +1,402 @@
+# مستند فرانت‌اند API گزارش PDF پرونده
+
+## هدف API
+این API داده‌ی ساخت‌یافته‌ی لازم برای تولید PDF پرونده در پنل بیمه‌گر را برمی‌گرداند.
+خروجی آن ترکیبی از اطلاعات پرونده‌ی تقصیر (`blame`) و پرونده‌ی خسارت (`claim`) است و طوری طراحی شده که فرانت‌اند بدون وابستگی به مدل‌های داخلی بک‌اند، فقط با `sections` و `fields` بتواند PDF را رندر کند.
+
+---
+
+## آدرس API
+
+```http
+GET /expert-insurer/files/:publicId/report
+```
+
+### پارامتر مسیر
+- `publicId`: شناسه عمومی پرونده
+
+---
+
+## ساختار کلی پاسخ
+
+```json
+{
+  "title": "گزارش پرونده بیمه گر",
+  "publicId": "RPT832-00406",
+  "requestNo": "BL-RPT832-000406",
+  "sections": []
+}
+```
+
+### فیلدهای سطح بالا
+
+#### `title`
+عنوان کلی گزارش.
+
+#### `publicId`
+شناسه عمومی پرونده.
+
+#### `requestNo`
+شماره درخواست، اگر در داده‌های پرونده موجود باشد.
+
+#### `sections`
+آرایه‌ای از سکشن‌های گزارش.
+هر سکشن یک عنوان دارد و شامل تعدادی ردیف اطلاعات (`fields`) است.
+
+---
+
+## ساختار هر سکشن
+
+```json
+{
+  "title": "زمان‌بندی پرونده",
+  "fields": [
+    {
+      "label": "تاریخ و ساعت ثبت پرونده",
+      "value": "1405/06/02 07:02"
+    }
+  ]
+}
+```
+
+### `title`
+عنوان فارسی سکشن، آماده‌ی نمایش در PDF.
+
+### `fields`
+لیست ردیف‌های اطلاعاتی همان سکشن.
+
+---
+
+## ساختار هر فیلد
+
+```json
+{
+  "label": "شماره بیمه‌نامه",
+  "value": "POL-12345"
+}
+```
+
+### `label`
+عنوان فارسی فیلد.
+
+### `value`
+مقدار فیلد.
+برای نمایش مستقیم در PDF استفاده می‌شود.
+
+---
+
+## سکشن‌های ممکن در پاسخ
+سکشن‌ها معمولاً با ترتیب زیر برمی‌گردند، ولی فرانت‌اند بهتر است به‌جای تکیه بر ایندکس آرایه، سکشن را با `title` پیدا کند:
+
+1. `زمان‌بندی پرونده`
+2. `مالک خودروی زیان دیده`
+3. `مالک خودروی مقصر`
+4. `راننده خودروی زیان دیده`
+5. `بیمه شخص ثالث زیان‌دیده`
+6. `بیمه بدنه زیان‌دیده`
+7. `بیمه شخص ثالث مقصر`
+8. `بیمه بدنه مقصر`
+9. `اطلاعات خودروی زیان‌دیده`
+10. `اطلاعات خودروی مقصر`
+11. `اظهارات و اقرار زیان‌دیده`
+12. `اظهارات و اقرار مقصر`
+13. `کدهای فناوران`
+14. `نتیجه ارزیابی`
+15. `گزارش حادثه`
+
+نکته:
+- بعضی سکشن‌ها بسته به نوع پرونده ممکن است وجود نداشته باشند.
+- در پرونده‌های بدنه (`CAR_BODY`) اگر طرفین عملاً یک نفر باشند، سکشن‌های مربوط به مقصر ممکن است حذف شوند.
+- در پرونده‌های شخص ثالث (`THIRD_PARTY`) انتظار می‌رود اطلاعات هر دو طرف به‌صورت تفکیک‌شده برگردد.
+
+---
+
+# توضیح سکشن‌ها
+
+## 1) `زمان‌بندی پرونده`
+برای نمایش زمان‌های مهم پرونده.
+
+فیلدهای مهم:
+- `تاریخ و ساعت ثبت پرونده`
+- `تاریخ و ساعت ثبت نتیجه ارزیابی`
+
+نکته:
+- این تاریخ‌ها در بک‌اند فرمت شده‌اند و آماده‌ی نمایش هستند.
+
+---
+
+## 2) `مالک خودروی زیان دیده`
+اطلاعات مالک یا صاحب خودروی زیان‌دیده.
+
+فیلدهای رایج:
+- `نام`
+- `شماره تلفن`
+- `کد ملی`
+- `تاریخ تولد`
+- `شماره شبا`
+
+نکته:
+- `شماره شبا` معمولاً برای زیان‌دیده مهم است و ممکن است فقط در همین سکشن وجود داشته باشد.
+
+---
+
+## 3) `مالک خودروی مقصر`
+اطلاعات مالک خودروی مقصر.
+
+فیلدهای رایج:
+- `نام`
+- `شماره تلفن`
+- `کد ملی`
+- `تاریخ تولد`
+
+نکته:
+- این سکشن مخصوص پرونده‌های شخص ثالث اهمیت دارد تا اطلاعات مالک هر دو طرف در PDF موجود باشد.
+
+---
+
+## 4) `راننده خودروی زیان دیده`
+اگر راننده با مالک/بیمه‌گذار متفاوت باشد، این سکشن برمی‌گردد.
+
+فیلدهای رایج:
+- `نام`
+- `نوع گواهینامه`
+- `تاریخ گواهینامه`
+- `شماره تلفن`
+- `کد ملی`
+- `تاریخ تولد`
+- `شماره گواهینامه`
+
+نکته:
+- اگر راننده و مالک یکی باشند، این سکشن ممکن است وجود نداشته باشد.
+
+---
+
+## 5) `بیمه شخص ثالث زیان‌دیده`
+اطلاعات بیمه شخص ثالث طرف زیان‌دیده.
+
+فیلدهای رایج:
+- `شماره بیمه‌نامه`
+- `شرکت بیمه`
+- `تاریخ شروع بیمه‌نامه`
+- `تاریخ پایان بیمه‌نامه`
+- `سقف تعهد مالی`
+- `پوشش‌ها`
+
+---
+
+## 6) `بیمه بدنه زیان‌دیده`
+اطلاعات بیمه بدنه‌ی طرف زیان‌دیده.
+
+فیلدهای رایج:
+- `شماره بیمه‌نامه`
+- `شرکت بیمه`
+- `تاریخ شروع بیمه‌نامه`
+- `تاریخ پایان بیمه‌نامه`
+- `پوشش‌ها`
+
+---
+
+## 7) `بیمه شخص ثالث مقصر`
+اطلاعات بیمه شخص ثالث طرف مقصر.
+
+فیلدهای رایج:
+- `شماره بیمه‌نامه`
+- `شرکت بیمه`
+- `تاریخ شروع بیمه‌نامه`
+- `تاریخ پایان بیمه‌نامه`
+- `سقف تعهد مالی`
+- `پوشش‌ها`
+
+---
+
+## 8) `بیمه بدنه مقصر`
+اطلاعات بیمه بدنه‌ی طرف مقصر.
+
+فیلدهای رایج:
+- `شماره بیمه‌نامه`
+- `شرکت بیمه`
+- `تاریخ شروع بیمه‌نامه`
+- `تاریخ پایان بیمه‌نامه`
+- `پوشش‌ها`
+
+---
+
+## 9) `اطلاعات خودروی زیان‌دیده`
+جزئیات خودروی زیان‌دیده.
+
+فیلدها می‌توانند شامل موارد زیر باشند:
+- `خودرو / پلاک`
+- `خودرو / نام خودرو`
+- `خودرو / مدل خودرو`
+- `خودرو / نوع خودرو`
+- `VIN`
+- `شماره موتور`
+- `شماره شاسی`
+- `رنگ اصلی`
+- `رنگ فرعی`
+- `سیستم`
+- `تیپ`
+- `کاربری`
+- `ظرفیت`
+- `تعداد سیلندر`
+
+نکته:
+- بسته به منبع داده، ممکن است بعضی فیلدها با برچسب‌های نزدیک به هم ولی از دو منبع مختلف برگردند.
+
+---
+
+## 10) `اطلاعات خودروی مقصر`
+جزئیات خودروی طرف مقصر.
+
+فیلدها مشابه سکشن خودروی زیان‌دیده هستند.
+
+---
+
+## 11) `اظهارات و اقرار زیان‌دیده`
+اطلاعات مربوط به اظهارات طرف زیان‌دیده.
+
+فیلدهای رایج:
+- `نقش طرف`
+- `نام`
+- `ادعای خسارت`
+- `پذیرش نظر کارشناس`
+- `توضیحات طرف`
+
+نکته:
+- معمولاً `اقرار به تقصیر` برای زیان‌دیده نمایش داده نمی‌شود.
+
+---
+
+## 12) `اظهارات و اقرار مقصر`
+اطلاعات مربوط به اظهارات طرف مقصر.
+
+فیلدهای رایج:
+- `نقش طرف`
+- `نام`
+- `اقرار به تقصیر`
+- `پذیرش نظر کارشناس`
+- `توضیحات طرف`
+
+نکته:
+- معمولاً `ادعای خسارت` برای مقصر نمایش داده نمی‌شود.
+
+---
+
+## 13) `کدهای فناوران`
+کدها و شناسه‌های فنی مرتبط با پرونده در فناوران.
+
+فیلدهای ممکن:
+- `شماره پرونده فناوران`
+- `کد پرونده فناوران`
+- `کد کیس خسارت فناوران`
+- `کد کارشناسی فناوران`
+- `کد بیمه‌نامه فناوران`
+- `کد راننده فناوران`
+- `کد نوع خودرو فناوران`
+- `کد شرکت بیمه فناوران`
+
+---
+
+## 14) `نتیجه ارزیابی`
+اطلاعات نتیجه‌ی ارزیابی کارشناس خسارت.
+
+فیلدهای مهم:
+- `نتیجه ارزیابی`
+- `کارشناس ارزیاب`
+- `تاریخ و ساعت ثبت ارزیابی`
+- `پاسخ / توضیحات کارشناس`
+
+---
+
+## 15) `گزارش حادثه`
+خلاصه‌ی اطلاعات حادثه، وضعیت پرونده و برخی خروجی‌های کارشناسی.
+
+فیلدهای رایج:
+- `تاریخ حادثه`
+- `ساعت حادثه`
+- `کارشناس(ان)`
+- `موقعیت (عرض و طول جغرافیایی)`
+- `وضعیت آب و هوا`
+- `وضعیت جاده`
+- `وضعیت نور`
+- `وضعیت مقصر`
+- `وضعیت خسارت`
+- `نظر کارشناس مقصر`
+- `نحوه برخورد`
+- `علت حادثه`
+- `نوع حادثه`
+- `توضیحات طرف`
+
+---
+
+## نکات مهم برای فرانت‌اند
+
+### 1) فقط بر اساس `sections` و `fields` رندر کنید
+ساختار اصلی خروجی این است:
+
+```ts
+response.sections[].title
+response.sections[].fields[].label
+response.sections[].fields[].value
+```
+
+---
+
+### 2) به ایندکس سکشن‌ها وابسته نشوید
+ممکن است بعضی سکشن‌ها در بعضی پرونده‌ها وجود نداشته باشند.
+بهتر است سکشن را با `title` پیدا کنید.
+
+---
+
+### 3) نبودن بعضی سکشن‌ها طبیعی است
+مثلاً:
+- `راننده خودروی زیان دیده`
+- سکشن‌های مربوط به مقصر در بعضی پرونده‌های بدنه
+- بعضی داده‌های فناوران
+
+---
+
+### 4) مقدار `-` یعنی داده‌ای برای نمایش وجود نداشته
+اگر سکشنی داده‌ی واقعی نداشته باشد، ممکن است فقط این مقدار را داشته باشد:
+
+```json
+{
+  "label": "اطلاعات",
+  "value": "-"
+}
+```
+
+---
+
+### 5) برچسب‌ها فارسی و آماده‌ی نمایش هستند
+فیلدهای `title` و `label` نیازی به ترجمه‌ی مجدد در فرانت‌اند ندارند.
+
+---
+
+## نمونه‌ی ساده‌ی رندر در فرانت‌اند
+
+```ts
+for (const section of response.sections) {
+  renderSectionTitle(section.title)
+
+  for (const field of section.fields) {
+    renderRow(field.label, field.value ?? "-")
+  }
+}
+```
+
+---
+
+## خلاصه
+این API برای تولید PDF پرونده، داده‌ها را به‌صورت کامل و تفکیک‌شده برمی‌گرداند، از جمله:
+
+- زمان‌بندی پرونده
+- اطلاعات مالک زیان‌دیده
+- اطلاعات مالک مقصر
+- اطلاعات راننده در صورت متفاوت بودن
+- بیمه‌نامه‌های تفکیک‌شده‌ی ثالث و بدنه برای هر طرف
+- اطلاعات خودرو برای هر دو طرف
+- اظهارات و اقرار هر دو طرف
+- کدهای فناوران
+- نتیجه ارزیابی و توضیحات کارشناس
+- گزارش حادثه