# ارتقای سطح انترپرایز (نسخه تیر ۱۴۰۵ — دور سوم)

## ۱) استخر کلید API با سویچ خودکار (Key-Pool Failover)

**درخواست:** استفاده از کلید دوم به‌عنوان جایگزین؛ وقتی کلید اصلی تمام شد، به‌صورت خودکار روی کلید دوم سویچ شود.

**پیاده‌سازی:** ماژول جدید `src/lib/llm-keys.server.ts`

- چند کلید در یک استخر اولویت‌دار نگهداری می‌شوند؛ **هر کلید endpoint و مدل‌های مخصوص خودش را دارد** (کلید اصلی = Gemini روی endpoint گوگل، کلید جایگزین = سرویس OpenAI-compatible).
- خطاهای «اتمام کلید» (۴۲۹ محدودیت/سهمیه، ۴۰۲ اتمام اعتبار، ۴۰۱/۴۰۳ کلید نامعتبر) از خطاهای گذرا (۵۰۳ و…) تفکیک می‌شوند:
  - خطای گذرا → تلاش مجدد با backoff روی همان کلید
  - اتمام کلید → کلید وارد دوره خنک‌سازی (cooldown) می‌شود و **بلافاصله کلید بعدی جایگزین می‌شود**
- دوره‌های خنک‌سازی: ۴۲۹ نرخ = ۱۰ دقیقه، ۴۲۹ سهمیه روزانه = ۳ ساعت، ۴۰۲ = ۶ ساعت، ۴۰۱/۴۰۳ = ۱۲ ساعت. پس از پایان cooldown، به کلید اصلی برمی‌گردد.
- اگر همه کلیدها در cooldown باشند، باز هم همه امتحان می‌شوند (بن‌بست وجود ندارد).
- در برچسب مدل داخل ضمیمه فنی گزارش، استفاده از کلید جایگزین شفاف اعلام می‌شود: «… — کلید جایگزین (سویچ خودکار)».
- کلیدها هرگز به‌صورت کامل در لاگ‌ها نمایش داده نمی‌شوند (masking).
- روی هر دو مسیر اعمال شد: خط لوله تحلیل اسناد (`analyze.functions.ts`) و چت‌بات گزارش (`chatbot.functions.ts`).

**پیکربندی (`.env`):**

```
LLM_FALLBACK_API_KEY=sk-…            # کلید جایگزین
LLM_FALLBACK_BASE_URL=…              # endpoint سرویس همان کلید
LLM_FALLBACK_MODEL_PRO=gpt-4o
LLM_FALLBACK_MODEL_FREE=gpt-4o-mini
# کلیدهای بیشتر: LLM_API_KEY_2..9 + LLM_BASE_URL_2..9 + LLM_MODEL_PRO_2..9
```

## ۲) مهر یکپارچگی گزارش (Tamper-Evidence)

- انتهای هر گزارش تولیدشده، بخش «مهر یکپارچگی گزارش» درج می‌شود: هش SHA-256 متن گزارش + زمان تولید (ISO).
- هر تغییر بعدی در متن، مهر را نامعتبر می‌کند — قابلیت راستی‌آزمایی برای اسناد حقوقی.
- پیاده‌سازی: `src/legacy/utils/reportAudit.ts` (Web Crypto).

## ۳) سوابق خودکار گزارش‌ها (Audit Trail)

- هر گزارش تحویل‌شده به‌صورت خودکار به‌عنوان نسخه (snapshot) با زمان، هش، مدل استفاده‌شده و EOT محاسبه‌شده ذخیره می‌شود (۱۰ نسخه آخر، localStorage با کلید `cm.reportHistory.v1`).
- هیچ خروجی تولیدشده‌ای دیگر از بین نمی‌رود؛ سوابق در فایل پشتیبان JSON هم گنجانده می‌شود.

## ۴) پشتیبان‌گیری یک‌کلیکه (Data Portability)

- دکمه جدید «💾 پشتیبان‌گیری (JSON)» در نوار اقدامات صفحه تحلیل تاخیرات.
- خروجی: فایل JSON شامل رویدادها، روش منتخب، گزارش جاری، خلاصه نتایج، متادیتای برنامه زمان‌بندی و سوابق ۱۰ گزارش آخر.

## فایل‌های تغییریافته/جدید

- **جدید:** `src/lib/llm-keys.server.ts`، `src/legacy/utils/reportAudit.ts`
- **تغییر:** `src/lib/ai-gateway.server.ts`، `src/lib/ai/analyze.functions.ts`، `src/lib/ai/chatbot.functions.ts`، `src/legacy/components/delay/DelayAnalysisPage.tsx`، `src/legacy/components/delay/StickyActionBar.tsx`، `.env`، `.env.example`

## نکته امنیتی

کلید جایگزین فقط در `.env` (خارج از گیت) ذخیره شده است؛ در کد منبع هاردکد نشده. اگر کلید در کانال ناامنی به اشتراک گذاشته شده، توصیه می‌شود پس از راه‌اندازی، از پنل سرویس‌دهنده rotate شود.