From bfbcfcab3750cd3cc9fc6804376fcbbddea37ed3 Mon Sep 17 00:00:00 2001 From: SepehrYahyaee <7heycallmegray@gmail.com> Date: Mon, 17 Aug 2026 17:18:49 +0330 Subject: [PATCH] Added documentation --- docs/blame-claim-flow-architecture.fa.html | 1506 ++++++++++++++++ docs/blame-claim-flow-architecture.html | 1893 ++++++++++++++++++++ docs/external-integrations-reference.html | 593 ++++++ docs/panel-roles-reference.fa.html | 624 +++++++ docs/panel-roles-reference.html | 616 +++++++ 5 files changed, 5232 insertions(+) create mode 100644 docs/blame-claim-flow-architecture.fa.html create mode 100644 docs/blame-claim-flow-architecture.html create mode 100644 docs/external-integrations-reference.html create mode 100644 docs/panel-roles-reference.fa.html create mode 100644 docs/panel-roles-reference.html diff --git a/docs/blame-claim-flow-architecture.fa.html b/docs/blame-claim-flow-architecture.fa.html new file mode 100644 index 0000000..6961e64 --- /dev/null +++ b/docs/blame-claim-flow-architecture.fa.html @@ -0,0 +1,1506 @@ + + + + معماری جریان تقصیر و خسارت + + + +
+

معماری جریان تقصیر و خسارت

+

+ تمام جریان‌های فعال — V1 (قدیمی) · V2 · V3 · V4 · V5 · V6 — به همراه نقش‌ها، + پیشوندهای مسیر و ترتیب مراحل +

+ + +

راهنما و نقش‌ها

+
+
+
نقش‌ها به تفکیک جریان
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
جریانبازیگر تقصیربازیگر خسارت / بررسی
V1 / V2 (کاربر)USER + USER + + DAMAGE_EXPERT +
پنل کارشناس تقصیر + EXPERT + FIELD_EXPERT + —
پنل کارشناس خسارت— + DAMAGE_EXPERT + FIELD_EXPERT + FILE_REVIEWER + FILE_MAKER +
V2 کارشناس میدانی (mirror) + FIELD_EXPERT + + FIELD_EXPERT +
V3 + FIELD_EXPERT + + FIELD_EXPERT +
V4 + FILE_MAKER + + FILE_REVIEWER +
V5 + FILE_MAKER + + FILE_REVIEWER + + + FILE_MAKER + (تأیید نهایی) +
V6 + CALL_CENTER + + USER + (از طریق لینک) + + USER + + DAMAGE_EXPERT + (جریان استاندارد V2) +
+
+
+
پیشوندهای مسیر (Route Prefix)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
جریانپیشوند تقصیرپیشوند خسارت / بررسی
V1 (قدیمی)blame-request-management/claim-request-management/
V2 کاربرv2/blame-request-management/v2/claim-request-management/
V2 کارشناس میدانی (mirror)v2/expert-initiated/blame-request-management/همان کنترلر (بدون پیشوند جداگانه)
پنل کارشناس تقصیر V2v2/expert-blame/v2/expert-claim/
V3v3/expert-initiated/blame-request-management/همان کنترلر
V4v4/file-maker/blame-request-management/v4/file-reviewer/blame-request-management/
V5v5/file-maker/blame-request-management/v5/file-reviewer/blame-request-management/ + v5/file-maker/claim-approval/
V6v6/call-center-blame/ (اپراتور) + v2/blame-request-management/ (کاربر لینک)v2/claim-request-management/
+
+
+ + +

جریان V1 / V2 — تقصیر و خسارت کاربر‌محور

+

+ جریان کاربری استاندارد. هر طرف روی دستگاه خودش اپ را باز می‌کند. + طرف اول اطلاعات تقصیر را پر می‌کند و طرف دوم را با لینک SMS دعوت می‌کند. + بررسی کارشناسی تقصیر اختیاری است. پس از تکمیل تقصیر، طرف خسارت‌دیده + پرونده خسارت باز می‌کند که توسط کارشناس قیمت‌گذاری می‌شود. + V1 = مسیرهای قدیمی (منسوخ) · V2 = همان منطق با پیشوند v2/. +

+
+
+
فاز تقصیر
+
+ بازیگر:USER Guard: GlobalGuard +
+
+
+
1
+
+
ایجاد درخواست
+
POST /
+
+
+
↓
+
+
2
+
+
اعتراف تقصیر
+
POST /blame-confession/:id
+
+
+
↓
+
+
2a
+
+
[فقط CAR_BODY] فرم بدنه خودرو
+
POST /car-body-form/:id
+
+
+
↓
+
+
3
+
+
فرم اولیه (پلاک یا VIN)
+
POST /initial-form/:id or /initial-form-vin/:id
+
+
+
↓
+
+
4
+
+
جزئیات: موقعیت · صدا · توضیح
+
POST /add-detail-location, /upload-voice, /add-detail-description
+
+
+
↓
+
+
5
+
+
افزودن طرف دوم (ارسال لینک SMS)
+
POST /add-second-party/:phone/:id/:frontendRoute
+
+
+
↓
+
+
6
+
+
طرف دوم مراحل ۲–۴ را پر می‌کند
+
طرف دوم با دستگاه خودش وارد می‌شود
+
+
+
↓
+
+
7
+
+
امضا (هر دو طرف)
+
PUT /sign/:id
+
تصویر امضا + فلگ isAccept ارسال می‌شود
+
+
+
↓
+
+
8
+
+
[اختیاری] بررسی کارشناس تقصیر
+
via v2/expert-blame — assign → reply/resend
+
کارشناس پرونده را قفل می‌کند، ممکن است ارسال مجدد بخواهد، رأی نهایی می‌دهد
+
+
+
↓
+
+
9
+
+
تقصیر تکمیل شد (COMPLETED)
+
طرف مقصر مشخص شد
+
+
+
+
+ +
+
فاز خسارت
+
+ بازیگر:USER (طرف خسارت‌دیده) + + DAMAGE_EXPERT +
+
+
+
1
+
+
ایجاد خسارت از تقصیر
+
POST v2/claim-request-management/create-from-blame/:blameId
+
+
+
↓
+
+
2
+
+
انتخاب قطعات بیرونی
+
PATCH /select-outer-parts/:claimId
+
+
+
↓
+
+
3
+
+
انتخاب سایر قطعات + اطلاعات بانکی
+
PATCH /select-other-parts/:claimId
+
+
+
↓
+
+
4
+
+
آپلود مدارک
+
POST /upload-document/:claimId
+
+
+
↓
+
+
5
+
+
کپچر قطعات (عکس + زوایا)
+
POST /capture-part/:claimId
+
+
+
↓
+
+
6
+
+
فیلم دور خودرو (walk-around)
+
PATCH /car-capture/:claimId
+
→ WAITING_FOR_DAMAGE_EXPERT
+
+
+
↓
+
+
7
+
+
کارشناس خسارت بررسی و قیمت‌گذاری می‌کند
+
via v2/expert-claim — assign → reply / price-drop
+
+
+
↓
+
+
8
+
+
کاربر قیمت را تأیید / اعتراض / امتیاز می‌دهد
+
PUT /owner-insurer-approval/sign or /objection or /user-rating
+
+
+
+
+
+ + +

جریان V2 — کارشناس میدانی (Mirror، حضوری)

+

+ FIELD_EXPERT در صحنه تصادف تمام مراحل را به نمایندگی از هر دو طرف پر می‌کند. + پیشوند مسیر دقیقاً آینه‌ی API کاربری است — + v2/expert-initiated/blame-request-management/ — تا فرانت‌اند بتواند + صفحات یکسانی را با تعویض پیشوند استفاده کند. اولین طرف ثبت‌شده همیشه مقصر است. + پس از هر دو امضا، تقصیر بلافاصله تکمیل می‌شود (بدون صف بررسی کارشناسی). +

+
+
+
فاز تقصیر
+
+ بازیگر:FIELD_EXPERT Guard: LocalActorAuthGuard +
+
+
+
1
+
+
ایجاد (creationMethod=IN_PERSON)
+
POST /
+
+
+
↓
+
+
2
+
+
ارسال و تأیید OTP (مقصر)
+
POST /send-party-otp/:id → /verify-party-otp/:id
+
+
+
↓
+
+
3
+
+
اعتراف تقصیر (مقصر)
+
POST /blame-confession/:id
+
+
+
↓
+
+
3a
+
+
[فقط CAR_BODY] فرم بدنه خودرو
+
POST /car-body-form/:id
+
+
+
↓
+
+
4
+
+
فرم اولیه / استعلام (مقصر)
+
POST /run-inquiries/:id or /run-inquiries-vin/:id
+
+
+
↓
+
+
5
+
+
آپلود ویدیو (طرف اول / مقصر)
+
POST /upload-video/:id
+
+
+
↓
+
+
6
+
+
جزئیات: موقعیت · صدا · توضیح (مقصر)
+
POST /add-detail-location, /upload-voice, /add-detail-description
+
+
+
↓
+
+
7
+
+
افزودن طرف دوم (بدون لینک SMS)
+
POST /add-second-party/:phone/:id/
+
+
+
↓
+
+
8
+
+
OTP + استعلام + جزئیات (زیان‌دیده) — تکرار مراحل ۲–۶
+
فقط THIRD_PARTY
+
+
+
↓
+
+
9
+
+
امضای FIRST سپس امضای SECOND
+
PUT /sign/:id (دو بار، partyRole=FIRST / SECOND)
+
+
+
↓
+
+
10
+
+
فیلدهای حادثه → تقصیر تکمیل شد
+
POST /accident-fields/:id
+
بدون صف بررسی — پرونده فوری بسته می‌شود
+
+
+
+
+ +
+
فاز خسارت (همان کارشناس)
+
+ بازیگر:FIELD_EXPERT +
+
+
+
1
+
+
ایجاد خسارت از تقصیر
+
POST v2/expert-initiated/claim-request-management/create-from-blame/:blameId
+
+
+
↓
+
+
2
+
+
انتخاب قطعات بیرونی + سایر قطعات
+
PATCH /select-outer-parts, /select-other-parts
+
+
+
↓
+
+
3
+
+
آپلود مدارک
+
POST /upload-document/:claimId
+
+
+
↓
+
+
4
+
+
کپچر قطعات
+
POST /capture-part/:claimId
+
+
+
↓
+
+
5
+
+
فیلم دور خودرو (walk-around)
+
PATCH /car-capture/:claimId
+
→ WAITING_FOR_DAMAGE_EXPERT
+
+
+
↓
+
+
6
+
+
کارشناس خسارت بررسی می‌کند (جریان عادی)
+
via v2/expert-claim
+
+
+
+
+
+ + +

جریان V3 — کارشناس میدانی (ترتیب مراحل بازچینی‌شده)

+

+ بازیگر یکسان با V2 میرور (FIELD_EXPERT)، نتیجه یکسان، اما مراحل بازچینی شده‌اند: + تمام مراحل روایی طرفین (OTP، استعلام، صدا، موقعیت، توضیح، امضا) ابتدا برای هر دو طرف انجام می‌شود، + سپس مراحل ارزیابی خسارت (فیلدهای حادثه، مدارک، انتخاب قطعات، کپچر، ویدیو) + در یک پاس جداگانه دنبال می‌شوند. + تقصیر و خسارت هر دو در یک کنترلر: + v3/expert-initiated/blame-request-management/. +

+
+
+ بازیگر:FIELD_EXPERT Guard: LocalActorAuthGuard +
+
+
+

مراحل روایی طرفین (تقصیر)

+
+
+
1
+
+
ایجاد (IN_PERSON)
+
POST /
+
+
+
↓
+
+
2
+
+
ارسال + تأیید OTP (مقصر)
+
POST /send-party-otp → /verify-party-otp
+
+
+
↓
+
+
3
+
+
[CAR_BODY] فرم بدنه خودرو
+
POST /car-body-form/:id
+
+
+
↓
+
+
4
+
+
اجرای استعلام (مقصر + ایجاد خودکار خسارت)
+
POST /run-inquiries/:id or /run-inquiries-vin/:id
+
+
+
↓
+
+
5
+
+
موقعیت · توضیح · صدا (مقصر)
+
POST /add-detail-location, /add-detail-description, /upload-voice
+
+
+
↓
+
+
6
+
+
امضا (مقصر)
+
PUT /sign/:id
+
+
+
↓
+
+
7
+
+
OTP + استعلام + جزئیات (زیان‌دیده)
+
فقط THIRD_PARTY؛ CAR_BODY مراحل ۷–۸ را رد می‌کند
+
+
+
↓
+
+
8
+
+
امضا (زیان‌دیده)
+
PUT /sign/:id
+
+
+
+
+
+

مراحل ارزیابی خسارت

+
+
+
9
+
+
فیلدهای حادثه
+
POST /accident-fields/:id
+
+
+
↓
+
+
10
+
+
دریافت شناسه خسارت مرتبط
+
GET /claim-id/:requestId
+
+
+
↓
+
+
11
+
+
آپلود مدارک (گواهینامه، کارت خودرو)
+
POST /upload-document/:claimId
+
+
+
↓
+
+
12
+
+
انتخاب قطعات بیرونی
+
PATCH /select-outer-parts/:claimId
+
+
+
↓
+
+
13
+
+
انتخاب سایر قطعات
+
PATCH /select-other-parts/:claimId
+
+
+
↓
+
+
14
+
+
کپچر عکس قطعات + زوایا
+
POST /capture-part/:claimId
+
+
+
↓
+
+
15
+
+
فیلم دور خودرو (walk-around)
+
PATCH /car-capture/:claimId
+
+
+
↓
+
+
16
+
+
آپلود ویدیو تقصیر (آخرین مرحله)
+
POST /upload-video/:requestId
+
→ WAITING_FOR_EXPERT (THIRD_PARTY) یا COMPLETED (CAR_BODY)
+
+
+
+
+
+
+ + +

جریان V4 — نقش‌های جداگانه: FileMaker + FileReviewer

+

+ دو بازیگر کار یکسان V3 را در دو کنترلر جداگانه انجام می‌دهند. + FileMaker (v4/file-maker/blame-request-management/) + مراحل روایی طرفین (OTP، استعلام، جزئیات، امضا) و آپلود مدارک اولیه را انجام می‌دهد. + FileReviewer (v4/file-reviewer/blame-request-management/) + ارزیابی خسارت را انجام می‌دهد. + ویدیو تقصیر نهایی (upload-video) در V4 بی‌عملکرد است — تقصیر از طریق car-capture تکمیل می‌شود. +

