arc42 §6c — تدفقات بيانات الميزات: التجارة والإدارة

flowchart TB
    subgraph MA["❌ Model A — Qwizin holds funds"]
        direction LR
        CA["👤 Customer"] -->|pays| QA["Qwizin<br/>merchant account"]
        QA -->|"holds balance"| QB[("Qwizin<br/>ledger")]
        QB -->|disburses| PA["🎓 Consultant"]
    end

    subgraph MB["✅ Model B — Qwizin never touches funds"]
        direction LR
        CB["👤 Customer"] -->|pays| PSP["💳 SAMA-licensed PSP"]
        PSP -->|"split settlement"| PB["🎓 Consultant<br/><i>sub-merchant under<br/>PSP's licence</i>"]
        PSP -->|"commission"| QC["Qwizin<br/><i>separate merchant txn</i>"]
        QD["Qwizin API"] -.->|"transmits split<br/>instructions only"| PSP
    end

    style MA fill:#fde8e8,stroke:#c94a4a
    style MB fill:#e8f5e9,stroke:#2d8659

stateDiagram-v2
    [*] --> pending_payment: Booking created,<br/>slot locked
    pending_payment --> awaiting_consultant: 💳 AUTHORIZE (hold)<br/><i>funds NOT taken</i>
    pending_payment --> abandoned: Payment window expires<br/>→ release slot

    awaiting_consultant --> confirmed: Consultant accepts<br/>→ 💳 CAPTURE
    awaiting_consultant --> declined: Consultant rejects<br/>→ 💳 VOID
    awaiting_consultant --> expired: SLA timer elapses<br/>→ 💳 VOID + release slot

    confirmed --> completed: Session held<br/>→ eligible for payout
    confirmed --> no_show_customer: Customer absent
    confirmed --> no_show_consultant: Consultant absent<br/>→ 💳 REFUND
    confirmed --> cancelled_by_customer: → refund per policy ⚠
    confirmed --> failed_technical: Session never established<br/>→ 💳 REFUND ⚠

    completed --> [*]
    declined --> [*]
    expired --> [*]

    note right of awaiting_consultant
        AUTHORIZE not CAPTURE.
        This is the fix for CONF-02 —
        money is never taken for a
        service not yet agreed.
    end note

    note right of cancelled_by_customer
        ⚠ Refund policy UNDEFINED
        in all source documents.
        Free cancellation window?
        Partial refund tiers?
        → OQ-05
    end note

sequenceDiagram
    autonumber
    participant SP as 🚚 Service Provider
    participant API as Qwizin API
    participant PAY as 💳 PSP
    participant SCH as Scheduler
    participant IDX as Search Index
    participant N as Notifications

    rect rgb(240,240,255)
    Note over SP,IDX: Initial subscription
    SP->>API: GET /v1/subscription-plans
    Note over API: Plans are ADMIN-CONFIGURABLE data,<br/>not code (CON-07).<br/>Monthly + annual tiers.
    SP->>API: POST /v1/subscriptions {plan_id}
    API->>API: ⚠ Precondition: account.state == active<br/>(documents approved — BR-RL-1)
    API->>PAY: Create subscription / initial charge
    PAY-->>API: Confirmed
    API->>DB: subscription(state: active, period_end)
    API->>IDX: 🔍 Index listing as VISIBLE
    N->>SP: 🔔 Subscription active
    end

    rect rgb(255,245,235)
    Note over SCH,IDX: Renewal cycle
    SCH->>API: T-7d: upcoming renewal
    N->>SP: 🔔 Renewal reminder
    SCH->>PAY: Charge on period_end
    alt Payment succeeds
        PAY-->>API: Confirmed
        API->>DB: period_end += interval
    else Payment fails
        API->>DB: subscription(state: past_due)
        N->>SP: 🔔 Payment failed
        loop Dunning: retry schedule
            SCH->>PAY: Retry
        end
        alt Still failing after grace period
            API->>DB: subscription(state: lapsed)
            API->>IDX: 🔍 Remove listing from index
            N->>SP: 🔔 Listing no longer visible
            Note over API,IDX: ⚠ Grace period length UNDEFINED<br/>→ OQ-20
        end
    end
    end

    rect rgb(255,240,240)
    Note over SP,IDX: Cancellation
    SP->>API: DELETE /v1/subscriptions/{id}
    API->>DB: cancel_at_period_end = true
    Note over API: Access retained until period_end —<br/>they paid for it. Do NOT revoke immediately.
    SCH->>API: At period_end
    API->>IDX: 🔍 Remove from index
    end

