fanavaran sales integration docs

docs/fanavaran/06-yara-integration.md

@@ -0,0 +1,140 @@
+---
+last_updated: 2026-08-08
+tags: [fanavaran, yara, integration]
+source: fanavaran-module-docs
+---
+
+# 06 — YARA ↔ Fanavaran integration points
+
+## Module map
+
+| Concern | Module | Primary files |
+|---------|--------|---------------|
+| HTTP surface | `FanavaranModule` | `fanavaran.controller.ts` |
+| Auth | `FanavaranModule` | `fanavaran-auth.service.ts` |
+| Lookups | `FanavaranLookupModule` / `LookupsModule` | `fanavaran-lookup.service.ts`, `lookups.*` |
+| Audit | `FanavaranAuditModule` | `fanavaran-audit.service.ts` |
+| Tenant config | boot + System Settings | `fanavaran-client-config.service.ts`, `system-settings.*` |
+| Orchestration | `ClaimRequestManagementModule` | `claim-request-management.service.ts` |
+| Policy select | same | `fanavaran-policy-selection.ts` |
+| SMS after base | `SmsOrchestrationModule` | `sms-orchestration.service.ts` |
+
+---
+
+## Interaction catalogue
+
+### A. Authentication
+
+| | |
+|--|--|
+| Module | `src/fanavaran` |
+| Service | `FanavaranAuthService` |
+| Controller | *(none external — used by claim/lookup)* |
+| Functions | `getAuthenticationToken`, GetAppToken + Login internals |
+| When | Before any Fanavaran business/lookup HTTP |
+| Send | appname/secret → appToken → username/password |
+| Receive | `authenticationToken` |
+| Store | Memory cache + `fanavaranAuthTokens` |
+| Consumers | Claim submit, lookups, policy inquiry |
+
+### B. Base claim preview/submit
+
+| | |
+|--|--|
+| Module | Fanavaran + ClaimRequestManagement |
+| Controller | `FanavaranController.preview` / `submit` |
+| Service | `ClaimRequestManagementService` |
+| Functions | `previewFanavaranSubmitV2`, `submitFanavaranV2`, `executeFanavaranV2Submit`, `buildFanavaranSubmitPayload`, `getPolicyIdFromNationalCode` |
+| When | Auto on claim create; manual preview/submit |
+| Send | GEN.03 JSON + business headers |
+| Receive | `Id`, `ClaimNo` |
+| Store | `claimId`, `claimNo`, `fanavaranSync.baseClaim.*`, history |
+| Consumers | Damage/expertise soft-ensure; UI claim detail; SMS |
+
+### C. Damage case
+
+| | |
+|--|--|
+| Controller | `previewDamageCase` / `submitDamageCase` |
+| Functions | `previewFanavaranDamageCaseV2`, `submitFanavaranDamageCaseV2`, `buildFanavaranDamageCasePayload`, `autoSubmitFanavaranDamageCaseOnOuterPartsSelected`, `ensureFanavaranBaseClaim` |
+| When | After outer parts selected; soft-ensure from later stages |
+| Send | GEN.12 JSON |
+| Receive | `Id` → `dmgCaseId` |
+| Store | `dmgCaseId`, `fanavaranSync.damageCase.{driverId,vehicleKindId,insuranceCorpId,lastPayload}` |
+| Consumers | Expertise payload (`DmgCaseId`) |
+
+### D. Attachments
+
+| | |
+|--|--|
+| Controller | `previewAttachments` / `submitAttachments` |
+| Functions | `previewFanavaranAttachmentsV2`, `submitFanavaranAttachmentsV2`, `autoSubmitFanavaranAttachment` |
+| When | After local required-doc / capture upload |
+| Send | multipart GEN.07 |
+| Receive | file metadata / ids |
+| Store | `fanavaranSync.attachments.files[]` |
+| Consumers | Manual retry of missing uploads |
+
+### E. Expertise
+
+| | |
+|--|--|
+| Controller | `previewExpertise` / `submitExpertise` |
+| Functions | `previewFanavaranExpertiseV2`, `submitFanavaranExpertiseV2`, `buildFanavaranExpertisePayload`, `autoSubmitFanavaranExpertiseOnExpertReply`, `ensureFanavaranDamageCase` |
+| When | Expert reply priced / factor validated |
+| Send | GEN.08 JSON |
+| Receive | `Id` → `expertiseId` |
+| Store | `expertiseId`, `fanavaranSync.expertise.*` |
+| Consumers | Claim completion reporting / history |
+
+### F. Lookups (read)
+
+| | |
+|--|--|
+| Controller | `LookupsController` |
+| Service | `LookupsService` → `FanavaranLookupService` |
+| When | UI dropdowns; cold cache; payload id resolution |
+| Store | `files/fanavaran-lookups/{client}/*.json` |
+
+### G. Tenant config admin
+
+| | |
+|--|--|
+| Module | System Settings |
+| Service | `SystemSettingsService` / `FanavaranClientConfigService` |
+| When | Boot seed missing keys; admin update |
+| Store | `fanavaranClientConfigs` → in-memory cache via `setFanavaranClientProfilesCache` |
+
+### H. Claim create call sites (auto base)
+
+`autoSubmitToFanavaranV2OnClaimCreated` is invoked from claim creation paths inside `ClaimRequestManagementService` (registrar / expert-initiated / v2 create flows — search call sites ~7717, 7839, 8141, 8243).
+
+Outer parts selection invokes damage auto-submit (~8422).  
+Document/capture upload hooks call attachment auto-submit (~9496+).  
+Expert reply path calls expertise auto-submit (~10576).
+
+---
+
+## Controllers summary
+
+| Controller | Fanavaran-related routes |
+|------------|--------------------------|
+| `FanavaranController` | All `/v2/fanavaran/*` preview/submit |
+| `LookupsController` | `/lookups/*` Fanavaran-backed reads |
+| Claim V2 / registrar / expert mirrors | Create/select/upload that **trigger** auto-submit (no direct Fanavaran URL) |
+
+---
+
+## Data written by Fanavaran stages
+
+| Field path | Stage |
+|------------|-------|
+| `claimCases.claimId` / `claimNo` | GEN.03 |
+| `claimCases.dmgCaseId` | GEN.12 |
+| `claimCases.expertiseId` | GEN.08 |
+| `claimCases.fanavaranSync.*` | All |
+| `claimCases.history[]` | Success/fail events |
+| `blameCases.parties[].person.fanavaranDriverId` | GEN.12 driver resolve |
+| `fanavaranAuditLogs` | Every real HTTP step |
+| `fanavaranAuthTokens` | Auth cache |
+| `fanavaranClientConfigs` | Tenant profiles |