پرش به محتویات

گزارش فنی — بهار ۱۴۰۴

دوره گزارش: فروردین تا خرداد ۱۴۰۴
نوع سند: گزارش بازنگری معماری و آمادگی‌های توسعه‌ای
مخاطب: ذینفعان فنی و مدیریتی پروژه دارانو

خلاصه اجرایی

در این دوره، تیم فنی دارانو تمرکز خود را از توسعه قابلیت‌های جدید به بازنگری بنیادی معماری معطوف کرده است. هدف اصلی، آماده‌سازی پلتفرم برای مقیاس‌پذیری بلندمدت، کاهش وابستگی‌های تکنولوژیک، و افزایش تاب‌آوری سیستم در برابر شرایط غیرعادی است.

محورهای اصلی این دوره عبارتند از:

  1. بازنگری لایه بلاکچین و ارائه راه‌حل چندگانه
  2. بازطراحی معماری کلان سیستم
  3. بهبود مدل‌سازی Use Case ها و روابط موجودیتی
  4. بازتعریف نقش‌های سامانه
  5. تعریف زیرساخت سرور جدید
  6. آمادگی برای سناریوی قطع اینترنت

۱. بازنگری لایه بلاکچین — راه‌حل چندگانه

۱.۱ وضعیت فعلی و چالش‌ها

در حال حاضر، تمام تراکنش‌های مالی دارانو روی شبکه ققنوس (Kuknos) — نسخه ایرانی پروتکل Stellar — انجام می‌شود. این انتخاب در ابتدا منطقی بود، اما با رشد پلتفرم، محدودیت‌های جدی آشکار شده‌اند:

چالش شرح
وابستگی یکتا قطع یا اختلال ققنوس کل سیستم را متوقف می‌کند
قابلیت برنامه‌نویسی محدود Stellar از قراردادهای هوشمند پیچیده (EVM) پشتیبانی نمی‌کند
اکوسیستم محدود ابزارهای توسعه، کیف‌پول‌های خارجی، و Bridge های کمتری نسبت به شبکه‌های EVM وجود دارد
انعطاف پایین برای محصولات آینده توکن‌های پیشرفته‌تر (مثل NFT با منطق سود اجاره) روی Stellar دشوارتر پیاده‌سازی می‌شوند
تأخیر تأیید تراکنش در اوج ترافیک، تأخیر شبکه بر تجربه کاربری تأثیر می‌گذارد

۱.۲ سه گزینه معماری پیشنهادی

بر اساس تحلیل‌های انجام‌شده، سه معماری جایگزین یا مکمل برای لایه تراکنش شناسایی شده‌اند:

گزینه A — ادامه ققنوس با بهبودهای عملیاتی (کم‌ریسک‌ترین)

حفظ ققنوس به عنوان لایه اصلی با اضافه‌کردن لایه Retry، Circuit Breaker قوی‌تر، و نود محلی.

graph LR
    WAL[Wallet Service] -->|Primary| KUKNOS[Kuknos Network]
    WAL -->|Fallback Queue| MQ[(RabbitMQ\nPending Txs)]
    MQ -->|Retry on recovery| KUKNOS
    CB[Circuit Breaker] -.->|Monitor| KUKNOS
    CB -.->|Open circuit| MQ

مزیت: تغییر معماری حداقلی، ریسک پایین
معایب: محدودیت‌های اکوسیستمی همچنان باقی است

گزینه B — مهاجرت به زنجیره EVM-Compatible (بالاترین قابلیت)

جایگزین‌کردن ققنوس با یک شبکه EVM مانند Polygon PoS، Arbitrum، یا یک Chain خصوصی بر بستر Besu (Hyperledger Besu — مناسب برای استقرار داخلی).

