merge upstream

2026-08-19 10:20:56 +03:30
parent bfbcfcab37 c7d77d30c4
commit 85fc83b564
16 changed files with 1409 additions and 48 deletions
--- a/docs/fanavaran/01-write-apis.md
+++ b/docs/fanavaran/01-write-apis.md
@@ -127,8 +127,7 @@ Full shape: see skill reference sample and `buildFanavaranSubmitPayload` / `appl
 | `Id` | `claimCases.claimId` |
 | `ClaimNo` | `claimCases.claimNo` |

-History: `FANAVARAN_EARLY_AUTO_SUBMIT_SUCCEEDED`.  
-SMS owner via `SmsOrchestrationService` (deduped `fanavaranSync.baseClaim.smsNotifiedAt`).
+History: `FANAVARAN_EARLY_AUTO_SUBMIT_SUCCEEDED`.

 ### Error handling

@@ -309,6 +308,7 @@ Requires `claimId` + `dmgCaseId` (soft-ensures earlier stages).
 | `Id` | `claimCases.expertiseId` |

 History: `FANAVARAN_EXPERTISE_AUTO_SUBMIT_SUCCEEDED`.  
+SMS owner via `SmsOrchestrationService` (deduped `fanavaranSync.expertise.smsNotifiedAt`).  
 Proven Parsian: `expertiseId=403144`, `ClaimExpertId=29`.

 Manual: `POST /v2/fanavaran/{client}/claim-cases/{id}/expertise/submit`.
--- a/docs/fanavaran/04-tenant-matrix.md
+++ b/docs/fanavaran/04-tenant-matrix.md
@@ -31,7 +31,7 @@ source: fanavaran-module-docs
 | Validation: FileTypeId ∈ tenant lookup | logic ✅ | allowed ids ✅ |
 | Business: THIRD_PARTY only | ✅ | ❌ |
 | Provisional address / dummy licence | ✅ today | may customize later |
-| SMS template after base claim | shared orchestration | provider/templates may ✅ |
+| SMS template after expertise | shared orchestration | provider/templates may ✅ |
 | Mongo collections / audit schema | ✅ | ❌ |
 | Offline inquiry seeds | may exist per client | ✅ |

--- a/docs/fanavaran/05-claim-flow.md
+++ b/docs/fanavaran/05-claim-flow.md
@@ -15,13 +15,13 @@ 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
+  → GEN.03 base claim → store claimId / claimNo
  → 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
+  → GEN.08 expertise → store expertiseId → SMS owner
  → End (local completion independent of Fanavaran success)
 ```

@@ -56,7 +56,6 @@ sequenceDiagram
  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...
@@ -77,6 +76,7 @@ sequenceDiagram
  YARA->>FV: POST .../expertise (GEN.08)
  FV-->>YARA: ExpertiseId
  YARA->>DB: expertiseId, history SUCCESS
+  YARA->>YARA: SMS owner (deduped)
 ```

 ## Flow diagram (stages + soft-ensure)
--- a/docs/fanavaran/06-yara-integration.md
+++ b/docs/fanavaran/06-yara-integration.md
@@ -17,7 +17,7 @@ source: fanavaran-module-docs
 | 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` |
+| SMS after expertise | `SmsOrchestrationModule` | `sms-orchestration.service.ts` |

 ---

--- a/docs/fanavaran/08-dependencies.md
+++ b/docs/fanavaran/08-dependencies.md
@@ -21,7 +21,7 @@ source: fanavaran-module-docs

 | Dependency | Role |
 |------------|------|
-| **SMS provider** | Notify owner after successful GEN.03 (`SmsOrchestrationService`; same as login SMS stack) |
+| **SMS provider** | Notify owner after successful GEN.08 expertise (`SmsOrchestrationService`; same as login SMS stack) |
 | **Offline inquiry seeds** | Can supply driver/policy test data without live inquiry |
 | **Redis / Queue** | **Not** used for Fanavaran stage orchestration today — retries are in-process `setTimeout` + Mongo `nextRetryAt` |

--- a/docs/fanavaran/09-error-handling.md
+++ b/docs/fanavaran/09-error-handling.md
@@ -69,4 +69,4 @@ Per HTTP step:

 ## 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.
+After successful expertise (last Fanavaran stage), owner SMS may be sent once (`fanavaranSync.expertise.smsNotifiedAt`). Failure to SMS should not roll back Fanavaran expertise submit; treat as separate notification concern. Claims already notified at base claim (`fanavaranSync.baseClaim.smsNotifiedAt`) are not re-notified.
--- a/docs/fanavaran/10-testing.md
+++ b/docs/fanavaran/10-testing.md
@@ -1,5 +1,5 @@
 ---
-last_updated: 2026-08-08
+last_updated: 2026-08-17
 tags: [fanavaran, testing]
 source: fanavaran-module-docs
 ---
