fanavaran sales integration docs

docs/fanavaran/09-error-handling.md

@@ -0,0 +1,72 @@
+---
+last_updated: 2026-08-08
+tags: [fanavaran, errors, retry]
+source: fanavaran-module-docs
+---
+
+# 09 — Error handling
+
+## Principles
+
+1. Fanavaran failures must **not** abort the local user claim flow on auto-submit.
+2. Persist warning + history + `fanavaranSync.*.lastError`.
+3. Allow manual retry via `/v2/fanavaran/.../submit`.
+4. Audit only real Fanavaran HTTP (warm cache hits are silent).
+
+---
+
+## Common errors
+
+| دلیل | پیام نمونه | مدیریت | Retry | Log | اطلاع‌رسانی |
+|------|------------|--------|-------|-----|-------------|
+| Wrong login / appToken | `نام کاربر یا رمز عبور صحیح نیست` | Fix credentials; ensure fresh GetAppToken before Login | After fix | Auth audit | Ops |
+| Transient overload | `لطفا پس از چند لحظه مجدد تلاش فرمایید` | Tenant-wide backoff 5 min; do **not** immediately re-auth storm | Delayed (~5 min) | Auth + stage | Ops via audit |
+| Missing PolicyId | No/expired policies messages | Block submit; preview may leave null | Manual after data fix | Stage fail history | Admin |
+| Duplicate create | Local `claimId`/`claimNo` exists | Skip create; use follow-ups | N/A | skipReason | — |
+| Invalid FileTypeId | `نوع فايل با منبع لوکاپ مطابقت ندارد` | Set `ClaimFileTypeId` from tenant `file-types` (Parsian **63**) | After config fix | Attachment stage | Ops |
+| Expertise not ready | `Fanavaran expertise payload is not ready` + warnings | Wait for priced parts / factor | Auto when ready | — | Expert UI |
+| Network / 5xx | Axios / gateway errors | Stage failed + schedule retry | Up to `maxRetries` (2) | Audit | Ops |
+| Max retries exhausted | Logged warn | Manual submit only | Stop auto | Stage status | Ops |
+
+---
+
+## Retry mechanics
+
+Implemented in `scheduleFanavaranRetry`:
+
+| Rule | Behavior |
+|------|----------|
+| Delay (normal) | 5 minutes |
+| Delay (transient try-later) | 10 minutes + `registerFailure` tenant backoff (5 min) |
+| Max | Default 2 per stage (`fanavaranSync.*.maxRetries`) |
+| Dedupe | In-process timer map + existing future `nextRetryAt` |
+| Lock | `withFanavaranStageLock` prevents concurrent stage runs |
+
+---
+
+## History event types (examples)
+
+| Event | Meaning |
+|-------|---------|
+| `FANAVARAN_EARLY_AUTO_SUBMIT_SUCCEEDED` | GEN.03 ok |
+| `FANAVARAN_EARLY_AUTO_SUBMIT_FAILED` | GEN.03 fail |
+| `FANAVARAN_DAMAGE_CASE_AUTO_SUBMIT_SUCCEEDED` / `_FAILED` | GEN.12 |
+| `FANAVARAN_EXPERTISE_AUTO_SUBMIT_SUCCEEDED` / `_FAILED` | GEN.08 |
+| Attachment success/fail | Via sync status + audit (and related history where pushed) |
+
+---
+
+## Audit log (`fanavaranAuditLogs`)
+
+Per HTTP step:
+
+- `requestUrl`, `requestMethod`, `httpStatus`, `durationMs`
+- Headers/bodies (secrets masked, truncated)
+- `errorMessage` / `errorDetails` on failure
+- Look for `fromCache: true` meta when PolicyId/auth reused without live call
+
+---
+
+## SMS
+
+After successful base claim, owner SMS may be sent once (`smsNotifiedAt`). Failure to SMS should not roll back Fanavaran claim create; treat as separate notification concern.