# راهنمای فرانت‌اند برای ارسال اطلاعات استعلام

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

## پاسخ کوتاه درباره `unknown`

`unknown` فقط برای یک حالت استثنایی لازم است: وقتی در مرحله طرف زیان‌دیده یک پرونده `THIRD_PARTY`، هویت بیمه‌گذار شخص ثالث واقعاً مشخص نیست.

```json
{
  "thirdPartyPolicyholder": { "unknown": true }
}
```

قواعد آن:

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

## ساختار کلی درخواست

برای پرونده `THIRD_PARTY`:

```json
{
  "driver": {
    "nationalCode": "0012345678",
    "birthday": "1370/01/01",
    "hasDrivingLicense": true,
    "licenseNumber": "123456789",
    "licenseType": "1"
  },
  "vehicleOwner": { "sameAs": "DRIVER" },
  "thirdPartyPolicyholder": { "sameAs": "VEHICLE_OWNER" },
  "vehicle": {
    "registrationState": "CURRENT",
    "currentPlate": {
      "leftDigits": "44",
      "centerAlphabet": "ب",
      "centerDigits": "111",
      "ir": "22"
    },
    "isNewCar": false
  },
  "sheba": "IR123456789012345678901234"
}
```

برای پرونده `CAR_BODY`، نقش بیمه‌گذار بدنه هم الزامی است:

```json
{
  "driver": {
    "nationalCode": "0012345678",
    "birthday": "1370/01/01",
    "hasDrivingLicense": false
  },
  "vehicleOwner": { "sameAs": "DRIVER" },
  "thirdPartyPolicyholder": {
    "nationalCode": "0023456789",
    "birthday": "1360/02/02"
  },
  "carBodyPolicyholder": {
    "nationalCode": "0034567890",
    "birthday": "1350/03/03"
  },
  "vehicle": {
    "currentPlate": {
      "leftDigits": "44",
      "centerAlphabet": "ب",
      "centerDigits": "111",
      "ir": "22"
    },
    "isNewCar": false
  },
  "sheba": "IR123456789012345678901234"
}
```

`sheba` فقط در routeهایی که قبلاً اطلاعات بانکی را در مرحله استعلام دریافت می‌کردند ارسال می‌شود؛ در V6 مرکز تماس، شماره شبا در این body نیست و بعداً توسط کاربر دریافت می‌شود.

## هر استعلام با اطلاعات کدام نقش انجام می‌شود؟

فرانت‌اند فقط اشخاص را با ساختار نقش‌محور ارسال می‌کند؛ انتخاب کد ملی مناسب برای هر سرویس در بک‌اند انجام می‌شود:

| استعلام | کد ملی مورد استفاده | شناسه خودرو/بانکی |
| --- | --- | --- |
| بیمه شخص ثالث با پلاک یا VIN | `thirdPartyPolicyholder.nationalCode` | پلاک یا `vehicle.vin` |
| بیمه بدنه با پلاک یا VIN | `carBodyPolicyholder.nationalCode` | پلاک یا `vehicle.vin` |
| تطبیق شبا | `vehicleOwner.nationalCode` | `sheba` |
| گواهینامه | `driver.nationalCode` | `driver.licenseNumber` |

بنابراین کد ملی راننده نباید به‌جای بیمه‌گذار یا مالک ارسال یا تکرار شود. اگر چند نقش متعلق به یک نفر است، `sameAs` ارتباط را مشخص می‌کند و بک‌اند همان شخص را برای استعلام مربوط به هر نقش انتخاب می‌کند.

در مرحله بانکی بعدی جریان V6، برای پرونده‌های جدید فقط `sheba` لازم است. بک‌اند کد ملی مالک خودرو را از `participants` و `participantRoles` ذخیره‌شده در پرونده تقصیر می‌خواند. فیلدهای قدیمی `nationalCodeOfInsurer` یا `nationalCodeOfOwner` فقط برای پرونده‌های تاریخی فاقد اطلاعات نقش‌محور fallback هستند؛ اگر همراه پرونده جدید ارسال شوند باید با مالک ذخیره‌شده یکسان باشند.

پنل‌های کارشناسی اطلاعات کامل اشخاص را در `parties[].participants` و نگاشت نقش‌ها را در `parties[].participantRoles` دریافت می‌کنند. اطلاعات راننده حتی اگر در استعلام بیمه یا شبا استفاده نشود در همین ساختار ذخیره و نمایش داده می‌شود.

## نقش‌ها و فیلدهای هر شخص

هر نقش باید یکی از این دو حالت را داشته باشد، نه هر دو را:

1. اطلاعات یک شخص جدید؛ یا
2. ارجاع با `sameAs` به شخصی که قبلاً در همین درخواست معرفی شده است.

| فیلد | کاربرد | وضعیت |
| --- | --- | --- |
| `nationalCode` | کد ملی شخص | برای شخص جدید الزامی |
| `birthday` | تاریخ تولد جلالی | برای شخص جدید الزامی |
| `fullName` | نام نمایشی شخص | اختیاری |
| `sameAs` | اتصال این نقش به نقش دیگر | به‌جای اطلاعات شخص جدید |
| `unknown` | نامشخص بودن بیمه‌گذار ثالث | فقط `SECOND` در `THIRD_PARTY` |
| `hasDrivingLicense` | داشتن گواهینامه راننده | برای نقش راننده الزامی |
| `licenseNumber` | شماره گواهینامه | اگر `hasDrivingLicense=true` الزامی |
| `licenseType` | نوع گواهینامه | اگر `hasDrivingLicense=true` الزامی |

