# مستندات مرجع جامع توسعه‌دهندگان، معماران سیستم و راهنمای API پلتفرم هوش مصنوعی دیکا (Dika AI API Platform)

> **نسخه جاری:** `v3.9.8`
> **سازمان مالک و توسعه‌دهنده:** شرکت راهکار الکترونیک سهند ([irres.ir](https://irres.ir))  
> **واحد فنی:** تیم تحقیق و توسعه هوش مصنوعی دیکا (`support@irres.ir`)  
> **درگاه پرداخت و تسویه:** وب‌سرویس مستقیم [spinora.ir](https://spinora.ir)  
> **مستندات تعاملی Swagger:** [dika.irres.ir/docs](https://dika.irres.ir/docs) یا فایل `docs.html`

---

## ۱. معماری کلی سیستم (System Architecture)

پلتفرم دیکا از معماری ترکیبی لایه‌ای (Hybrid Cloud & On-Premise) بهره می‌برد که پردازش‌های بلادرنگ عصبی، واژه‌نامه محلی SQLite FTS5، سرویس کراولر ضدتحریم و وب‌هوک‌های سازمانی را با کارایی بالا مدیریت می‌کند.

```mermaid
graph TB
    subgraph Clients["💻 لایه کلاینت‌ها و توسعه‌دهندگان"]
        WebApp["🌐 وب‌اپلیکیشن و PWA دیکا"]
        SDKs["📦 کیت‌های توسعه (Python, Node, C#, PHP)"]
        ThirdParty["🏢 سیستم‌های یکپارچه سازمانی و اتوماسیون"]
        Widget["🧩 ویجت ۱ خطی ترجمه وب‌سایت"]
    end

    subgraph Gateway["🛡️ دروازه ورودی و امنیت (Gateway & Reverse Proxy)"]
        IIS["🖥️ سرور وب IIS / Apache / Nginx"]
        RateLimiter["⏱️ کنترل نرخ درخواست (Rate Limiter: 60/600 RPM)"]
        AuthModule["🔑 اعتبارسنجی توکن و کلید API (Auth Module)"]
    end

    subgraph CoreEngine["⚡ موتور اصلی دیکا (Dika Core Engine - FastAPI)"]
        NMT["🧠 موتور هوش مصنوعی ترجمه عصبی (Neural MT)"]
        StreamServer["📡 سرور استریم بلادرنگ (SSE Streaming)"]
        Crawler["🕷️ کراولر هوشمند و استخراج DOM (Web Crawler)"]
        AudioTTS["🗣️ موتور تبدیل متن به صوت طبیعی (Neural TTS)"]
        DictDB["📚 واژه‌نامه آفلاین و FTS5 SQLite (50,000+ کلمه)"]
        Billing["💳 زیرسیستم پرداخت و درگاه اسپینورا"]
    end

    subgraph External["🌍 شبکه‌های خارجی و پشتیبان"]
        SpinoraGW["🏦 درگاه پرداخت Spinora.ir"]
        CloudProxy["☁️ درگاه‌های ابری ضدتحریم (Cloud CORS Proxies)"]
        ServerTor["🧅 شبکه امن Tor / SOCKS5"]
    end

    WebApp --> IIS
    SDKs --> IIS
    ThirdParty --> IIS
    Widget --> IIS

    IIS --> RateLimiter
    RateLimiter --> AuthModule
    AuthModule --> CoreEngine

    NMT --> DictDB
    Crawler --> CloudProxy
    Crawler --> ServerTor
    Billing --> SpinoraGW
```

---

## ۲. دیاگرام جریان صدور کلید و احراز هویت (Key Issuance & Authentication Flow)

```mermaid
sequenceDiagram
    autonumber
    actor Dev as توسعه‌دهنده / مدیر
    participant UI as رابط کاربری دیکا (UI)
    participant API as سرور احراز هویت (/api/v1/keys/generate)
    participant DB as پایگاه داده SQLite Store

    alt صدور کلید توسط مدیر (Developer / Enterprise Tier)
        Dev->>UI: وارد کردن مشخصات پروژه و توکن مدیر (DIKA_ADMIN_TOKEN)
        UI->>API: POST /api/v1/keys/generate با هدر Authorization: Bearer <AdminToken>
        API->>API: بررسی صحت توکن مدیر (verify_admin)
        API->>DB: ثبت کاربر و پروژه با سهمیه پلن انتخابی
        DB-->>API: تولید کلید با پیشوند dika_...
        API-->>UI: بازگرداندن کلید API معتبر
        UI-->>Dev: نمایش کلید و آماده‌سازی نمونه‌کدها
    else صدور کلید نامحدود سازمانی (Enterprise Tier)
        Dev->>UI: انتخاب پلن Enterprise + وارد کردن رمز مدیر (DIKA_ADMIN_TOKEN)
        UI->>API: POST /api/v1/keys/generate با هدر Authorization: Bearer <AdminToken>
        API->>API: بررسی صحت توکن مدیر (verify_admin)
        API->>DB: ثبت کاربر با سقف 600 RPM و 2,000,000 کاراکتر روزانه
        DB-->>API: تولید کلید سازمانی با پیشوند dika_...
        API-->>UI: بازگرداندن کلید سازمانی معتبر
        UI-->>Dev: نمایش کلید سازمانی با اولویت صف High-Priority
    end
```

---

## ۳. معماری امن و لایه‌ای استخراج و ترجمه وب‌سایت‌ها (Layered Web Fetch Architecture)

هنگامی که آدرس یک وب‌سایت برای ترجمه ارسال می‌شود، سیستم از مسیرهای امن زیر برای دریافت و ترجمه استفاده می‌کند:

```mermaid
flowchart TD
    Start(["🌐 شروع: دریافت آدرس اینترنتی (URL)"]) --> L1{"آیا نسخه دسکتاپ فعال است؟"}
    
    L1 -- "بله" --> L1Exec["مسیر ۱: بریج پایتون محلی دسکتاپ با سوکت امن"]
    L1 -- "خیر" --> L2["مسیر ۲: کراولر امن سرور دیکا (FastAPI Server Crawler)"]
    
    L1Exec -- "موفقیت" --> Parse["تحلیلگر DOM: پاکسازی اسکریپت‌ها و استخراج بلوک‌های متنی"]
    L1Exec -- "خطا" --> L2
    
    L2 -- "موفقیت" --> Parse
    L2 -- "خطا" --> L3["مسیر ۳: واکشی مستقیم مرورگر (Direct Browser Fetch)"]
    
    L3 -- "موفقیت" --> Parse
    L3 -- "خطا" --> Fail(["❌ خطای عدم دسترسی به منبع وب"])
    
    Parse --> TranslateEngine["🧠 ارسال بلوک‌ها به موتور ترجمه هوش مصنوعی با حفظ ساختار HTML"]
    TranslateEngine --> Render(["🖥️ رندر و نمایش مقاله کامل ترجمه‌شده به کاربر"])

    classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef step fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef fail fill:#ffebee,stroke:#c62828,stroke-width:2px;
    class L1Exec,L2,L3,Parse,TranslateEngine step;
    class Render,Parse success;
    class Fail fail;
```

---

## ۴. آدرس‌های پایه و پروتکل‌ها (Base URLs & Headers)

| محیط | آدرس پایه (Base URL) |
|---|---|
| **سرور عملیاتی (Production)** | `https://dika.irres.ir/api` یا `https://dika.irres.ir` |
| **توسعه و تست محلی (Localhost)** | `http://127.0.0.1:8000` |
| **مستندات تعاملی Swagger** | `https://dika.irres.ir/docs` |
| **تعریف استاندارد OpenAPI** | `https://dika.irres.ir/openapi.json` |

### هدرهای الزامی احراز هویت:
```http
Content-Type: application/json
X-API-Key: dika_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
یا با استفاده از توکن مدیریت سرور (`DIKA_ADMIN_TOKEN`):
```http
Authorization: Bearer <YOUR_DIKA_ADMIN_TOKEN>
```

---

## ۵. مشخصات کامل اندپوینت‌ها (Complete API Reference)

### ۵.۱. ترجمه متن عصبی (`POST /api/v1/translate`)
موتور اصلی ترجمه متون ساده، گروهی یا کدهای HTML با تعیین دقیق لحن.

* **درخواست (JSON Payload):**
```json
{
  "q": "هوش مصنوعی در حال تغییر دادن ساختار کسب‌وکارهای بین‌المللی است.",
  "source": "fa",
  "target": "en",
  "format": "text",
  "tone": "academic"
}
```

* **پارامترهای قابل قبول `tone` (لحن و حوزه تخصصی):**
  * `general`: ترجمه استاندارد و طبیعی
  * `formal`: رسمی، اداری و مکاتبات سازمانی
  * `academic`: دانشگاهی، علمی و مقالات ISI
  * `casual`: عامیانه، گفتاری و صمیمانه
  * `technical`: فنی، مهندسی و علوم کامپیوتر
  * `medical`: پزشکی، داروسازی و بهداشت

* **پاسخ موفق (200 OK):**
```json
{
  "success": true,
  "data": {
    "translations": [
      {
        "translatedText": "Artificial intelligence is transforming the structure of international businesses.",
        "detectedSourceLanguage": "fa"
      }
    ]
  },
  "target": "en",
  "source": "fa",
  "tone": "academic",
  "format": "text",
  "client_tier": "Developer"
}
```

---

### ۵.۲. استریم زنده ترجمه (`POST /api/v1/translate/stream`)
ارسال کلمه به کلمه متن ترجمه به صورت بلادرنگ از طریق پروتکل **Server-Sent Events (SSE)** بدون معطلی و با حداقل Latency.

* **درخواست (JSON):**
```json
{
  "text": "Welcome to Dika AI platform. We provide intelligent multilingual translation services.",
  "source": "en",
  "target": "fa"
}
```

* **جریان پاسخ (SSE Data Stream):**
```http
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache

data: {"chunk": "به پلتفرم هوش مصنوعی دیکا خوش آمدید.", "source": "en", "target": "fa", "done": false}

data: {"chunk": " ما خدمات ترجمه چندزبانه هوشمند را ارائه می‌دهیم.", "source": "en", "target": "fa", "done": false}

data: {"done": true}
```

---

### ۵.۳. کراولر و استخراج صفحات وب (`POST /api/v1/proxy/fetch-webpage`)
واکشی محتوای صفحات وب، عبور از محدودیت‌های CORS و استخراج پاراگراف‌ها و عناوین به صورت بلوک‌های ساختاریافته.

* **درخواست (JSON):**
```json
{
  "url": "https://example.com/article",
  "use_tor": false,
  "proxy_type": "socks5"
}
```

* **پاسخ موفق (200 OK):**
```json
{
  "success": true,
  "url": "https://example.com/article",
  "title": "عنوان مقاله استخراج شده",
  "lang": "en",
  "blocks": [
    { "tag": "h1", "text": "Main Headline" },
    { "tag": "p", "text": "First paragraph content..." }
  ],
  "text": "Full extracted text content...",
  "source": "direct"
}
```

---

### ۵.۴. واژه‌نامه ۵۰,۰۰۰ واژه‌ای و جستجوی تمام‌متن FTS5 (`POST /api/v1/dictionary/search`)

* **درخواست (JSON):**
```json
{
  "query": "artificial intelligence",
  "limit": 5
}
```

* **پاسخ موفق:**
```json
{
  "success": true,
  "query": "artificial intelligence",
  "results": [
    {
      "word": "artificial intelligence",
      "meaning": "هوش مصنوعی، شاخه‌ای از علوم کامپیوتر برای ساخت ماشین‌های هوشمند",
      "phonetic": "/ˌɑːtɪfɪʃl ɪnˈtelɪdʒəns/",
      "part_of_speech": "noun"
    }
  ]
}
```

---

### ۵.۵. صورتحساب و اتصال به درگاه پرداخت اسپینورا (`POST /api/v1/billing/checkout`)

* **درخواست صدور فاکتور (JSON):**
```json
{
  "plan_id": "pro",
  "user_email": "developer@irres.ir",
  "user_name": "سعید داوودی",
  "gateway": "spinora",
  "callback_url": "https://dika.irres.ir/#billing-callback"
}
```

* **پاسخ سرور:**
```json
{
  "success": true,
  "payment_id": "SPIN_17904456789",
  "amount": 190000,
  "currency": "IRT",
  "gateway": "spinora",
  "payment_url": "https://spinora.ir/api/payment/pay?order_id=SPIN_17904456789&amount=190000&email=developer%40irres.ir"
}
```

---

### ۵.۶. مدیریت توکن‌های پروژه و تکرارپذیری امن پرداخت‌ها (Project Tokens & Idempotent Verification)

* **ایجاد کلید برای پروژه خاص توسط مدیر (`POST /api/v1/keys/create` یا `POST /api/v1/keys/generate`):**
درخواست باید هدر `Authorization: Bearer <DIKA_ADMIN_TOKEN>` داشته باشد؛ صدور عمومی و بدون احراز هویت غیرفعال است.
```json
{
  "email": "team@example.com",
  "name": "پروژه فروشگاه",
  "project_name": "Ecommerce-Mobile-App",
  "tier": "Developer"
}
```

* **دریافت لیست کلیدها با توکن مدیر (`GET /api/v1/keys/list`):**
```http
GET /api/v1/keys/list HTTP/1.1
Authorization: Bearer <DIKA_ADMIN_TOKEN>
```

* **تأیید امن و تکرارپذیر پرداخت (`POST /api/v1/billing/verify`):**
درخواست‌های مکرر تأیید سفارش (Idempotent) یک کلید تکراری مجدد ایجاد نمی‌کنند، بلکه کلید صادرشده قبلی را با مشخصات سفارش برمی‌گردانند.

---

## ۶. نمونه‌کدهای آماده در زبان‌های برنامه‌نویسی (به ترتیب محبوبیت)

### ۱. 🐍 پایتون (Python 3.8+)
```python
import requests

API_URL = "https://dika.irres.ir/api/v1/translate"
HEADERS = {
    "X-API-Key": "dika_dev_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

payload = {
    "q": ["سلام و درود", "هوش مصنوعی آینده صنعت نرم‌افزار را متحول می‌کند."],
    "source": "fa",
    "target": "en",
    "tone": "academic"
}

resp = requests.post(API_URL, json=payload, headers=HEADERS)
data = resp.json()

if data.get("success"):
    for item in data["data"]["translations"]:
        print("ترجمه:", item["translatedText"])
```

### ۲. ⚡ جاوااسکریپت و نود جی‌اس (Node.js / JavaScript)
```javascript
const axios = require('axios');

async function translate() {
    const res = await axios.post('https://dika.irres.ir/api/v1/translate', {
        q: 'Universal AI Translation Engine for Developers',
        source: 'en',
        target: 'fa',
        tone: 'formal'
    }, {
        headers: {
            'X-API-Key': 'dika_dev_xxxxxxxxxxxxxxxx',
            'Content-Type': 'application/json'
        }
    });

    console.log('نتیجه:', res.data.data.translations[0].translatedText);
}

translate();
```

### ۳. ⚙️ زبان سی (C / C11 / libcurl)
```c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <curl/curl.h>

struct ResponseBuffer {
    char *data;
    size_t size;
};

static size_t WriteCallback(void *contents, size_t size, size_t nmemb, void *userp) {
    size_t total_size = size * nmemb;
    struct ResponseBuffer *mem = (struct ResponseBuffer *)userp;
    char *ptr = realloc(mem->data, mem->size + total_size + 1);
    if (!ptr) return 0;
    mem->data = ptr;
    memcpy(&(mem->data[mem->size]), contents, total_size);
    mem->size += total_size;
    mem->data[mem->size] = 0;
    return total_size;
}

int main(void) {
    CURL *curl;
    CURLcode res;
    struct ResponseBuffer buffer = { .data = malloc(1), .size = 0 };

    curl_global_init(CURL_GLOBAL_ALL);
    curl = curl_easy_init();

    if (curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Content-Type: application/json");
        headers = curl_slist_append(headers, "X-API-Key: dika_dev_xxxxxxxxxxxxxxxx");

        const char *payload = "{\"q\":\"Universal AI Translation Engine\",\"source\":\"en\",\"target\":\"fa\",\"tone\":\"technical\"}";

        curl_easy_setopt(curl, CURLOPT_URL, "https://dika.irres.ir/api/v1/translate");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&buffer);

        res = curl_easy_perform(curl);

        if (res == CURLE_OK) {
            printf("پاسخ سرور دیکا:\n%s\n", buffer.data);
        } else {
            fprintf(stderr, "خطا در برقراری ارتباط: %s\n", curl_easy_strerror(res));
        }

        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
        free(buffer.data);
    }

    curl_global_cleanup();
    return 0;
}
```

### ۴. 🚀 زبان سی‌پلاس‌پلاس (C++ / C++17 / C++20)
```cpp
#include <iostream>
#include <string>
#include <curl/curl.h>

static size_t WriteCallback(void* contents, size_t size, size_t nmemb, void* userp) {
    ((std::string*)userp)->append((char*)contents, size * nmemb);
    return size * nmemb;
}

int main() {
    curl_global_init(CURL_GLOBAL_DEFAULT);
    CURL* curl = curl_easy_init();

    if (curl) {
        std::string response;
        struct curl_slist* headers = nullptr;
        headers = curl_slist_append(headers, "Content-Type: application/json");
        headers = curl_slist_append(headers, "X-API-Key: dika_dev_xxxxxxxxxxxxxxxx");

        std::string payload = R"({
            "q": "Cutting-edge neural translation and enterprise microservices.",
            "source": "en",
            "target": "fa",
            "tone": "academic"
        })";

        curl_easy_setopt(curl, CURLOPT_URL, "https://dika.irres.ir/api/v1/translate");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload.c_str());
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);

        CURLcode res = curl_easy_perform(curl);
        if (res == CURLE_OK) {
            std::cout << "پاسخ سرور دیکا:\n" << response << std::endl;
        } else {
            std::cerr << "خطای اتصال: " << curl_easy_strerror(res) << std::endl;
        }

        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }

    curl_global_cleanup();
    return 0;
}
```

### ۵. 🔷 سی‌شارپ و دات‌نت (.NET 8 / C#)
```csharp
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("X-API-Key", "dika_dev_xxxxxxxxxxxxxxxx");

        var payload = new
        {
            q = "High performance microservices architecture.",
            source = "en",
            target = "fa",
            tone = "technical"
        };

        var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
        var response = await client.PostAsync("https://dika.irres.ir/api/v1/translate", content);
        var json = await response.Content.ReadAsStringAsync();
        Console.WriteLine(json);
    }
}
```

### ۶. ☕ جاوا و کاتلین (Java 17+ / Kotlin / Android)
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class DikaClient {
    public static void main(String[] args) throws Exception {
        String jsonPayload = """
            {
                "q": "Next-generation multilingual translation and localization",
                "source": "en",
                "target": "fa",
                "tone": "academic"
            }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://dika.irres.ir/api/v1/translate"))
            .header("Content-Type", "application/json")
            .header("X-API-Key", "dika_dev_xxxxxxxxxxxxxxxx")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("Response Status: " + response.statusCode());
        System.out.println("Body: " + response.body());
    }
}
```