stateDiagram-v2
    [*] --> none: Provider approved,<br/>no subscription
    none --> active: Payment succeeds
    active --> past_due: Renewal fails
    past_due --> active: Retry succeeds
    past_due --> lapsed: Grace period exhausted
    lapsed --> active: Provider resubscribes
    active --> cancelling: Provider cancels
    cancelling --> lapsed: period_end reached

    note right of none
        Visible in directory: ❌
    end note
    note right of active
        Visible in directory: ✅
    end note
    note right of past_due
        Visible: ✅ (grace)
        — do not punish a
        transient card failure
    end note
    note right of lapsed
        Visible: ❌
    end note

flowchart LR
    SP["🚚 Provider"] --> CHK{"Precondition:<br/>active subscription?"}
    CHK -->|No| DENY["❌ Featured requires<br/>an active base subscription"]
    CHK -->|Yes| PLANS["Featured packages<br/><i>admin-configurable</i><br/>duration · category · placement"]
    PLANS --> PAY2["💳 Payment"]
    PAY2 --> GRANT["featured_placement<br/>(category, starts_at, ends_at)"]
    GRANT --> IDX2["🔍 Reindex with<br/>featured_rank + expiry"]
    IDX2 --> RANK["→ C-04 ranking effect"]

    SCH2["⏰ Scheduler"] -->|"at ends_at"| EXPIRE["Expire placement"]
    EXPIRE --> IDX3["🔍 Reindex without boost"]

    style DENY fill:#fde8e8,stroke:#c94a4a
    style GRANT fill:#e8f5e9,stroke:#2d8659

flowchart TB
    Q["🔍 Query: 'مورد أغذية' + filters"] --> NORM["Arabic normalisation<br/><i>alef · teh marbuta · yeh ·<br/>diacritics · tatweel</i>"]
    NORM --> REL["Compute relevance score<br/>per candidate"]
    REL --> BOOST["Apply featured multiplier"]

    BOOST --> CHECK{"Boost model?"}
    CHECK -->|"❌ Sort by featured DESC,<br/>then relevance"| BAD["Irrelevant featured providers<br/>appear above relevant ones.<br/><b>Users stop trusting search.</b><br/>Featured product loses value."]
    CHECK -->|"✅ Relevance × bounded multiplier"| GOOD["Featured providers outrank<br/>comparable non-featured.<br/>An irrelevant result<br/><b>cannot</b> be promoted."]

    GOOD --> DECAY["Apply recency decay<br/><i>stale featured listing must not<br/>outrank a perfect match forever</i>"]
    DECAY --> HYD2["Hydrate from DB"]
    HYD2 --> POST["⚠ Post-filter:<br/>approved AND subscription current"]
    POST --> OUT["Ranked results<br/>+ featured badge"]

    style BAD fill:#fde8e8,stroke:#c94a4a
    style GOOD fill:#e8f5e9,stroke:#2d8659
    style POST fill:#fff4e5,stroke:#d98c1f

sequenceDiagram
    autonumber
    participant SCH as ⏰ Scheduler
    participant API as Qwizin API
    participant PSP as 💳 SAMA-licensed PSP
    participant CON as 🎓 Consultant
    participant ADM as 🛡️ Admin

    rect rgb(240,240,255)
    Note over CON,PSP: Onboarding — Model B
    CON->>API: Provide payout details
    API->>PSP: Initiate sub-merchant onboarding
    PSP->>CON: KYC / AML directly with PSP
    Note over PSP,CON: ⚠ KYC is the PSP's obligation<br/>under ITS licence — not Qwizin's.<br/>This is the point of Model B.
    PSP-->>API: {sub_merchant_ref, status}
    API->>DB: Store reference ONLY — never bank details
    end

    rect rgb(240,255,240)
    Note over SCH,PSP: Earnings & settlement
    SCH->>API: Compute settlement period
    API->>DB: Aggregate completed sessions + delivered requests
    API->>API: Apply commission
    API->>DB: statement(gross, commission, net) — immutable
    API->>PSP: Instruct split settlement
    PSP->>CON: 💰 Funds — direct, never via Qwizin
    API->>DB: 📝 Hash-chained financial audit entry
    end

    rect rgb(255,240,240)
    Note over CON,ADM: ⚠ Highest-value fraud target
    CON->>API: Change payout bank details
    API->>API: 🔐 Step-up MFA required
    API->>API: ⏳ Delay window before effective
    API->>CON: 🔔 Out-of-band notification to<br/>PREVIOUS contact channel
    API->>DB: 📝 Audit with actor + IP
    Note over API,CON: Account takeover → redirect payouts<br/>is the classic marketplace fraud.<br/>MFA + delay + out-of-band alert<br/>are all required, not optional.
    end

