Completed DOCS for participants

2026-09-16 10:24:22 +03:30
parent 8173764913
commit dc30518a7f
3 changed files with 34 additions and 34 deletions
--- a/docs/inquiry-participants-frontend-guide.fa.md
+++ b/docs/inquiry-participants-frontend-guide.fa.md
@@ -2,25 +2,6 @@

 این سند قرارداد نهایی فرانت‌اند برای مرحله استعلام است. از این به بعد اطلاعات اشخاص و خودرو باید با ساختار نقش‌محور زیر ارسال شود. فیلدهای تخت قدیمی مانند `nationalCodeOfDriver` و `nationalCodeOfInsurer` دیگر ورودی معتبر نیستند.

-## پاسخ کوتاه درباره `unknown`
-
-`unknown` فقط برای یک حالت استثنایی لازم است: وقتی در مرحله طرف زیان‌دیده یک پرونده `THIRD_PARTY`، هویت بیمه‌گذار شخص ثالث واقعاً مشخص نیست.
-
-```json
-{
-  "thirdPartyPolicyholder": { "unknown": true }
-}
-```
-
-قواعد آن:
-
- فقط برای طرف زیان‌دیده (`SECOND`) مجاز است؛ برای طرف مقصر (`FIRST`) خطا برمی‌گردد.
- فقط برای `thirdPartyPolicyholder` مجاز است؛ برای راننده، مالک یا بیمه‌گذار بدنه مجاز نیست.
- وقتی `unknown: true` ارسال می‌شود، هیچ فیلد هویتی دیگری در همان آبجکت نفرستید.
- در استعلام شخص ثالث با پلاک یا VIN، استعلام بیمه‌گذار عمداً skip می‌شود و سیستم نباید کد ملی راننده یا مالک را جایگزین کند.
- استعلام‌های راننده، مالکیت خودرو و اطلاعات افراد شناخته‌شده همچنان اجرا می‌شوند.
- اگر هویت بیمه‌گذار مشخص است، اصلاً از `unknown` استفاده نکنید و اطلاعات واقعی یا `sameAs` را بفرستید.
-
 ## ساختار کلی درخواست

 برای پرونده `THIRD_PARTY`:
@@ -113,7 +94,6 @@
 | `birthday` | تاریخ تولد جلالی | برای شخص جدید الزامی |
 | `fullName` | نام نمایشی شخص | اختیاری |
 | `sameAs` | اتصال این نقش به نقش دیگر | به‌جای اطلاعات شخص جدید |
-| `unknown` | نامشخص بودن بیمه‌گذار ثالث | فقط `SECOND` در `THIRD_PARTY` |
 | `hasDrivingLicense` | داشتن گواهینامه راننده | برای نقش راننده الزامی |
 | `licenseNumber` | شماره گواهینامه | اگر `hasDrivingLicense=true` الزامی |
 | `licenseType` | نوع گواهینامه | اگر `hasDrivingLicense=true` الزامی |
@@ -136,7 +116,8 @@
 | `vehicle.registrationState` | وضعیت ثبت رسمی خودرو | `CURRENT` یا `RECENTLY_TRANSFERRED`؛ پیش‌فرض `CURRENT` |
 | `vehicle.currentPlate` | پلاک رسمی فعلی و شناسه اصلی خودرو | الزامی |
 | `vehicle.previousPlate` | پلاک قبلی در انتقال اخیر | فقط در `RECENTLY_TRANSFERRED` |
-| `vehicle.vin` | شماره شاسی/VIN | در انتقال اخیر الزامی؛ حداکثر ۱۷ کاراکتر |
+| `vehicle.previousPolicyholderNationalCode` | کد ملی بیمه‌گذار مربوط به پلاک قبلی | فقط در `RECENTLY_TRANSFERRED` و الزامی |
+| `vehicle.vin` | شماره شاسی/VIN | در انتقال اخیر الزامی؛ در صورت ارسال دقیقاً ۱۷ کاراکتر |
 | `vehicle.isNewCar` | نو بودن خودرو | اختیاری |

 اجزای پلاک:
@@ -170,19 +151,20 @@
      "centerDigits": "222",
      "ir": "33"
    },