graph TB
    subgraph "لایه انتزاع بلاکچین"
        BC_INTERFACE[IBlockchainAdapter\ninterface در Go]
    end

    subgraph "پیاده‌سازی‌های ممکن"
        KUKNOS_IMPL[KuknosAdapter\nStellar SDK]
        EVM_IMPL[EVMAdapter\nethclient go-ethereum]
        BESU_IMPL[BesuAdapter\nPrivate Chain]
    end

    WAL[Wallet Service] --> BC_INTERFACE
    BC_INTERFACE --> KUKNOS_IMPL
    BC_INTERFACE --> EVM_IMPL
    BC_INTERFACE --> BESU_IMPL

    KUKNOS_IMPL --> KUKNOS[Kuknos Network]
    EVM_IMPL --> POLYGON[Polygon / Arbitrum]
    BESU_IMPL --> BESU_NODE[نود Besu داخلی]

الزامات فنی این گزینه: - تعریف Interface یکپارچه IBlockchainAdapter در Go با متدهای استاندارد: Transfer, GetBalance, IssueToken, CreateAccount - نگاشت مدل توکن Stellar (Asset) به مدل ERC-20 / ERC-1155 - بازنویسی Wallet Streamer برای هر دو پروتکل (Horizon vs WebSocket/eth_subscribe) - مهاجرت کلیدهای خصوصی و آدرس‌های کیف‌پول

مزیت: قراردادهای هوشمند، DeFi-ready، Bridge به اکوسیستم جهانی
معایب: مهاجرت داده پیچیده، نیاز به Audit امنیتی قراردادها

گزینه C — لایه دیتابیسی به عنوان جایگزین یا مکمل (چابک‌ترین)

استفاده از یک دفتر کل داخلی (Internal Ledger) بر پایه PostgreSQL به عنوان منبع اصلی موجودی، با ققنوس یا EVM به عنوان لایه Audit/Settlement اختیاری.

graph TB
    subgraph "Internal Ledger — منبع اصلی"
        LEDGER[(PostgreSQL\nLedger Tables)]
        ENTRY[Double-Entry\nAccounting]
        RECONCILE[Reconciliation\nService]
    end

    subgraph "Settlement Layer — اختیاری"
        BC[بلاکچین\nققنوس یا EVM]
    end

    WAL[Wallet Service] -->|همه تراکنش‌ها| ENTRY
    ENTRY -->|ثبت دوطرفه| LEDGER
    RECONCILE -->|بررسی دوره‌ای| LEDGER
    RECONCILE -.->|Settlement خودکار| BC
    LEDGER -.->|در صورت نیاز| BC

ساختار جداول Ledger پیشنهادی:

