OmniRoute/docs/i18n/fa/docs/architecture/CODEBASE_DOCUMENTATION.md

OmniRoute Codebase Documentation (فارسی)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

نسخه: v3.8.51 آخرین بهروزرسانی: 2026-06-28 مخاطبان: مهندسانی که در توسعه OmniRoute مشارکت میکنند یا یکپارچهسازیهایی را بر بستر آن میسازند.

برای نمودارهای سطحبالای معماری و منطق پشت هر زیرسیستم، فایل ARCHITECTURE.md را مطالعه کنید. برای بررسی عمیق زیرسیستمهای مجزا (Auto Combo، سرور MCP، سرور A2A، Skills، Memory، Cloud Agents، Resilience، Compression و غیره)، فایلهای اختصاصی آنها را در این پوشه docs/ ببینید.

این فایل آنچه امروز در مخزن وجود دارد را شرح میدهد تا یک مهندس جدید بتواند در ساختار درختی پیمایش کند، لایهبندی زمان اجرا را درک کند و بداند کد را کجا اضافه کند، بدون آنکه ماژولهای جدیدی ابداع کند.

---

1. پشته فناوری

موضوع	انتخاب
چارچوب وب	Next.js 16 (App Router، خروجی مستقل، بدون میانافزار سراسری)
زبان	TypeScript 6.0+ — هدف ES2022،‏ module: esnext،‏ moduleResolution: bundler،‏ strict: false
زمان اجرا	Node.js >=22.22.2 <23 یا >=24.0.0 <27 (اعمالشده از طریق engines و SUPPORTED_NODE_RANGE)
پایگاه داده	SQLite از طریق better-sqlite3 (تکنمونه، ثبت وقایع WAL)
دسکتاپ	Electron 41 + electron-builder 26.10 (فضای کاری جداگانه در electron/)
آزمونها	اجراکننده آزمون بومی Node (واحد/یکپارچهسازی)، Vitest (MCP، autoCombo، کش)، Playwright (e2e + protocols-e2e)
ساخت	خروجی مستقل Next.js از طریق scripts/build/build-next-isolated.mjs
لینت/قالببندی	پیکربندی مسطح ESLint + Prettier (lint-staged از طریق پیشکامیت Husky)
سیستم ماژول	ESM در همهجا ("type": "module")
فضاهای کاری	فضای کاری npm — ‏open-sse تنها زیرفضای کاری است

نامهای مستعار مسیر (tsconfig.json):