+    "previousPolicyholderNationalCode": "0098765432",
    "vin": "NAAM01E15HK123456"
  }
 }
 ```

-سیستم ابتدا پلاک فعلی را استعلام می‌کند. اگر نتیجه ناموجود، منقضی یا فاقد بیمه‌نامه مرتبط باشد، پلاک قبلی را امتحان می‌کند. نتیجه پلاک قبلی فقط در صورت تطبیق VIN پذیرفته می‌شود؛ پلاک قبلی هرگز جایگزین پلاک فعلی نمی‌شود.
+سیستم ابتدا پلاک فعلی را با کد ملی بیمه‌گذار فعلیِ مرتبط با نوع بیمه استعلام می‌کند. اگر نتیجه ناموجود، منقضی یا فاقد بیمه‌نامه مرتبط باشد، پلاک قبلی را با `previousPolicyholderNationalCode` امتحان می‌کند. نتیجه پلاک قبلی فقط در صورت تطبیق VIN پذیرفته می‌شود؛ پلاک قبلی هرگز جایگزین پلاک فعلی نمی‌شود.

 حتی در route مربوط به VIN، آبجکت `vehicle` از قرارداد مشترک استفاده می‌کند و `currentPlate` در قرارداد فعلی الزامی است. مقدار VIN در `vehicle.vin` قرار می‌گیرد، نه در فیلد سطح بالای `vin`.

 ## ترتیب پیشنهادی نمایش فرم

 1. پلاک فعلی و وضعیت انتقال خودرو را بگیرید.
-2. اگر انتقال اخیر بود، پلاک قبلی و VIN را بگیرید.
+2. اگر انتقال اخیر بود، پلاک قبلی، کد ملی بیمه‌گذار پلاک قبلی و VIN را بگیرید.
 3. اطلاعات راننده و وضعیت گواهینامه را بگیرید.
 4. بپرسید مالک خودرو همان راننده است یا شخص دیگری؛ در حالت یکسان از `sameAs` استفاده کنید.
 5. بیمه‌گذار شخص ثالث را از بین راننده، مالک یا شخص دیگر انتخاب کنید.
@@ -199,7 +181,19 @@
 | کارشناس/پرونده‌ساز V3 تا V5 | `.../run-inquiries/:requestId` | `.../run-inquiries-vin/:requestId` |
 | مرکز تماس V6 | `/v6/call-center-blame/run-inquiry/:requestId` | `/v6/call-center-blame/run-inquiry-vin/:requestId` |

-در جریان‌های V3 تا V5، فراخوان اول برای طرف مقصر (`FIRST`) و فراخوان دوم، فقط در `THIRD_PARTY`، برای طرف زیان‌دیده (`SECOND`) است. همین تفاوت تعیین می‌کند که `unknown` مجاز است یا نه.
+در جریان‌های V3 تا V5، فراخوان اول برای طرف مقصر (`FIRST`) و فراخوان دوم، فقط در `THIRD_PARTY`، برای طرف زیان‌دیده (`SECOND`) است. اطلاعات بیمه‌گذار برای هر دو طرف الزامی است.
+
+## تفاوت اطلاعات مقصر و زیان‌دیده
+
+ساختار نقش‌محور اشخاص و خودرو برای هر دو طرف یکسان است، اما ترتیب و قواعد کسب‌وکار آن‌ها تفاوت دارد:
+
+| پرونده و طرف | نقش‌ها و رفتار |
+| --- | --- |
+| `THIRD_PARTY / FIRST` (مقصر) | راننده، مالک و بیمه‌گذار شخص ثالثِ خودروی مقصر ارسال می‌شوند. شبا در این فراخوان لازم نیست. بیمه‌نامه مقصر باید متعلق به شرکت بیمه همین سامانه باشد. |
+| `THIRD_PARTY / SECOND` (زیان‌دیده) | راننده، مالک و بیمه‌گذار شخص ثالثِ خودروی زیان‌دیده ارسال می‌شوند. این مرحله فقط بعد از امضای مقصر و احراز OTP زیان‌دیده اجرا می‌شود. `sheba` الزامی است و با کد ملی `vehicleOwner` اعتبارسنجی می‌شود. بیمه‌گذار زیان‌دیده نیز همیشه باید مشخص باشد. |
+| `CAR_BODY / FIRST` (بیمه‌گذار/زیان‌دیده بدنه) | هر چهار نقش راننده، مالک، بیمه‌گذار شخص ثالث و بیمه‌گذار بدنه ارسال می‌شوند. `sheba` در همین فراخوان الزامی است و با کد ملی `vehicleOwner` اعتبارسنجی می‌شود. استعلام بدنه با کد ملی `carBodyPolicyholder` انجام می‌شود. |
+
+در V2 و V6 که شبا در مرحله جداگانه از کاربر دریافت می‌شود، شبا داخل درخواست استعلام مقصر ارسال نمی‌شود؛ بک‌اند هنگام مرحله بانکی آن را با کد ملی مالک ذخیره‌شده تطبیق می‌دهد.

 ## فیلدهایی که نباید ارسال شوند

@@ -220,6 +214,7 @@ plateId
 vin                         // در سطح بالا؛ مقدار صحیح داخل vehicle.vin است
 isNewCar                    // در سطح بالا؛ مقدار صحیح داخل vehicle.isNewCar است
 phoneNumber                 // در participantها
+unknown                     // حذف شده؛ بیمه‌گذار همیشه باید مشخص باشد
 ```

 ## خطاهای رایج فرانت‌اند
@@ -227,9 +222,10 @@ phoneNumber                 // در participantها
 - ارسال `vehicleOwner` به‌صورت خالی؛ باید شخص جدید یا `sameAs` باشد.
 - استفاده از `sameAs` همراه با `nationalCode` یا `birthday`.
 - ارسال `carBodyPolicyholder` برای `THIRD_PARTY`.
- ارسال `unknown` برای طرف مقصر یا برای نقشی غیر از بیمه‌گذار ثالث.
+- ارسال `unknown` برای هر نقش؛ این فیلد دیگر پذیرفته نمی‌شود.
 - فرستادن `previousPlate` بدون `registrationState=RECENTLY_TRANSFERRED`.
- فرستادن `RECENTLY_TRANSFERRED` بدون `previousPlate` یا `vin`.
+- فرستادن `RECENTLY_TRANSFERRED` بدون `previousPlate`، `previousPolicyholderNationalCode` یا `vin`.
+- فرستادن `previousPolicyholderNationalCode` برای خودروی دارای وضعیت `CURRENT`.
 - قرار دادن VIN یا پلاک در سطح بالای body.
 - ارسال شماره تلفن در آبجکت شخص.
 - تکرار کد ملی راننده یا بیمه‌گذار در مرحله شبا؛ تطبیق شبا همیشه با مالک خودرو انجام می‌شود.