-- حساب‌های کاربران
CREATE TABLE ledger_accounts (
    id          UUID PRIMARY KEY,
    user_id     UUID NOT NULL,
    asset_code  VARCHAR(12) NOT NULL,  -- "IRR", "MOJGAN", ...
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- ورودی‌های دوطرفه (Double-Entry)
CREATE TABLE ledger_entries (
    id              UUID PRIMARY KEY,
    account_id      UUID REFERENCES ledger_accounts(id),
    amount          NUMERIC(28, 8) NOT NULL,  -- مثبت = credit، منفی = debit
    transaction_id  UUID NOT NULL,
    memo            TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- تراکنش‌های کامل (جفت ورودی‌ها)
CREATE TABLE ledger_transactions (
    id              UUID PRIMARY KEY,
    type            VARCHAR(32) NOT NULL,  -- "transfer", "mint", "burn"
    status          VARCHAR(16) NOT NULL DEFAULT 'confirmed',
    blockchain_hash VARCHAR(128),  -- اگر روی chain ثبت شد
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- ایندکس‌های حیاتی
CREATE INDEX idx_entries_account_time ON ledger_entries(account_id, created_at DESC);
CREATE INDEX idx_entries_tx ON ledger_entries(transaction_id);

مزیت: سرعت بسیار بالا، بدون وابستگی به شبکه خارجی، آماده آفلاین
معایب: از‌دست‌دادن شفافیت Public Blockchain، نیاز به Audit داخلی قوی

۱.۳ ماتریس مقایسه و توصیه

معیار ققنوس فعلی EVM Chain Internal Ledger
سرعت تراکنش متوسط بالا (L2) بسیار بالا
وابستگی شبکه بالا بالا ندارد
قراردادهای هوشمند محدود کامل ندارد
شفافیت عمومی عمومی داخلی
پیچیدگی مهاجرت — بالا متوسط
آمادگی آفلاین ندارد ندارد کامل
هزینه اجرایی Gas ققنوس Gas شبکه صفر

توصیه فنی: معماری لایه‌بندی ترکیبی — Internal Ledger برای تراکنش‌های روزانه سریع، با قابلیت Settlement به بلاکچین (ققنوس یا EVM) برای آیتم‌های قابل Audit. این رویکرد هم آمادگی آفلاین را می‌دهد، هم مسیر مهاجرت به EVM را باز نگه می‌دارد.

۲. بازنگری معماری کلان سیستم

۲.۱ وضعیت فعلی

graph LR
    UI[Next.js UI] -->|REST| API[API Gateway]
    AdminPanel[Django Admin] -->|REST| API
    API -->|gRPC| Auth[Auth Service]
    API -->|gRPC| Wallet[Wallet Service]
    API -->|gRPC| Market[Market Service]
    Market -->|gRPC| Wallet
    Wallet -->|Horizon API| Kuknos[(Kuknos)]
    Streamer[Wallet Streamer] -->|Stream| Kuknos

محدودیت‌های شناسایی‌شده: - ارتباط همزمان (Synchronous) در تمام مسیرها → یک سرویس کند کل درخواست را کند می‌کند - RabbitMQ نصب شده ولی فعال نیست - بدون Event Bus مرکزی → اضافه‌کردن سرویس جدید نیاز به تغییر چند سرویس دارد - Wallet Streamer تنهاترین Consumer بلاکچین → Single Point of Failure

۲.۲ معماری هدف (Target Architecture)

graph TB
    subgraph "Edge Layer"
        CF[Cloudflare WAF]
        TFK[Traefik]
    end

    subgraph "Presentation Layer"
        UI[Next.js UI]
        AP[Django Admin]
        MOB[Mobile App\nAndroid / PWA]
    end

    subgraph "API Layer"
        GW[API Gateway\nGo + Gin]
    end

    subgraph "Core Services"
        AUTH[Auth Service]
        WAL[Wallet Service]
        MKT[Market Service]
    end

    subgraph "Event Bus"
        MQ[(RabbitMQ\nExchanges + Queues)]
    end

    subgraph "New Services"
        NOTIF[Notification Service]
        LEDGER[Ledger Service\nInternal Accounting]
        SETTLE[Settlement Service\nBC Batch Writer]
    end

    subgraph "Blockchain Adapters"
        KUKNOS_A[Kuknos Adapter]
        EVM_A[EVM Adapter\nآماده‌شده]
    end

    subgraph "Data Layer"
        DB[(PostgreSQL)]
        CACHE[(Redis)]
        LEDGER_DB[(Ledger DB\nPostgreSQL)]
    end

    CF --> TFK
    TFK --> UI & AP & MOB
    UI & AP & MOB --> GW
    GW --> AUTH & WAL & MKT
    AUTH & WAL & MKT --> MQ
    MQ --> NOTIF & LEDGER & SETTLE
    LEDGER --> LEDGER_DB
    SETTLE --> KUKNOS_A & EVM_A
    AUTH & WAL & MKT --> DB & CACHE

۲.۳ سرویس‌های جدید پیشنهادی

سرویس زبان مسئولیت
Ledger Service Go دفتر کل داخلی، Double-Entry Accounting، محاسبه موجودی
Settlement Service Go دسته‌بندی تراکنش‌ها و ارسال batch به بلاکچین
Notification Service Go ارسال SMS/Push/Email از طریق Event Bus

۳. بهبود Use Case ها و روابط موجودیتی

۳.۱ نقشه کامل Use Case های سیستم

graph TB
    subgraph "بازیگران"
        GUEST([کاربر مهمان])
        USER([کاربر احراز شده])
        ADMIN([مدیر سامانه])
        ASSET_MGR([مدیر دارایی])
        MARKET_OP([اپراتور بازار])
        DEVOPS([DevOps])
    end

    subgraph "احراز هویت"
        UC1[ثبت‌نام / ورود OTP]
        UC2[احراز هویت KYC]
        UC3[مدیریت توکن‌های دسترسی]
    end

    subgraph "کیف پول"
        UC4[مدیریت کیف ریالی]
        UC5[واریز ریال]
        UC6[برداشت ریال]
        UC7[واریز توکن از خارج]
        UC8[برداشت توکن به خارج]
    end

    subgraph "بازار"
        UC9[خرید توکن — بازار اولیه]
        UC10[ثبت سفارش فروش — P2P]
        UC11[خرید از بازار ثانویه]
        UC12[مشاهده Order Book]
        UC13[لغو سفارش]
        UC14[اعمال کد تخفیف]
        UC15[استفاده از کد دعوت]
    end

    subgraph "مدیریت دارایی"
        UC16[صدور توکن جدید]
        UC17[مدیریت بازخرید]
        UC18[تخصیص اولیه توکن]
    end

    subgraph "مدیریت بازار"
        UC19[مدیریت سفارش‌ها]
        UC20[تنظیم کارمزدها]
        UC21[مدیریت کدهای تخفیف]
        UC22[نظارت بر فعالیت مشکوک]
    end

    subgraph "مدیریت کاربران"
        UC23[جستجو و مشاهده کاربران]
        UC24[مدیریت وضعیت KYC]
        UC25[فعال/مسدود کردن حساب]
        UC26[گزارش‌گیری مالی]
    end

    subgraph "پایش سیستم"
        UC27[مانیتورینگ سرویس‌ها]
        UC28[مدیریت Backup]
        UC29[مدیریت Deploy]
    end

    GUEST --> UC1
    USER --> UC2 & UC4 & UC5 & UC6 & UC7 & UC8
    USER --> UC9 & UC10 & UC11 & UC12 & UC13 & UC14 & UC15
    ASSET_MGR --> UC16 & UC17 & UC18
    MARKET_OP --> UC19 & UC20 & UC21 & UC22
    ADMIN --> UC23 & UC24 & UC25 & UC26
    DEVOPS --> UC27 & UC28 & UC29

۳.۲ ERD بهبودیافته

erDiagram
    USER {
        uuid id PK
        varchar mobile
        varchar national_id
        varchar iban
        varchar kyc_status
        timestamp created_at
    }

    WALLET {
        uuid id PK
        uuid user_id FK
        varchar blockchain_address
        varchar asset_code
        timestamp created_at
    }

    FIAT_BALANCE {
        uuid id PK
        uuid user_id FK
        numeric amount
        timestamp updated_at
    }

    LEDGER_ENTRY {
        uuid id PK
        uuid account_id FK
        numeric amount
        uuid transaction_id FK
        varchar memo
        timestamp created_at
    }

    PROJECT {
        uuid id PK
        varchar token_code
        varchar token_name
        numeric total_supply
        numeric sold_amount
        numeric price_per_token
        varchar status
    }

    ORDER {
        uuid id PK
        uuid user_id FK
        uuid project_id FK
        varchar type
        numeric amount
        numeric price
        varchar status
        timestamp created_at
    }

    TRADE {
        uuid id PK
        uuid buy_order_id FK
        uuid sell_order_id FK
        numeric amount
        numeric price
        varchar blockchain_hash
        timestamp executed_at
    }

    BLOCKCHAIN_TX {
        uuid id PK
        varchar hash
        varchar from_address
        varchar to_address
        numeric amount
        varchar asset_code
        varchar status
        timestamp confirmed_at
    }

    DISCOUNT_CODE {
        uuid id PK
        varchar code
        numeric discount_percent
        int max_uses
        int used_count
        timestamp expires_at
    }

    REFERRAL {
        uuid id PK
        uuid referrer_id FK
        uuid referred_id FK
        numeric fee_percent
        timestamp created_at
    }

    USER ||--o{ WALLET : "دارد"
    USER ||--|| FIAT_BALANCE : "دارد"
    USER ||--o{ ORDER : "ثبت می‌کند"
    USER ||--o{ REFERRAL : "معرفی می‌کند"
    WALLET ||--o{ LEDGER_ENTRY : "دارد"
    PROJECT ||--o{ ORDER : "دارد"
    ORDER ||--o{ TRADE : "در آن تکمیل می‌شود"
    TRADE ||--o| BLOCKCHAIN_TX : "روی بلاکچین"
    ORDER }o--o| DISCOUNT_CODE : "از آن استفاده می‌کند"

۴. بازتعریف نقش‌های سامانه

۴.۱ نقش‌های فعلی (مشکل‌دار)

نقش‌های فعلی سیستم خیلی کلی تعریف شده‌اند و در عمل منجر به Over-permission می‌شوند:

User → دسترسی به همه قابلیت‌های کاربری
Admin → دسترسی به همه قابلیت‌های مدیریتی (بیش از حد گسترده)

۴.۲ ساختار نقش‌های پیشنهادی (RBAC سه‌سطحی)

graph TD
    subgraph "نقش‌های کاربران عادی"
        GUEST[مهمان\nGuest]
        BASIC[کاربر پایه\nBasic User]
        VERIFIED[کاربر احراز شده\nVerified User]
        PREMIUM[کاربر ممتاز\nPremium User]
    end

    subgraph "نقش‌های عملیاتی داخلی"
        SUPPORT[پشتیبانی\nSupport]
        KYC_OPS[اپراتور KYC\nKYC Operator]
        MARKET_OP[اپراتور بازار\nMarket Operator]
        FINANCE_OP[اپراتور مالی\nFinance Operator]
    end

    subgraph "نقش‌های مدیریتی"
        ASSET_MGR[مدیر دارایی\nAsset Manager]
        RISK_MGR[مدیر ریسک\nRisk Manager]
        SYS_ADMIN[مدیر سیستم\nSystem Admin]
        SUPER_ADMIN[فوق مدیر\nSuper Admin]
    end

    GUEST -->|ثبت‌نام| BASIC
    BASIC -->|KYC تأیید شد| VERIFIED
    VERIFIED -->|حجم بالای معاملات| PREMIUM

۴.۳ ماتریس دسترسی

عملیات مهمان کاربر پایه کاربر احراز شده اپراتور KYC اپراتور بازار مدیر دارایی سوپر ادمین
مشاهده پروژه‌ها ✅ ✅ ✅ ✅ ✅ ✅ ✅
واریز ریال ❌ ✅ ✅ ❌ ❌ ❌ ✅
خرید توکن ❌ ❌ ✅ ❌ ❌ ❌ ✅
معامله P2P ❌ ❌ ✅ ❌ ❌ ❌ ✅
تأیید KYC ❌ ❌ ❌ ✅ ❌ ❌ ✅
مدیریت Order Book ❌ ❌ ❌ ❌ ✅ ❌ ✅
صدور توکن جدید ❌ ❌ ❌ ❌ ❌ ✅ ✅
مدیریت بازخرید ❌ ❌ ❌ ❌ ❌ ✅ ✅
تغییر کارمزدها ❌ ❌ ❌ ❌ ✅ ❌ ✅
مشاهده لاگ‌های سیستم ❌ ❌ ❌ ❌ ❌ ❌ ✅

۴.۴ سیاست‌های ABAC تکمیلی

علاوه بر RBAC، دسترسی به برخی عملیات باید بر اساس ویژگی‌های موجودیت هم محدود شود:

Policy: خرید توکن
  نیاز دارد:
    - نقش: Verified User
    - KYC Level: >= 1
    - حساب: فعال (not suspended)
    - محدودیت روزانه: < سقف تعریف‌شده برای هر پروژه

Policy: صدور توکن
  نیاز دارد:
    - نقش: Asset Manager
    - مجوز پروژه: Project-scoped (Asset Manager فقط برای پروژه‌های تحت نظرش)
    - تأیید Super Admin برای مبالغ > X

Policy: بازخرید خودکار
  نیاز دارد:
    - نقش: Asset Manager یا بالاتر
    - موجودی ریالی سیستم: > حداقل Reserve
    - Lock Period توکن: سپری شده باشد

۵. تعریف سرور جدید

۵.۱ وضعیت فعلی زیرساخت

در حال حاضر، تمام سرویس‌ها روی یک VPS ابرآروان مستقر هستند:

VPS واحد:
  - تمام سرویس‌های Application (API، Auth، Wallet، Market، Streamer)
  - UI و Admin Panel
  - پایگاه داده (PostgreSQL، Redis، RabbitMQ)
  - مانیتورینگ (Prometheus، Grafana)
  - Reverse Proxy (Traefik)

ریسک‌های این معماری: - Single Point of Failure در سطح سرور - رقابت منابع بین سرویس‌های Application و Database - عدم امکان Scale مستقل اجزا - اگر Database سنگین شود، API هم کند می‌شود

۵.۲ معماری پیشنهادی Multi-Server

graph TB
    subgraph "Server 1 — Edge & Application\nAbr Cloud VPS - فعلی"
        TFK[Traefik\nReverse Proxy]
        UI_C[UI Container]
        AP_C[Admin Panel Container]
        API_C[API Gateway Container]
        AUTH_C[Auth Service Container]
        MKT_C[Market Service Container]
    end

    subgraph "Server 2 — Wallet & Blockchain\nAbr Cloud VPS - جدید"
        WAL_C[Wallet Service Container]
        STR_C[Wallet Streamer Container]
        LEDGER_C[Ledger Service Container]
        SETTLE_C[Settlement Service Container]
        KMS_C[Key Management\nVault Container]
    end

    subgraph "Server 3 — Database & Queue\nAbr Cloud VPS - جدید"
        PG[(PostgreSQL 16\nPrimary)]
        PG_R[(PostgreSQL\nRead Replica)]
        REDIS[(Redis Cluster)]
        MQ_C[(RabbitMQ Cluster)]
        MINIO[(MinIO\nObject Storage)]
    end

    subgraph "Server 4 — Monitoring\nAbr Cloud VPS - جدید"
        PROM[Prometheus]
        GRAF[Grafana]
        ALERT[Alertmanager]
        PORT[Portainer]
        LOKI[Loki\nLog Aggregation]
    end

    Internet -->|HTTPS| TFK
    TFK --> UI_C & AP_C & API_C
    API_C -->|gRPC - Internal Network| AUTH_C & MKT_C
    API_C -->|gRPC - Internal Network| WAL_C
    WAL_C & STR_C & LEDGER_C --> PG & REDIS & MQ_C
    AUTH_C & MKT_C --> PG & REDIS
    PROM -->|Scrape| API_C & AUTH_C & WAL_C & MKT_C & PG

۵.۳ مشخصات پیشنهادی سرورها

سرور نقش CPU RAM Disk توضیح
S1 — Application Edge + API Services 4 Core 8 GB 50 GB SSD فعلی — کافی
S2 — Wallet Wallet + Blockchain 4 Core 8 GB 100 GB SSD جدید — نیاز به Disk بیشتر برای کلیدها
S3 — Database PostgreSQL + Redis + RabbitMQ 8 Core 16 GB 500 GB NVMe جدید — مهم‌ترین سرور
S4 — Monitoring Prometheus + Grafana + Loki 2 Core 4 GB 200 GB HDD جدید — HDD برای نگهداری متریک‌های بلندمدت

۵.۴ شبکه داخلی (Internal Network)

ارتباط بین سرورها باید از طریق شبکه خصوصی ابرآروان (Private Network) انجام شود تا ترافیک از اینترنت عبور نکند:

S1 <--Private Network--> S2  (gRPC calls: API → Wallet)
S1 <--Private Network--> S3  (DB connections: Auth/Market → PostgreSQL)
S2 <--Private Network--> S3  (DB connections: Wallet/Ledger → PostgreSQL)
S4 <--Private Network--> S1,S2,S3  (Prometheus scraping)

۶. آمادگی برای سناریوی قطع اینترنت

۶.۱ تعریف سناریو

در محیط ایران، قطع کامل اینترنت یا محدودیت شدید آن سناریویی واقعی است. باید سیستم بتواند در سه حالت عمل کند:

حالت ۱ — Normal: اینترنت کامل، همه سرویس‌ها فعال
حالت ۲ — Degraded: اینترنت ضعیف/محدود، سرویس‌های ضروری فعال
حالت ۳ — Offline: بدون اینترنت، فقط عملیات داخلی امکان‌پذیر

۶.۲ تحلیل وابستگی به اینترنت

سرویس / وابستگی وابستگی به اینترنت حالت Offline
رابط کاربری (UI) برای کاربر خارجی نیاز دارد فقط LAN قابل استفاده
API Gateway نیاز ندارد (داخلی) فعال
Auth Service نیاز ندارد فعال (JWT local)
Wallet Service — موجودی به بلاکچین نیاز دارد با Internal Ledger: فعال
Wallet Service — تراکنش به بلاکچین نیاز دارد Queue شدن + Settlement بعداً
Market Service نیاز ندارد فعال
Wallet Streamer به Kuknos Horizon نیاز دارد متوقف می‌شود
KYC (شاهکار/زحل) به API خارجی نیاز دارد متوقف — صف انتظار
درگاه پرداخت به بانک نیاز دارد متوقف
SMS / OTP به اپراتور نیاز دارد بدیل لازم دارد

۶.۳ راهکارهای فنی پیشنهادی

۶.۳.۱ OTP بدون SMS — TOTP

sequenceDiagram
    participant U as کاربر
    participant APP as اپلیکیشن موبایل
    participant API as API Gateway
    participant AUTH as Auth Service

    Note over U,AUTH: Setup (یکبار، آنلاین)
    U->>API: درخواست فعال‌سازی TOTP
    API->>AUTH: Generate TOTP Secret
    AUTH-->>API: QR Code + Secret
    API-->>APP: نمایش QR Code
    U->>APP: اسکن با Google Authenticator
    APP->>API: تأیید کد اول

    Note over U,AUTH: Login (آفلاین ممکن)
    U->>APP: تولید کد 6 رقمی (TOTP)
    APP->>API: ارسال کد
    API->>AUTH: بررسی TOTP (بدون نیاز به SMS)
    AUTH-->>API: تأیید

پیاده‌سازی با کتابخانه github.com/pquerna/otp در Go.

۶.۳.۲ Internal Ledger به عنوان Offline-Ready Wallet

با معماری لایه دیتابیسی (گزینه C از بخش ۱)، تمام تراکنش‌های P2P داخلی بدون نیاز به بلاکچین قابل انجام هستند:

graph LR
    subgraph "Offline Mode"
        U1[کاربر A] -->|فروش توکن| MKT[Market Service]
        U2[کاربر B] -->|خرید توکن| MKT
        MKT -->|Transfer داخلی| LEDGER[(Internal Ledger)]
        LEDGER -->|Queue| SETTLE_Q[(Settlement Queue\nRabbitMQ)]
    end

    subgraph "Online Recovery"
        SETTLE_Q -->|زمانی که اینترنت برگشت| SETTLE[Settlement Service]
        SETTLE -->|Batch Submit| KUKNOS[(Kuknos / EVM)]
    end

۶.۳.۳ CDN محلی برای UI

استقرار یک Cache محلی (مثلاً با Nginx) روی سرور Application که نسخه Static Build شده UI را نگه می‌دارد. این باعث می‌شود حتی بدون دسترسی به CDN خارجی، رابط کاربری قابل لود باشد.

۶.۳.۴ Health Check و Mode Switching خودکار

// تشخیص خودکار حالت کارکرد
type OperationMode string

const (
    ModeNormal   OperationMode = "normal"
    ModeDegraded OperationMode = "degraded"
    ModeOffline  OperationMode = "offline"
)

func (s *SystemMonitor) DetectMode() OperationMode {
    if !s.isBlockchainReachable() && !s.isSMSReachable() {
        return ModeOffline
    }
    if !s.isBlockchainReachable() || !s.isSMSReachable() {
        return ModeDegraded
    }
    return ModeNormal
}

API Gateway بر اساس حالت، پاسخ‌های متفاوت به کاربر می‌دهد و قابلیت‌های غیرممکن را با پیام مناسب غیرفعال می‌کند.

۶.۴ دیاگرام حالت‌های سیستم

stateDiagram-v2
    [*] --> Normal : اینترنت فعال

    Normal --> Degraded : بلاکچین یا SMS قطع شد
    Normal --> Offline : اینترنت قطع کامل

    Degraded --> Normal : سرویس‌ها برگشتند
    Degraded --> Offline : قطع کامل

    Offline --> Degraded : اینترنت جزئی برگشت
    Offline --> Normal : اینترنت کامل برگشت

    state Normal {
        همه قابلیت‌ها فعال
    }

    state Degraded {
        معامله داخلی فعال
        KYC در صف انتظار
        تراکنش بلاکچین در Queue
        OTP از طریق TOTP
    }

    state Offline {
        فقط معامله P2P داخلی
        موجودی از Internal Ledger
        بدون واریز/برداشت خارجی
    }

۷. جمع‌بندی و اولویت‌بندی

۷.۱ نقشه راه پیشنهادی

gantt
    title نقشه راه توسعه — ۱۴۰۴ و ۱۴۰۵
    dateFormat YYYY-MM
    section لایه بلاکچین
    تعریف IBlockchainAdapter Interface   :2024-04, 1M
    پیاده‌سازی Internal Ledger           :2024-05, 2M
    Settlement Service                  :2024-07, 2M
    EVM Adapter (آماده‌سازی)             :2024-09, 2M
    section زیرساخت
    راه‌اندازی Server 3 (Database)       :2024-04, 1M
    راه‌اندازی Server 2 (Wallet)         :2024-05, 1M
    راه‌اندازی Server 4 (Monitoring)     :2024-06, 1M
    section آفلاین‌پذیری
    پیاده‌سازی TOTP                      :2024-05, 1M
    Mode Switching در API Gateway        :2024-06, 1M
    section نقش‌ها و دسترسی
    بازتعریف نقش‌ها در Auth Service       :2024-04, 2M
    پیاده‌سازی ABAC Policies             :2024-06, 2M
    section Event Bus
    فعال‌سازی RabbitMQ کامل             :2024-07, 2M
    Notification Service                :2024-08, 1M

۷.۲ اولویت‌بندی کارها

اولویت وظیفه تأثیر پیچیدگی زمان تخمینی
🔴 بحرانی Internal Ledger (آمادگی آفلاین + مستقل از بلاکچین) بالا متوسط ۲ ماه
🔴 بحرانی جداسازی Database به سرور مستقل بالا کم ۲ هفته
🟠 بالا بازتعریف نقش‌ها و ABAC Policies بالا متوسط ۱.۵ ماه
🟠 بالا پیاده‌سازی TOTP متوسط کم ۲ هفته
🟡 متوسط IBlockchainAdapter Interface متوسط کم ۲ هفته
🟡 متوسط فعال‌سازی کامل RabbitMQ + Event Bus متوسط متوسط ۱ ماه
🟢 پایین EVM Adapter آماده‌سازی پایین (آینده) بالا ۲ ماه
🟢 پایین Notification Service پایین کم ۳ هفته