fanavaran sales integration docs

2026-08-08 15:53:35 +03:30
parent 91028f999c
commit 5a4a511e84
13 changed files with 1429 additions and 0 deletions
--- a/docs/fanavaran/05-claim-flow.md
+++ b/docs/fanavaran/05-claim-flow.md
@@ -0,0 +1,130 @@
+---
+last_updated: 2026-08-08
+tags: [fanavaran, flow, sequence]
+source: fanavaran-module-docs
+---
+
+# 05 — Full claim registration flow
+
+Applies to **THIRD_PARTY** claims only. Template behavior = **Parsian**.
+
+## High-level stages
+
+```text
+Start local claim
+  → Validate THIRD_PARTY + data readiness
+  → Auth (cached token)
+  → Policy inquiry (resolve-once PolicyId)
+  → GEN.03 base claim → store claimId / claimNo → SMS owner
+  → SELECT_OUTER_PARTS
+  → GEN.12 damage case → store dmgCaseId
+  → Upload docs/images locally
+  → GEN.07 attachments (per file, best-effort)
+  → Expert pricing ready
+  → GEN.08 expertise → store expertiseId
+  → End (local completion independent of Fanavaran success)
+```
+
+## Sequence diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant User as User / Expert
+  participant YARA as YARA ClaimRequestManagement
+  participant Auth as FanavaranAuthService
+  participant FV as Fanavaran API
+  participant DB as Mongo claimCases
+
+  User->>YARA: Create THIRD_PARTY claim
+  YARA->>DB: Persist claimCase
+  YARA->>YARA: autoSubmitToFanavaranV2OnClaimCreated
+
+  YARA->>Auth: getAuthenticationToken(client)
+  alt cache miss / past Tehran midnight
+    Auth->>FV: POST GetAppToken
+    Auth->>FV: POST Login
+    Auth->>DB: fanavaranAuthTokens
+  end
+  Auth-->>YARA: authenticationToken
+
+  alt no cached policyId
+    YARA->>FV: GET inquiry-my-policies
+    YARA->>DB: fanavaranSync.baseClaim.policyId
+  end
+
+  YARA->>FV: POST third-party-car-financial-claims (GEN.03)
+  FV-->>YARA: Id, ClaimNo
+  YARA->>DB: claimId, claimNo, history SUCCESS
+  YARA->>YARA: SMS owner (deduped)
+
+  User->>YARA: SELECT_OUTER_PARTS
+  YARA->>YARA: autoSubmitFanavaranDamageCase...
+  Note over YARA: soft-ensure base if missing
+  YARA->>FV: POST .../dmg-cases (GEN.12)
+  FV-->>YARA: DmgCaseId
+  YARA->>DB: dmgCaseId
+
+  User->>YARA: Upload images/docs
+  loop each image not yet uploaded
+    YARA->>FV: POST .../files multipart (GEN.07)
+    YARA->>DB: attachments.files[]
+  end
+
+  User->>YARA: Expert reply priced
+  YARA->>YARA: autoSubmitFanavaranExpertise...
+  Note over YARA: soft-ensure damage/base
+  YARA->>FV: POST .../expertise (GEN.08)
+  FV-->>YARA: ExpertiseId
+  YARA->>DB: expertiseId, history SUCCESS
+```
+
+## Flow diagram (stages + soft-ensure)
+
+```mermaid
+flowchart TD
+  A[Local claim created THIRD_PARTY] --> B{claimId exists?}
+  B -->|No| C[GEN.03 Base claim]
+  B -->|Yes| D[Skip base]
+  C --> E[Store claimId/claimNo]
+  E --> F[Outer parts selected]
+  D --> F
+  F --> G{dmgCaseId exists?}
+  G -->|No| H[Ensure base then GEN.12]
+  G -->|Yes| I[Skip damage]
+  H --> J[Store dmgCaseId]
+  J --> K[Local media upload]
+  I --> K
+  K --> L[GEN.07 per file]
+  L --> M[Expert pricing ready]
+  M --> N{expertiseId exists?}
+  N -->|No| O[Ensure damage then GEN.08]
+  N -->|Yes| P[Done]
+  O --> P
+```
+
+## Local triggers
+
+| Stage | Auto trigger | Function |
+|-------|--------------|----------|
+| Base | Claim create (early) | `autoSubmitToFanavaranV2OnClaimCreated` |
+| Base | Claim completed (legacy/fallback; skips if already submitted) | `autoSubmitToFanavaranV2OnClaimCompleted` |
+| Damage | After outer parts selection | `autoSubmitFanavaranDamageCaseOnOuterPartsSelected` |
+| Attachments | After successful local image/doc upload | `autoSubmitFanavaranAttachment` |
+| Expertise | After expert reply when priced | `autoSubmitFanavaranExpertiseOnExpertReply` |
+
+V5 note: when `requiresFileMakerApproval=true`, Fanavaran submit may wait for FileMaker approval per claim flow rules.
+
+## Manual retry
+
+Use `/v2/fanavaran/{client}/claim-cases/{claimCaseId}/.../submit` for any failed stage. Preview endpoints build payload without requiring submit success.
+
+## Status persistence
+
+Per stage under `claimCases.fanavaranSync.{baseClaim|damageCase|attachments|expertise}`:
+
+- `status`: success / failed / pending / skipped
+- `lastError`, `lastTriedAt`, `retryCount`, `nextRetryAt`
+- Cached ids + `lastPayload`
+
+Top-level: `claimId`, `claimNo`, `dmgCaseId`, `expertiseId`.