flowchart TB
    subgraph ROLES["⚠ Multi-role administration — CONF-03 unresolved"]
        R1["Approval Reviewer<br/>documents, accounts"]
        R2["Content Manager<br/>templates, learning, assessments"]
        R3["Marketplace Manager<br/>consultants, providers, featured"]
        R4["Finance<br/>payments, payouts, refunds"]
        R5["Support<br/>read-mostly, impersonation"]
        R6["Super Admin<br/>role assignment"]
    end

    subgraph GUARD["Admin access controls"]
        G1["🔐 MFA mandatory"]
        G2["Separate origin from<br/>user-facing app"]
        G3["📝 EVERY action audited"]
        G4["Impersonation explicitly<br/>logged + time-boxed"]
    end

    subgraph QUEUES["Work queues"]
        Q1["📥 Document review<br/><i>oldest-first, SLA-tracked</i>"]
        Q2["📥 Custom template requests"]
        Q3["📥 Disputes / refunds"]
        Q4["📥 Reported content"]
    end

    ROLES --> GUARD --> QUEUES

    style R6 fill:#fde8e8,stroke:#c94a4a
    style G1 fill:#fff4e5,stroke:#d98c1f

flowchart LR
    subgraph CM["Content management"]
        T["Templates<br/>create · version · publish · retire"]
        L["Learning modules<br/>author · publish"]
        A["Assessments<br/>question banks · passing score ⚠"]
        CAT["Categories &amp; taxonomy<br/><i>bilingual</i>"]
    end

    subgraph MM["Marketplace management"]
        CN["Consultants<br/>approve · suspend · verify specialties"]
        PR["Providers<br/>approve · suspend · categories"]
        FT["Featured inventory<br/><i>if scarce — OQ-21</i>"]
        PL["Subscription plans<br/><i>CON-07: configurable</i>"]
    end

    CM --> PUB["Publish → versioned,<br/>previous version retained"]
    MM --> IDX4["→ Reindex affected listings"]

    A -.->|"⚠ CON-08"| SCORE["Passing score is<br/>ADMIN-CONFIGURABLE<br/>per assessment"]

    style SCORE fill:#fff4e5,stroke:#d98c1f

flowchart TB
    subgraph SOURCES["Event sources — Pipeline 1"]
        E1["BookingConfirmed<br/>ConsultationCompleted"]
        E2["TemplateDownloaded<br/>CustomRequestDelivered"]
        E3["AssessmentPassed<br/>CertificateIssued"]
        E4["SubscriptionActivated<br/>FeaturedPurchased<br/>PaymentCaptured"]
    end

    subgraph PROJ["Projection — Pipeline 4"]
        OUT2["Outbox"] --> P["Projectors"]
        P --> RM[("Reporting read model<br/><i>pre-aggregated</i>")]
    end

    subgraph KPI["SRC-MOM §13 KPIs"]
        K1["📊 Consultations booked<br/>&amp; completed / month"]
        K2["📊 Templates downloaded<br/>&amp; customised"]
        K3["📊 % employees passing<br/>&amp; certified"]
        K4["📊 MRR — subscriptions<br/>+ featured packages"]
    end

    subgraph VIEWS["Dashboards"]
        V1["🛡️ Platform admin<br/><i>all tenants</i>"]
        V2["🏢 Company admin<br/><i>own employees only —<br/>RLS enforced</i>"]
        V3["🎓 Consultant<br/><i>own bookings + earnings</i>"]
        V4["🚚 Provider<br/><i>own listing performance</i>"]
    end

    E1 & E2 & E3 & E4 --> OUT2
    RM --> K1 & K2 & K3 & K4
    K1 & K2 & K3 & K4 --> V1
    RM --> V2 & V3 & V4

    style V2 fill:#fff4e5,stroke:#d98c1f

flowchart TB
    subgraph TRIG["Triggers"]
        T1["Account state changed"]
        T2["Booking confirmed / declined /<br/>expired / reminder"]
        T3["Document approved / rejected"]
        T4["Certificate issued"]
        T5["Training assigned / overdue"]
        T6["Payment succeeded / failed"]
        T7["Custom request delivered"]
    end

    TRIG --> EV["Domain event → Outbox"]
    EV --> DISP["Notification dispatcher"]

    DISP --> PREF{"User channel<br/>preferences<br/>+ locale"}

    PREF --> EMAIL["✉️ Email"]
    PREF --> SMS["📱 SMS ⚠"]
    PREF --> PUSH["🔔 Push (APNs/FCM)"]
    PREF --> INAPP["📥 In-app inbox"]

    EMAIL & SMS & PUSH --> RETRY{"Delivered?"}
    RETRY -->|No| BACKOFF["Exponential backoff<br/>retry queue"]
    BACKOFF --> RETRY
    RETRY -->|"Exhausted"| DLQ["Dead letter<br/>+ alert"]
    RETRY -->|Yes| LOG2["📝 Delivery record"]

    style SMS fill:#fff4e5,stroke:#d98c1f
    style DLQ fill:#fde8e8,stroke:#c94a4a