مقادیر مجاز `sameAs` عبارت‌اند از:

- `DRIVER`
- `VEHICLE_OWNER`
- `THIRD_PARTY_POLICYHOLDER`
- `CAR_BODY_POLICYHOLDER`

برای `sameAs` هیچ‌کدام از `nationalCode`، `birthday`، `fullName`، اطلاعات گواهینامه یا `phoneNumber` را در همان آبجکت نفرستید.

شماره تلفن بخشی از هویت استعلام نیست و در این DTOها وجود ندارد. احراز هویت پیامکی و شماره تماس طرفین از این مرحله جداست.

## اطلاعات خودرو و پلاک

| فیلد | کاربرد | وضعیت |
| --- | --- | --- |
| `vehicle.registrationState` | وضعیت ثبت رسمی خودرو | `CURRENT` یا `RECENTLY_TRANSFERRED`؛ پیش‌فرض `CURRENT` |
| `vehicle.currentPlate` | پلاک رسمی فعلی و شناسه اصلی خودرو | الزامی |
| `vehicle.previousPlate` | پلاک قبلی در انتقال اخیر | فقط در `RECENTLY_TRANSFERRED` |
| `vehicle.vin` | شماره شاسی/VIN | در انتقال اخیر الزامی؛ حداکثر ۱۷ کاراکتر |
| `vehicle.isNewCar` | نو بودن خودرو | اختیاری |

اجزای پلاک:

```json
{
  "leftDigits": "44",
  "centerAlphabet": "ب",
  "centerDigits": "111",
  "ir": "22"
}
```

`leftDigits`، `centerDigits` و `ir` را می‌توان به‌صورت string یا number فرستاد؛ ارسال string پیشنهاد می‌شود تا صفرهای ابتدایی از بین نروند. `centerAlphabet` باید حرف فارسی پلاک باشد.

### انتقال اخیر

```json
{
  "vehicle": {
    "registrationState": "RECENTLY_TRANSFERRED",
    "currentPlate": {
      "leftDigits": "44",
      "centerAlphabet": "ب",
      "centerDigits": "111",
      "ir": "22"
    },
    "previousPlate": {
      "leftDigits": "55",
      "centerAlphabet": "ج",
      "centerDigits": "222",
      "ir": "33"
    },
    "vin": "NAAM01E15HK123456"
  }
}
```

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

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

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

1. پلاک فعلی و وضعیت انتقال خودرو را بگیرید.
2. اگر انتقال اخیر بود، پلاک قبلی و VIN را بگیرید.
3. اطلاعات راننده و وضعیت گواهینامه را بگیرید.
4. بپرسید مالک خودرو همان راننده است یا شخص دیگری؛ در حالت یکسان از `sameAs` استفاده کنید.
5. بیمه‌گذار شخص ثالث را از بین راننده، مالک یا شخص دیگر انتخاب کنید.
6. در `CAR_BODY` همین کار را برای بیمه‌گذار بدنه انجام دهید.
7. خلاصه اطلاعات را به کاربر نشان دهید و سپس درخواست استعلام را ارسال کنید.

## مسیرهای اصلی

بدنه درخواست در همه این مسیرها همین ساختار را دارد:

| جریان | مسیر پلاک | مسیر VIN |
| --- | --- | --- |
| کاربر V2 | `/v2/blame-request-management/initial-form/:requestId` | `/v2/blame-request-management/initial-form-vin/:requestId` |
| کارشناس/پرونده‌ساز 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` مجاز است یا نه.

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

این فیلدها دیگر بخشی از قرارداد ورودی نیستند و ارسال آن‌ها باعث خطای اعتبارسنجی می‌شود:

```text
nationalCodeOfDriver
driverBirthday
driverLicense
licenseType                 // در سطح بالا؛ مقدار صحیح داخل driver است
nationalCodeOfInsurer
insurerBirthday
insurerLicense
driverIsInsurer
userNoCertificate
plate                       // در سطح بالا؛ مقدار صحیح داخل vehicle.currentPlate است
plateId
vin                         // در سطح بالا؛ مقدار صحیح داخل vehicle.vin است
isNewCar                    // در سطح بالا؛ مقدار صحیح داخل vehicle.isNewCar است
phoneNumber                 // در participantها
```

## خطاهای رایج فرانت‌اند

- ارسال `vehicleOwner` به‌صورت خالی؛ باید شخص جدید یا `sameAs` باشد.
- استفاده از `sameAs` همراه با `nationalCode` یا `birthday`.
- ارسال `carBodyPolicyholder` برای `THIRD_PARTY`.
- ارسال `unknown` برای طرف مقصر یا برای نقشی غیر از بیمه‌گذار ثالث.
- فرستادن `previousPlate` بدون `registrationState=RECENTLY_TRANSFERRED`.
- فرستادن `RECENTLY_TRANSFERRED` بدون `previousPlate` یا `vin`.
- قرار دادن VIN یا پلاک در سطح بالای body.
- ارسال شماره تلفن در آبجکت شخص.
- تکرار کد ملی راننده یا بیمه‌گذار در مرحله شبا؛ تطبیق شبا همیشه با مالک خودرو انجام می‌شود.

مستند مدل دامنه و جزئیات تصمیم معماری در [inquiry-participants-proposal.fa.md](./inquiry-participants-proposal.fa.md) قرار دارد.