create mvp path

archive/product/business/01-actors-and-onboarding.md

@@ -0,0 +1,29 @@
+# 1. Actors & Onboarding
+
+[← Business Requirements](index.md)
+
+## (a) Business requirements
+- Three actor types: **customer** (the family member / payer), **nurse** (the independent caregiver / seller), and **admin** (Balinyaar back-office staff: support, finance, moderation, super-admin).
+- **Phone number is the primary login credential.** Authentication is **phone-OTP** (one-time code by SMS). Email is optional/secondary (required only for admin accounts).
+- The **patient** (care recipient) is a first-class entity distinct from the customer, because the payer (an adult child, a spouse) is frequently not the patient (an elderly parent, a newborn, a post-surgical adult). A customer may register multiple patients.
+- **KYC timing is role- and risk-staged, not up-front-for-everyone:**
+  - A **customer** can register and browse with only a verified phone (OTP). National-ID KYC for customers is anti-fraud only and is **deferred** at launch.
+  - A **nurse** must complete the full verification pipeline (Section 2) before any of their service variants become bookable. `national_id` is populated only after the identity step passes.
+  - An **admin** is provisioned internally with RBAC roles.
+- Each successful login creates a refresh-token session that can be revoked (logout, stolen-token detection).
+- **As-built decisions (backend-phase-2):** each refresh **rotates** the session (old revoked, new pair issued); a refresh token presented against an already-revoked session is treated as **stolen-token reuse → all of the user's sessions are revoked and the call returns 401**. Logout rotates the security stamp, so every outstanding access token dies (other devices recover by refreshing). OTP request/verify never reveal whether a phone already has an account; one OTP per phone per resend window (`auth_otp_resend_seconds`), and after `auth_otp_max_attempts` wrong codes verification refuses until a fresh OTP. `customer`/`nurse` are the only self-selectable roles (a user may hold both; grants audited via `granted_by`/`granted_at`); any admin sub-role self-assign attempt returns **403** — admin provisioning is internal-only.
+- **As-built decisions (frontend-phase-2 — onboarding UI):** the "who is care for?" onboarding step captures the patient's **relation to the payer** as a stable enum — `parent` | `spouse` | `child` | `self` (the `self` case still creates a distinct patient row; the customer is never collapsed into the patient). It also collects optional **condition** chips (`elderly`/`post_surgery`/`diabetes`/`mobility`/`dementia`). Neither `relation` nor `conditions` exists on the `patients` table yet — they are carried client-side and requested for the backend as **REQ-005** (frontend `requests/for-backend.md`); confirm/adjust the enum values when persisting.
+
+## (b) Iran-specific considerations
+- Phone-OTP is the dominant Iranian login norm and is also the anchor for **Shahkar** SIM↔national-ID binding (Section 2).
+- Storing `national_id` only post-KYC matches the reality that identity is verified through gated vendor APIs, not collected casually at signup.
+- Cultural reality: the booking flow must let a family member act on behalf of a patient who cannot self-advocate (infant, dementia, post-anesthesia). The customer/patient split is essential, not cosmetic.
+
+## (c) MVP vs DEFERRED
+- **MVP:** phone-OTP login; customer/nurse/admin roles; customer→patient (1:N); session management; admin RBAC; nurse onboarding gated on verification.
+- **DEFERRED:** customer national-ID KYC (`customer_profiles.national_id_verified_at` exists but is optional/unused at launch); push notifications; social login; nursing-company (organization) self-onboarding.
+
+## (d) Supporting database entities
+`users`, `user_sessions`, `roles`, `user_roles`, `nurse_profiles`, `customer_profiles`, `patients`, `customer_addresses`.
+
+> **Related:** Data model — [Identity & Access](../data-model/01-identity-and-access.md).