+
+
+
فاز FileMaker
+
+ بازیگر:FILE_MAKER + v4/file-maker/blame-request-management/ +
+
+
+
1
+
+
ایجاد (IN_PERSON)
+
POST /
+
+
+
↓
+
+
2
+
+
ارسال + تأیید OTP (مقصر)
+
POST /send-party-otp → /verify-party-otp
+
+
+
↓
+
+
3
+
+
[CAR_BODY] فرم بدنه خودرو
+
POST /car-body-form/:id
+
+
+
↓
+
+
4
+
+
اجرای استعلام (مقصر + ایجاد خودکار خسارت)
+
POST /run-inquiries/:id or /run-inquiries-vin/:id
+
+
+
↓
+
+
5
+
+
موقعیت · توضیح · صدا (مقصر)
+
POST /add-detail-location, /add-detail-description, /upload-voice
+
+
+
↓
+
+
6
+
+
امضا (مقصر)
+
PUT /sign/:id (partyRole=FIRST)
+
+
+
↓
+
+
7
+
+
OTP + استعلام + جزئیات + امضا (زیان‌دیده)
+
فقط THIRD_PARTY
+
+
+
↓
+
+
8
+
+
آپلود مدارک (گواهینامه، کارت خودرو)
+
POST /upload-document/:claimId
+
از claim-id/:requestId برای دریافت claimId استفاده می‌شود
+
+
+
↓
+
+
✓
+
+
FileMaker تمام شد — پرونده مهر شد
+
FileReviewer می‌تواند پرونده را بردارد
+
+
+
+
+ +
+
فاز FileReviewer
+
+ بازیگر:FILE_REVIEWER + v4/file-reviewer/blame-request-management/ +
+
+
+
1
+
+
دریافت شناسه خسارت مرتبط
+
GET /claim-id/:requestId
+
+
+
↓
+
+
2
+
+
فیلدهای حادثه
+
POST /accident-fields/:requestId
+
+
+
↓
+
+
3
+
+
بررسی نیازمندی‌های کپچر
+
GET /capture-requirements/:claimId
+
+
+
↓
+
+
4
+
+
آپلود مدارک (شاسی / موتور)
+
POST /upload-document/:claimId
+
+
+
↓
+
+
5
+
+
انتخاب قطعات بیرونی
+
PATCH /select-outer-parts/:claimId
+
+
+
↓
+
+
6
+
+
انتخاب سایر قطعات
+
PATCH /select-other-parts/:claimId
+
+
+
↓
+
+
7
+
+
کپچر عکس قطعات + زوایا
+
POST /capture-part/:claimId
+
+
+
↓
+
+
8
+
+
فیلم دور خودرو (walk-around)
+
PATCH /car-capture/:claimId
+
خسارت → WAITING_FOR_DAMAGE_EXPERT · تقصیر → COMPLETED
+
+
+
↓
+
+
9
+
+
کارشناس خسارت بررسی و قیمت‌گذاری می‌کند
+
via v2/expert-claim
+
+
+
↓
+
+
10
+
+
امضای صاحب پرونده بر قیمت‌گذاری (FileReviewer به نمایندگی از کاربر)
+
PUT /claim-sign/:claimId
+
ارسال agree + branchId + تصویر امضا
+
+
+
↓
+
+
—
+
+
upload-video — بی‌عملکرد
+
POST /upload-video/:requestId (تقصیر قبلاً COMPLETED شده)
+
+
+
+
+
+ + +

جریان V5 — مانند V4 + دروازه تأیید FileMaker

+

+ مراحل FileMaker با V4 یکسان است، با این تفاوت که + requiresFileMakerApproval=true هنگام ایجاد ست می‌شود. + مراحل FileReviewer نیز با V4 یکسان است. تنها تفاوت در انتهای جریان است: + پس از تکمیل بررسی کارشناس خسارت و امضای صاحب پرونده، خسارت به جای ارسال مستقیم به فناوران + به وضعیت WAITING_FOR_FILE_MAKER_APPROVAL منتقل می‌شود. + FileMaker سپس تأیید (→ فناوران) یا رد می‌کند (→ بازگشت به WAITING_FOR_DAMAGE_EXPERT، حداکثر ۲ بار رد). +

+
+
+ بازیگران:FILE_MAKERFILE_REVIEWERDAMAGE_EXPERT + FILE_MAKER (تأیید) +
+
+
+

مراحل FileMaker (یکسان با V4)

+

+ همان ترتیب زیر + v5/file-maker/blame-request-management/ + — بدون تغییر. +

+
+
+
1–8
+
+
یکسان با FileMaker در V4
+
ستون چپ V4 را ببینید
+
+
+
↓
+
+
✓
+
+
FileMaker تمام شد — پرونده مهر شد
+
+
+
+
+
+

مراحل FileReviewer + دنباله تأیید

+
+
+
1–10
+
+
یکسان با FileReviewer در V4 (مراحل ۱–۱۰)
+
v5/file-reviewer/blame-request-management/
+
+
+
↓
+
+
11
+
+
خسارت → WAITING_FOR_FILE_MAKER_APPROVAL
+
(به جای ارسال مستقیم به فناوران)
+
+
+
↓
+
+
12
+
+
FileMaker تأیید یا رد می‌کند
+
POST v5/file-maker/claim-approval/approve/:claimId
+
POST v5/file-maker/claim-approval/reject/:claimId
+
رد → بازگشت به WAITING_FOR_DAMAGE_EXPERT · حداکثر ۲ بار رد
+
+
+
↓
+
+
✓
+
+
ارسال به فناوران (در صورت تأیید)
+
+
+
+
+
+
+ + +

جریان V6 — شروع از مرکز تماس (Call-Center)

+

+ اپراتور CALL_CENTER اطلاعات طرف مقصر را تلفنی دریافت می‌کند + (پلاک + کد ملی یا شاسی/VIN)، استعلام بیمه را اجرا می‌کند، سپس لینک تقصیر را + از طریق SMS ارسال می‌کند. طرف مقصر لینک را باز می‌کند و فرم را از طریق جریان + استاندارد V2 تکمیل می‌کند — اما مرحله فرم اولیه/استعلام به‌طور خودکار رد می‌شود + (skipInitialFormStep=true) چون اپراتور قبلاً آن را اجرا کرده است. + برای فایل‌های THIRD_PARTY، فقط اطلاعات طرف مقصر توسط اپراتور جمع‌آوری می‌شود. + جریان خسارت پس از تکمیل تقصیر، جریان استاندارد V2 خسارت است. +

+
+
+
فاز اپراتور
+
+ بازیگر:CALL_CENTER Guard: LocalActorAuthGuard · v6/call-center-blame/ +
+
+
+
1
+
+
ایجاد پرونده تقصیر
+
POST /create
+
بدنه: { type: "THIRD_PARTY" | "CAR_BODY" }
+
+
+
↓
+
+
2
+
+
اجرای استعلام برای مقصر (پلاک یا VIN)
+
POST /run-inquiry/:requestId
+
POST /run-inquiry-vin/:requestId
+
اپراتور پلاک + کد ملی دریافت‌شده از تماس‌گیرنده را ارسال می‌کند
+
+
+
↓
+
+
3
+
+
ارسال لینک تقصیر به مقصر از طریق SMS
+
POST /send-link/:requestId
+
بدنه: { phoneNumber }. در صورت نیاز کاربر ثبت می‌شود، به عنوان طرف اول ذخیره و SMS ارسال می‌شود.
+
+
+
↓
+
+
✓
+
+
اپراتور تمام شد
+
پیگیری از طریق GET /my-files و GET /blame/:requestId
+
+
+
+
+ +
+
فاز کاربر (جریان استاندارد V2، استعلام رد شده)
+
+ بازیگر:USER از طریق لینک SMS ← + v2/blame-request-management/ +
+
+
+
1
+
+
اعتراف تقصیر
+
POST /blame-confession/:id
+
+
+
↓
+
+
2
+
+
مرحله فرم اولیه / استعلام — رد شده
+
skipInitialFormStep=true چون اپراتور قبلاً اجرا کرده
+
+
+
↓
+
+
3
+
+
جزئیات: موقعیت · صدا · توضیح (مقصر)
+
+
+
↓
+
+
4
+
+
افزودن طرف دوم (THIRD_PARTY: ارسال SMS)
+
POST /add-second-party/:phone/:id/:frontendRoute
+
+
+
↓
+
+
5
+
+
طرف دوم مراحل عادی را روی دستگاه خودش پر می‌کند
+
فقط THIRD_PARTY
+
+
+
↓
+
+
6
+
+
امضا (هر دو طرف)
+
PUT /sign/:id
+
+
+
↓
+
+
7
+
+
[اختیاری] بررسی کارشناس تقصیر
+
via v2/expert-blame
+
+
+
↓
+
+
8
+
+
تقصیر تکمیل شد → جریان خسارت استاندارد V2
+
طرف زیان‌دیده خسارت را از طریق v2/claim-request-management/ باز می‌کند
+
+
+
+
+
+ + +

پنل‌های بررسی کارشناسی (مشترک در V1–V6)

+
+
+
+ پنل کارشناس تقصیر — v2/expert-blame/ +
+
+ بازیگر:EXPERTFIELD_EXPERT +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
متدمسیرهدف
GET/فهرست پرونده‌های تقصیر برای بررسی
GET/:idجزئیات پرونده
POST/:id/assignدریافت و قفل‌کردن پرونده
PUT/reply/submit/:idثبت رأی نهایی
PUT/reply/resend/:idدرخواست ارسال مجدد مدارک
PUT/reply/inPerson/:idثبت رأی بازدید حضوری
GET/report/unified-file-statusesکاتالوگ وضعیت‌ها و تعداد
+
+
+
+ پنل کارشناس خسارت — v2/expert-claim/ +
+
+ بازیگر:DAMAGE_EXPERTFIELD_EXPERTFILE_REVIEWERFILE_MAKER +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
متدمسیرهدف
GET/requestsفهرست صف خسارت
GET/request/:idجزئیات خسارت
POST/assign/:idدریافت و قفل‌کردن
PUT/reply/submit/:idثبت ارزیابی خسارت
PUT/reply/resend/:idدرخواست ارسال مجدد
GET/PUT/request/:id/price-dropمحاسبه کاهش قیمت
PATCH/validate-factors/:idاعتبارسنجی ضرایب تعمیر
PATCH/:id/visitدرخواست بازدید حضوری
+
+
+ + +

مقایسه جریان‌ها در یک نگاه

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
بُعدV1 / V2 کاربرV2 کارشناس میدانیV3V4V5V6
چه کسی تقصیر را پر می‌کند؟هر طرف روی دستگاه خودشFIELD_EXPERT برای هر دوFIELD_EXPERT برای هر دوFILE_MAKERFILE_MAKERCALL_CENTER (استعلام) + USER (بقیه، از طریق لینک)
چه کسی ارزیابی می‌کند؟کاربر، سپس کارشناس بررسی می‌کندFIELD_EXPERTFIELD_EXPERT (همان جلسه)FILE_REVIEWERFILE_REVIEWERUSER + DAMAGE_EXPERT (خسارت استاندارد V2)
بررسی کارشناس تقصیر؟صف اختیاریخیر — تکمیل فوری پس از accident-fieldsWAITING_FOR_EXPERT پس از upload-videoCOMPLETED پس از car-captureCOMPLETED پس از car-captureصف اختیاری (مانند V2 کاربر)
بررسی خسارتDAMAGE_EXPERTDAMAGE_EXPERTDAMAGE_EXPERTDAMAGE_EXPERT ← امضای صاحب پرونده (FileReviewer)DAMAGE_EXPERT ← امضا ← تأیید FileMakerDAMAGE_EXPERT (استاندارد V2)
مرحله استعلامکاربر initial-form را پر می‌کندکارشناس run-inquiries به ازای هر طرفکارشناس run-inquiries به ازای هر طرفFileMaker run-inquiries به ازای هر طرفFileMaker run-inquiries به ازای هر طرفاپراتور از قبل پر می‌کند؛ کاربر رد می‌کند
مرحله upload-videoدر جریان V2 کاربر وجود نداردبله — upload-video برای هر طرف (mirror)بله — آخرین مرحله → WAITING_FOR_EXPERTبی‌عملکرد (تقصیر با car-capture تکمیل شد)بی‌عملکرد (تقصیر با car-capture تکمیل شد)مربوط نیست
پیشوند مسیر تقصیرv2/blame-request-management/v2/expert-initiated/blame.../v3/expert-initiated/blame.../v4/file-maker/blame.../v5/file-maker/blame.../v6/call-center-blame/
پیشوند مسیر ارزیابیv2/claim-request-management/همان کنترلرهمان کنترلرv4/file-reviewer/blame.../v5/file-reviewer/blame.../v2/claim-request-management/
+ + +
+ + diff --git a/docs/blame-claim-flow-architecture.html b/docs/blame-claim-flow-architecture.html new file mode 100644 index 0000000..684dfb1 --- /dev/null +++ b/docs/blame-claim-flow-architecture.html @@ -0,0 +1,1893 @@ + + + + Blame & Claim Flow Architecture + + + +
+

Blame & Claim Flow Architecture

+

+ All active flows — V1 (legacy) · V2 · V3 · V4 · V5 · V6 — with roles, + route prefixes, and step sequences. +

+ + +

Legend & Roles

+
+
+
Roles by Flow
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlowBlame actorClaim/Review actor
V1 / V2 (user)USER + USER + + DAMAGE_EXPERT +
Expert blame panel + EXPERT + FIELD_EXPERT + —
Expert claim panel— + DAMAGE_EXPERT + FIELD_EXPERT + FILE_REVIEWER + FILE_MAKER +
V2 expert-init (mirror) + FIELD_EXPERT + + FIELD_EXPERT +
V3 + FIELD_EXPERT + + FIELD_EXPERT +
V4 + FILE_MAKER + + FILE_REVIEWER +
V5 + FILE_MAKER + + FILE_REVIEWER + + + FILE_MAKER + (approval) +
V6 + CALL_CENTER + + USER + (via link) + + USER + + DAMAGE_EXPERT + (standard V2 claim) +
+
+
+
Route Prefixes
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlowBlame prefixClaim / Review prefix
V1 (legacy)blame-request-management/claim-request-management/
V2 userv2/blame-request-management/v2/claim-request-management/
V2 expert-init (mirror) + v2/expert-initiated/blame-request-management/ + + same controller (no separate claim prefix) +
V2 expert blame panelv2/expert-blame/v2/expert-claim/
V3 + v3/expert-initiated/blame-request-management/ + same controller
V4 + v4/file-maker/blame-request-management/ + + v4/file-reviewer/blame-request-management/ +
V5 + v5/file-maker/blame-request-management/ + + v5/file-reviewer/blame-request-management/ + + + v5/file-maker/claim-approval/ +
V6 + v6/call-center-blame/ + (agent) + + v2/blame-request-management/ + (user link) + + v2/claim-request-management/ + (standard) +
+
+
+ + +

Flow V1 / V2 — User-Initiated Blame & Claim

+

+ The canonical user flow. Each party opens the app on their own device. + First party fills blame info and invites the second party via SMS link. + An expert blame review is optional. After blame completes the damaged + party opens a claim which a damage expert prices. + V1 = legacy routes (deprecated, @ApiExcludeController) · + V2 = same logic, v2/ prefix, GlobalGuard + RolesGuard (USER). +

+
+
+
Blame Phase
+
+ Actor:USER Guard: GlobalGuard +
+
+
+
1
+
+
Create request
+
POST /
+
+
+
↓
+
+
2
+
+
Blame confession
+
POST /blame-confession/:id
+
+
+
↓
+
+
2a
+
+
[CAR_BODY only] Car body form
+
POST /car-body-form/:id
+
+
+
↓
+
+
3
+
+
Initial form (plate or VIN)
+
+ POST /initial-form/:id or /initial-form-vin/:id +
+
+
+
↓
+
+
4
+
+
+ Details: location · voice · description +
+
+ POST /add-detail-location, /upload-voice, + /add-detail-description +
+
+
+
↓
+
+
5
+
+
+ Add second party (sends SMS invite) +
+
+ POST /add-second-party/:phone/:id/:frontendRoute +
+
+
+
↓
+
+
6
+
+
+ Second party fills same steps 2–4 +
+
+ Second party logs in on their own device +
+
+
+
↓
+
+
7
+
+
Sign (both parties)
+
PUT /sign/:id
+
+ Uploads signature image + isAccept flag +
+
+
+
↓
+
+
8
+
+
+ [Optional] Expert blame review +
+
+ via v2/expert-blame — assign → reply/resend +
+
+ Expert assigns case, may request resend, + submits verdict +
+
+
+
↓
+
+
9
+
+
Blame COMPLETED
+
Guilty party determined
+
+
+
+
+ +
+
Claim Phase
+
+ Actor:USER (damaged party) + + DAMAGE_EXPERT +
+
+
+
1
+
+
Create claim from blame
+
+ POST v2/claim-request-management/create-from-blame/:blameId +
+
+
+
↓
+
+
2
+
+
Select outer parts
+
+ PATCH /select-outer-parts/:claimId +
+
+
+
↓
+
+
3
+
+
+ Select other parts + bank info +
+
+ PATCH /select-other-parts/:claimId +
+
+
+
↓
+
+
4
+
+
Upload documents
+
+ POST /upload-document/:claimId +
+
+
+
↓
+
+
5
+
+
+ Capture parts (photos + angles) +
+
+ POST /capture-part/:claimId +
+
+
+
↓
+
+
6
+
+
+ Car capture (walk-around video) +
+
+ PATCH /car-capture/:claimId +
+
+ → WAITING_FOR_DAMAGE_EXPERT +
+
+
+
↓
+
+
7
+
+
+ Damage expert reviews & prices +
+
+ via v2/expert-claim — assign → reply / price-drop +
+
+
+
↓
+
+
8
+
+
+ User signs pricing / objects / rates +
+
+ PUT /owner-insurer-approval/sign or /objection or + /user-rating +
+
+
+
+
+
+ + +

