fanavaran sales integration docs

docs/fanavaran/11-onboard-new-client.md

@@ -0,0 +1,76 @@
+---
+last_updated: 2026-08-08
+tags: [fanavaran, onboarding, checklist]
+source: fanavaran-module-docs
+---
+
+# 11 — Onboard a new insurance client
+
+Use **Parsian** as the behavioral template. API shapes stay the same; only tenant config + lookup ids change.
+
+## Checklist
+
+### 1. Register tenant key
+
+- [ ] Add key to `FanavaranClientKey` / `FANAVARAN_CLIENT_KEYS` in `fanavaran-client.config.ts`
+- [ ] Add `SEED_FANAVARAN_CLIENT_PROFILES[key]` with auth + defaults
+- [ ] Boot app once so `FanavaranClientConfigService` seeds Mongo if missing
+
+### 2. Auth verification
+
+- [ ] `scripts/fanavaran-auth.sh <key>` succeeds
+- [ ] Login returns `authenticationToken`
+- [ ] Business call with CorpId/ContractId/Location succeeds (any small lookup)
+
+### 3. Warm lookups
+
+- [ ] Fetch `file-types`, `vehicle-kinds`, `insurance-corp`, `car-components`, `inspection-place`, `accident-level`, expert-related lists
+- [ ] Confirm cache under `files/fanavaran-lookups/<key>/`
+
+### 4. Choose tenant-specific ids
+
+| Field | How to pick |
+|-------|-------------|
+| `ClaimExpertId` (GEN.03) | Financial case owner role for that insurer |
+| `ExpertiseClaimExpertId` (GEN.08) | Assessor role — **different** from GEN.03 |
+| `ClaimFileTypeId` | Must exist in **that** tenant’s `file-types.json` |
+| Shared codebook defaults | Start from `SHARED_FANAVARAN_DEFAULTS`; override if Fanavaran rejects |
+
+### 5. Deploy env
+
+```bash
+FANAVARAN_CLIENT=<key>
+INSURANCE_CORP_ID='<exact Caption from insurance-corp lookup>'
+```
+
+### 6. Dry-run on a test claim
+
+- [ ] Preview base → PolicyId resolves
+- [ ] Submit base → `claimId`/`claimNo`
+- [ ] Outer parts → `dmgCaseId`
+- [ ] Upload → attachments with correct FileTypeId
+- [ ] Expertise → `expertiseId`
+- [ ] Review `fanavaranAuditLogs` and history events
+
+### 7. Document deltas
+
+- [ ] Add a short section under [04-tenant-matrix.md](./04-tenant-matrix.md) for the new key
+- [ ] Note any non-Parsian business rules (validation, required fields)
+
+## Do / Don’t
+
+| Do | Don’t |
+|----|-------|
+| Copy orchestration from existing code | Copy Parsian expert/file-type ids blindly |
+| Verify FileTypeId in tenant lookup | Use template sample `70` without checking |
+| Keep null fields in payloads | Strip nulls from GEN.03/12 templates |
+| Soft-fail auto-submit | Block user UX on Fanavaran outage |
+
+## Acceptance for “docs-only onboarding”
+
+A backend engineer should be able to complete the checklist above using only:
+
+1. This docs set (`docs/fanavaran/`)
+2. `docs/external-api-curls.md`
+3. Seed/config + System Settings for credentials
+4. Parsian proven values as the reference baseline