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/README.md
+++ b/docs/fanavaran/README.md
@@ -0,0 +1,99 @@
+---
+last_updated: 2026-08-08
+tags: [fanavaran, documentation, parsian, third-party-claim]
+source: fanavaran-module-docs
+---
+
+# Fanavaran Integration — Technical Reference
+
+مرجع فنی یکپارچه‌سازی یارا با سرویس‌های فناوران برای ثبت خسارت مالی ثالث خودرو.
+
+**Template tenant:** `parsian` (proven end-to-end, 2026-08-03 — claim `CL68535` / publicId `A00153`)  
+**Also configured:** `tejaratno` (production shape), `moallem` (auth seeded; expert/file-type ids TBD)
+
+## Goals
+
+1. Document every Fanavaran API used in claim registration
+2. Clarify per-insurer dependencies
+3. Identify reusable pieces
+4. Map YARA ↔ Fanavaran integration points
+5. Enable onboarding a new insurer from this docs set alone
+
+## Document index
+
+| # | Document | Covers |
+|---|----------|--------|
+| 1 | [01-write-apis.md](./01-write-apis.md) | Auth + GEN.03 / GEN.12 / GEN.07 / GEN.08 write APIs |
+| 2 | [02-read-apis-lookups.md](./02-read-apis-lookups.md) | Policy inquiry, driver inquiry, lookups |
+| 3 | [03-constants.md](./03-constants.md) | Shared vs tenant constants |
+| 4 | [04-tenant-matrix.md](./04-tenant-matrix.md) | Shared ✅ / tenant-specific ✅ matrix |
+| 5 | [05-claim-flow.md](./05-claim-flow.md) | Full claim flow + sequence diagrams |
+| 6 | [06-yara-integration.md](./06-yara-integration.md) | Module / service / controller / function map |
+| 7 | [07-data-mapping.md](./07-data-mapping.md) | YARA field → Fanavaran field |
+| 8 | [08-dependencies.md](./08-dependencies.md) | Mongo, files, env, SMS, audit |
+| 9 | [09-error-handling.md](./09-error-handling.md) | Errors, retry, backoff, logging |
+| 10 | [10-testing.md](./10-testing.md) | Test scenarios, scripts, proven case |
+| 11 | [11-onboard-new-client.md](./11-onboard-new-client.md) | Checklist to add a new insurer |
+
+## Related sources (code)
+
+| Path | Role |
+|------|------|
+| `src/core/config/fanavaran-client.config.ts` | Tenant keys, seed auth + defaults |
+| `src/fanavaran/` | Auth, lookup, audit, YARA HTTP surface |
+| `src/claim-request-management/claim-request-management.service.ts` | Payload build + staged submit orchestration |
+| `src/claim-request-management/fanavaran-policy-selection.ts` | Latest active policy selection |
+| `src/lookups/` | Local lookup HTTP façade over Fanavaran |
+| `.agents/skills/fanavaran-apis/references/third-party-cases.md` | Agent-oriented implementation rules |
+| `docs/external-api-curls.md` | Ready-to-run curl sequences |
+| `scripts/fanavaran-auth.sh` | Token helper |
+
+## Architecture (one glance)
+
+```text
+YARA claim flow (THIRD_PARTY only)
+  │
+  ├─ auto / manual stage triggers
+  │
+  ▼
+ClaimRequestManagementService
+  ├─ FanavaranAuthService          (GetAppToken → Login, cache until Tehran midnight)
+  ├─ FanavaranLookupService        (lookups + insurance-corp resolve)
+  ├─ FanavaranAuditService         (fanavaranAuditLogs)
+  └─ FanavaranClientConfigService  (Mongo fanavaranClientConfigs)
+  │
+  ▼
+Fanavaran API Manager
+  https://apimanager.iraneit.com/BimeApiManager/api
+```
+
+## Stages (order)
+
+| Stage | Fanavaran doc | Local ids stored |
+|-------|---------------|------------------|
+| Auth | EITAuthentication | token cache (`fanavaranAuthTokens`) |
+| Policy inquiry | inquiry-my-policies | `fanavaranSync.baseClaim.policyId` |
+| Base claim | GEN.03 | `claimId`, `claimNo` |
+| Damage case | GEN.12 | `dmgCaseId`, `driverId`, … |
+| Attachments | GEN.07 | `fanavaranSync.attachments.files[]` |
+| Expertise | GEN.08 | `expertiseId` |
+
+Soft-ensure: later stages create earlier ones if missing (damage → base; expertise → damage → base).
+
+## Secrets policy
+
+This documentation **does not** embed live secrets. Auth values (`appName`, `secret`, `username`, `password`) live in:
+
+1. Mongo collection `fanavaranClientConfigs` (runtime source of truth after boot seed)
+2. Seed fallback: `SEED_FANAVARAN_CLIENT_PROFILES` in `fanavaran-client.config.ts`
+
+Use `scripts/fanavaran-auth.sh <client>` or System Settings admin APIs to inspect/update tenant config.
+
+## Activate a tenant
+
+```bash
+FANAVARAN_CLIENT=parsian   # or tejaratno | moallem
+INSURANCE_CORP_ID='...'    # Persian caption matching Fanavaran insurance-corp lookup
+```
+
+Optional: `CLIENT_ID=8` maps to `parsian` when `FANAVARAN_CLIENT` is unset.