Flow V2 — Expert-Initiated Mirror (In-Person)

+

+ A FIELD_EXPERT at the accident scene fills every step on + behalf of both parties. The route prefix mirrors the user API exactly — + v2/expert-initiated/blame-request-management/ — so the + frontend can reuse the same pages by swapping only the prefix. The FIRST + party registered is always the guilty party. After both signatures the + blame completes immediately (no expert review queue). + The expert also handles the claim steps on the same controller as the + user flow (under v2/expert-initiated/claim-request-management/ + if needed, or via the standard V2 claim controller). +

+
+
+
Blame Phase
+
+ Actor:FIELD_EXPERT Guard: LocalActorAuthGuard +
+
+
+
1
+
+
+ Create (creationMethod=IN_PERSON) +
+
POST /
+
+
+
↓
+
+
2
+
+
+ Send & verify party OTP (guilty) +
+
+ POST /send-party-otp/:id → + /verify-party-otp/:id +
+
+
+
↓
+
+
3
+
+
Blame confession (guilty)
+
+ POST /blame-confession/:id +
+
+
+
↓
+
+
3a
+
+
+ [CAR_BODY only] Car body form +
+
POST /car-body-form/:id
+
+
+
↓
+
+
4
+
+
+ Initial form / run inquiries (guilty) +
+
+ POST /run-inquiries/:id or /run-inquiries-vin/:id +
+
+
+
↓
+
+
5
+
+
+ Upload video (guilty first party) +
+
POST /upload-video/:id
+
+
+
↓
+
+
6
+
+
+ Details: location · voice · description (guilty) +
+
+ POST /add-detail-location, /upload-voice, + /add-detail-description +
+
+
+
↓
+
+
7
+
+
+ Add second party (no SMS link) +
+
+ POST /add-second-party/:phone/:id/ +
+
+
+
↓
+
+
8
+
+
+ OTP + inquiries + details (damaged) — same steps 2–6 +
+
THIRD_PARTY only
+
+
+
↓
+
+
9
+
+
+ Sign FIRST then Sign SECOND +
+
+ PUT /sign/:id (called twice, partyRole=FIRST / SECOND) +
+
+
+
↓
+
+
10
+
+
+ Accident fields → Blame COMPLETED +
+
+ POST /accident-fields/:id +
+
+ No expert review queue — blame closes immediately +
+
+
+
+
+ +
+
Claim Phase (same expert)
+
+ Actor:FIELD_EXPERT +
+
+
+
1
+
+
Create claim from blame
+
+ POST v2/expert-initiated/claim-request-management/create-from-blame/:blameId +
+
+
+
↓
+
+
2
+
+
+ Select outer + other parts +
+
+ PATCH /select-outer-parts, /select-other-parts +
+
+
+
↓
+
+
3
+
+
Upload documents
+
+ POST /upload-document/:claimId +
+
+
+
↓
+
+
4
+
+
Capture parts
+
+ POST /capture-part/:claimId +
+
+
+
↓
+
+
5
+
+
+ Car capture (walk-around video) +
+
+ PATCH /car-capture/:claimId +
+
+ → WAITING_FOR_DAMAGE_EXPERT +
+
+
+
↓
+
+
6
+
+
+ Damage expert reviews (normal flow) +
+
via v2/expert-claim
+
+
+
+
+
+ + +

Flow V3 — Expert-Initiated (Reorganised Steps)

+

+ Same actor as V2 mirror (FIELD_EXPERT), same end result, but steps are + reorganised: all party narrative steps (OTPs, inquiries, voice, location, + description, sign) come first for both parties, then the damage-assessment + steps (accident fields, documents, part selection, capture, walk-around + video) follow in a single dedicated pass. Blame + Claim share a single + controller: + v3/expert-initiated/blame-request-management/. +

+
+
+ Actor:FIELD_EXPERT Guard: LocalActorAuthGuard +
+
+
+

Party Steps (blame narrative)

+
+
+
1
+
+
Create (IN_PERSON)
+
POST /
+
+
+
↓
+
+
2
+
+
+ OTP send + verify (guilty) +
+
+ POST /send-party-otp → /verify-party-otp +
+
+
+
↓
+
+
3
+
+
+ [CAR_BODY] Car body form +
+
+ POST /car-body-form/:id +
+
+
+
↓
+
+
4
+
+
+ Run inquiries (guilty + auto-claim) +
+
+ POST /run-inquiries/:id or /run-inquiries-vin/:id +
+
+
+
↓
+
+
5
+
+
+ Location · description · voice (guilty) +
+
+ POST /add-detail-location, /add-detail-description, + /upload-voice +
+
+
+
↓
+
+
6
+
+
Sign (guilty)
+
PUT /sign/:id
+
+
+
↓
+
+
7
+
+
+ OTP + inquiries + details (damaged) +
+
+ THIRD_PARTY only; CAR_BODY skips 7–8 +
+
+
+
↓
+
+
8
+
+
Sign (damaged)
+
PUT /sign/:id
+
+
+
+
+
+

Damage Assessment Steps

+
+
+
9
+
+
Accident fields
+
+ POST /accident-fields/:id +
+
+
+
↓
+
+
10
+
+
Get linked claim ID
+
+ GET /claim-id/:requestId +
+
+
+
↓
+
+
11
+
+
+ Upload documents (licences, car cards) +
+
+ POST /upload-document/:claimId +
+
+
+
↓
+
+
12
+
+
Select outer parts
+
+ PATCH /select-outer-parts/:claimId +
+
+
+
↓
+
+
13
+
+
Select other parts
+
+ PATCH /select-other-parts/:claimId +
+
+
+
↓
+
+
14
+
+
+ Capture part photos + angles +
+
+ POST /capture-part/:claimId +
+
+
+
↓
+
+
15
+
+
+ Car capture (walk-around) +
+
+ PATCH /car-capture/:claimId +
+
+
+
↓
+
+
16
+
+
+ Upload blame video (FINAL) +
+
+ POST /upload-video/:requestId +
+
+ → WAITING_FOR_EXPERT (THIRD_PARTY) or COMPLETED + (CAR_BODY) +
+
+
+
+
+
+
+ + +

Flow V4 — Split Roles: FileMaker + FileReviewer

+

+ Two actors handle the same V3 work split across two controllers. + FileMaker (v4/file-maker/blame-request-management/) + handles the party narrative (OTPs, inquiries, details, signatures) and + uploads the initial claim documents. FileReviewer + (v4/file-reviewer/blame-request-management/) handles the + damage assessment pass. The final blame video (upload-video) is a no-op + in V4 — blame is already COMPLETED by car-capture. +

+
+
+
FileMaker Phase
+
+ Actor:FILE_MAKER + v4/file-maker/blame-request-management/ +
+
+
+
1
+
+
Create (IN_PERSON)
+
POST /
+
+
+
↓
+
+
2
+
+
+ OTP send + verify (guilty) +
+
+ POST /send-party-otp → /verify-party-otp +
+
+
+
↓
+
+
3
+
+
+ [CAR_BODY] Car body form +
+
POST /car-body-form/:id
+
+
+
↓
+
+
4
+
+
+ Run inquiries (guilty + auto-claim) +
+
+ POST /run-inquiries/:id or /run-inquiries-vin/:id +
+
+
+
↓
+
+
5
+
+
+ Location · description · voice (guilty) +
+
+ POST /add-detail-location, /add-detail-description, + /upload-voice +
+
+
+
↓
+
+
6
+
+
Sign (guilty)
+
+ PUT /sign/:id (partyRole=FIRST) +
+
+
+
↓
+
+
7
+
+
+ OTP + inquiries + details + sign (damaged) +
+
THIRD_PARTY only
+
+
+
↓
+
+
8
+
+
+ Upload documents (licences, car cards) +
+
+ POST /upload-document/:claimId +
+
+ Uses claim-id/:requestId to resolve claimId +
+
+
+
↓
+
+
✓
+
+
+ FileMaker DONE — file sealed +
+
+ FileReviewer can now pick up +
+
+
+
+
+ +
+
FileReviewer Phase
+
+ Actor:FILE_REVIEWER + v4/file-reviewer/blame-request-management/ +
+
+
+
1
+
+
Get linked claim ID
+
+ GET /claim-id/:requestId +
+
+
+
↓
+
+
2
+
+
Accident fields
+
+ POST /accident-fields/:requestId +
+
+
+
↓
+
+
3
+
+
+ Capture requirements lookup +
+
+ GET /capture-requirements/:claimId +
+
+
+
↓
+
+
4
+
+
+ Upload document (chassis / engine) +
+
+ POST /upload-document/:claimId +
+
+
+
↓
+
+
5
+
+
Select outer parts
+
+ PATCH /select-outer-parts/:claimId +
+
+
+
↓
+
+
6
+
+
Select other parts
+
+ PATCH /select-other-parts/:claimId +
+
+
+
↓
+
+
7
+
+
+ Capture part photos + angles +
+
+ POST /capture-part/:claimId +
+
+
+
↓
+
+
8
+
+
+ Car capture (walk-around video) +
+
+ PATCH /car-capture/:claimId +
+
+ claim → WAITING_FOR_DAMAGE_EXPERT · blame → COMPLETED +
+
+
+
↓
+
+
9
+
+
+ Damage expert reviews & prices +
+
via v2/expert-claim
+
+
+
↓
+
+
10
+
+
+ Owner sign on expert pricing (FileReviewer acts on + behalf of user) +
+
+ PUT /claim-sign/:claimId +
+
+ Submits agree + branchId + signature image +
+
+
+
↓
+
+
—
+
+
upload-video — no-op
+
+ POST /upload-video/:requestId (blame already COMPLETED) +
+
+
+
+
+
+ + +

Flow V5 — Same as V4 + FileMaker Approval Gate

+

+ FileMaker steps are identical to V4 except + requiresFileMakerApproval=true is set at creation. The + FileReviewer steps are also identical to V4. The only difference is the + tail: after the damage expert completes their review and the owner signs, + the claim moves to + WAITING_FOR_FILE_MAKER_APPROVAL instead of proceeding + directly to fanavaran submission. The FileMaker then approves (→ fanavaran) + or rejects (→ back to WAITING_FOR_DAMAGE_EXPERT, max 2 rejections). +

+
+
+ Actors:FILE_MAKERFILE_REVIEWERDAMAGE_EXPERT + FILE_MAKER (approval) +
+
+
+

FileMaker steps (identical to V4)

+

+ Same sequence under + v5/file-maker/blame-request-management/ + — no changes. +

+
+
+
1–8
+
+
+ Identical to V4 FileMaker +
+
+ See V4 left column above +
+
+
+
↓
+
+
✓
+
+
+ FileMaker DONE — file sealed +
+
+
+
+
+
+

FileReviewer steps + Approval tail

+
+
+
1–10
+
+
+ Identical to V4 FileReviewer (steps 1–10) +
+
+ v5/file-reviewer/blame-request-management/ +
+
+
+
↓
+
+
11
+
+
+ Claim → WAITING_FOR_FILE_MAKER_APPROVAL +
+
+ (instead of direct fanavaran submit) +
+
+
+
↓
+
+
12
+
+
+ FileMaker approves or rejects +
+
+ POST v5/file-maker/claim-approval/approve/:claimId +
+
+ POST v5/file-maker/claim-approval/reject/:claimId +
+
+ Reject sends back to WAITING_FOR_DAMAGE_EXPERT · + max 2 rejections +
+
+
+
↓
+
+
✓
+
+
+ Fanavaran submission (on approve) +
+
+
+
+
+
+
+ + +

Flow V6 — Call-Center Initiated

+

+ A CALL_CENTER agent takes the guilty party's details + over the phone (plate + national code, or chassis/VIN), runs the + insurance inquiry, then sends the blame link via SMS. The guilty party + opens the link and completes the form through the standard V2 user flow + — but the initial-form / inquiry step is automatically skipped + (skipInitialFormStep=true) because the agent already ran it. + For THIRD_PARTY files only the guilty party's data is + collected by the agent; the damaged party fills their portion normally + after the link is opened. The downstream claim flow (after blame + completes) is the standard V2 claim flow. +

+
+
+
Agent Phase
+
+ Actor:CALL_CENTER Guard: LocalActorAuthGuard · v6/call-center-blame/ +
+
+
+
1
+
+
Create blame file
+
+ POST /create +
+
+ Body: { type: "THIRD_PARTY" | "CAR_BODY" } +
+
+
+
↓
+
+
2
+
+
+ Run inquiry for guilty party (plate or VIN) +
+
+ POST /run-inquiry/:requestId +
+
+ POST /run-inquiry-vin/:requestId +
+
+ Agent supplies plate + national-code collected from + caller; results stored on blame document +
+
+
+
↓
+
+
3
+
+
+ Send blame link to guilty party via SMS +
+
+ POST /send-link/:requestId +
+
+ Body: { phoneNumber }. Registers user if needed, + stores as first party, fires SMS invite. +
+
+
+
↓
+
+
✓
+
+
Agent done
+
+ Monitor via GET /my-files and GET /blame/:requestId +
+
+
+
+
+ +
+
User Phase (standard V2 flow, inquiry skipped)
+
+ Actor:USER via SMS link → + v2/blame-request-management/ +
+
+
+
1
+
+
Blame confession
+
+ POST /blame-confession/:id +
+
+
+
↓
+
+
2
+
+
+ Initial-form / inquiry step — SKIPPED +
+
+ skipInitialFormStep=true because agent already ran it +
+
+
+
↓
+
+
3
+
+
+ Details: location · voice · description (guilty) +
+
+
+
↓
+
+
4
+
+
+ Add second party (THIRD_PARTY: sends SMS invite) +
+
+ POST /add-second-party/:phone/:id/:frontendRoute +
+
+
+
↓
+
+
5
+
+
+ Second party fills normal steps on own device +
+
THIRD_PARTY only
+
+
+
↓
+
+
6
+
+
Sign (both parties)
+
PUT /sign/:id
+
+
+
↓
+
+
7
+
+
+ [Optional] Expert blame review +
+
via v2/expert-blame
+
+
+
↓
+
+
8
+
+
+ Blame COMPLETED → standard V2 claim flow +
+
+ Damaged party opens claim via + v2/claim-request-management/ +
+
+
+
+
+
+ + +

Expert Review Panels (shared across V1–V6)

+
+
+
+ Expert Blame Panel — v2/expert-blame/ +
+
+ Actor:EXPERTFIELD_EXPERT +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodRoutePurpose
GET/List blame cases for review
GET/:idCase details
POST/:id/assignAssign & lock case
PUT/reply/submit/:idSubmit verdict
PUT/reply/resend/:idRequest document resend
PUT/reply/inPerson/:idSubmit in-person visit verdict
GET/report/unified-file-statusesStatus catalog & counts
+
+
+
+ Expert Claim Panel — v2/expert-claim/ +
+
+ Actor:DAMAGE_EXPERTFIELD_EXPERTFILE_REVIEWERFILE_MAKER +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodRoutePurpose
GET/requestsList claim queue
GET/request/:idClaim details
POST/assign/:idAssign & lock
PUT/reply/submit/:idSubmit damage assessment
PUT/reply/resend/:idRequest resend
GET/PUT/request/:id/price-dropPrice drop calculation
PATCH/validate-factors/:idValidate repair factors
PATCH/:id/visitRequest in-person visit
+
+
+ + +

