# ارتباط سازمانی: تلگرام و ایتا

پیاده‌سازی: `backend/src/modules/communications/service.ts`

## ۱. اصل بنیادی

> هیچ توکنی هرگز در Frontend قرار نمی‌گیرد و هیچ «تحویل موفق» جعلی ثبت نمی‌شود.

مرورگر فقط `POST /api/civic/channels/:channelId/send` را صدا می‌زند. اعتبارنامه‌ها
(`TELEGRAM_BOT_TOKEN`, `EITAA_TOKEN`) تنها در محیط سرور خوانده می‌شوند.

## ۲. معماری آداپتور

```
CommunicationService
  ├── TelegramAdapter   → https://api.telegram.org/bot<token>/sendMessage
  └── EitaaAdapter      → درگاه ایتا
```

هر آداپتور سه قرارداد دارد:

```ts
interface ChannelAdapter {
  isConfigured(): boolean;
  buildDeepLink(handle, payload): string;
  send(handle, payload): Promise<DeliveryResult>;
}
```

## ۳. وضعیت واقعی تحویل

`outbound_messages.state` یکی از این‌هاست و هیچ‌کدام حدسی نیست:

| وضعیت | معنا |
|---|---|
| `queued` | در صف؛ هنوز تلاش نهایی انجام نشده |
| `delivered` | سرویس پیام‌رسان پاسخ موفق داد؛ `provider_message_id` ذخیره شد |
| `failed` | سرویس پاسخ خطا داد؛ متن خطا ذخیره شد |
| `unavailable` | **توکن پیکربندی نشده است** — پیام ارسال نشد |

در حالت `unavailable`، سامانه یک **Deep Link معتبر** می‌سازد
(`https://t.me/<handle>?text=…` یا `https://eitaa.com/<handle>`) تا اپراتور بتواند
دستی اقدام کند. پاسخ API شامل `humanState` فارسی است:

> «سرویس پیام‌رسان پیکربندی نشده است؛ فقط پیوند مستقیم ساخته شد.»

فضای کاری سازمان همین وضعیت را با چراغ رنگی نمایش می‌دهد. کاربر هرگز پیام
«ارسال شد» را نمی‌بیند مگر واقعاً ارسال شده باشد.

## ۴. پیام رسمی بین سازمان‌ها

جدا از پیام‌رسان‌های عمومی، سامانه یک کانال رسمی داخلی دارد:

```
POST /api/civic/org/:organizationId/messages
{
  "toOrganizationId": "…",
  "subject": "…",
  "body": "…",
  "priority": "critical|high|normal|low",
  "deadline": "2026-09-01T00:00:00Z",
  "actionRequested": true,
  "relatedCaseId": "…"
}
```

پیام در صندوق ورودی سازمان مقصد (فضای کاری → «پیام‌های سازمانی») ظاهر می‌شود،
می‌تواند به یک پرونده پیوند بخورد و در `audit_logs` ثبت می‌شود.

## ۵. پیکربندی

```env
TELEGRAM_BOT_TOKEN=          # خالی بگذارید تا حالت Deep Link فعال شود
EITAA_TOKEN=
```

بدون این متغیرها سامانه کاملاً کار می‌کند؛ فقط ارسال خودکار غیرفعال است و این
موضوع صریحاً به کاربر اعلام می‌شود.