• @/* → src/*
• @omniroute/open-sse → open-sse/index.ts
• @omniroute/open-sse/* → open-sse/*

پورت پیشفرض HTTP: 20128 (API و داشبورد فرایند یکسانی را به اشتراک میگذارند). پوشه دادهها متغیر محیطی DATA_DIR است که مقدار پیشفرض آن ~/.omniroute/ است.

---

2. ساختار مخزن

OmniRoute/
├── src/                  برنامه Next.js (App Router، کتابخانهها، دامنه، سرور، اجزای مشترک)
├── open-sse/             فضای کاری موتور استریم (@omniroute/open-sse)
├── electron/             پوشش دسکتاپ (فرایند اصلی Electron 41 + preload)
├── bin/                  نقاط ورود CLI (omniroute، reset-password)
├── tests/                آزمونهای واحد، یکپارچهسازی، e2e، protocols-e2e، مترجم، امنیت و دادههای آزمون
├── scripts/              اسکریپتهای کمکی ساخت، همگامسازی، بررسی، مهاجرت و زمان اجرا
├── docs/                 مستندات عمومی (این پوشه)
├── public/               داراییهای ایستا، مانیفست PWA، سرویسورکر
├── config/               نمونههای پیکربندی زمان اجرا
├── images/               داراییهای بازاریابی/تصاویر صفحه
├── _ideia/, _references/, _mono_repo/, _tasks/   یادداشتهای موقت / برنامهریزی داخلی (توزیع نمیشوند)
├── CLAUDE.md             قواعد مخزن برای Claude Code
├── AGENTS.md             مرجع عمیقتر معماری برای عاملها
├── package.json          v3.8.51، ریشه فضای کاری
└── tsconfig.json         نامهای مستعار مسیر + گزینههای اصلی کامپایلر

---

3. src/ — برنامه Next.js

src/
├── app/                  صفحات App Router و مسیرهای API
├── lib/                  کتابخانههای اصلی (پایگاه داده، احراز هویت، OAuth، مهارتها، حافظه و غیره)
├── domain/               لایه دامنه خالص (سیاست، جایگزینی، هزینه، قفلشدن و غیره)
├── server/               ماژولهای مختص سرور (مجوزدهی، cors، احراز هویت)
├── shared/               نوعها، ثابتها، اعتبارسنجی، قراردادها و ابزارهای کمکی (ایمن برای استفاده در مرزهای مختلف)
├── mitm/                 ابزارهای کمکی پروکسی مرد میانی برای یکپارچهسازی CLI
├── models/               فراداده مدلهای محلی / نامگذاری مستعار
├── sse/                  کنترلکنندههای قدیمی SSE که همچنان در src/ قرار دارند (نه open-sse/)
├── store/                مخازن وضعیت سمت کلاینت
├── middleware/           ابزارهای میانافزار در سطح مسیر (نه میانافزار سراسری Next.js)
├── scripts/              اسکریپتهای دروندرختی قابل واردکردن توسط کد برنامه
├── types/                نوعهای محیطی و مشترک TS
├── i18n/                 بستههای زبان
├── instrumentation.ts    هوک ابزاربندی Next.js
├── instrumentation-node.ts
└── proxy.ts              ابزار کمکی راهاندازی پروکسی سطح بالا

3.1 src/app/ — App Router

App Router هم رابط کاربری داشبورد و هم API عمومی/مدیریتی HTTP را ارائه میکند. هیچ میانافزار سراسریای وجود ندارد — رهگیری بهصورت مجزا برای هر مسیر انجام میشود.

بخشهای سطح بالا در src/app/:

مسیر	هدف
api/	همه مسیرهای API مبتنی بر HTTP (تفکیک زیر را ببینید)
a2a/	نقطه پایانی A2A مبتنی بر JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	سند کشف Agent Card مربوط به A2A
(dashboard)/	رابط کاربری داشبورد (گروه مسیر، بدون پیشوند URL)
auth/, login/, forgot-password/, callback/	جریانهای احراز هویت
landing/	صفحه بازاریابی/فرود
docs/	نمایشگر تعبیهشده مستندات API
status/, maintenance/, offline/	صفحات عملیاتی
privacy/, terms/	صفحات حقوقی
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	صفحات خطای ایستا
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	مرزهای خطا/بارگذاری فریمورک
layout.tsx, page.tsx, globals.css, manifest.ts	پوسته ریشه

3.1.1 src/app/(dashboard)/dashboard/ — صفحات رابط کاربری

agents، analytics، api-manager، audit، auto-combo، batch، cache، changelog، cli-tools، cloud-agents، combos، compression، context، costs، endpoint، health، limits، logs، memory، onboarding، playground، providers، search-tools، settings، skills، system، translator، usage، webhooks، بهعلاوه page.tsx ریشه، HomePageClient.tsx، BootstrapBanner.tsx.

3.1.2 src/app/api/ — گروههای سطح بالای API

src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   مدیریت سرویسهای تعبیهشده (9router، cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API عمومی سازگار با OpenAI
├── v1beta/     سازگاری به سبک Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — مدیریت سرویسهای تعبیهشده

مسیرهایی برای نصب، راهاندازی، توقف و پایش 9Router و CLIProxyAPI. همه مسیرها در رده LOCAL_ONLY طبقهبندی میشوند (فقط loopback، قانون قطعی شماره 17)، زیرا میتوانند npm install را فراخوانی کرده و فرایندهای فرزند ایجاد کنند.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             تابع کمکی getOrInitSupervisor()
│   ├── install/route.ts    POST — نصب npm از طریق execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — نصب نسخه جدیدتر با npm
│   ├── rotate-key/route.ts POST — تولید کلید API جدید + راهاندازی مجدد
│   ├── status/route.ts     GET  — وضعیت زنده + وضعیت DB + فراداده نسخه
│   └── auto-start/route.ts POST — تغییر وضعیت پرچم auto_start
├── cliproxy/
│   ├── _lib.ts             تابع کمکی getOrInitSupervisor()
│   ├── install/route.ts    POST — نصب npm
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — نصب نسخه جدیدتر با npm
│   ├── status/route.ts     GET  — وضعیت زنده + وضعیت DB + فراداده نسخه
│   └── auto-start/route.ts POST — تغییر وضعیت پرچم auto_start
└── [name]/
    └── logs/route.ts       GET  — دنباله زنده گزارشها با SSE (مشترک میان همه سرویسها)

رابط کاربری داشبورد مربوطه: src/app/(dashboard)/dashboard/providers/services/ — صفحهای با دو زبانه (CLIProxyAPI + 9Router). پراکسی معکوس برای رابط کاربری تعبیهشده 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

بررسی عمیق: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API عمومی سازگار با OpenAI

v1/
├── accounts/[id]/                       جستوجوی حساب
├── agents/tasks/[id]/, agents/tasks/    نقاط پایانی وظایف با سبک A2A
├── api/                                 توابع کمکی API داخلی که زیر v1/api ارائه میشوند
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API دستههای OpenAI
├── chat/completions/                    تکمیلهای چت (نقطه پایانی اصلی)
├── completions/                         تکمیلهای متنی قدیمی
├── embeddings/                          جاسازیها
├── files/[id]/, files/                  API فایلها
├── _helpers/                            توابع کمکی مشترک مسیر (بدون URL عمومی)
├── images/{edits, generations}/         تولید + ویرایش تصویر
├── issues/                              نقاط پایانی کمکی برای اولویتبندی
├── management/{proxies}/                مسیرهای محدود به مدیریت درون v1
├── messages/{count_tokens}/             سازگاری پیامها به سبک Anthropic
├── models/                              فهرست مدلها (`route.ts`، `catalog.ts`)
├── moderations/                         تعدیل محتوا
├── music/                               تولید موسیقی
├── providers/[provider]/                عملیات مختص هر ارائهدهنده
├── quotas/{check}                       بررسیهای سهمیه
├── registered-keys/                     مدیریت کلیدهای ثبتشده
├── rerank/                              رتبهبندی مجدد
├── responses/[...path]/                 API پاسخهای OpenAI (فراگیر)
├── search/                              جستوجوی وب
├── videos/                              تولید ویدئو
├── ws/                                  پل WebSocket
└── route.ts                             کنترلکننده نمایه

هر فایل مسیر از الگوی یکسانی پیروی میکند:

مسیر → پیشدرخواست CORS → اعتبارسنجی بدنه با Zod → احراز هویت اختیاری
     → اعمال خطمشی کلید API → واگذاری به کنترلکننده (open-sse)

v1beta/ سطح سازگاری به سبک Gemini است (یک پوشش نازک که درخواستها را به همان خط لوله open-sse/handlers/ ترجمه میکند).

3.2 src/lib/ — کتابخانههای اصلی

همیشه دادهها، همگامسازی، OAuth، مهارت، حافظه و موارد مشابه را از طریق این ماژولها وارد کنید. این جدول، دایرکتوریهای واقعی و فایلهای سطح بالای قابلتوجه را گروهبندی میکند.

ماژول	هدف
a2a/	سرور پروتکل A2A:‏ taskManager.ts، streaming.ts، taskExecution.ts، routingLogger.ts، ‏skills/ (۶ مهارت: تحلیل هزینه، گزارش سلامت، کشف ارائهدهنده، مدیریت سهمیه، مسیریابی هوشمند، فهرست قابلیتها)
acp/	پروتکل کنترل عامل:‏ index.ts، manager.ts، registry.ts
api/	ابزارهای کمکی API داخلی:‏ requireManagementAuth.ts، requireCliToolsAuth.ts، errorResponse.ts
auth/	managementPassword.ts (بازنشانی / هشکردن گذرواژه)
batches/	سرویس OpenAI Batches API ‏(service.ts)
catalog/	همگامسازی کاتالوگ OpenRouter ‏(openrouterCatalog.ts)
cloudAgent/	رجیستری عامل ابری:‏ api.ts، baseAgent.ts، db.ts، index.ts، registry.ts، types.ts، agents/{codex, devin, jules}.ts
combos/	ابزارهای کمکی تفکیک ترکیبها
compliance/	ممیزی + ممیزی ارائهدهنده:‏ index.ts، providerAudit.ts
config/	کد اتصال پیکربندی زمان اجرا
db/	ماژولهای دامنه SQLite (نگاه کنید به §3.2.1)
display/	ابزارهای کمکی رابط کاربری/نمایش که پاسخهای API از آنها استفاده میکنند
embeddings/	رجیستری سرویس تعبیهسازی
env/	بارگذاری + بررسی درونی محیط
evals/	زمان اجرای ارزیابی
guardrails/	piiMasker.ts، promptInjection.ts، visionBridge.ts، visionBridgeHelpers.ts، registry.ts، base.ts
jobs/	کارهای پسزمینه (autoUpdate.ts، …)
memory/	حافظه پایدار:‏ store.ts، cache.ts، retrieval.ts، summarization.ts، extraction.ts، injection.ts، qdrant.ts، settings.ts، verify.ts، schemas.ts، types.ts
monitoring/	observability.ts
oauth/	ماژولهای OAuth/واردسازی ارائهدهنده (۲۲ مورد):‏ agy، antigravity، claude، cline، codebuddy-cn، codex، cursor، devin-desktop، ghe-copilot، github، gitlab-duo، grok-cli-oauth، grok-cli، kilocode، kimi-coding، kiro، openference، qoder، trae، xai-oauth، zed-hosted، zed، بهعلاوه services/، utils/ و constants/oauth.ts
plugins/	بارگذار افزونه (index.ts)
promptCache/	prefixAnalyzer.ts، index.ts
providerModels/	چرخه عمر مدل مدیریتشده:‏ modelDiscovery.ts، managedModelImport.ts، managedAvailableModels.ts، cursorAgent.ts
providers/	ابزارهای کمکی ارائهدهنده:‏ catalog.ts، validation.ts، imageValidation.ts، claudeExtraUsage.ts، codexConnectionDefaults.ts، codexFastTier.ts، webCookieAuth.ts، managedAvailableModels.ts، requestDefaults.ts
resilience/	settings.ts — تنظیمات قطعکننده مدار، دوره انتظار و قفل موقت
runtime/	تشخیص قابلیتها در زمان اجرا
search/	executeWebSearch.ts
services/	چارچوب سرویسهای تعبیهشده:‏ ServiceSupervisor.ts (ناظر عمومی فرایند فرزند با قفل عملیات، بافر حلقوی و بررسیکننده سلامت)، bootstrap.ts (ثبت در سطح فرایند و شروع خودکار)، registry.ts (نگاشت ابزار ← ناظر)، apiKey.ts (مخزن کلید AES-256-GCM)، modelSync.ts (همگامسازی دورهای مدل)، ringBuffer.ts (بافر حلقوی گزارش ۵ مگابایتی)، healthCheck.ts (کاوش سلامت HTTP)، types.ts، embedWsProxy.ts (پراکسی WebSocket)، installers/{ninerouter,cliproxy}.ts. نگاه کنید به docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	کاتالوگ + مولد مهارتهای عامل:‏ catalog.ts ‏(getCatalog/getSkillById/filterCatalog/computeCoverage)، generator.ts ‏(generateAgentSkills → در skills/{id}/SKILL.md مینویسد)، openapiParser.ts (نقاط پایانی REST را از مشخصات OpenAPI استخراج میکند)، cliRegistryParser.ts (زیرفرمانهای CLI را از bin/cli-registry استخراج میکند)، schemas.ts ‏(Zod: AgentSkillSchema، SkillCoverageSchema، ListQuerySchema، GenerateBodySchema)، types.ts ‏(AgentSkill، SkillCoverage، SkillMarkdown، GeneratorReport). مسیرهای REST ‏(/api/agent-skills/*)، ابزارهای MCP ‏(omniroute_agent_skills_*) و مهارت A2A با نام list-capabilities از آن استفاده میکنند. نگاه کنید به AGENT-SKILLS.md.
skills/	چارچوب مهارت:‏ registry.ts، executor.ts، interception.ts، injection.ts، sandbox.ts، custom.ts، hybrid.ts، builtins.ts، a2a.ts، providerSettings.ts، schemas.ts، skillssh.ts، types.ts، بهعلاوه builtin/browser.ts
spend/	batchWriter.ts (بافر نوشتن با تأخیر)
sync/	bundle.ts، tokens.ts (همگامسازی ابری)
system/	ابزارهای کمکی سطح سیستم
translator/	کد اتصال سطحبالای مترجم (به open-sse/translator/ واگذار میکند)
usage/	حسابداری مصرف:‏ costCalculator.ts، tokenAccounting.ts، usageHistory.ts، aggregateHistory.ts، usageStats.ts، callLogs.ts، callLogArtifacts.ts، fetcher.ts، providerLimits.ts، migrations.ts
versionManager/	بهروزرسانی خودکار + مانیفست نسخه
ws/	پل WebSocket
zed-oauth/	جریان OAuth ویرایشگر Zed

فایلهای سطح بالای src/lib/:

• فایل barrel قدیمی localDb.ts حذف شده است — مصرفکنندگان ماژولهای مشخص src/lib/db/* را مستقیماً import میکنند.
• proxyHealth.ts, proxyLogger.ts, tokenHealthCheck.ts, localHealthCheck.ts
• apiBridgeServer.ts, cacheLayer.ts, semanticCache.ts, settingsCache.ts
• cloudSync.ts, initCloudSync.ts
• cloudflaredTunnel.ts, ngrokTunnel.ts, tailscaleTunnel.ts
• consoleInterceptor.ts, container.ts, gracefulShutdown.ts, idempotencyLayer.ts
• ipUtils.ts, logEnv.ts, logPayloads.ts, logRotation.ts
• modelAliasSeed.ts, modelCapabilities.ts, modelMetadataRegistry.ts, modelsDevSync.ts
• piiSanitizer.ts, pricingSync.ts
• apiKeyExposure.ts, cacheControlSettings.ts, dataPaths.ts, toolPolicy.ts
• translatorEvents.ts, usageDb.ts, usageAnalytics.ts, webhookDispatcher.ts

3.2.1 src/lib/db/

پایگاه دادهٔ SQLite تکنمونه (getDbInstance() در core.ts، با ثبت وقایع WAL). هرگز SQL خام را در routeها یا handlerها ننویسید — از این ماژولها استفاده کنید.

منبع: diagrams/db-schema-overview.mmd

ماژولهای دامنه (هرکدام مالک یک یا چند جدول هستند): apiKeys.ts, backup.ts, batches.ts, cleanup.ts, cliToolState.ts, combos.ts, commandCodeAuth.ts, compression.ts, compressionAnalytics.ts, compressionCacheStats.ts, compressionCombos.ts, compressionScheduler.ts, contextHandoffs.ts, core.ts, creditBalance.ts, databaseSettings.ts, detailedLogs.ts, domainState.ts, encryption.ts, evals.ts, files.ts, healthCheck.ts, jsonMigration.ts, migrationRunner.ts, modelComboMappings.ts, models.ts, oneproxy.ts, prompts.ts, providers.ts, providerLimits.ts, proxies.ts, quotaSnapshots.ts, readCache.ts, reasoningCache.ts, registeredKeys.ts, secrets.ts, sessionAccountAffinity.ts, settings.ts, stateReset.ts, stats.ts, syncTokens.ts, tierConfig.ts, upstreamProxy.ts, versionManager.ts, webhooks.ts.

migrations/ شامل 168 فایل نسخهبندیشدهٔ .sql (ایدِمپوتنت و تراکنشی) است و هنگام راهاندازی توسط migrationRunner.ts اجرا میشود.

جدولهای ایجادشده در مجموع migrationها (در کل 123 مورد):

a, account_key_limits, api_keys, batches, call_logs, combo_adaptation_state, combos, command_code_auth_sessions, compression_analytics, compression_cache_stats, compression_combo_assignments, compression_combos, context_handoffs, daily_usage_summary, db_meta, domain_budgets, domain_circuit_breakers, domain_cost_history, domain_fallback_chains, domain_lockout_state, eval_cases, eval_runs, eval_suites, files, hourly_usage_summary, key_value, mcp_tool_audit, memories, model_combo_mappings, provider_connections, provider_key_limits, provider_nodes, proxy_assignments, proxy_logs, proxy_registry, quota_snapshots, reasoning_cache, registered_keys, request_detail_logs, routing_decisions, semantic_cache, session_account_affinity, skill_executions, skills, sync_tokens, tier_assignments, tier_config, upstream_proxy_config, usage_history, version_manager, webhooks (بهعلاوهٔ جدولهای مجازی FTS5 برای جستوجوی حافظه).

3.3 src/domain/ — لایهٔ دامنه

منطق کسبوکار خالص، بدون I/O. توسط routeها و handlerها import میشود.

فایل	هدف
policyEngine.ts	حلکنندهٔ سیاست سطح بالا
fallbackPolicy.ts	درخت تصمیم fallback
costRules.ts	قواعد محاسبهٔ هزینه
lockoutPolicy.ts	تصمیمهای قفلکردن مدل
tagRouter.ts	مسیریابی مبتنی بر برچسب
comboResolver.ts	حل combo از درخواست → فهرست مقصد
connectionModelRules.ts	فیلترهای مدل برای هر اتصال
modelAvailability.ts	بررسی دسترسپذیری مدل
degradation.ts	گذارهای حالت تنزلیافته
providerExpiration.ts	تشخیص حساب/کلید منقضیشده
quotaCache.ts	تصمیمهای cacheشدهٔ سهمیه
responses.ts, omnirouteResponseMeta.ts	ابزارهای کمکی ساختار پاسخ
configAudit.ts	ممیزی تغییرات پیکربندی
assessment/	ارزیابی مدل (طبق RFC، بهطور جزئی پیادهسازی شده)
types.ts	typeهای مشترک دامنه

3.4 src/server/ — فقط سمت سرور

نمیتوان آن را از کامپوننتهای کلاینت import کرد.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        routeها را به عمومی یا مدیریتی دستهبندی میکند
│   ├── assertAuth.ts      ابزار کمکی assertion
│   ├── context.ts         context مجوزدهی برای هر درخواست
│   ├── headers.ts
│   ├── pipeline.ts        pipeline مجوزدهی
│   ├── policies/          سیاستهای عملیاتی
│   └── types.ts
└── cors/origins.ts        فهرست مجاز originهای CORS

3.5 src/shared/ — ایمن برای اشتراکگذاری

به زیرشاخههای متمرکز تقسیم شده است:

• constants/ — providers.ts (فهرست ارائهدهندگان اعتبارسنجیشده با Zod)، models.ts، modelSpecs.ts، modelCompat.ts، pricing.ts، cliTools.ts، cliCompatProviders.ts، routingStrategies.ts، comboConfigMode.ts، headers.ts، upstreamHeaders.ts (فهرست موارد ممنوع)، mcpScopes.ts، errorCodes.ts، publicApiRoutes.ts، batch.ts، batchEndpoints.ts، bodySize.ts، colors.ts، appConfig.ts، config.ts، sidebarVisibility.ts، visionBridgeDefaults.ts.
• validation/ — schemas.ts (حدود ۸۰ شِمای Zod)، compressionConfigSchemas.ts، providerSchema.ts، settingsSchemas.ts، helpers.ts.
• contracts/ — قراردادهای API عمومی منتشرشده در npm.
• types/ — انواع مشترک TS.
• utils/ — circuitBreaker.ts، apiAuth.ts، apiKey.ts، apiKeyPolicy.ts، api.ts، classify429.ts، cliCompat.ts، clipboard.ts، cloud.ts، cn.ts، cors.ts، featureFlags.ts، fetchTimeout.ts، formatting.ts، inputSanitizer.ts، logger.ts، machine.ts، machineId.ts، maskEmail.ts، modelCatalogSearch.ts، nodeRuntimeSupport.ts، parseApiKeys.ts، providerHints.ts، providerModelAliases.ts، rateLimiter.ts، releaseNotes.ts، a11yAudit.ts، بهعلاوه هوکها/کامپوننتهای داشبورد در services/، network/، middleware/، schemas/، hooks/، components/.

---

4. open-sse/ — فضای کاری موتور استریم

یک فضای کاری مستقل npm که با نام @omniroute/open-sse منتشر میشود. این فضا مسئول پردازش درخواستها، اجراگرها، مترجمها، سرویسها، تبدیلکننده و سرور MCP است.

open-sse/
├── index.ts                خروجیهای عمومی
├── package.json            مانیفست فضای کاری
├── tsconfig.json
├── types.d.ts
├── config/                 رجیستریهای ارائهدهندگان، پروفایلهای هدر، هویت، …
├── handlers/               هندلرهای درخواست (چت، امبدینگ، صوت، تصویر، …)
├── executors/              108 اجراگر HTTP مختص ارائهدهندگان
├── translator/             تبدیل قالب (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            تبدیلکننده استریم Responses API ↔ Chat Completions
├── services/               بیش از 80 ماژول سرویس (ترکیبها، جایگزینی، سهمیهها، هویت، …)
├── utils/                  ابزارهای کمکی استریم، کلاینت TLS، AWS SigV4، واکشی پروکسی، …
└── mcp-server/             سرور MCP (3 روش انتقال، 33 محدوده، 110 ابزار)

4.1 open-sse/handlers/

هندلر	هدف
chatCore.ts	خط لوله اصلی چت (کش، محدودیت نرخ، مسیریابی ترکیبی، اعزام اجراگر)
responsesHandler.ts	نقطه ورود OpenAI Responses API
embeddings.ts	امبدینگها
imageGeneration.ts	تولید تصویر
audioSpeech.ts	تبدیل متن به گفتار
audioTranscription.ts	تبدیل گفتار به متن
videoGeneration.ts	تولید ویدئو
musicGeneration.ts	تولید موسیقی
rerank.ts	رتبهبندی مجدد
moderations.ts	تعدیل محتوا
search.ts	جستوجوی وب
sseParser.ts	تجزیهگر رویداد SSE
usageExtractor.ts	استخراج تعداد توکنها از استریمهای بالادستی
responseSanitizer.ts	حذف نویز مختص ارائهدهنده
responseTranslator.ts	لایه اتصال میان پاسخ ارائهدهنده و لایه مترجم

4.2 open-sse/executors/

108 اجراگر ارائهدهنده که هر یک BaseExecutor (base.ts) را گسترش میدهند:

antigravity, azure-openai, blackbox-web, cliproxyapi, chatgpt-web-codex, cloudflare-ai, codex, commandCode, cursor, default, devin-cli, muse-spark-web, nlpcloud, opencode, perplexity-web, petals, pollinations, qoder, vertex, devin-desktop، بهعلاوه claudeIdentity.ts (ابزار کمکی مشترک هویت) و index.ts (رجیستری).

توجه: ارائهدهندگانی که در اینجا فهرست نشدهاند، توسط default.ts و با استفاده از اجراگر عمومی سازگار با OpenAI سرویسدهی میشوند. کاتالوگ کامل ارائهدهندگان (355 ارائهدهنده) در src/shared/constants/providers.ts قرار دارد.

4.3 open-sse/translator/

ترجمه بهصورت هابومحور (OpenAI هاب است).

• 9 مترجم درخواست (translator/request/): antigravity-to-openai, claude-to-gemini, claude-to-openai, gemini-to-openai, openai-responses, openai-to-claude, openai-to-cursor, openai-to-gemini, openai-to-kiro.
• 9 مترجم پاسخ (translator/response/): claude-to-openai, cursor-to-openai, gemini-to-claude, gemini-to-openai, kiro-to-openai, openai-responses, openai-to-antigravity, openai-to-claude.
• 9 ابزار کمکی (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper، بهعلاوه آزمونهای ابزارهای کمکی.
• ابزارهای کمکی تصویر (translator/image/sizeMapper.ts).
• سطح بالا: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — تبدیلکننده Responses API ↔ Chat Completions مبتنی بر TransformStream (مورد استفاده توسط مسیر فراگیر responses/).

4.5 open-sse/services/

موارد برجسته (فهرست کامل در open-sse/services/):

موضوع	فایلها
مسیریابی ترکیبی	combo.ts (19 راهبرد)، comboConfig.ts، comboMetrics.ts، comboManifestMetrics.ts، comboAgentMiddleware.ts
موتور ترکیبی خودکار	autoCombo/ — engine.ts، scoring.ts، taskFitness.ts، virtualFactory.ts، modePacks.ts، autoPrefix.ts، persistence.ts، providerDiversity.ts، providerRegistryAccessor.ts، routerStrategy.ts، selfHealing.ts، index.ts
تابآوری	accountFallback.ts (دوره انتظار + قفلشدن)، errorClassifier.ts، emergencyFallback.ts، rateLimitManager.ts، rateLimitSemaphore.ts، accountSemaphore.ts، accountSelector.ts
سهمیهها	quotaMonitor.ts، quotaPreflight.ts، bailianQuotaFetcher.ts، codexQuotaFetcher.ts، deepseekQuotaFetcher.ts، openrouterQuotaFetcher.ts، openrouterFreeWindow.ts، crofUsageFetcher.ts، antigravityCredits.ts
ذخیرهسازی موقت	reasoningCache.ts، searchCache.ts، signatureCache.ts، requestDedup.ts
هوشمندی مسیریابی	intentClassifier.ts، taskAwareRouter.ts، backgroundTaskDetector.ts، volumeDetector.ts، wildcardRouter.ts، workflowFSM.ts، specificityDetector.ts، specificityRules.ts، specificityTypes.ts
مدیریت مدل	modelCapabilities.ts، modelDeprecation.ts، modelFamilyFallback.ts، modelStrip.ts، model.ts، provider.ts، providerRequestDefaults.ts، providerCostData.ts، payloadRules.ts
فشردهسازی	compression/ — سیمکشی کامل موتور فشردهسازی
توکن + نشست	tokenRefresh.ts، sessionManager.ts، apiKeyRotator.ts، contextManager.ts، contextHandoff.ts، systemPrompt.ts، roleNormalizer.ts، responsesInputSanitizer.ts، toolSchemaSanitizer.ts، toolLimitDetector.ts، thinkingBudget.ts
سطح / مانیفست	tierResolver.ts، tierConfig.ts، tierDefaults.json، tierTypes.ts، manifestAdapter.ts
IP / شبکه	ipFilter.ts، webSearchFallback.ts
دستهها	batchProcessor.ts
میزان استفاده	usage.ts

4.6 open-sse/mcp-server/

• 110 ابزار منحصربهفرد در server.ts سیمکشی شدهاند (45 ابزار استاندارد در schemas/tools.ts + ماژولهای حافظه، مهارتها، مهارتهای GitHub، مخزن، بازیوارسازی، افزونه، Notion، Obsidian، پیکره محلی و فشردهسازی — اجتماع آنها توسط countUniqueMcpTools شمارش میشود).
• 3 روش انتقال: stdio، HTTP Streamable، SSE.
• 33 محدوده دسترسی در زمان اجرا اعمال میشوند — فهرست پایه در src/shared/constants/mcpScopes.ts قرار دارد و مجموعه کامل، اجتماع محدودههای اعلامشده توسط هر ماژول ابزار است.
• جدول حسابرسی: mcp_tool_audit (توسط audit.ts پر میشود).
• فایلها: server.ts، index.ts، httpTransport.ts، audit.ts، scopeEnforcement.ts، runtimeHeartbeat.ts، descriptionCompressor.ts، schemas/{tools, a2a, audit, index}.ts، tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts، بهعلاوه آزمونهای موجود در __tests__/.
• برای مشاهده فهرست کامل ابزارها، به MCP-SERVER.md مراجعه کنید.

4.7 open-sse/config/

رجیستریهای ارائهدهندگان (providerRegistry.ts، providerModels.ts، providerHeaderProfiles.ts)، رجیستریهای مدل بهازای هر قالب (audioRegistry.ts، embeddingRegistry.ts، imageRegistry.ts، moderationRegistry.ts، musicRegistry.ts، rerankRegistry.ts، searchRegistry.ts، videoRegistry.ts)، ابزارهای کمکی هویت (codexIdentity.ts، codexInstructions.ts، anthropicHeaders.ts، antigravityUpstream.ts، antigravityModelAliases.ts، cliFingerprints.ts، toolCloaking.ts، defaultThinkingSignature.ts)، ابزارهای کمکی اعتبارنامه (credentialLoader.ts، codexClient.ts) و آداپتورهای ابری (azureAi.ts، bedrock.ts، datarobot.ts، glmProvider.ts، maritalk.ts، oci.ts، petals.ts، runway.ts، sap.ts، watsonx.ts، ollamaModels.ts، errorConfig.ts، constants.ts، registryUtils.ts).

4.8 open-sse/utils/

اجزای پایهٔ استریم و ابزارهای کمکی ارائهدهنده: stream.ts، streamHandler.ts، streamHelpers.ts، streamPayloadCollector.ts، streamReadiness.ts، sseHeartbeat.ts، proxyFetch.ts، proxyDispatcher.ts، tlsClient.ts، networkProxy.ts، awsSigV4.ts، cacheControlPolicy.ts، cursorChecksum.ts، cursorAgentProtobuf.ts، cursorVersionDetector.ts، comfyuiClient.ts، kieTask.ts، bypassHandler.ts، aiSdkCompat.ts، thinkTagParser.ts، urlSanitize.ts، usageTracking.ts، requestLogger.ts، progressTracker.ts، cors.ts، error.ts، logger.ts، sleep.ts، ollamaTransform.ts.

---

5. electron/ — پوشش دسکتاپ

electron/
├── main.js                  فرایند اصلی Electron
├── preload.js               پل پیشبارگذاری (contextIsolation فعال است)
├── types.d.ts
├── package.json             پیکربندی electron-builder، نسخهٔ 3.8.51
├── README.md
├── assets/                  منابع ساخت (آیکونها، مجوزها، …)
├── node_modules/            node_modules اختصاصی (better-sqlite3، electron-updater)
└── dist-electron/           خروجی ساخت (commit نمیشود)

پنج اسکریپت npm در ریشهٔ فضای کاری وجود دارد: electron:dev، electron:build، electron:build:{win,mac,linux}، electron:smoke:packaged. بهروزرسانی خودکار از طریق electron-updater انجام میشود و به فید انتشار GitHub اشاره دارد.

---

6. bin/ — رابط خط فرمان

bin/
├── omniroute.mjs           ورودی اصلی رابط خط فرمان (Node ESM)
├── reset-password.mjs      بازنشانی گذرواژهٔ مدیریت از طریق رابط خط فرمان
├── mcp-server.mjs          راهانداز سرور MCP (stdio)
├── nodeRuntimeSupport.mjs  محافظ نسخهٔ Node
└── cli/
    ├── program.mjs         سازندهٔ برنامهٔ Commander
    ├── runtime.mjs         ابزار کمکی withRuntime (ابتدا سرور/در صورت شکست پایگاه داده)
    ├── output.mjs          قالببندهای خروجی (json/jsonl/table/csv)
    ├── i18n.mjs            ابزار کمکی t() با زبانها
    ├── api.mjs             ابزار کمکی fetch برای API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    ثبت فرمانها
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (یک فایل برای هر فرمان/گروه)

دو فایل اجرایی در package.json ← bin ارائه میشوند:

• omniroute ← bin/omniroute.mjs
• omniroute-reset-password ← bin/reset-password.mjs

---

7. tests/

دایرکتوری	نوع
tests/unit/	تستهای واحد با اجراکنندهٔ بومی تست Node (۱۸۲۱ فایل، بهعلاوهٔ زیردایرکتوریهای api/، auth/ و authz/)
tests/integration/	تستهای بینماژولی و وضعیت پایگاه داده
tests/e2e/	تستهای رابط کاربری Playwright
tests/e2e/protocol-clients.test.ts	تست سرتاسری پروتکلهای MCP/A2A
tests/translator/	تستهای مختص مترجم
tests/security/	رگرسیونهای امنیتی
tests/load/	تستهای بار / فشار
tests/golden-set/	خروجیهای مرجع برای رگرسیونهای مترجم
tests/helpers/، tests/fixtures/، tests/manual/	پشتیبانی

فرمانهای متداول:

فرمان	آنچه اجرا میکند
npm run test:unit	همهٔ فایلهای tests/unit/*.test.ts با اجراکنندهٔ تست Node (همزمانی ۱۰)
npm run test:vitest	مجموعهتست Vitest‏ (MCP، autoCombo، cache)
npm run test:e2e	مجموعهتست رابط کاربری Playwright
npm run test:protocols:e2e	تست سرتاسری پروتکلهای MCP و A2A
npm run test:coverage	آستانهٔ پوشش (≥۶۰٪ خطوط/عبارتها/توابع/شاخهها)
node --import tsx/esm --test tests/unit/<file>.test.ts	اجرای یک فایل

---

8. scripts/

بر اساس کاربرد در 6 زیرپوشه سازماندهی شده است.

• scripts/build/ — build-next-isolated.mjs، prepublish.ts، prepare-electron-standalone.mjs، pack-artifact-policy.ts، validate-pack-artifact.ts، postinstall.mjs، postinstallSupport.mjs، uninstall.mjs، bootstrap-env.mjs، runtime-env.mjs، native-binary-compat.mjs.
• scripts/dev/ — run-next.mjs، run-next-playwright.mjs، run-standalone.mjs، standalone-server-ws.mjs، responses-ws-proxy.mjs، v1-ws-bridge.mjs، smoke-electron-packaged.mjs، run-playwright-tests.mjs، run-ecosystem-tests.mjs، run-protocol-clients-tests.mjs، sync-env.mjs، healthcheck.mjs، system-info.mjs.
• scripts/check/ — check-cycles.mjs، check-docs-sync.mjs، check-docs-counts-sync.mjs، check-env-doc-sync.mjs، check-deprecated-versions.mjs، check-route-validation.mjs، check-t11-any-budget.mjs، check-pr-test-policy.mjs، check-supported-node-runtime.ts، test-report-summary.mjs.
• scripts/docs/ — generate-docs-index.mjs، gen-provider-reference.ts.
• scripts/i18n/ — generate-multilang.mjs، run-visual-qa.mjs، generate-qa-checklist.mjs، apply-priority-overrides.mjs، validate_translation.py، check_translations.py، i18n_autotranslate.py، untranslatable-keys.json.
• scripts/ad-hoc/ — cursor-tap.cjs، sync-cursor-models.mjs، migrate-env.mjs، dbsetup.js.

---

9. خط لوله درخواست (خلاصه)

منبع: diagrams/request-pipeline.mmd

درخواست کلاینت
  → /v1/chat/completions (route.ts)
     بررسی پیشدرخواست CORS
     اعتبارسنجی Zod (chatCompletionsSchema در shared/validation/schemas.ts)
     احراز هویت (extractApiKey + isValidApiKey یا requireManagementAuth)
     موتور سیاستگذاری (src/server/authz/pipeline.ts)
     محافظها (پوشاننده PII، تزریق پرامپت، پل بینایی)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     بررسی کش (کش معنایی + کش خواندن)
     محدودیت نرخ (rateLimitManager، accountSemaphore)
     مسیریابی ترکیبی (اگر مدل به یک ترکیب تفکیک شود)
       comboResolver → حلقه برای هر مقصد → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       واکشی از بالادست → تلاش مجدد/وقفه تصاعدی از طریق accountFallback
     translateResponse() (open-sse/translator/response/*)
     جریان SSE یا پاسخ JSON
     اگر Responses API باشد: TransformStream از طریق open-sse/transformer/responsesTransformer.ts
  → ممیزی انطباق (src/lib/compliance/)
  → پاسخ به کلاینت

وضعیت زمان اجرای تابآوری (سه سازوکار)

سازوکار	دامنه	محل
قطعکننده مدار ارائهدهنده	کل ارائهدهنده	src/shared/utils/circuitBreaker.ts، ذخیرهشده در domain_circuit_breakers
دوره انتظار اتصال	یک حساب/کلید	markAccountUnavailable() در src/sse/services/auth.ts؛ مصرفشده توسط accountFallback.checkFallbackError()
قفل مدل	ارائهدهنده + اتصال + مدل	open-sse/services/accountFallback.ts، ذخیرهشده در domain_lockout_state

به RESILIENCE_GUIDE.md و بخش اختصاصی در CLAUDE.md مراجعه کنید.

---

10. نحوه مشارکت

افزودن یک ارائهدهنده جدید

1. آن را در src/shared/constants/providers.ts ثبت کنید (هنگام بارگذاری با Zod اعتبارسنجی میشود).
2. اگر منطق سفارشی لازم است، یک اجراکننده در open-sse/executors/ اضافه کنید (BaseExecutor را گسترش دهید).
3. اگر از قالب OpenAI استفاده نمیکند، یک مترجم در open-sse/translator/ اضافه کنید.
4. اگر مبتنی بر OAuth است، پیکربندی را در src/lib/oauth/providers/ و src/lib/oauth/services/ اضافه کنید.
5. مدلها را در open-sse/config/providerRegistry.ts (یا رجیستری مختص قالب در open-sse/config/) ثبت کنید.
6. تستها را در tests/unit/ بنویسید.

افزودن یک مسیر API جدید

1. فایل src/app/api/your-route/route.ts را ایجاد کنید.
2. از این الگو پیروی کنید: CORS ← اعتبارسنجی بدنه با Zod ← احراز هویت ← واگذاری به کنترلکننده.
3. اگر ساختار درخواست جدید است، اسکیمای Zod را در src/shared/validation/schemas.ts اضافه کنید.
4. اگر فقط برای مدیریت است، مسیر را به src/shared/constants/publicApiRoutes.ts (فهرست مسدود برای سطح عمومی API) اضافه کنید.
5. تستها را در tests/unit/ اضافه کنید.
6. فایلهای docs/reference/API_REFERENCE.md و docs/openapi.yaml را بهروزرسانی کنید.

افزودن یک ماژول DB جدید

1. فایل src/lib/db/yourModule.ts را ایجاد و getDbInstance() را از ./core.ts وارد کنید.
2. توابع CRUD مربوط به دامنه خود را صادر کنید.
3. اگر جدولهای جدیدی وجود دارند، یک مهاجرت در src/lib/db/migrations/ اضافه کنید که شمارهگذاری ترتیبی داشته، همتوان باشد و درون تراکنش اجرا شود.
4. واردکنندهها باید مستقیماً از @/lib/db/yourModule ایمپورت کنند (بدون barrel — لایه بازصادرکردن قدیمی localDb.ts حذف شده است).
5. تستها را در tests/unit/ اضافه کنید.

افزودن یک ابزار MCP جدید

1. تعریف ابزار را در open-sse/mcp-server/tools/ اضافه کنید (یا open-sse/mcp-server/schemas/tools.ts را گسترش دهید).
2. حوزه یا حوزههای مناسب را در src/shared/constants/mcpScopes.ts اختصاص دهید.
3. ابزار را در open-sse/mcp-server/server.ts ثبت کنید.
4. تستها را در open-sse/mcp-server/__tests__/ اضافه کنید.
5. MCP-SERVER.md را بهروزرسانی کنید.

افزودن یک مهارت A2A جدید

به A2A-SERVER.md § افزودن یک مهارت جدید مراجعه کنید. مهارتها در src/lib/a2a/skills/ قرار دارند و از طریق مدیر وظایف A2A ثبت میشوند.

---

11. قراردادها

• سبک کد: تورفتگی ۲ فاصلهای، نقلقول دوتایی، عرض ۱۰۰ نویسه، نقطهویرگول، ویرگول انتهایی es5 — بهوسیله Prettier و از طریق lint-staged اعمال میشود.
• ایمپورتها: خارجی ← داخلی (@/، @omniroute/open-sse) ← نسبی.
• نامگذاری: فایلها بهصورت camelCase یا kebab-case، مؤلفهها بهصورت PascalCase، ثابتها بهصورت UPPER_SNAKE.
• ESLint: قوانین no-eval، no-implied-eval و no-new-func در همهجا برابر error هستند؛ no-explicit-any در open-sse/ و tests/ برابر warn و در سایر بخشها برابر error است.
• TypeScript: مقدار strict: false است (رویکرد موروثی). برای مرزهای بین ماژولها، انواع صریح را بر استنتاج نوع ترجیح دهید.
• پایگاه داده: هرگز SQL خام را در مسیرها یا کنترلکنندهها ننویسید — همیشه از ماژولهای src/lib/db/ استفاده کنید. هرگز بهصورت barrel ایمپورت نکنید — مستقیماً از ماژولهای مشخص src/lib/db/* استفاده کنید.
• نوعدهی موجودیتهای DB (#3512): تابعی که شکل ردیف یک جدول DB را مینویسد یا میخواند، باید یک رابط نامگذاریشده TS را بپذیرد یا برگرداند که ستونهای آن جدول را بهصورت ۱:۱ بازتاب میدهد، نه any یا یک نوع بینام درونخطی در محل فراخوانی. رابط را در کنار تابع قرار دهید (برای مثال export interface UsageEntry در src/lib/usage/usageHistory.ts بالای saveRequestUsage)، فیلدهای منفرد را هنگامی که نویسندههای مختلف ردیف را بهتدریج پر میکنند، اختیاری/تهیپذیر نگه دارید و برای فیلدی که شکل آن بین فراخوانها متفاوت است، unknown را بر any ترجیح دهید (این موضوع را روی فیلد مستند کنید؛ برای مثال UsageEntry.tokens هم داده خام با شکل ارائهدهنده و هم شکل نرمالشده را میپذیرد). وقتی تعداد anyهای یک فایل به این روش به صفر رسید، آن را به فهرست مجاز check:any-budget:t11 اضافه کنید (scripts/check/check-t11-any-budget.mjs، maxAny: 0) تا امکان پسرفت وجود نداشته باشد. این یک قرارداد برای نخستین بخش کار است — پاکسازی گستردهتر «نبود any بینام» در باقی کدبیس بهصورت تدریجی انجام میشود.
• خطاها: از try/catch همراه با انواع خطای مشخص استفاده کنید و با زمینه pino لاگ بگیرید. هرگز خطاها را در جریانهای SSE بیصدا نادیده نگیرید؛ برای پاکسازی از سیگنالهای لغو استفاده کنید.
• امنیت: هرگز از eval() / new Function() / ارزیابی ضمنی استفاده نکنید. همه ورودیها را با Zod اعتبارسنجی کنید. اطلاعات اعتبارسنجی را در حالت ذخیرهشده رمزگذاری کنید (AES-256-GCM). فهرست مسدود src/shared/constants/upstreamHeaders.ts را با لایه پاکسازی/اعتبارسنجی همگام نگه دارید.
• کامیتها: Conventional Commits — feat(scope): subject. حوزههای مجاز: db، sse، oauth، dashboard، api، cli، docker، ci، mcp، a2a، memory، skills.
• شاخهها: پیشوندهای feat/، fix/، refactor/، docs/، test/، chore/. هرگز مستقیماً روی main کامیت نکنید.
• Husky: مرحله pre-commit دستورهای lint-staged + check:docs-sync + check:any-budget:t11 را اجرا میکند؛ مرحله pre-push نیز check:any-budget:t11 + check:tracked-artifacts را اجرا میکند (گیتهای سریع؛ test:unit مستثنا است).

---

12. قوانین سختگیرانه (از CLAUDE.md)

1. هرگز اطلاعات محرمانه یا اعتبارنامهها را commit نکنید.
2. هرگز barrel import انجام ندهید — مستقیماً از ماژولهای مشخص src/lib/db/* استفاده کنید.
3. هرگز از eval() / new Function() / eval ضمنی استفاده نکنید.
4. هرگز مستقیماً در main، commit نکنید.
5. هرگز SQL خام را در routeها ننویسید — همیشه از ماژولهای src/lib/db/ استفاده کنید.
6. هرگز خطاها را در جریانهای SSE بدون اطلاع نادیده نگیرید.
7. همیشه ورودیها را با schemaهای Zod اعتبارسنجی کنید.
8. هنگام تغییر کد production، همیشه تستها را نیز اضافه کنید.
9. پوشش تست باید ≥ 60% باقی بماند (statementها، lineها، functionها و branchها).

---

13. همچنین ببینید

• ARCHITECTURE.md — معماری سطح بالا و مسئولیتهای ماژولها.
• API_REFERENCE.md — مرجع API عمومی و مدیریتی.
• FEATURES.md — ماتریس قابلیتها و نکات برجسته نسخهها.
• RESILIENCE_GUIDE.md — بررسی عمیق circuit breaker، cooldown و lockout.
• AUTO-COMBO.md — امتیازدهی و راهبردهای Auto Combo.
• MCP-SERVER.md — فهرست کامل ابزارهای MCP و روشهای انتقال.
• A2A-SERVER.md — مهارتها و سازوکار کشف پروتکل A2A.
• COMPRESSION_GUIDE.md — فشردهسازی RTK و Caveman.
• CLI-TOOLS.md — یکپارچهسازیهای CLI.
• ELECTRON_GUIDE.md (در صورت وجود)، DOCKER_GUIDE.md، FLY_IO_DEPLOYMENT_GUIDE.md، VM_DEPLOYMENT_GUIDE.md، TERMUX_GUIDE.md، PWA_GUIDE.md — اهداف استقرار.
• TROUBLESHOOTING.md — مشکلات عملیاتی رایج.
• CONTRIBUTING.md — گردشکار مشارکتکنندگان.
• CLAUDE.md — قوانین مخزن برای Claude Code (مرجع اصلی بسیاری از قراردادهای بالا).
• AGENTS.md — مرجع معماری عمیقتر که عاملها از آن استفاده میکنند.