Flow Comparison at a Glance

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DimensionV1 / V2 UserV2 Expert-InitV3V4V5V6
Who fills blame?Each party on own deviceFIELD_EXPERT for bothFIELD_EXPERT for bothFILE_MAKERFILE_MAKERCALL_CENTER (inquiry) + USER (rest, via link)
Who does assessment?User, then expert reviewsFIELD_EXPERTFIELD_EXPERT (same session)FILE_REVIEWERFILE_REVIEWERUSER + DAMAGE_EXPERT (standard V2 claim)
Expert blame review?Optional queueNo — immediate COMPLETED after accident-fieldsWAITING_FOR_EXPERT after upload-videoCOMPLETED after car-captureCOMPLETED after car-captureOptional queue (same as V2 user)
Claim reviewDAMAGE_EXPERTDAMAGE_EXPERTDAMAGE_EXPERTDAMAGE_EXPERT → owner sign (FileReviewer)DAMAGE_EXPERT → owner sign → FileMaker approvalDAMAGE_EXPERT (standard V2)
Inquiry stepUser fills initial-formExpert fills run-inquiries per partyExpert fills run-inquiries per partyFileMaker fills run-inquiries per partyFileMaker fills run-inquiries per partyAgent pre-fills; user skips it
Upload-video stepNot in V2 user flowYes — upload-video per party (mirror)Yes — last step → WAITING_FOR_EXPERTNo-op (blame done by car-capture)No-op (blame done by car-capture)Not applicable
Blame route prefixv2/blame-request-management/v2/expert-initiated/blame.../v3/expert-initiated/blame.../v4/file-maker/blame.../v5/file-maker/blame.../v6/call-center-blame/
Assessment route prefixv2/claim-request-management/same controllersame controllerv4/file-reviewer/blame.../v5/file-reviewer/blame.../v2/claim-request-management/
+ + +
+ + diff --git a/docs/external-integrations-reference.html b/docs/external-integrations-reference.html new file mode 100644 index 0000000..a0e6fdf --- /dev/null +++ b/docs/external-integrations-reference.html @@ -0,0 +1,593 @@ + + + + + External Integrations Reference + + + +
+

External Integrations Reference

+

+ Every outbound integration: what it does, when it fires, how auth works, + retry behaviour, fallbacks, and all environment variables. Internal-only + services (captcha, offline inquiry seed) are included for completeness. +

+ + +
+
Contents
+
    +
  1. Inquiry routing decision tree
    2. +
  2. Fanavaran — insurance claims platform
    3. +
  3. SandHub — legacy inquiry gateway
    4. +
  4. Tejarat inquiry — block-inquiry gateway (V2+)
    5. +
  5. ESG — Parsian-tenant inquiry provider
    6. +
  6. SMS — Kavenegar and Parsian gateways
    7. +
  7. AI service — car damage detection
    8. +
  8. Car pricing service — market value lookup
    9. +
  9. Offline inquiry — fallback seed data
    10. +
  10. Environment variable reference
    11. +
+
+ + +

1 — Inquiry Routing Decision Tree

+

+ Every blame file starts with a "run-inquiries" call that fetches the + guilty party's insurance policy from an external provider. Which provider + is actually called depends on three factors: the tenant (CLIENT_ID), + the file type (THIRD_PARTY vs CAR_BODY), and whether live API mode is + enabled in system settings. The offline-inquiry seed layer sits in front + of all three providers. +

+ +
+

Provider selection

+
+ For every plate-based block inquiry: +
    +
  • 1. Check offline-inquiry seeds (MongoDB) — if a matching seed exists, return it and skip all HTTP.
    • +
  • 2. If CLIENT_ID=8 (Parsian/ESG tenant) → route to ESG /inquiry/policyByPlate or /inquiry/policyByChassis.
    • +
  • 3. Otherwise → route to Tejarat inquiry /block-inquiry-tejarat (THIRD_PARTY) or /block-inquiry-tejarat/badane (CAR_BODY).
    • +
  • 4. If system_settings.externalApis.sandHubUseLiveApi = false (default) → return mock response instead of making HTTP calls.
    • +
+
+ For personal-identity, driving-licence, ownership, and Sheba checks: +
    +
  • If CLIENT_ID=8 → ESG /inquiry/person and /inquiry/sheba.
    • +
  • Otherwise → Tejarat/SandHub /personal-inquiry/tejarat-no, /driver-license-check, /ownership, /sheba/sheba-tejaratno.
    • +
+
+ Key difference — birth date format: + SandHub/Tejarat expect a Gregorian birth date (converted internally from Jalali). + ESG expects the Jalali date directly. +
+

+ SandHub endpoints are only used in legacy code paths. All active V2+ blame flows go through the Tejarat or ESG providers. +

+
+ + +

2 — Fanavaran live

+

+ Fanavaran (apimanager.iraneit.com) is the national insurance + damage-case platform. After the damage expert submits their assessment, + the system auto-submits a structured claim to Fanavaran through a + four-step protocol. Fanavaran also serves as the lookup source for + code-lists (accident types, car components, city codes, etc.) used + across the platform. +

+ +
+

Authentication lifecycle

+
+
1
GET AppToken — POST /EITAuthentication/GetAppToken with appname + secret headers. Returns apptoken header.
+
2
Login — POST /EITAuthentication/Login with appToken + userName + password headers. Returns authenticationToken header.
+
3
Cache — token is cached in memory and persisted to MongoDB (fanavaran_auth_tokens). Valid until midnight Asia/Tehran — the first call after 00:00 fetches a fresh token.
+
4
All subsequent calls include four headers: authenticationToken, CorpId, ContractId, Location — tenant-specific, hardcoded per FANAVARAN_CLIENT key.
+
+

+ A config fingerprint (hash of appName + secret + username + password + corpId + contractId + location) + forces a fresh login when any credential changes, even before midnight. +

+
+ +
+

Claim submission protocol (4 steps)

+
+
1
Base claim (GEN.03) — POST /car/third-party-car-financial-claims. Sends owner, driver, insurance, vehicle, and accident data. Returns a Fanavaran claimId and claimNo. SMS is sent to the owner with both identifiers.
+
2
Damage cases (GEN.05) — POST /car/third-party-car-financial-claims/{claimId}/dmg-cases. One entry per damaged part with component ID, severity, and price. Cap: total ≤ 53 000 000 Toman.
+
3
Attachments (GEN.07) — POST /car/third-party-car-financial-claims/{claimId}/files. Documents, car-capture images, and videos referenced by file ID.
+
4
Expertise (GEN.08) — POST /car/third-party-car-financial-claims/{claimId}/expertise. Expert assessment metadata (expert role, date, result). Finalises the submission.
+
+

+ All four steps are recorded in the fanavaran_audit_logs collection with full request/response bodies, HTTP status, duration, and tracking code for debugging. +

+
+ +
+

Lookup endpoints

+

All under https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/. Results are cached to disk (per client key) and in the lookups MongoDB collection. Parsian tenant reads DB before hitting the API; others go to the API first.

+ + + + + + + + + + + + + + + + + + + +
PathUsed for
/car/base-info/accident-causesaccidentReason dropdown options (mapped to local IDs)
/car/code-list/accident-report-typeaccidentWay options
/car/base-info/vehicle-use-typesvehicle usage classification
/car/code-list/dmg-pay-methoddamage payment method
/car/base-info/driving-licence-typeslicence type options
/car/code-list/accident-culprit-typeguilty-party classification
/car/code-list/inspection-placeinspection location options
/car/code-list/drop-amount-statusprice-drop status codes
/car/base-info/car-componentscomponent catalog (maps to outer/inner parts)
/car/code-list/accident-levelaccident severity options
/common/code-list/insurance-corpresolve INSURANCE_CORP_ID → Fanavaran corpId
/common/base-info/cities, /common/base-info/Provincescity/province pickers
/car/third-party-car-policies/{policyId}fetch full policy by ID after inquiry
/car/vehicles/inquiry-by-vin?vin=…VIN-based vehicle lookup
/common/Policies/inquiry-my-policieslist policies for a national code
/common/customers/{customerId}fetch customer record by ID
/common/parties/inquiry-by-unique-identifierparty lookup by national code + birth date
+
+ +
+

Error handling & resilience

+ + + + + + + + +
MechanismDetail
Retry3 attempts, 500 ms → 1 000 ms exponential backoff on all HTTP calls.
Transient backoffWhen Fanavaran returns the Persian "try again later" message (or tracking-code 500), a tenant-wide 5-minute pause is activated. All calls during this window get 503 ServiceUnavailable immediately — no hammering.
Token invalidationOn 401, token is cleared from memory and MongoDB; next call triggers a fresh GetAppToken + Login.
Inflight de-dupConcurrent login requests for the same tenant are collapsed to a single in-flight Promise.
Audit logEvery step (GET_APP_TOKEN, LOGIN, and all four submission steps) is written to fanavaran_audit_logs with STARTED / SUCCESS / FAILURE status, full headers, body, and duration.
Timeout20–30 s per HTTP call.
+
+ +
+

Tenant profiles (FANAVARAN_CLIENT)

+

Three pre-seeded tenant profiles exist. The active one is chosen by the FANAVARAN_CLIENT env var. Each profile carries its own appName, secret, username, password, CorpId, ContractId, and Location headers, plus payload defaults (AccidentCityId, etc.).

+ + + + + +
KeyInsurance company
parsianParsian Insurance
tejaratnoTejaratno Insurance
moallemMoallem Insurance
+

+ INSURANCE_CORP_ID is a display-caption string (e.g. "بیمه پارسیان") that is resolved against the live Fanavaran insurance-corp list to produce the numeric corpId used in submissions. The resolved ID is cached to disk. +

+
+ + +

3 — SandHub legacy

+

+ SandHub is the original inquiry gateway. It is still present in the + codebase but all active blame flows (V2+) have been migrated to the + Tejarat inquiry provider. SandHub endpoints remain callable but are + only reached through legacy code paths. Its mock mode is controlled + by the same sandHubUseLiveApi system setting. +

+ +
+

Auth

+

+ POST {SANHUB_BASE_URL}/user/login with username + password JSON body. + Token cached in memory for 55 minutes. On 401, token is cleared and one retry is made. + 3 attempts with 1 000 ms → 2 000 ms exponential backoff. +

+
+ +
+

Endpoints

+ + + + + + + + +
MethodPathWhat it does
POST/block-inquiry-tejaratPlate-based insurance policy inquiry (THIRD_PARTY). Body: leftTwoDigits, serialLetter, threeDigits, rightTwoDigits, nationalCode.
POST/block-inquiry-tejarat/badaneCAR_BODY policy inquiry. Timeout 50 s (longer than standard).
POST/personal-inquiry/tejarat-noPersonal identity check. Body: nationalCode + Gregorian birthDate (converted from Jalali internally).
POST/driver-license-checkDriving licence validation. Returns IsSucceed flag.
POST/ownershipVehicle ownership check. Returns IsSuccess flag.
POST/sheba/sheba-tejaratnoSheba / bank account validation. Returns ReturnValue + HasError.
+

+ All endpoints support full mock responses when sandHubUseLiveApi=false in system settings (default). Mock data is deterministic and produced locally without any HTTP calls. +

+
+ + +

4 — Tejarat Inquiry live

+

+ The active block-inquiry gateway for all non-ESG tenants. Used in every + V2+ run-inquiries call where CLIENT_ID ≠ 8. + The base URL is configurable; in production it points to the same host + as SandHub but uses separate credentials. +

+ +
+

Auth

+

+ POST {TEJARAT_INQUIRY_BASE_URL}/user/login with email + password JSON body. + Token cached for 55 minutes. 2 attempts with 500 ms → 1 000 ms backoff. + Separate from SandHub credentials — uses TEJARAT_INQUIRY_EMAIL / TEJARAT_INQUIRY_PASSWORD. +

+
+ +
+

Endpoints

+ + + + +
MethodPathWhat it does
POST/block-inquiry-tejaratTHIRD_PARTY plate inquiry. Body: plate fields + nationalCode. Offline seed checked first.
POST/block-inquiry-tejarat/badaneCAR_BODY plate inquiry. Body: part1–part4 (numeric) + nationalCode. Always goes live (no mock for badane path).
+

+ When sandHubUseLiveApi=false, the THIRD_PARTY path returns a mock response without HTTP. The CAR_BODY path always calls the live API regardless of this flag. +

+
+ + +

5 — ESG live (CLIENT_ID=8)

+

+ ESG is an internal insurance API gateway used exclusively by the Parsian + tenant (CLIENT_ID=8). It replaces Tejarat/SandHub for all + inquiry types when this tenant is active. It has a different response + shape, a dynamic token TTL, and expects birth dates in Jalali + format (not Gregorian, unlike SandHub/Tejarat). +

+ +
+

Auth

+

+ POST {ESG_URL}/auth/login with { username, password } JSON body. + Token TTL is read from the response expiresIn field (default 14 min). + 2 attempts with 500 ms → 1 000 ms backoff. On 401, token cleared and one retry. + Default URL: http://192.168.20.22:8085 (internal network). +

+
+ +
+

Endpoints

+ + + + + + +
MethodPathWhat it does
POST/inquiry/policyByPlatePlate-based policy lookup (THIRD_PARTY). Body: nationalCode, plk1–plk4. Response is mapped to the old Tejarat format before being stored.
POST/inquiry/policyByChassisVIN/chassis-based alternative to plate inquiry. Called by run-inquiries-vin endpoints. Uses ESG chassis lookup (not the SandHub path). Body: nationalCode, chassis.
POST/inquiry/personPersonal identity check. Body: nationalCode, birthDate (Jalali, NOT Gregorian).
POST/inquiry/shebaSheba / bank account validation.
+

+ ESG wraps every response as { success: boolean, data: … }. A success=false body is translated to a Persian "استعلام در دسترس نیست" (inquiry unavailable) error. + The offline-inquiry seed check still runs first, before any ESG HTTP call. +

+
+ + +

6 — SMS live

+

+ Two SMS providers are supported: Kavenegar (default) + and Parsian SMS Gateway. The active provider is chosen + by the SMS_PROVIDER (or SMS) env var. Both + providers implement the same internal gateway interface so the + orchestration layer is provider-agnostic. +

+ +
+

Provider selection

+ + + + +
Env varValueActive provider
SMS_PROVIDER (or SMS)kavenegar (default)Kavenegar — api.kavenegar.com
SMS_PROVIDER (or SMS)parsianParsian SMS Gateway — PARSIAN_SMS_URL
+
+ +
+

Kavenegar endpoints

+

Base URL: https://api.kavenegar.com/v1/{SMS_API_KEY}/

+ + + + +
MethodPathWhen used
POSTsms/send.jsonPlain-text messages (e.g. key-based notification texts stored in sms_texts collection).
GETverify/lookup.jsonAll template-based messages (OTPs, invite links, expert notifications). Params: receptor, token[, token2, token3, token10], template.
+
+ +
+

Parsian SMS Gateway

+

Base URL from PARSIAN_SMS_URL. Auth: X-PACKAGE-API-KEY header + Authorization: Basic {PARSIAN_BASIC_TOKEN}. Sends as a GET with URL-encoded ReceiverNumbers and Message query params. Template messages are pre-rendered into a plain text body before sending (no verify/lookup equivalent).

+
+ +
+

SMS templates in use

+ + + + + + + + + + + +
Template nameTriggerTokens
AUTH_SMS_TEMPLATE (env)User / actor OTP login, forget-password, party OTPstoken = OTP code
yara724-invite-linkSecond party receives blame invite link via SMStoken = publicId, token2 = link
yara-field-expert-linkField expert sends link to a partytoken = file type, token2 = expert surname, token3 = link
yara-blame-agreementNotify party that the other side agreed to the expert verdicttoken = publicId, token2 = link
yara-claim-linkDamaged party notified to open claim flow after blame is completetoken = publicId, token2 = link
yara-expert-lockExpert locks a blame or claim filetoken = "تصادف"/"خسارت", token2 = publicId, token3 = expert surname
yara-resend-documentsExpert requests document resendtoken = file kind, token2 = publicId, token3 = link
yara-signatureParty notified to sign the expert's damage assessmenttoken = file kind, token2 = publicId, token3 = expert surname, token10 = link
yara-fanavaran-claimFanavaran submission confirmed — sent to claim owner with Fanavaran claim number and IDtoken = publicId, token2 = Fanavaran claimId, token3 = Fanavaran claimNo
+