### ۷. 🐘 پی‌اچ‌پی (PHP 8.x / Laravel)
```php
<?php
$ch = curl_init('https://dika.irres.ir/api/v1/translate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: dika_dev_xxxxxxxxxxxxxxxx',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'q' => 'توسعه نرم‌افزارهای یکپارچه ابری با موتور دیکا',
        'source' => 'fa',
        'target' => 'en',
        'tone' => 'formal'
    ])
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
```

### ۸. 🐹 گو (Golang)
```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://dika.irres.ir/api/v1/translate"
	payload, _ := json.Marshal(map[string]interface{}{
		"q":      "Cloud native microservices with resilient AI pipelines",
		"source": "en",
		"target": "fa",
		"tone":   "technical",
	})

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
	req.Header.Set("X-API-Key", "dika_dev_xxxxxxxxxxxxxxxx")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

### ۹. 🦀 راست (Rust / reqwest)
```rust
use reqwest::header::{HeaderMap, HeaderValue, CONTENT_TYPE};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("dika_dev_xxxxxxxxxxxxxxxx"));
    headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));

    let payload = json!({
        "q": "High safety, memory-safe backend integration with Rust and Dika AI",
        "source": "en",
        "target": "fa",
        "tone": "academic"
    });

    let res = client.post("https://dika.irres.ir/api/v1/translate")
        .headers(headers)
        .json(&payload)
        .send()
        .await?
        .text()
        .await?;

    println!("{:#?}", res);
    Ok(())
}
```

### ۱۰. 🎯 دارت و فلاتر (Dart / Flutter Mobile)
```dart
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> translateText() async {
  final url = Uri.parse('https://dika.irres.ir/api/v1/translate');
  final response = await http.post(
    url,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'dika_dev_xxxxxxxxxxxxxxxx',
    },
    body: jsonEncode({
      'q': 'Smart cross-platform mobile translation with Dika AI',
      'source': 'en',
      'target': 'fa',
      'tone': 'conversational',
    }),
  );

  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    print('ترجمه: ${data["data"]["translations"][0]["translatedText"]}');
  }
}
```

### ۱۱. 💻 خط فرمان لینوکس، مک و ویندوز (cURL / Bash CLI)
```bash
curl -X POST "https://dika.irres.ir/api/v1/translate" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: dika_dev_xxxxxxxxxxxxxxxx" \
     -d '{
       "q": "Fast translation via terminal CLI",
       "source": "en",
       "target": "fa",
       "tone": "general"
     }'