@@ -22,6 +22,96 @@ source files/fanavaran-auth/parsian/tokens.env
 # then curl a lookup — see docs/external-api-curls.md
 ```

+## Manual Fanavaran flow test (no YARA)
+
+Use this when there is **no YARA claim** and you need to prove a tenant (Parsian / Tejaratno / Moallem) against Fanavaran with the **same stage order as the app**.
+
+Files in git:
+
+| Path | Role |
+|------|------|
+| `scripts/fanavaran-flow-test.sh` | Standalone tester |
+| `scripts/data/fanavaran-flow.env.example` | Template env (section A = you fill, section B = script fills) |
+
+Do **not** commit a filled copy (`fanavaran-flow.moallem.env` and similar). It contains national codes, plate data, and secrets. Copy the example on the machine that runs the test.
+
+### 1. Copy and fill the env
+
+```bash
+cp scripts/data/fanavaran-flow.env.example scripts/data/fanavaran-flow.<client>.env
+```
+
+Fill **section A** before the first run:
+
+- Tenant: `FANAVARAN_CLIENT`, optional auth overrides (`APP_NAME`, `CORP_ID`, `LOCATION`, …)
+- Lookup ids **from that tenant** (`files/fanavaran-lookups/<client>/`): `CLAIM_EXPERT_ID`, `EXPERTISE_CLAIM_EXPERT_ID`, `CLAIM_FILE_TYPE_ID`, `VEHICLE_KIND_ID`, `DMG_SECTION_ID`
+- `INSURANCE_CORP_ID`: Persian caption **or** numeric Fanavaran Id
+- Case data: guilty national code, driver national code + Jalali birthday, plate/chassis/VIN if you have them
+- `ATTACHMENT_FILE`: absolute path(s) to image(s) **on the host that runs the script** (comma-separated for several files)
+- Leave **section B empty** (`POLICY_ID`, `CLAIM_ID`, …)
+
+Lookup ids from Tejaratno/Parsian files are invalid for Moallem (Fanavaran returns `نوع خودرو یافت نشد` and similar). Fetch Moallem lookups first (`GET /lookups/vehicle-kinds` with `FANAVARAN_CLIENT=moallem`, or curl Fanavaran with that tenant’s token).
+
+### 2. Network / IP whitelist
+
+Fanavaran Login is IP-restricted. From a **whitelisted server**, run with no proxy. From **localhost**, Termius dynamic port forwarding does **not** apply automatically — set:
+
+```env
+CURL_PROXY=socks5h://127.0.0.1:<termius-socks-port>
+```
+
+Error `کاربر … مجاز به لاگین با آی پی … نمیباشد` means curl is still using your home IP.
+
+### 3. Run (same sequence as the app)
+
+```text
+auth (cached until Tehran midnight)
+  → policy inquiry → GEN.03 base
+  → driver inquiry + insurance-corp
+  → GEN.12 damage
+  → GEN.07 attachments (one request per file)
+  → GEN.08 expertise
+```
+
+From repo root (`bash`, `curl`, `node`, `awk` required):
+
+```bash
+chmod +x scripts/fanavaran-flow-test.sh
+
+# Full flow (confirms before each POST)
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env
+
+# One or more stages
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages base,damage
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages attachments
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages expertise
+
+# Build payloads / inquiries only
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --preview-only
+```
+
+Missing section-A fields can be typed when prompted; they are written back into the env file.
+
+### 4. Token cache (do not Login every run)
+
+`authenticationToken` is stored in `files/fanavaran-auth/<client>/tokens.env` until **Asia/Tehran midnight** (same as Nest). Later runs print `Reusing cached authenticationToken`. Use `--force-login` only when you must mint a new token.
+
+Repeated Login causes Fanavaran `لطفا پس از چند لحظه مجدد تلاش فرمایید`.
+
+### 5. Resume after a stage succeeds
+
+Section B is updated in the **same env file**. Re-run; stages with `CLAIM_ID` / `DMG_CASE_ID` already set are skipped (soft-skip). Payloads and HTTP bodies also land under `files/fanavaran-flow/<client>/<timestamp>/` (gitignored).
+
+### 6. Typical failures
+
+| Message | What to do |
+|---------|------------|
+| Login IP not allowed | Run on the tenant server, or set `CURL_PROXY` to Termius SOCKS |
+| Try again later | Wait; reuse cache; do not `--force-login` |
+| `نوع خودرو یافت نشد` | Set `VEHICLE_KIND_ID` from **this** tenant’s `vehicle-kinds` lookup |
+| File type lookup mismatch | Set `CLAIM_FILE_TYPE_ID` from this tenant’s `file-types` |
+| No `authenticationToken` | Read `login.body.json` in the run folder — Fanavaran `Message` is the real error |
+
 ## Unit / service specs

 | Spec | Focus |
@@ -31,7 +121,7 @@ source files/fanavaran-auth/parsian/tokens.env

 Prefer mocks for Fanavaran HTTP in unit tests; use live calls only in controlled integration.

-## Manual E2E (Parsian template)
+## Manual E2E (Parsian template — via YARA)

 1. Create THIRD_PARTY claim with guilty party national code that has an **active** Fanavaran policy.
 2. Confirm history `FANAVARAN_EARLY_AUTO_SUBMIT_SUCCEEDED` and `claimId`/`claimNo`.
--- a/docs/fanavaran/README.md
+++ b/docs/fanavaran/README.md
@@ -1,5 +1,5 @@
 ---
-last_updated: 2026-08-08
+last_updated: 2026-08-17
 tags: [fanavaran, documentation, parsian, third-party-claim]
 source: fanavaran-module-docs
 ---
@@ -32,7 +32,7 @@ source: fanavaran-module-docs
 | 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 |
+| 10 | [10-testing.md](./10-testing.md) | Test scenarios, **manual flow-test script**, proven case |
 | 11 | [11-onboard-new-client.md](./11-onboard-new-client.md) | Checklist to add a new insurer |

 ## Related sources (code)
@@ -47,6 +47,8 @@ source: fanavaran-module-docs
 | `.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 |
+| `scripts/fanavaran-flow-test.sh` | Manual Fanavaran-only staged submit (see [10-testing.md](./10-testing.md)) |
+| `scripts/data/fanavaran-flow.env.example` | Env template for the flow-test script |

 ## Architecture (one glance)