+ All SMS calls are fire-and-forget — they never throw. Failures are logged but do not block the main flow. + An sms_send_logs MongoDB collection records every outbound message with its kind (OTP vs TEMPLATE), provider, template name, and success/failure status. + Notification text messages (parties-disagree, one-party-signed, etc.) are seeded into the sms_texts collection on startup and editable at runtime. +

+
+ + +

7 — AI Service disabled (code present)

+

+ An image-based car damage detection service is integrated in the + codebase but its HTTP calls are fully commented out. + The module initialises on startup, attempts a login (silently swallowed + if it fails), and exposes an aiRequestImage method — but + the underlying axios calls are disabled. The service does not affect + any production flow. +

+ +
+

Intended interface (when re-enabled)

+ + + + + +
MethodPathWhat it does
POST{AI_URL_V2}/auth/loginAuthenticate with username + password. Returns accessToken.
GET{AI_URL_V2}/auth/profileFetch apiKey.key needed as the gateway-api-key request header.
POST{AI_URL_V2}/services/car-damage/detector?version=ai-v7Submit a car part image (multipart). Returns downloadLink with annotated result.
+

+ Status: all three calls are wrapped in commented-out axios.request(…) blocks. + CW_URL is not in .env.example. To re-enable, uncomment the login, getApiKey, and aiRequestImage axios calls, and configure AI_URL_V2, AI_USERNAME, AI_PASSWORD. +

+
+ + +

8 — Car Pricing Service partially active

+

+ Used only during damage-expert price-drop calculation. When an expert + provides per-part severity values the system fetches real-time market + prices for the damaged car model, then computes the price-drop using + the formula: carPrice × yearCoefficient × sumOfPartCoefficients ÷ 400. + The service has two data sources (endpoints) that are tried in parallel. +

+ +
+

Endpoints

+ + + + +
MethodPathWhat it does
GET{CW_URL}price?akharinFetch car market prices from the "Akharin" source. Returns array of { carName, marketPrice }.
GET{CW_URL}price?hamrahFetch car market prices from the "Hamrah" source. Same response shape.
+

+ Both endpoints are tried; results are merged and de-duplicated. The best match for + the damaged car's name is found using Levenshtein distance (fuzzy string match). + If both endpoints fail or return empty, the price-drop calculation is skipped (marked incomplete) — it does not block claim submission. +

+

+ CW_URL is not documented in .env.example. + This service will silently produce no price-drop if the variable is unset. +

+
+ + +

9 — Offline Inquiry internal / fallback

+

+ The offline inquiry layer intercepts plate-based inquiry calls before + any external HTTP is made. It is primarily used for development and + testing (pre-seeded known plates) but also acts as a resilience fallback + when live inquiry services are unavailable. It is controlled by a + runtime database flag, not an env var. +

+ +
+

How it works

+ + + + + + + +
AspectDetail
StorageMongoDB collection offline-inquiries. Documents contain clientKey, normalised plate fields, nationalCode, and the pre-built raw + mapped response to return.
Master switchsystem_settings.offlineInquiry.enabled — defaults to true. Toggle via PATCH /super-admin/system-settings/offline-inquiry.
Lookup orderNormalised plate (digits-only, Arabic→Persian) + national code + Fanavaran client key must all match. If found, returned immediately; no HTTP call is made.
ScopeOnly applies to plate-based block-inquiry (THIRD_PARTY). CAR_BODY inquiry (/badane) always hits the live API.
Live API flagsystem_settings.externalApis.sandHubUseLiveApi — when false (default), even if no offline seed matches, a built-in mock response is returned rather than calling Tejarat/ESG.
+
+ + +

10 — Environment Variable Reference

+

+ All env vars across all integrations, grouped by service. + Variables marked * are not present in .env.example. +

+ +
+

Fanavaran

+ + + + +
VariableDescription
FANAVARAN_CLIENTActive tenant profile key: parsian | tejaratno | moallem
INSURANCE_CORP_IDDisplay caption of the insurer company (e.g. "بیمه پارسیان") — resolved to a numeric corpId at startup against the Fanavaran insurance-corp list.
+

Per-tenant credentials (appName, secret, username, password, CorpId, ContractId, Location) are hardcoded in src/core/config/fanavaran-client.config.ts under SEED_FANAVARAN_CLIENT_PROFILES.

+
+ +
+

SandHub (legacy)

+ + + + + + +
VariableDescription
SANHUB_BASE_URLBase URL for SandHub. Default: http://82.99.202.245:3027
SANHUB_URL_LOGINFull login URL (usually base + /user/login)
SANHUB_USERNAMESandHub login email
SANHUB_PASSWORDSandHub login password
+
+ +
+

Tejarat inquiry

+ + + + + +
VariableDescription
TEJARAT_INQUIRY_BASE_URLBase URL. Default: http://82.99.202.245:3027
TEJARAT_INQUIRY_EMAILLogin email
TEJARAT_INQUIRY_PASSWORDLogin password
+
+ +
+

ESG (CLIENT_ID=8 only)

+ + + + + + +
VariableDescription
CLIENT_IDSet to 8 to activate the ESG inquiry provider for the Parsian tenant.
ESG_URLESG base URL. Default: http://192.168.20.22:8085 (internal network)
ESG_USERNAMEESG login username
ESG_PASSWORDESG login password
+
+ +
+

SMS

+ + + + + + + + + +
VariableDescription
SMS_PROVIDER (or SMS)kavenegar (default) or parsian
SMS_API_KEYKavenegar API key (required when provider = kavenegar)
AUTH_SMS_TEMPLATEKavenegar template name for OTP messages (e.g. yara-otp)
PARSIAN_SMS_URLParsian SMS Gateway base URL (required when provider = parsian)
PARSIAN_API_KEYParsian SMS X-PACKAGE-API-KEY header value
PARSIAN_BASIC_TOKENBase64-encoded credentials for Authorization: Basic … header
URLFrontend base URL — used to build all invite + claim links embedded in SMS messages
+
+ +
+

AI service

+ + + + + +
VariableDescription
AI_URL_V2AI gateway base URL. Default: https://ai-gw.ittalie.ir (unused — service is disabled)
AI_USERNAMEAI service login username (unused)
AI_PASSWORDAI service login password (unused)
+
+ +
+

Car pricing service