```

### ۱۲. 📡 دریافت استریم بلادرنگ (Streaming SSE - Node.js / Browser)
```javascript
async function streamTranslation(text) {
    const response = await fetch('https://dika.irres.ir/api/v1/translate/stream', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'dika_dev_xxxxxxxxxxxxxxxx'
        },
        body: JSON.stringify({ text, source: 'en', target: 'fa' })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        const chunk = decoder.decode(value);
        console.log('قطعه دریافتی:', chunk);
    }
}
```

### ۱۳. 🌐 ویجت ۱ خطی دیکا برای وب‌سایت‌ها (Drop-in Translation Widget)
برای افزودن قابلیت تغییر زبان خودکار به هر سایتی، کافی است تگ زیر را در انتهای `<body>` قرار دهید:
```html
<script src="https://dika.irres.ir/dika_widget.js" 
        data-api-key="dika_dev_xxxxxxxxxxxxxxxx" 
        data-languages="fa,en,ar,tr,ru,fr,de" 
        data-position="bottom-left" 
        async></script>
```

---

## ۷. راهنمای استقرار و پایداری در سرور (Production Deployment)

### در ویندوز سرور (Windows Server & Plesk):
1. **استارت‌آپ خودکار با تسک اسکدولر:** اجرای فایل [register_autostart.bat](file:///c:/Users/Taimazus/Desktop/Irres.Dic/register_autostart.bat) با دسترسی Administrator.
2. **اجرا به عنوان سرویس ویندوز (Windows Service با NSSM):**
```cmd
nssm install DikaBackend "C:\path\to\publish_backend\run_server.bat"
nssm start DikaBackend
```

### در لینوکس (Ubuntu / Debian / CentOS):
1. کپی فایل [dika-backend.service](file:///c:/Users/Taimazus/Desktop/Irres.Dic/dika-backend.service) به مسیر `/etc/systemd/system/`.
2. فعال‌سازی و استارت سرویس:
```bash
sudo systemctl daemon-reload
sudo systemctl enable dika-backend
sudo systemctl start dika-backend
```