+ + + +
VariableDescription
CW_URL *Base URL for car market price API (e.g. https://…/). Not in .env.example. Price-drop silently skipped if unset.
+
+ +
+

General / app

+ + + + + + +
VariableDescription
PORTHTTP port (default 3000). Used by the Fanavaran insurance-corp fallback to call its own local lookup endpoint.
CAPTCHA_ENABLEDtrue / false — enables/disables login CAPTCHA challenge. Internal, no external service.
EXP_CAPTCHA_TIMECAPTCHA challenge TTL in minutes.
EXP_OTP_TIMEOTP TTL in minutes.
+
+ + +
+ + diff --git a/docs/panel-roles-reference.fa.html b/docs/panel-roles-reference.fa.html new file mode 100644 index 0000000..a5f13ca --- /dev/null +++ b/docs/panel-roles-reference.fa.html @@ -0,0 +1,624 @@ + + + + + مرجع نقش‌های پنل + + + +
+

مرجع نقش‌های پنل

+

+ آنچه هر نقش می‌تواند ببیند و انجام دهد — اندپوینت‌ها، مسئولیت‌ها و + مراحل فرآیند. سوپر ادمین در این مستند نیست. +

+ + +
+
نقش‌های پوشش‌داده‌شده
+
    +
  1. بیمه‌گر (COMPANY) — ادمین تنانت شرکت بیمه
    2. +
  2. کارشناس تقصیر (EXPERT) — صف بررسی اختلاف
    3. +
  3. کارشناس خسارت (DAMAGE_EXPERT) — قیمت‌گذاری خسارت
    4. +
  4. کارشناس میدانی (FIELD_EXPERT) — ثبت حضوری در صحنه
    5. +
  5. فایل‌ساز (FILE_MAKER) — روایت طرفین در V4/V5
    6. +
  6. بازبین فایل (FILE_REVIEWER) — ارزیابی خسارت V4/V5
    7. +
  7. ثبات (REGISTRAR) — ثبت اداری حضوری
    8. +
  8. مرکز تماس (CALL_CENTER) — ثبت تلفنی V6
    9. +
+
+ + +

نمای کلی نقش‌ها

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
وظیفه اصلیمحدودهپنل ورودenum نقش
مشاهده تمام فایل‌ها؛ مدیریت شعب و کارشناسان؛ گزارش‌گیری؛ امتیازدهی به کارشناسانسطح تنانتپورتال بیمه‌گرcompany
قفل‌کردن پرونده‌های تقصیر، بررسی اسناد طرفین، صدور رأی یا درخواست ارسال مجددصف DISAGREEMENT تنانتپنل کارشناس تقصیرexpert
قفل‌کردن خسارت، قیمت‌گذاری، اعتبارسنجی فاکتورها، درخواست ارسال مجدد/بازدیدصف خسارت تنانتپنل خسارتdamage_expert
ثبت حضوری تقصیر + خسارت در V2/V3؛ دسترسی به پنل‌های تقصیر/خسارتفایل‌های ساخته‌شده توسط خودپنل کارشناس میدانیfield_expert
روایت طرفین V4/V5 (OTP، استعلام، جزئیات، امضا)؛ تأیید خسارت در V5فایل‌های ساخته‌شده توسط خودپنل فایل‌سازfile_maker
ارزیابی خسارت V4/V5 (فیلدهای تصادف، قطعات، عکس‌ها، امضای مالک)فایل‌های تخصیص‌یافتهپنل بازبین فایلfile_reviewer
ثبت حضوری اداری تقصیر + خسارت به نمایندگی از طرفینفایل‌های ساخته‌شده توسط خودپنل ثباتregistrar
ثبت تلفنی V6: اجرای استعلام، ارسال لینک؛ کاربر بقیه را تکمیل می‌کندفایل‌های ساخته‌شده توسط خودپنل مرکز تماسcall_center
+ + +

۱ — بیمه‌گر company

+

+ به ازای هر تنانت شرکت بیمه یک اکتور company وجود دارد. پورتال بیمه‌گر + لایه مدیریتی است: می‌تواند همه چیز زیر تنانت خود را ببیند، لیست کارشناسان را مدیریت + کند، شعب را اداره کند، تنظیمات رسانه‌ای هر تنانت را پیکربندی کند و گزارش‌های آماری + استخراج کند. بیمه‌گر هرگز مستقیماً با مراحل تقصیر/خسارت درگیر نمی‌شود — فقط نظاره‌گر + و امتیازدهنده است. +

+ +
+

مدیریت فایل — expert-insurer/

+ + + + + + + + + +
متدمسیرتوضیح
GETexpert-insurer/filesفهرست تمام فایل‌های تقصیر + خسارت تنانت (ادغام‌شده بر اساس publicId). فیلترپذیر بر اساس وضعیت، نوع فایل، جستجو، مرتب‌سازی، صفحه.
GETexpert-insurer/files/:publicIdجزئیات کامل یک فایل بر اساس publicId.
GETexpert-insurer/files/:publicId/timelineتایم‌لاین فعالیت به ترتیب زمانی (تمام رویدادهای تاریخچه: منبع، نوع، اکتور، متادیتا).
GETexpert-insurer/files/:publicId/reportداده‌های ساختاریافته گزارش برای تولید PDF (بخش‌های مالک، راننده، بیمه، خودرو، تصادف).
PUTexpert-insurer/files/:publicId/ratingامتیازدهی به کارشناسان یک فایل (۱–۵ در هر بُعد: روش تصادف، به‌موقع‌بودن، دقت علت، دقت شناسایی مقصر، امتیاز ربات).
GETexpert-insurer/report/unified-file-statusesکاتالوگ وضعیت یکپارچه + تعداد به ازای هر وضعیت برای کل پرتفولیوی تنانت. فیلترپذیر بر اساس fileType و بازه تاریخ.
GETexpert-insurer/report/status-countsمنسوخ‌شده — از unified-file-statuses استفاده کنید.
+
+ +
+

مدیریت شعب — expert-insurer/branches

+ + + + + +
متدمسیرتوضیح
GETexpert-insurer/branchesفهرست تمام شعب این بیمه‌گر. پارامترها: جستجو، بازه تاریخ from/to، فیلتر isActive.
POSTexpert-insurer/branchesافزودن شعبه جدید (نام، کد، آدرس، شهر، تلفن و غیره).
PUTexpert-insurer/branches/:branchId/statusفعال یا غیرفعال کردن یک شعبه.
+
+ +
+

مدیریت لیست کارشناسان — expert-insurer/experts

+ + + + + + + + + + +
متدمسیرتوضیح
POSTexpert-insurer/experts/blameایجاد حساب کارشناس تقصیر جدید زیر این بیمه‌گر.
POSTexpert-insurer/experts/claimایجاد حساب کارشناس خسارت جدید زیر این بیمه‌گر.
POSTexpert-insurer/experts/file-makerایجاد حساب فایل‌ساز جدید زیر این بیمه‌گر.
POSTexpert-insurer/experts/file-reviewerایجاد حساب بازبین فایل جدید زیر این بیمه‌گر.
GETexpert-insurer/experts/listفهرست صفحه‌بندی‌شده تمام حساب‌های کارشناس در این تنانت.
GETexpert-insurer/experts/topبرترین کارشناسان تقصیر و خسارت رتبه‌بندی‌شده بر اساس میانگین امتیاز کلی (حداکثر ۱۰ نفر از هر نوع).
GETexpert-insurer/top-expertsنام مستعار experts/top (سازگاری با فرانت‌اند).
GETexpert-insurer/:expertIdفایل‌های رسیدگی‌شده توسط یک کارشناس (ردیف‌های خلاصه — تقصیر یا خسارت بسته به نوع کارشناس).
+
+ +
+

آمار و گزارش‌ها

+ + + + + + + + + + +
متدمسیرتوضیح
GETexpert-insurer/statisticsکارت‌های KPI: totalFilesReviewed، averageUserRating، inPersonCount، filesThisMonth، objectionPercentage و غیره. فیلترپذیر بر اساس بازه تاریخ.
GETexpert-insurer/top-files۱۰ فایل خسارت برتر بر اساس بالاترین امتیاز (ترکیبی از امتیاز بیمه‌گر + کاربر).
GETexpert-insurer/expert-work-logلاگ کاری هر کارشناس: totalHandled، currentlyChecking، distinctFilesCheckedInPeriod. فیلترپذیر بر اساس expertKind و بازه تاریخ.
GETreports/report/insurer/requestsتعداد خسارت + وضعیت تقصیر + تعداد فایل یکپارچه برای تنانت.
GETreports/report/insurer/per-month-requestsهمان خلاصه، تفکیک‌شده بر اساس ۵ ماه تقویمی اخیر.
GETreports/report/insurer/checked-requestsهمان خلاصه، فیلترشده بر اساس بازه زمانی اختیاری createdAt.
GETreports/report/insurer/expert-work-logلاگ کاری کارشناسان (مجموعه‌های کارشناس تقصیر و خسارت، نه کارشناسان میدانی).
GETreports/report/insurer/expert-work-log/per-monthهمان لاگ کاری تفکیک‌شده بر اساس ماه تقویمی (۵ ماه اخیر).
+
+ +
+

تنظیمات تنانت — client-panel/

+ + + + +
متدمسیرتوضیح
GETclient-panel/settingsدریافت محدودیت‌های رسانه‌ای هر تنانت (حداکثر بایت ویدیو/تصویر/صوت) و پنجره زمانی تصادف CAR_BODY (روز).
PATCHclient-panel/settingsبه‌روزرسانی جزئی این تنظیمات. نمی‌تواند از سقف‌های سطح سیستم تجاوز کند.
+
+ + +

۲ — کارشناس تقصیر expert

+

+ فایل‌های تقصیر در صف DISAGREEMENT را بررسی می‌کند — پرونده‌هایی که دو طرف درباره + مقصر بودن توافق ندارند. پس از بررسی اسناد و اظهارات طرفین، کارشناس پرونده را قفل + می‌کند، سپس یا رأی صادر می‌کند، درخواست ارسال مجدد اسناد می‌دهد، یا نتیجه بازدید + حضوری را ثبت می‌کند. تمام اندپوینت‌ها زیر v2/expert-blame/ هستند. +

+ +
+

فرآیند

+

+ ۱ مرور فهرست ← ۲ تخصیص (قفل) پرونده ← ۳ بررسی مدارک طرفین (ویدیو، صدا، اسناد) ← + ۴الف صدور رأی یا ۴ب درخواست ارسال مجدد اسناد یا ۴پ ثبت بازدید حضوری. +

+
+ +
+

اندپوینت‌ها — v2/expert-blame/

+ + + + + + + + + + + +
متدمسیرتوضیح
GETv2/expert-blame/فهرست پرونده‌های تقصیر در صف DISAGREEMENT (موجود، قفل‌شده توسط من، یا تصمیم‌گرفته‌شده توسط من). پارامترها: search، sortBy، sortOrder، page، limit، unifiedStatus، fileType.
GETv2/expert-blame/:idجزئیات کامل یک پرونده تقصیر (اظهارات، عکس، صدا، ویدیو طرفین).
POSTv2/expert-blame/:id/assignبررسی در دسترس بودن و قفل پرونده برای این کارشناس. بازمی‌گرداند: assigned، already_assigned_to_you، یا ۴۰۹ در صورتی که شخص دیگری آن را نگه داشته باشد.
PUTv2/expert-blame/reply/submit/:idارسال رأی (accidentWay، accidentReason، accidentType، تصمیم طرف مقصر). پرونده را آزاد می‌کند و به COMPLETED منتقل می‌کند.
PUTv2/expert-blame/reply/resend/:idدرخواست از طرفین برای بارگذاری مجدد اسناد. تقصیر را به WAITING_FOR_RESEND تنظیم می‌کند. یک درخواست ارسال مجدد در هر چرخه عمر.
PUTv2/expert-blame/reply/inPerson/:idثبت اینکه بازدید حضوری انجام شده و صدور رأی.
GETv2/expert-blame/report/unified-file-statusesکاتالوگ وضعیت + تعداد به ازای هر وضعیت برای پرتفولیوی این کارشناس.
GETv2/expert-blame/report/status-countsمنسوخ‌شده — از unified-file-statuses استفاده کنید.
PUTv2/expert-blame/lock/:idاندپوینت قفل منسوخ‌شده — از POST assign استفاده کنید.
+
+ + +

۳ — کارشناس خسارت damage_expert

+

+ فایل‌های خسارت را پس از ارسال مدارک خسارت توسط کاربر بررسی می‌کند. کارشناس + هر قطعه آسیب‌دیده را قیمت‌گذاری می‌کند، به‌صورت اختیاری کاهش قیمت (استهلاک) + محاسبه می‌کند، و می‌تواند از کاربر بخواهد مدارک را مجدداً ارسال کند، حضوری مراجعه + کند، یا فاکتورهای تعمیرگاه را هنگام نیاز به قیمت‌گذاری کارگاهی بارگذاری کند. + تمام اندپوینت‌ها زیر v2/expert-claim/ هستند. +

+ +
+

فرآیند

+

+ ۱ مرور فهرست ← ۲ تخصیص (قفل) خسارت ← ۳ بررسی عکس‌ها و اسناد خسارت ← + ۴ ویرایش اختیاری قطعات انتخاب‌شده یا محاسبه کاهش قیمت ← + ۵الف ارسال پاسخ قیمت‌گذاری‌شده یا ۵ب درخواست ارسال مجدد یا ۵پ درخواست بازدید حضوری ← + ۶ در صورت وجود قطعات فاکتوردار: اعتبارسنجی فاکتورهای تعمیرگاه بارگذاری‌شده. +

+
+ +
+

اندپوینت‌ها — v2/expert-claim/

+ + + + + + + + + + + + + + + + + + + +
متدمسیرتوضیح
GETv2/expert-claim/requestsفهرست خسارت‌ها در صف WAITING_FOR_DAMAGE_EXPERT + صف اعتبارسنجی فاکتور. پارامترها: search، sortBy، page، limit، unifiedStatus، fileType.
GETv2/expert-claim/request/:claimRequestIdجزئیات کامل خسارت: قطعات آسیب‌دیده، تصاویر گرفته‌شده، اسناد، priceDrop، داده طرف بلیم، آدرس‌های ویدیو.
POSTv2/expert-claim/assign/:claimRequestIdقفل خسارت برای این کارشناس. بازمی‌گرداند: assigned، already_assigned_to_you، یا ۴۰۹.
GETv2/expert-claim/request/:claimRequestId/price-dropمحتوای کاهش قیمت: برچسب‌های شدت، کاتالوگ ضریب، قطعات آسیب‌دیده + نگاشت، سال پیشنهادی خودرو از استعلام تقصیر.
PUTv2/expert-claim/request/:claimRequestId/price-dropمحاسبه و ذخیره کاهش قیمت: قیمت خودرو × ضریب سال × مجموع ضرایب ÷ ۴۰۰.
PUTv2/expert-claim/reply/submit/:claimRequestIdارسال پاسخ ارزیابی خسارت (لیست قطعات قیمت‌گذاری‌شده، داغی، branchId). سقف: کل ≤ ۵۳،۰۰۰،۰۰۰ تومان. بسته به پرچم‌های factorNeeded، خسارت را به owner-sign، mixed-factors-pending، یا صف اعتبارسنجی فاکتور منتقل می‌کند.
PUTv2/expert-claim/reply/resend/:claimRequestIdدرخواست از کاربر برای ارسال مجدد اسناد/عکس‌ها. یک ارسال مجدد در هر چرخه خسارت؛ در صورت تکمیل قبلی ۴۲۲ برمی‌گرداند.
PATCHv2/expert-claim/:claimRequestId/visitدرخواست از کاربر برای مراجعه حضوری. خسارت را آزاد می‌کند، وضعیت claimStatus را به NEEDS_REVISION تنظیم می‌کند.
PATCHv2/expert-claim/validate-factors/:claimRequestIdاعتبارسنجی فاکتورهای تعمیرگاه بارگذاری‌شده. تأیید یا رد هر خط فاکتور با totalPayment. سقف برای تمام خطوط اعمال می‌شود (≤ ۵۳،۰۰۰،۰۰۰ تومان). پس از تصمیم‌گیری درباره تمام خطوط، به‌صورت خودکار تکمیل می‌شود.
PATCHv2/expert-claim/request/:claimRequestId/damaged-partsویرایش قطعات آسیب‌دیده انتخاب‌شده در حالی که خسارت توسط این کارشناس قفل است (EXPERT_REVIEWING).
GETv2/expert-claim/outer-parts-catalogکاتالوگ قطعات بیرونی خودرو فناوران (مشترک با جریان کاربر).
GETv2/expert-claim/inner-parts-catalogJSON ثابت کاتالوگ قطعات داخلی خودرو.
GETv2/expert-claim/branchesشعب بیمه‌گر برای تنانت این کارشناس (برای انتخاب داغی/شعبه در پیلود پاسخ).
GETv2/expert-claim/stream/:id/videoپخش ویدیوی خسارت (ویدیوی دور زدن خودرو یا ویدیوی تصادف). پارامتر: query=car-capture|accident.
GETv2/expert-claim/report/unified-file-statusesکاتالوگ وضعیت + تعداد برای پرتفولیوی خسارت این کارشناس.
GETv2/expert-claim/report/status-countsمنسوخ‌شده — از unified-file-statuses استفاده کنید.
PUTv2/expert-claim/lock/:claimRequestIdاندپوینت قفل منسوخ‌شده — از POST assign استفاده کنید.
+
+ + +

۴ — کارشناس میدانی field_expert

+

+ به صحنه تصادف می‌رود و فرم‌های هر دو طرف را حضوری پر می‌کند (جریان V2 mirror / V3). + کارشناس میدانی همچنین دسترسی خواندن به پنل‌های expert-blame و expert-claim دارد + (محدود به فایل‌های خودش). تنها نقشی است که هم ثبت تقصیر و هم + ثبت خسارت را در یک جلسه انجام می‌دهد. +

+ +
+

ثبت تقصیر — v2/expert-initiated/blame-request-management/

+

آینه‌ای از API تقصیر کاربر. فرانت‌اند همان صفحات را با تغییر فقط پیشوند مسیر بازاستفاده می‌کند.

+ + + + + + + + + + + + + + + +
متدمسیرتوضیح
POSTPOST /ایجاد فایل تقصیر IN_PERSON.
POSTsend-party-otp/:idارسال OTP به یک طرف از طریق شماره تلفن (بدون لینک دعوت).
POSTverify-party-otp/:idتأیید OTP یک طرف و اتصال حساب آنها.
POSTblame-confession/:idثبت اعتراف تقصیر طرف.
POSTcar-body-form/:id[فقط CAR_BODY] فرم نوع تصادف.
POSTrun-inquiries/:id / run-inquiries-vin/:idفرم اولیه / استعلام پلاک یا VIN برای طرف فعلی.
POSTupload-video/:idبارگذاری ویدیوی طرف اول.
POSTadd-detail-location/:idافزودن موقعیت GPS برای طرف فعلی.
POSTupload-voice/:idبارگذاری ضبط صوتی برای طرف فعلی.
POSTadd-detail-description/:idافزودن توضیحات برای طرف فعلی.
POSTadd-second-party/:phone/:id/پیشروی به طرف دوم (بدون ارسال لینک SMS).
PUTsign/:idبارگذاری امضای طرف (اول سپس دوم، پارامتر partyRole).
POSTaccident-fields/:idذخیره فیلدهای تصادف و تکمیل فوری تقصیر (بدون صف کارشناس).
+
+ +
+

ثبت تقصیر + خسارت V3 — v3/expert-initiated/blame-request-management/

+

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

+ + + + + + + + + + +
متدمسیرتوضیح
POSTPOST / ← send-party-otp ← verify-party-otp ← run-inquiries ← add-detail-* ← sign (×۲)مرحله روایت طرفین (مراحل ۱–۸) — اندپوینت‌های یکسان با mirror، همان قرارداد.
POSTaccident-fields/:idمرحله ۹: ذخیره فیلدهای تصادف پس از امضای هر دو طرف.
GETclaim-id/:requestIdمرحله ۱۰: دریافت شناسه خسارت ایجادشده به‌صورت خودکار.
POSTupload-document/:claimIdمرحله ۱۱: بارگذاری اسناد گواهینامه / کارت خودرو.
PATCHselect-outer-parts/:claimId / select-other-parts/:claimIdمراحل ۱۲–۱۳: انتخاب قطعات آسیب‌دیده.
POSTcapture-part/:claimIdمرحله ۱۴: عکس‌برداری از قطعات + زوایا.
PATCHcar-capture/:claimIdمرحله ۱۵: ویدیوی دور زدن خودرو.
POSTupload-video/:requestIdمرحله ۱۶: ویدیوی تصادف تقصیر (نهایی) ← WAITING_FOR_EXPERT (THIRD_PARTY) یا COMPLETED (CAR_BODY).
+
+ +
+

دسترسی به پنل expert-blame + expert-claim (خواندن + اقدام روی فایل‌های خود)

+

+ FIELD_EXPERT مسیر v2/expert-blame/ را محدود به فایل‌های ساخته‌شده توسط خودش می‌بیند (نه صف اختلاف). + همچنین v2/expert-claim/ را برای خسارت‌های مرتبط با فایل‌های تقصیرش می‌بیند. + اندپوینت‌های یکسان با پنل‌های کارشناس تقصیر و کارشناس خسارت در بالا. +

+
+ + +

۵ — فایل‌ساز file_maker

+

+ اولین اکتور در تقسیم V4/V5. فایل‌ساز روایت طرفین را در محل انجام می‌دهد: + OTPها، استعلام‌ها، موقعیت/توضیحات/صدا و امضاها برای هر دو طرف. + همچنین اسناد اولیه خسارت (گواهینامه‌ها، کارت‌های خودرو) را بارگذاری می‌کند. پس از + امضای دوم، فایل برای تحویل به بازبین فایل «مهرومومه» می‌شود. در V5، فایل‌ساز + در انتها بازمی‌گردد تا خسارت تکمیل‌شده را قبل از ارسال به فناوران تأیید یا رد کند. +

+ +
+

ثبت تقصیر — v4/file-maker/blame-request-management/ و v5/…

+

اندپوینت‌های V4 و V5 یکسان هستند — فقط پیشوند تغییر می‌کند. V5 هنگام ایجاد requiresFileMakerApproval=true را تنظیم می‌کند.

+ + + + + + + + + + + + + +
متدمسیرتوضیح
POSTPOST /ایجاد فایل تقصیر IN_PERSON.
GETmy-filesفهرست تمام فایل‌های تقصیر ایجادشده توسط این فایل‌ساز.
GETmy-files/:requestIdجزئیات کامل یک فایل (طرفین، گردش کار، شناسه خسارت مرتبط).
GETclaim-id/:requestIdدریافت شناسه خسارت ایجادشده به‌صورت خودکار پس از استعلام طرف مقصر.
POSTsend-party-otp/:id / verify-party-otp/:idارسال + تأیید OTP برای یک طرف در هر بار (ابتدا مقصر، سپس زیان‌دیده).
POSTcar-body-form/:id[فقط CAR_BODY] فرم نوع تصادف.
POSTrun-inquiries/:id / run-inquiries-vin/:idاجرای استعلام پلاک یا VIN. فراخوانی اول = مقصر (+ خودکار خسارت ایجاد می‌کند). فراخوانی دوم = زیان‌دیده (فقط THIRD_PARTY).
POSTadd-detail-location/:id / add-detail-description/:id / upload-voice/:idافزودن موقعیت، توضیحات و صدا برای طرف فعلی (پارامتر partyRole، FIRST/SECOND را انتخاب می‌کند).
PUTsign/:idبارگذاری امضای طرف (partyRole=FIRST سپس SECOND). پس از امضای دوم، فایل مهرومومه می‌شود.
POSTupload-document/:claimIdبارگذاری گواهینامه / کارت‌های خودرو روی خسارت ایجادشده به‌صورت خودکار.
GETcapture-requirements/:claimIdالزامات عکس‌برداری آگاه از مرحله (فازها: اسناد پیش از عکس‌برداری در مقابل قطعات آسیب‌دیده + شاسی/موتور).
+
+ +
+

تأیید خسارت V5 — v5/file-maker/claim-approval/

+

فقط در V5 استفاده می‌شود. پس از بررسی کارشناس خسارت و امضای مالک، خسارت وارد WAITING_FOR_FILE_MAKER_APPROVAL می‌شود.

+ + + + +
متدمسیرتوضیح
POSTapprove/:claimIdتأیید خسارت تکمیل‌شده ← ارسال SMS امضای مالک را فعال می‌کند ← پس از امضای مالک به فناوران ارسال می‌شود.
POSTreject/:claimIdرد به بازبین فایل ← خسارت به WAITING_FOR_DAMAGE_EXPERT برمی‌گردد. محدودیت: حداکثر ۲ رد در هر خسارت؛ تلاش سوم ۴۲۲ با کد FILE_MAKER_REJECTION_LIMIT_EXCEEDED برمی‌گرداند.
+
+ + +

۶ — بازبین فایل file_reviewer

+

+ دومین اکتور در تقسیم V4/V5. بازبین فایل فایل‌های مهرومومه‌شده (پس از اتمام کار + فایل‌ساز) را تحویل می‌گیرد و مرحله کامل ارزیابی خسارت را انجام می‌دهد: فیلدهای + تصادف، دریافت الزامات عکس‌برداری، بارگذاری اسناد (شاسی/موتور)، انتخاب قطعات، + عکس‌های قطعات، ویدیوی دور زدن خودرو، امضای مالک. تقصیر با car-capture به + COMPLETED علامت‌گذاری می‌شود. بازبین فایل همچنین دسترسی خواندن به پنل expert-claim + برای خسارت‌هایی که بررسی می‌کند دارد. +

+ +
+

ارزیابی خسارت — v4/file-reviewer/blame-request-management/ و v5/…

+

اندپوینت‌های V4 و V5 یکسان هستند — فقط پیشوند تغییر می‌کند.

+ + + + + + + + + + + + + + +
متدمسیرتوضیح
GETmy-filesفهرست تمام فایل‌های تخصیص‌یافته به این بازبین فایل.
GETmy-files/:requestIdجزئیات کامل یک فایل (طرفین، گردش کار، فیلدهای کارشناس، شناسه خسارت مرتبط).
GETclaim-id/:requestIdدریافت شناسه خسارت ایجادشده به‌صورت خودکار (از استعلام طرف مقصر فایل‌ساز).
POSTaccident-fields/:requestIdمرحله ۱ (بازبین): ذخیره فیلدهای تصادف (accidentWay، accidentReason، accidentType).
GETcapture-requirements/:claimIdالزامات عکس‌برداری آگاه از مرحله (فاز اسناد پیش از عکس‌برداری در مقابل فاز عکس‌برداری قطعات).
POSTupload-document/:claimIdبارگذاری اسناد شاسی / موتور / پلاک فلزی.
PATCHselect-outer-parts/:claimIdانتخاب قطعات آسیب‌دیده بیرونی (بدنه).
PATCHselect-other-parts/:claimIdانتخاب سایر قطعات آسیب‌دیده (غیر بدنه).
POSTcapture-part/:claimIdعکس‌برداری از قطعات + زوایا برای هر قطعه آسیب‌دیده انتخاب‌شده.
PATCHcar-capture/:claimIdویدیوی دور زدن خودرو (آخرین مرحله عکس‌برداری بازبین). خسارت ← WAITING_FOR_DAMAGE_EXPERT، تقصیر ← COMPLETED.
PUTclaim-sign/:claimIdثبت امضای مالک روی قیمت‌گذاری کارشناس به نمایندگی از طرف زیان‌دیده (موافقت + branchId + تصویر امضا).
POSTupload-video/:requestIdدر V4/V5 بی‌اثر است — تقصیر از قبل توسط car-capture COMPLETED شده. موفقیت idempotent برمی‌گرداند.
+
+ +
+

دسترسی به پنل expert-claim

+

+ FILE_REVIEWER در نقش‌های مجاز برای v2/expert-claim/ است. + می‌تواند جزئیات خسارت را مشاهده کند و جریان assign/lock را برای خسارت‌های + مرتبط با فایل‌هایش اجرا کند. نمی‌تواند به‌طور مستقل درخواست ارسال مجدد + کارشناس خسارت را آغاز کند. +

+
+ + +

۷ — ثبات registrar

+

+ نقش اداری که تقصیر و خسارت حضوری را به نمایندگی از طرفین ثبت می‌کند. + از جریان OTP دسته‌ای استفاده می‌کند (OTPهای هر دو طرف به‌صورت همزمان ارسال و + تأیید می‌شوند) به جای OTP یک‌به‌یک که توسط کارشناسان میدانی استفاده می‌شود. + پس از تقصیر، ثبات آینه API خسارت کاربر را دنبال می‌کند تا انتخاب قطعات، اسناد + و عکس‌برداری را پر کند. سپس فایل وارد چرخه عادی بررسی کارشناس خسارت می‌شود. +

+ +
+

ثبت تقصیر — registrar-initiated-blame/

+

توجه: @ApiExcludeController — مسیرها وجود دارند اما در مستندات Swagger نمایش داده نمی‌شوند.

+ + + + + + + + + + + + +
متدمسیرتوضیح
POSTregistrar-initiated-blame/createایجاد فایل تقصیر IN_PERSON.
GETregistrar-initiated-blame/my-filesفهرست تمام فایل‌های تقصیر ایجادشده توسط این ثبات.
GETregistrar-initiated-blame/blame/:requestIdجزئیات کامل یک فایل تقصیر.
POSTregistrar-initiated-blame/send-party-otps/:idارسال OTP به هر دو طرف به‌صورت همزمان.
POSTregistrar-initiated-blame/verify-party-otps/:idتأیید OTPهای هر دو طرف در یک فراخوانی.
POSTregistrar-initiated-blame/complete-blame-data/:idارسال تمام داده‌های فرم تقصیر هر دو طرف در یک پیلود.
POSTregistrar-initiated-blame/upload-video/:idبارگذاری ویدیوی تقصیر.
POSTregistrar-initiated-blame/upload-voice/:idبارگذاری ضبط صوتی.
POSTregistrar-initiated-blame/add-accident-fields/:idذخیره فیلدهای تصادف و تکمیل تقصیر.
POSTregistrar-initiated-blame/upload-party-signature/:idبارگذاری امضای یک طرف (partyRole=FIRST/SECOND).
+
+ +
+

ثبت خسارت — v2/registrar/claim-request-management/

+

آینه‌ای از API خسارت کاربر. فرانت‌اند همان صفحات خسارت را با تغییر فقط پیشوند بازاستفاده می‌کند.

+ + + + + + + + + + +
متدمسیرتوضیح
POSTcreate-from-blame/:blameIdایجاد خسارت از یک فایل تقصیر تکمیل‌شده.
GETouter-parts-catalog / car-other-partکاتالوگ قطعات (قطعات بیرونی بدنه + JSON سایر قطعات).
GETbranches/:insuranceIdفهرست شعب بیمه‌گر (برای انتخاب شعبه در مرحله امضای خسارت).
PATCHselect-outer-parts/:claimIdانتخاب قطعات آسیب‌دیده بیرونی.
PATCHselect-other-parts/:claimIdانتخاب سایر قطعات آسیب‌دیده + اطلاعات بانکی.
POSTupload-document/:claimIdبارگذاری اسناد خسارت (گواهینامه، کارت خودرو).
POSTcapture-part/:claimIdعکس‌برداری از قطعات + زوایا.
PATCHcar-capture/:claimIdویدیوی دور زدن خودرو (مرحله نهایی) ← WAITING_FOR_DAMAGE_EXPERT.
+
+ + +

۸ — مرکز تماس call_center

+

+ ثبت تقصیر تلفنی V6 را مدیریت می‌کند. اپراتور داده‌های طرف مقصر را از طریق تلفن + جمع‌آوری می‌کند، استعلام بیمه را اجرا می‌کند و لینک تقصیر را از طریق SMS ارسال + می‌کند. کاربر سپس بقیه فرم را از طریق جریان استاندارد V2 تکمیل می‌کند + (با رد شدن مرحله فرم اولیه/استعلام). کار اپراتور مرکز تماس پس از send-link + پایان می‌یابد؛ می‌تواند پیشرفت را از طریق اندپوینت‌های خواندن پایش کند. +

+ +
+

اندپوینت‌ها — v6/call-center-blame/

+ + + + + + + + +
متدمسیرتوضیح
POSTcreateایجاد فایل تقصیر LINK. بدنه: { type: "THIRD_PARTY" | "CAR_BODY" }.
POSTrun-inquiry/:requestIdاجرای استعلام بیمه پلاک + کد ملی برای طرف مقصر. نتیجه را روی سند تقصیر ذخیره می‌کند.
POSTrun-inquiry-vin/:requestIdVIN/شاسی جایگزین برای run-inquiry. از جستجوی شاسی ESG استفاده می‌کند.
POSTsend-link/:requestIdدر صورت لزوم کاربر را ثبت‌نام می‌کند، به‌عنوان طرف اول ذخیره می‌کند، لینک دعوت تقصیر را از طریق SMS ارسال می‌کند. بدنه: { phoneNumber }.
GETmy-filesفهرست تمام فایل‌های تقصیر شروع‌شده توسط این اپراتور.
GETblame/:requestIdوضعیت فعلی و مرحله گردش کار یک فایل (برای بررسی اینکه کاربر لینک را باز کرده و پیشرفت کرده است).
+

+ پس از send-link، کاربر فرم را از طریق + v2/blame-request-management/ (جریان استاندارد V2) تکمیل می‌کند. + مرحله فرم اولیه / استعلام به‌صورت خودکار رد می‌شود + (skipInitialFormStep=true). جریان خسارت پایین‌دستی همان + جریان استاندارد خسارت V2 است. +

+
+ + +

مشترک: احراز هویت اکتورها

+

+ تمام اکتورهای پنل (هر نقش به جز user) از طریق همان اندپوینت + POST actor/login با کپچا احراز هویت می‌کنند. بازنشانی رمز عبور از + طریق OTP ایمیل است. خواندن و ویرایش پروفایل نیز مشترک است. +

+
+

اندپوینت‌ها — actor/

+ + + + + + + + +
متدمسیرتوضیح
GETactor/captchaصدور یک چالش کپچای ورود جدید (captchaId + تصویر SVG را برمی‌گرداند).
POSTactor/loginاحراز هویت هر نقش اکتور. بدنه: role، username/email/nationalCode، password، captchaId، captcha. توکن‌های JWT دسترسی + رفرش را برمی‌گرداند.
POSTactor/forget-passwordارسال OTP بازنشانی رمز عبور به ایمیل.
POSTactor/forget-password-verifyتأیید OTP و تنظیم رمز عبور جدید.
GETactor/profileدریافت پروفایل اکتور فعلی.
PATCHactor/profileبه‌روزرسانی پروفایل اکتور فعلی.
+
+ + +
+ + diff --git a/docs/panel-roles-reference.html b/docs/panel-roles-reference.html new file mode 100644 index 0000000..84eab3e --- /dev/null +++ b/docs/panel-roles-reference.html @@ -0,0 +1,616 @@ + + + + + Panel Roles Reference + + + +
+

Panel Roles Reference

+

+ What every actor role can see and do — endpoints, responsibilities, and + process steps. Super-admin excluded. +

+ + +
+
Roles covered
+
    +
  1. Insurer (COMPANY) — the insurance-company tenant admin
    2. +
  2. Blame Expert (EXPERT) — disagreement review queue
    3. +
  3. Damage Expert (DAMAGE_EXPERT) — claim pricing
    4. +
  4. Field Expert (FIELD_EXPERT) — on-scene in-person filing
    5. +
  5. File Maker (FILE_MAKER) — V4/V5 party narrative
    6. +
  6. File Reviewer (FILE_REVIEWER) — V4/V5 damage assessment
    7. +
  7. Registrar (REGISTRAR) — office-based filing
    8. +
  8. Call Center (CALL_CENTER) — V6 phone-initiated filing
    9. +
+
+ + +

Role Overview

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Role enumLogin panelScopePrimary job
companyInsurer portalTenant-wideView all files; manage branches, experts; run reports; rate experts
expertBlame expert panelTenant DISAGREEMENT queueLock blame cases, review party submissions, submit verdict or request resend
damage_expertClaim/damage panelTenant claim queueLock claims, price damage, validate repair factors, request resend/visit
field_expertField expert panelOwn created filesV2/V3 in-person blame + claim filing; also sees blame/claim review panels
file_makerFileMaker panelOwn created filesV4/V5 party narrative (OTPs, inquiries, details, signatures); V5 claim approval
file_reviewerFileReviewer panelAssigned filesV4/V5 damage assessment (accident fields, parts, captures, owner sign)
registrarRegistrar panelOwn created filesOffice-based in-person blame + claim filing on behalf of parties
call_centerCall-center panelOwn created filesV6 phone-initiated blame: run inquiry, send link; user completes the rest
+ + +

1 — Insurer company

+

+ One company actor per insurance-company tenant. The insurer portal is the + management layer: it can see everything under its tenant, manage the expert roster, + manage branches, configure per-tenant media settings, and pull statistical reports. + The insurer never touches blame/claim steps directly — it only observes and rates. +

+ +
+

File management — expert-insurer/

+ + + + + + + + + +
MethodRouteWhat it does
GETexpert-insurer/filesList all blame + claim files for the tenant (merged by publicId). Filterable by status, file type, search, sort, page.
GETexpert-insurer/files/:publicIdFull detail for one file by publicId.
GETexpert-insurer/files/:publicId/timelineChronological activity timeline (all history events: source, type, actor, metadata).
GETexpert-insurer/files/:publicId/reportStructured report data for PDF generation (owner, driver, insurance, vehicle, accident sections).
PUTexpert-insurer/files/:publicId/ratingRate the experts on a file (1–5 per dimension: collision method, timeliness, cause accuracy, guilty-ID accuracy, bot rating).
GETexpert-insurer/report/unified-file-statusesUnified status catalog + per-status counts for the whole tenant portfolio. Filterable by fileType and date range.
GETexpert-insurer/report/status-countsDeprecated — prefer unified-file-statuses.
+
+ +
+

Branch management — expert-insurer/branches

+ + + + + +
MethodRouteWhat it does
GETexpert-insurer/branchesList all branches for this insurer. Query: search, from/to date, isActive filter.
POSTexpert-insurer/branchesAdd a new branch (name, code, address, city, phone, etc.).
PUTexpert-insurer/branches/:branchId/statusActivate or deactivate a branch.
+
+ +
+

Expert roster management — expert-insurer/experts

+ + + + + + + + + + +
MethodRouteWhat it does
POSTexpert-insurer/experts/blameCreate a new blame-expert account under this insurer.
POSTexpert-insurer/experts/claimCreate a new damage-expert (claim) account under this insurer.
POSTexpert-insurer/experts/file-makerCreate a new FileMaker account under this insurer.
POSTexpert-insurer/experts/file-reviewerCreate a new FileReviewer account under this insurer.
GETexpert-insurer/experts/listPaginated list of all expert accounts on this tenant.
GETexpert-insurer/experts/topTop blame vs claim experts ranked by overall average rating (up to 10 each).
GETexpert-insurer/top-expertsAlias for experts/top (frontend compat).
GETexpert-insurer/:expertIdFiles handled by one expert (slim summary rows — blame or claim depending on expert type).
+
+ +
+

Statistics & reports

+ + + + + + + + + + +
MethodRouteWhat it does
GETexpert-insurer/statisticsKPI cards: totalFilesReviewed, averageUserRating, inPersonCount, filesThisMonth, objectionPercentage, etc. Filterable by date range.
GETexpert-insurer/top-filesTop 10 highest-rated claim files (combined insurer + user score).
GETexpert-insurer/expert-work-logPer-expert work log: totalHandled, currentlyChecking, distinctFilesCheckedInPeriod. Filterable by expertKind and date range.
GETreports/report/insurer/requestsClaim + blame status bucket counts + unified file count for the tenant.
GETreports/report/insurer/per-month-requestsSame summary, broken down by the last 5 calendar months.
GETreports/report/insurer/checked-requestsSame summary filtered by optional createdAt date range.
GETreports/report/insurer/expert-work-logExpert work log (blame + damage expert collections, not field experts).
GETreports/report/insurer/expert-work-log/per-monthSame work log per calendar month (last 5).
+
+ +
+

Tenant settings — client-panel/

+ + + + +
MethodRouteWhat it does
GETclient-panel/settingsGet per-tenant media limits (video/image/voice maxBytes) and CAR_BODY accident window (days).
PATCHclient-panel/settingsUpdate those settings (partial). Cannot exceed system-level route ceilings.
+
+ + +

2 — Blame Expert expert

+

+ Reviews blame files in the DISAGREEMENT queue — cases where the two parties do not + agree on who is at fault. After reviewing submitted documents and party statements + the expert locks the case, then either submits a verdict, asks the parties to resend + documents, or records an in-person visit outcome. All endpoints are under + v2/expert-blame/. +

+ +
+

Process

+

+ 1 Browse list → 2 Assign (lock) the case → 3 Review party evidence (videos, voices, documents) → + 4a Submit verdict or 4b Request document resend or 4c Record in-person visit. +

+
+ +
+

Endpoints — v2/expert-blame/

+ + + + + + + + + + + +
MethodRouteWhat it does
GETv2/expert-blame/List blame cases in the DISAGREEMENT queue (available, locked by me, or decided by me). Query: search, sortBy, sortOrder, page, limit, unifiedStatus, fileType.
GETv2/expert-blame/:idFull detail for one blame case (party statements, photos, voices, videos).
POSTv2/expert-blame/:id/assignCheck availability and lock the case to this expert. Returns assigned, already_assigned_to_you, or 409 if someone else holds it.
PUTv2/expert-blame/reply/submit/:idSubmit verdict (accidentWay, accidentReason, accidentType, guilty party decision). Unlocks the case and moves it to COMPLETED.
PUTv2/expert-blame/reply/resend/:idRequest parties to re-upload documents. Sets blame to WAITING_FOR_RESEND. One resend request per lifecycle.
PUTv2/expert-blame/reply/inPerson/:idRecord that an in-person visit was made and submit verdict.
GETv2/expert-blame/report/unified-file-statusesStatus catalog + per-status counts for this expert's portfolio.
GETv2/expert-blame/report/status-countsDeprecated — prefer unified-file-statuses.
PUTv2/expert-blame/lock/:idDeprecated lock endpoint — use POST assign.
+
+ + +

3 — Damage Expert damage_expert

+

+ Reviews claim files after the user has submitted their damage evidence. The expert + prices each damaged part, optionally calculates a price-drop (depreciation), and + can ask the user to resend documents, come in person, or upload repair factor invoices + when workshop pricing is needed. All endpoints are under v2/expert-claim/. +

+ +
+

Process

+

+ 1 Browse list → 2 Assign (lock) the claim → 3 Review damage photos and documents → + 4 Optionally edit selected parts or calculate price-drop → + 5a Submit priced reply or 5b Request resend or 5c Request in-person visit → + 6 If factor parts present: validate uploaded factor invoices. +

+
+ +
+

Endpoints — v2/expert-claim/

+ + + + + + + + + + + + + + + + + + + +
MethodRouteWhat it does
GETv2/expert-claim/requestsList claims in WAITING_FOR_DAMAGE_EXPERT queue + factor-validation queue. Query: search, sortBy, page, limit, unifiedStatus, fileType.
GETv2/expert-claim/request/:claimRequestIdFull claim detail: damaged parts, captured images, documents, priceDrop, blameCase party data, video URLs.
POSTv2/expert-claim/assign/:claimRequestIdLock claim to this expert. Returns assigned, already_assigned_to_you, or 409.
GETv2/expert-claim/request/:claimRequestId/price-dropPrice-drop context: severity labels, coefficient catalog, damaged parts + mapping, suggested car year from blame inquiry.
PUTv2/expert-claim/request/:claimRequestId/price-dropCalculate and persist price-drop: carPrice × yearCoeff × sumOfCoeffs ÷ 400.
PUTv2/expert-claim/reply/submit/:claimRequestIdSubmit damage assessment reply (priced parts list, daghi, branchId). Cap: total ≤ 53 000 000 Toman. Depending on factorNeeded flags moves claim to owner-sign, mixed-factors-pending, or factor-validation queue.
PUTv2/expert-claim/reply/resend/:claimRequestIdRequest user to resend documents/photos. One resend per claim lifecycle; returns 422 if already fulfilled.
PATCHv2/expert-claim/:claimRequestId/visitAsk user to come in person. Unlocks claim, sets claimStatus to NEEDS_REVISION.
PATCHv2/expert-claim/validate-factors/:claimRequestIdValidate uploaded repair factor invoices. Approve or reject each factor line with totalPayment. Cap applies across all lines (≤ 53 000 000 Toman). Auto-completes when all lines are decided.
PATCHv2/expert-claim/request/:claimRequestId/damaged-partsEdit selected damaged parts while the claim is locked by this expert (EXPERT_REVIEWING).
GETv2/expert-claim/outer-parts-catalogFanavaran outer car-components catalog (shared with user flow).
GETv2/expert-claim/inner-parts-catalogStatic inner car-parts catalog JSON.
GETv2/expert-claim/branchesInsurer branches for this expert's tenant (for daghi/branch selection in reply payload).
GETv2/expert-claim/stream/:id/videoStream claim video (car-capture walk-around or accident video). Query: query=car-capture|accident.
GETv2/expert-claim/report/unified-file-statusesStatus catalog + counts for this expert's claim portfolio.
GETv2/expert-claim/report/status-countsDeprecated — prefer unified-file-statuses.
PUTv2/expert-claim/lock/:claimRequestIdDeprecated lock endpoint — use POST assign.
+
+ + +

4 — Field Expert field_expert

+

+ Goes to the accident scene and fills both parties' forms in-person (V2 mirror / V3 flows). + The field expert also has read access to the expert-blame and expert-claim panels + (scoped to their own files). They are the only role that spans both + blame filing and claim filing in the same session. +

+ +
+

Blame filing — v2/expert-initiated/blame-request-management/

+

Mirror of the user blame API. Frontend reuses same pages by swapping prefix only.

+ + + + + + + + + + + + + + + +
MethodRouteWhat it does
POSTPOST /Create IN_PERSON blame file.
POSTsend-party-otp/:idSend OTP to one party by phone number (no invite link).
POSTverify-party-otp/:idVerify one party's OTP and bind their account.
POSTblame-confession/:idRecord party's blame confession.
POSTcar-body-form/:id[CAR_BODY only] Accident type form.
POSTrun-inquiries/:id / run-inquiries-vin/:idInitial form / plate or VIN inquiry for current party.
POSTupload-video/:idUpload first-party video.
POSTadd-detail-location/:idAdd GPS location for current party.
POSTupload-voice/:idUpload voice recording for current party.
POSTadd-detail-description/:idAdd description for current party.
POSTadd-second-party/:phone/:id/Advance to second party (no SMS link sent).
PUTsign/:idUpload party signature (FIRST then SECOND, partyRole param).
POSTaccident-fields/:idSave accident fields and complete blame immediately (no expert queue).
+
+ +
+

V3 blame + claim filing — v3/expert-initiated/blame-request-management/

+

Reorganised step order: all party narrative first, then damage assessment. Blame and claim both handled in this single controller.

+ + + + + + + + + + +
MethodRouteWhat it does
POSTPOST / → send-party-otp → verify-party-otp → run-inquiries → add-detail-* → sign (×2)Party narrative phase (steps 1–8) — identical endpoints to mirror, same contract.
POSTaccident-fields/:idStep 9: save accident fields after both parties have signed.
GETclaim-id/:requestIdStep 10: get auto-created claim ID.
POSTupload-document/:claimIdStep 11: upload licence / car card documents.
PATCHselect-outer-parts/:claimId / select-other-parts/:claimIdSteps 12–13: select damaged parts.
POSTcapture-part/:claimIdStep 14: capture part photos + angles.
PATCHcar-capture/:claimIdStep 15: walk-around video.
POSTupload-video/:requestIdStep 16: blame accident video (final) → WAITING_FOR_EXPERT (THIRD_PARTY) or COMPLETED (CAR_BODY).
+
+ +
+

Expert-blame + expert-claim panel (read + action on own files)

+

+ FIELD_EXPERT sees v2/expert-blame/ scoped to their own created files (not the disagreement queue). + They also see v2/expert-claim/ for claims linked to their blame files. + Same endpoints as blame-expert and damage-expert panels above. +

+
+ + +

5 — File Maker file_maker

+

+ The first actor in the V4/V5 split. FileMaker handles the party narrative on-site: + OTPs, inquiries, location/description/voice, and signatures for both parties. + They also upload the initial claim documents (licences, car cards). After the second + signature the file is "sealed" for FileReviewer pickup. In V5, FileMaker comes + back at the end to approve or reject the completed claim before fanavaran submission. +

+ +
+

Blame filing — v4/file-maker/blame-request-management/ and v5/…

+

V4 and V5 endpoints are identical — only the prefix changes. V5 sets requiresFileMakerApproval=true at creation.

+ + + + + + + + + + + + + +
MethodRouteWhat it does
POSTPOST /Create IN_PERSON blame file.
GETmy-filesList all blame files created by this FileMaker.
GETmy-files/:requestIdFull detail for one file (parties, workflow, linked claim ID).
GETclaim-id/:requestIdGet the auto-created claim ID after guilty-party run-inquiries.
POSTsend-party-otp/:id / verify-party-otp/:idSend + verify OTP for one party at a time (guilty first, then damaged).
POSTcar-body-form/:id[CAR_BODY only] Accident type form.
POSTrun-inquiries/:id / run-inquiries-vin/:idRun plate or VIN inquiry. First call = guilty (+ auto-creates claim). Second call = damaged (THIRD_PARTY only).
POSTadd-detail-location/:id / add-detail-description/:id / upload-voice/:idAdd location, description, and voice for current party (partyRole param selects FIRST/SECOND).
PUTsign/:idUpload party signature (partyRole=FIRST then SECOND). After second signature, file is sealed.
POSTupload-document/:claimIdUpload licences / car cards against the auto-created claim.
GETcapture-requirements/:claimIdStep-aware capture requirements (phases: pre-capture docs vs damaged parts + chassis/engine).
+
+ +
+

V5 claim approval — v5/file-maker/claim-approval/

+

Used only in V5. After damage expert review and owner sign, claim enters WAITING_FOR_FILE_MAKER_APPROVAL.

+ + + + +
MethodRouteWhat it does
POSTapprove/:claimIdApprove the completed claim → triggers owner sign SMS → fanavaran submission after owner signs.
POSTreject/:claimIdReject back to FileReviewer → claim returns to WAITING_FOR_DAMAGE_EXPERT. Limit: max 2 rejections per claim; 3rd attempt returns 422 FILE_MAKER_REJECTION_LIMIT_EXCEEDED.
+
+ + +

6 — File Reviewer file_reviewer

+

+ The second actor in the V4/V5 split. FileReviewer picks up sealed files (after + FileMaker is done) and performs the full damage assessment pass: accident fields, + capture requirements lookup, document upload (chassis/engine), part selection, + part photos, walk-around video, owner signature. The blame is marked COMPLETED + by car-capture. FileReviewer also has read access to the expert-claim panel for + claims they are reviewing. +

+ +
+

Damage assessment — v4/file-reviewer/blame-request-management/ and v5/…

+

V4 and V5 endpoints are identical — only the prefix changes.

+ + + + + + + + + + + + + + +
MethodRouteWhat it does
GETmy-filesList all files assigned to this FileReviewer.
GETmy-files/:requestIdFull detail for one file (parties, workflow, expert fields, linked claim ID).
GETclaim-id/:requestIdGet the auto-created claim ID (from FileMaker's guilty-party inquiry).
POSTaccident-fields/:requestIdStep 1 (FileReviewer): save accident fields (accidentWay, accidentReason, accidentType).
GETcapture-requirements/:claimIdStep-aware capture requirements (pre-capture docs phase vs capture-parts phase).
POSTupload-document/:claimIdUpload chassis / engine / metal-plate documents.
PATCHselect-outer-parts/:claimIdSelect outer (body) damaged parts.
PATCHselect-other-parts/:claimIdSelect other (non-body) damaged parts.
POSTcapture-part/:claimIdCapture part photos + angles for each selected damaged part.
PATCHcar-capture/:claimIdWalk-around video (final FileReviewer capture step). Claim → WAITING_FOR_DAMAGE_EXPERT, blame → COMPLETED.
PUTclaim-sign/:claimIdSubmit owner signature on expert pricing on behalf of the damaged party (agree + branchId + signature image).
POSTupload-video/:requestIdNo-op in V4/V5 — blame already COMPLETED by car-capture. Returns idempotent success.
+
+ +
+

Expert-claim panel access

+

+ FILE_REVIEWER is in the allowed roles for v2/expert-claim/. + They can view claim details and run the assign/lock flow for claims associated + with their files. They cannot initiate a damage-expert resend independently. +

+
+ + +

7 — Registrar registrar

+

+ Office-based role that files in-person blame and claim on behalf of parties. + Uses a bulk-OTP flow (both parties' OTPs sent and verified in one call each) + rather than the one-at-a-time OTP used by field experts. After blame, the + registrar mirrors the user claim API to fill part selection, documents, and + captures. The file then enters the normal damage-expert review lifecycle. +

+ +
+

Blame filing — registrar-initiated-blame/

+

Note: @ApiExcludeController — routes exist but not surfaced in Swagger docs.

+ + + + + + + + + + + + +
MethodRouteWhat it does
POSTregistrar-initiated-blame/createCreate IN_PERSON blame file.
GETregistrar-initiated-blame/my-filesList all blame files created by this registrar.
GETregistrar-initiated-blame/blame/:requestIdFull detail for one blame file.
POSTregistrar-initiated-blame/send-party-otps/:idSend OTPs to both parties simultaneously.
POSTregistrar-initiated-blame/verify-party-otps/:idVerify both parties' OTPs in one call.
POSTregistrar-initiated-blame/complete-blame-data/:idSubmit all blame form data for both parties in one payload.
POSTregistrar-initiated-blame/upload-video/:idUpload blame video.
POSTregistrar-initiated-blame/upload-voice/:idUpload voice recording.
POSTregistrar-initiated-blame/add-accident-fields/:idSave accident fields and complete blame.
POSTregistrar-initiated-blame/upload-party-signature/:idUpload a party's signature (partyRole=FIRST/SECOND).
+
+ +
+

Claim filing — v2/registrar/claim-request-management/

+

Mirror of the user claim API. Frontend reuses same claim pages by swapping prefix only.

+ + + + + + + + + + +
MethodRouteWhat it does
POSTcreate-from-blame/:blameIdCreate claim from a completed blame file.
GETouter-parts-catalog / car-other-partParts catalogs (outer body parts + other parts JSON).
GETbranches/:insuranceIdInsurer branch list (for branch selection in claim sign step).
PATCHselect-outer-parts/:claimIdSelect outer damaged parts.
PATCHselect-other-parts/:claimIdSelect other damaged parts + bank info.
POSTupload-document/:claimIdUpload claim documents (licences, car card).
POSTcapture-part/:claimIdCapture part photos + angles.
PATCHcar-capture/:claimIdWalk-around video (final step) → WAITING_FOR_DAMAGE_EXPERT.
+
+ + +

8 — Call Center call_center

+

+ Handles V6 phone-initiated blame filing. The agent collects the guilty party's + data over the phone, runs the insurance inquiry, and sends the blame link via + SMS. The user then completes the rest of the form through the standard V2 flow + (with the initial-form/inquiry step skipped). The call-center agent's job ends + after send-link; they can monitor progress via the read endpoints. +

+ +
+

Endpoints — v6/call-center-blame/

+ + + + + + + + +
MethodRouteWhat it does
POSTcreateCreate a LINK blame file. Body: { type: "THIRD_PARTY" | "CAR_BODY" }.
POSTrun-inquiry/:requestIdRun plate + national-code insurance inquiry for the guilty party. Stores result on blame document.
POSTrun-inquiry-vin/:requestIdVIN/chassis alternative to run-inquiry. Uses ESG chassis lookup.
POSTsend-link/:requestIdRegister user if needed, store as first party, send blame invite link via SMS. Body: { phoneNumber }.
GETmy-filesList all blame files started by this agent.
GETblame/:requestIdCurrent status and workflow step for one file (to check if user has opened the link and progressed).
+

+ After send-link the user completes the form via + v2/blame-request-management/ (standard V2 flow). + The initial-form / inquiry step is automatically skipped + (skipInitialFormStep=true). Downstream claim flow is the + standard V2 claim flow. +

+
+ + +

Shared: Actor Authentication

+

+ All panel actors (every role except user) authenticate through the same + POST actor/login endpoint with captcha. Password reset is via email OTP. + Profile reads and edits are also shared. +

+
+

Endpoints — actor/

+ + + + + + + + +
MethodRouteWhat it does
GETactor/captchaIssue a new login captcha challenge (returns captchaId + SVG image).
POSTactor/loginAuthenticate any actor role. Body: role, username/email/nationalCode, password, captchaId, captcha. Returns JWT access + refresh tokens.
POSTactor/forget-passwordSend password-reset OTP to email.
POSTactor/forget-password-verifyVerify OTP and set new password.
GETactor/profileGet current actor's profile.
PATCHactor/profileUpdate current actor's profile.
+
+ + +
+ +