Files
2026-10-01 01:16:52 +03:30

977 lines
40 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>تحلیل معماری پروژه xAiApi - فن آوران ساحر علم</title>
<style>
:root {
--primary: #1e3a8a;
--secondary: #3b82f6;
--accent: #f59e0b;
--success: #10b981;
--danger: #ef4444;
--bg-light: #f8fafc;
--bg-code: #1e293b;
--text-dark: #0f172a;
--text-muted: #64748b;
--border: #e2e8f0;
}
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: 'Tahoma', 'Segoe UI', sans-serif;
background: linear-gradient(135deg, #f8fafc 0%, #e0e7ff 100%);
color: var(--text-dark);
line-height: 1.8;
padding: 20px;
}
.container {
max-width: 1200px;
margin: 0 auto;
background: white;
border-radius: 16px;
box-shadow: 0 20px 60px rgba(0,0,0,0.1);
overflow: hidden;
}
.header {
background: linear-gradient(135deg, var(--primary) 0%, var(--secondary) 100%);
color: white;
padding: 40px;
text-align: center;
position: relative;
}
.header::before {
content: '';
position: absolute;
top: 0; left: 0; right: 0; bottom: 0;
background: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><circle cx="50" cy="50" r="40" fill="none" stroke="white" stroke-width="0.5" opacity="0.1"/></svg>');
opacity: 0.3;
}
.header h1 {
font-size: 2.2em;
margin-bottom: 10px;
position: relative;
}
.header .subtitle {
font-size: 1.1em;
opacity: 0.95;
position: relative;
}
.meta-bar {
display: flex;
justify-content: space-between;
background: var(--bg-light);
padding: 15px 30px;
border-bottom: 2px solid var(--border);
flex-wrap: wrap;
gap: 15px;
}
.meta-item {
display: flex;
align-items: center;
gap: 8px;
font-size: 0.9em;
color: var(--text-muted);
}
.meta-item strong { color: var(--primary); }
.content { padding: 40px; }
.section {
margin-bottom: 35px;
padding: 25px;
background: var(--bg-light);
border-radius: 12px;
border-right: 5px solid var(--secondary);
}
.section h2 {
color: var(--primary);
font-size: 1.6em;
margin-bottom: 20px;
padding-bottom: 10px;
border-bottom: 2px solid var(--border);
display: flex;
align-items: center;
gap: 10px;
}
.section h3 {
color: var(--secondary);
font-size: 1.2em;
margin: 20px 0 12px;
}
.step {
background: white;
padding: 20px;
margin: 15px 0;
border-radius: 10px;
box-shadow: 0 2px 8px rgba(0,0,0,0.05);
border-right: 4px solid var(--accent);
}
.step-number {
display: inline-block;
background: var(--accent);
color: white;
width: 32px;
height: 32px;
border-radius: 50%;
text-align: center;
line-height: 32px;
font-weight: bold;
margin-left: 10px;
}
.arch-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: 20px;
margin: 20px 0;
}
.arch-card {
background: white;
padding: 20px;
border-radius: 10px;
box-shadow: 0 4px 12px rgba(0,0,0,0.08);
border-top: 4px solid var(--secondary);
transition: transform 0.3s;
}
.arch-card:hover { transform: translateY(-5px); }
.arch-card h4 {
color: var(--primary);
margin-bottom: 12px;
font-size: 1.15em;
}
.arch-card ul {
list-style: none;
padding-right: 0;
}
.arch-card li {
padding: 6px 0;
padding-right: 20px;
position: relative;
font-size: 0.95em;
}
.arch-card li::before {
content: '▸';
position: absolute;
right: 0;
color: var(--accent);
font-weight: bold;
}
.tech-badge {
display: inline-block;
background: var(--secondary);
color: white;
padding: 4px 12px;
border-radius: 20px;
font-size: 0.85em;
margin: 3px;
}
.tech-badge.primary { background: var(--primary); }
.tech-badge.success { background: var(--success); }
.tech-badge.accent { background: var(--accent); }
.tech-badge.danger { background: var(--danger); }
pre {
background: var(--bg-code);
color: #e2e8f0;
padding: 18px;
border-radius: 8px;
overflow-x: auto;
direction: ltr;
text-align: left;
font-family: 'Consolas', 'Courier New', monospace;
font-size: 0.88em;
margin: 15px 0;
border-right: 4px solid var(--accent);
}
code {
background: #fef3c7;
color: #92400e;
padding: 2px 8px;
border-radius: 4px;
font-family: 'Consolas', monospace;
font-size: 0.9em;
direction: ltr;
display: inline-block;
}
table {
width: 100%;
border-collapse: collapse;
margin: 15px 0;
background: white;
border-radius: 8px;
overflow: hidden;
box-shadow: 0 2px 8px rgba(0,0,0,0.05);
}
th {
background: var(--primary);
color: white;
padding: 12px;
text-align: right;
font-weight: bold;
}
td {
padding: 12px;
border-bottom: 1px solid var(--border);
}
tr:hover { background: var(--bg-light); }
.flow-diagram {
background: white;
padding: 25px;
border-radius: 10px;
margin: 20px 0;
text-align: center;
}
.flow-step {
display: inline-block;
background: var(--secondary);
color: white;
padding: 10px 20px;
border-radius: 8px;
margin: 5px;
font-size: 0.9em;
}
.flow-arrow {
display: inline-block;
color: var(--accent);
font-size: 1.5em;
margin: 0 8px;
vertical-align: middle;
}
.alert {
padding: 15px 20px;
border-radius: 8px;
margin: 15px 0;
border-right: 4px solid;
}
.alert-info {
background: #dbeafe;
border-color: var(--secondary);
color: #1e40af;
}
.alert-success {
background: #d1fae5;
border-color: var(--success);
color: #065f46;
}
.alert-warning {
background: #fef3c7;
border-color: var(--accent);
color: #92400e;
}
.footer {
background: var(--primary);
color: white;
padding: 25px;
text-align: center;
margin-top: 40px;
}
.footer p { margin: 5px 0; }
.highlight {
background: linear-gradient(120deg, #fef3c7 0%, #fef3c7 100%);
padding: 2px 6px;
border-radius: 4px;
font-weight: bold;
}
.toc {
background: white;
padding: 20px;
border-radius: 10px;
margin-bottom: 25px;
border: 2px solid var(--border);
}
.toc h3 { color: var(--primary); margin-bottom: 15px; }
.toc ol { padding-right: 25px; }
.toc li { padding: 6px 0; }
.toc a {
color: var(--secondary);
text-decoration: none;
transition: color 0.2s;
}
.toc a:hover { color: var(--primary); text-decoration: underline; }
</style>
</head>
<body>
<div class="container">
<div class="header">
<h1>🧠 تحلیل جامع معماری پروژه xAiApi</h1>
<div class="subtitle">پلتفرم یکپارچه ارائه خدمات هوش مصنوعی مبتنی بر ASP.NET Core</div>
</div>
<div class="meta-bar">
<div class="meta-item">👨‍💻 <strong>توسعه‌دهنده:</strong> هادی خزاعی اصل</div>
<div class="meta-item">🏢 <strong>شرکت:</strong> فن آوران ساحر علم</div>
<div class="meta-item">📅 <strong>تاریخ تحلیل:</strong> چهارشنبه ۸ مهر ۱۴۰۵</div>
<div class="meta-item">📦 <strong>نسخه بررسی شده:</strong> 2026.09.30</div>
</div>
<div class="content">
<div class="toc">
<h3>📑 فهرست مطالب</h3>
<ol>
<li><a href="#overview">مرور کلی و چشم‌انداز پروژه</a></li>
<li><a href="#architecture">معماری کلان و ساختار ماژولار</a></li>
<li><a href="#layers">لایه‌بندی و مسئولیت‌ها</a></li>
<li><a href="#ai-providers">ارائه‌دهندگان هوش مصنوعی پشتیبانی شده</a></li>
<li><a href="#data-model">مدل داده و پایگاه داده</a></li>
<li><a href="#api-endpoints">نقاط پایانی API</a></li>
<li><a href="#features">ویژگی‌های کلیدی پیاده‌سازی شده</a></li>
<li><a href="#flow">جریان پردازش درخواست</a></li>
<li><a href="#di">مدیریت وابستگی‌ها (DI)</a></li>
<li><a href="#strengths">نقاط قوت و پیشنهادات بهبود</a></li>
<li><a href="#memory">خلاصه ذخیره شده در حافظه</a></li>
</ol>
</div>
<!-- Section 1: Overview -->
<div class="section" id="overview">
<h2>🎯 گام ۱: مرور کلی و چشم‌انداز پروژه</h2>
<p>
پروژه <span class="highlight">xAiApi</span> یک پلتفرم جامع و مقیاس‌پذیر برای ارائه خدمات هوش مصنوعی است که بر بستر
<code>ASP.NET Core</code> توسعه یافته است. این پروژه با رویکرد <strong>Modular Architecture</strong> طراحی شده
و قابلیت اتصال به چندین ارائه‌دهنده LLM را به صورت یکپارچه فراهم می‌کند.
</p>
<div class="alert alert-info">
<strong>💡 هدف اصلی:</strong> ایجاد یک لایه انتزاعی (Abstraction Layer) بر روی ارائه‌دهندگان مختلف AI
تا توسعه‌دهندگان بتوانند بدون وابستگی به یک ارائه‌دهنده خاص، از قابلیت‌های هوش مصنوعی در محصولات خود استفاده کنند.
</div>
<h3>سه ماژول اصلی پروژه:</h3>
<div class="arch-grid">
<div class="arch-card">
<h4>📡 xAiApi (لایه ارائه)</h4>
<ul>
<li>Controllers و API Endpoints</li>
<li>Database Context و Migrations</li>
<li>Providers و Service Implementations</li>
<li>Configuration و DI Extensions</li>
</ul>
</div>
<div class="arch-card">
<h4>🧩 xAiModels (لایه مدل)</h4>
<ul>
<li>Entities و DTOs</li>
<li>Repository Pattern</li>
<li>Enrichers و Data Providers</li>
<li>GraphQL Support</li>
</ul>
</div>
<div class="arch-card">
<h4>⚙️ xAiService (لایه سرویس)</h4>
<ul>
<li>Vector Helper (Embedding)</li>
<li>Cosine Similarity</li>
<li>User Validation Extensions</li>
<li>Configuration Node Names</li>
</ul>
</div>
</div>
</div>
<!-- Section 2: Architecture -->
<div class="section" id="architecture">
<h2>🏗️ گام ۲: معماری کلان و ساختار ماژولار</h2>
<p>
معماری پروژه بر پایه الگوی <strong>Clean Architecture</strong> همراه با <strong>Repository Pattern</strong>
و <strong>Dependency Injection</strong> گسترده طراحی شده است.
</p>
<h3>سلسله مراتب لایه‌ها:</h3>
<div class="flow-diagram">
<span class="flow-step">🌐 Client</span>
<span class="flow-arrow">→</span>
<span class="flow-step">📡 Controllers</span>
<span class="flow-arrow">→</span>
<span class="flow-step">🧠 AI Services</span>
<span class="flow-arrow">→</span>
<span class="flow-step">💾 Data Provider</span>
<span class="flow-arrow">→</span>
<span class="flow-step">🗄️ Repository</span>
</div>
<h3>ساختار پوشه‌ای پروژه xAiApi:</h3>
<pre>xAiApi/
├── 📂 Controllers/
│ ├── DefaultAiController.cs
│ ├── DefaultEmbeddingController.cs
│ ├── DefaultThinkingAiController.cs
│ ├── StartupController.cs
│ ├── XAiServiceControllerBase.cs
│ └── XAiEmbeddingServiceControllerBase.cs
├── 📂 Providers/
│ ├── XAIServiceBase.cs (هسته اصلی)
│ ├── XAiEmbeddingServiceBase.cs
│ ├── XDefaultAiService.cs
│ ├── XDefaultEmbeddingService.cs
│ └── XDefaultThinkingAiService.cs
├── 📂 Database/
│ ├── XAiApiDbContext.cs
│ └── XAiApiDatabaseDescriptor.cs
├── 📂 Interfaces/
│ ├── IXAiServiceBase.cs
│ ├── IXAiEmbeddingServiceBase.cs
│ └── IXDefault*.cs
├── 📂 Configurations/
│ └── XAiApiConfiguration.cs
├── 📂 Extensions/
│ ├── XModelsExtensions.cs
│ └── XProgramExtensions.cs
├── 📂 DI/
│ └── XDIHelperExtension.cs
├── 📂 Constants/
│ ├── XAiApiConstants.cs
│ └── ConfigurationNodeNames.cs
└── 📂 Migrations/
└── InitialMigrationAiApi.cs</pre>
</div>
<!-- Section 3: Layers -->
<div class="section" id="layers">
<h2>🧱 گام ۳: لایه‌بندی و مسئولیت‌ها</h2>
<h3>۳.۱ لایه Controllers (لایه ارائه)</h3>
<table>
<tr>
<th>Controller</th>
<th>مسئولیت</th>
<th>ویژگی کلیدی</th>
</tr>
<tr>
<td><code>DefaultAiController</code></td>
<td>پاسخ به سوالات عمومی</td>
<td>استفاده از مدل Gemma</td>
</tr>
<tr>
<td><code>DefaultEmbeddingController</code></td>
<td>تبدیل متن به بردار</td>
<td>پشتیبانی از Batch</td>
</tr>
<tr>
<td><code>DefaultThinkingAiController</code></td>
<td>استدلال عمیق (Reasoning)</td>
<td>مدل Qwen با Reasoning</td>
</tr>
<tr>
<td><code>StartupController</code></td>
<td>پیام خوش‌آمدگویی</td>
<td>AllowAnonymous</td>
</tr>
</table>
<div class="alert alert-success">
<strong>✅ نکته مهم:</strong> استفاده از <code>XBaseIdentityApiV1Controller</code> به عنوان کلاس پایه،
مدیریت هویت و مجوزها را به صورت یکپارچه فراهم می‌کند.
</div>
<h3>۳.۲ لایه Providers (هسته منطقی)</h3>
<p>کلاس <code>XAIServiceBase</code> به عنوان <strong>قلب تپنده</strong> پروژه عمل می‌کند و مسئولیت‌های زیر را بر عهده دارد:</p>
<ul style="padding-right: 25px; margin: 15px 0;">
<li>مدیریت ارتباط با LLM از طریق <code>IChatClient</code></li>
<li>پیاده‌سازی Memory Management برای حفظ Context مکالمات</li>
<li>پشتیبانی از Streaming Response (SSE)</li>
<li>مدیریت پروژه‌ها، مکالمات و پیام‌ها</li>
<li>تزریق Introduction Prompt به صورت خودکار</li>
</ul>
<h3>۳.۳ لایه Data Provider</h3>
<p>کلاس <code>XAiDataProvider</code> مسئولیت‌های زیر را مدیریت می‌کند:</p>
<ul style="padding-right: 25px; margin: 15px 0;">
<li>ایجاد خودکار <strong>Default Project</strong> و <strong>Default Conversation</strong> برای هر کاربر</li>
<li>مدیریت Multi-language Resources</li>
<li>ارسال SignalR Notifications</li>
<li>Enrichment اشیاء با اطلاعات مرتبط</li>
</ul>
</div>
<!-- Section 4: AI Providers -->
<div class="section" id="ai-providers">
<h2>🤖 گام ۴: ارائه‌دهندگان هوش مصنوعی پشتیبانی شده</h2>
<p>
پروژه از طریق <code>XAiModelProviderType</code> از چندین ارائه‌دهنده پشتیبانی می‌کند:
</p>
<div class="arch-grid">
<div class="arch-card">
<h4>🟢 OpenAI</h4>
<ul>
<li>استفاده از <code>OpenAIClient</code></li>
<li>پشتیبانی از ApiKey</li>
<li>Endpoint قابل تنظیم</li>
<li>Chat & Embedding</li>
</ul>
</div>
<div class="arch-card">
<h4>🔵 Ollama</h4>
<ul>
<li>اجرای Local Models</li>
<li>بدون نیاز به ApiKey</li>
<li>مناسب برای توسعه</li>
<li>مدل‌های Gemma, Qwen</li>
</ul>
</div>
<div class="arch-card">
<h4>🟡 DeepSeek</h4>
<ul>
<li>پشتیبانی تعریف شده</li>
<li>برای Reasoning Models</li>
<li>در حال توسعه</li>
</ul>
</div>
<div class="arch-card">
<h4>🟣 HuggingFace</h4>
<ul>
<li>دسترسی به هزاران مدل</li>
<li>پشتیبانی تعریف شده</li>
<li>در حال توسعه</li>
</ul>
</div>
</div>
<h3>مدل‌های پیش‌فرض پیکربندی شده:</h3>
<pre>// از XAiApiConstants.cs
XAiDefaultModelName = "Gemma" // مدل پیش‌فرض چت
XAiEmbeddingModelName = "Embed" // مدل Embedding
XAiDefaultThinkingModelName = "Qwen" // مدل Reasoning</pre>
<div class="alert alert-warning">
<strong>⚠️ نکته طراحی:</strong> استفاده از <code>Microsoft.Extensions.AI</code> به عنوان لایه انتزاعی استاندارد،
امکان تعویض ارائه‌دهنده بدون تغییر کد را فراهم می‌کند.
</div>
</div>
<!-- Section 5: Data Model -->
<div class="section" id="data-model">
<h2>🗄️ گام ۵: مدل داده و پایگاه داده</h2>
<p>پایگاه داده شامل ۶ جدول اصلی است:</p>
<table>
<tr>
<th>جدول</th>
<th>کلید</th>
<th>فیلدهای کلیدی</th>
<th>رابطه</th>
</tr>
<tr>
<td><code>AiProjects</code></td>
<td>Guid</td>
<td>OwnerId, Title, Description, Prompt</td>
<td>→ Conversations</td>
</tr>
<tr>
<td><code>AiConversations</code></td>
<td>Guid</td>
<td>OwnerId, Title, ProjectId</td>
<td>→ Messages, Project</td>
</tr>
<tr>
<td><code>AiMessages</code></td>
<td>Guid</td>
<td>Content, Role, MetaDatas, ConversationId</td>
<td>→ Conversation</td>
</tr>
<tr>
<td><code>Files</code></td>
<td>Guid</td>
<td>Name, Path, Thumb, References</td>
<td>مستقل</td>
</tr>
<tr>
<td><code>Strings</code></td>
<td>Int (Auto)</td>
<td>Language, ResourceTitle, TranslatedValue</td>
<td>Multi-language</td>
</tr>
<tr>
<td><code>Tags</code></td>
<td>Int (Auto)</td>
<td>Tag, References</td>
<td>مستقل</td>
</tr>
</table>
<h3>سلسله مراتب داده‌ها:</h3>
<div class="flow-diagram">
<span class="flow-step">👤 User (OwnerId)</span>
<span class="flow-arrow">→</span>
<span class="flow-step">📁 Project</span>
<span class="flow-arrow">→</span>
<span class="flow-step">💬 Conversation</span>
<span class="flow-arrow">→</span>
<span class="flow-step">📝 Message</span>
</div>
<div class="alert alert-info">
<strong>💡 ویژگی مهم:</strong> هر کاربر به صورت خودکار یک <strong>Default Project</strong> و یک
<strong>Default Conversation</strong> دارد که از طریق <code>XAiDataProvider</code> مدیریت می‌شود.
</div>
</div>
<!-- Section 6: API Endpoints -->
<div class="section" id="api-endpoints">
<h2>🔌 گام ۶: نقاط پایانی API</h2>
<h3>۶.۱ Endpoints عمومی (از XAiServiceControllerBase):</h3>
<table>
<tr>
<th>متد</th>
<th>مسیر</th>
<th>توضیح</th>
</tr>
<tr>
<td><span class="tech-badge success">GET</span></td>
<td><code>/AskText?question=</code></td>
<td>پرسش ساده و دریافت پاسخ</td>
</tr>
<tr>
<td><span class="tech-badge success">GET</span></td>
<td><code>/AskTextStream?question=</code></td>
<td>پرسش با پاسخ Streaming (SSE)</td>
</tr>
<tr>
<td><span class="tech-badge primary">POST</span></td>
<td><code>/Ask</code></td>
<td>پرسش با Context (Project/Conversation)</td>
</tr>
<tr>
<td><span class="tech-badge primary">POST</span></td>
<td><code>/AskStream</code></td>
<td>پرسش Context دار با Streaming</td>
</tr>
<tr>
<td><span class="tech-badge success">GET</span></td>
<td><code>/Projects</code></td>
<td>دریافت لیست پروژه‌ها</td>
</tr>
<tr>
<td><span class="tech-badge primary">POST</span></td>
<td><code>/Projects</code></td>
<td>ایجاد پروژه جدید</td>
</tr>
<tr>
<td><span class="tech-badge success">GET</span></td>
<td><code>/Projects/{id}/Conversations</code></td>
<td>مکالمات یک پروژه</td>
</tr>
<tr>
<td><span class="tech-badge success">GET</span></td>
<td><code>/Conversations/{id}/Messages</code></td>
<td>پیام‌های یک مکالمه</td>
</tr>
<tr>
<td><span class="tech-badge success">GET</span></td>
<td><code>*/Query</code></td>
<td>جستجوی پیشرفته با XQuery</td>
</tr>
</table>
<h3>۶.۲ Endpoints Embedding:</h3>
<table>
<tr>
<td><span class="tech-badge success">GET</span></td>
<td><code>/Embedding?content=</code></td>
<td>تبدیل یک متن به بردار</td>
</tr>
<tr>
<td><span class="tech-badge success">GET</span></td>
<td><code>/Embeddings?batch=</code></td>
<td>تبدیل دسته‌ای متون به بردار</td>
</tr>
</table>
</div>
<!-- Section 7: Features -->
<div class="section" id="features">
<h2>✨ گام ۷: ویژگی‌های کلیدی پیاده‌سازی شده</h2>
<div class="arch-grid">
<div class="arch-card">
<h4>🔄 Streaming Responses</h4>
<ul>
<li>پیاده‌سازی SSE (Server-Sent Events)</li>
<li>غیرفعال‌سازی Buffering</li>
<li>پاسخ بلادرنگ به کاربر</li>
</ul>
</div>
<div class="arch-card">
<h4>🧠 Memory Management</h4>
<ul>
<li>حفظ Context مکالمات</li>
<li>Introduction Prompt</li>
<li>Project-specific Prompts</li>
</ul>
</div>
<div class="arch-card">
<h4>🌐 Multi-language Support</h4>
<ul>
<li>Resource-based Localization</li>
<li>Owned Item Resources</li>
<li>Default Language Management</li>
</ul>
</div>
<div class="arch-card">
<h4>📡 Real-time Notifications</h4>
<ul>
<li>SignalR Hub</li>
<li>Project/Conversation/Message Events</li>
<li>Connection-aware Broadcasting</li>
</ul>
</div>
<div class="arch-card">
<h4>🔐 Authorization</h4>
<ul>
<li>OAuth2 Introspection</li>
<li>Policy-based Authorization</li>
<li>Role-based Access Control</li>
</ul>
</div>
<div class="arch-card">
<h4>📚 Swagger Documentation</h4>
<ul>
<li>XML Comments</li>
<li>API V1 Versioning</li>
<li>Auto-generated Docs</li>
</ul>
</div>
<div class="arch-card">
<h4>🎯 Reasoning Models</h4>
<ul>
<li>ReasoningEffort Configuration</li>
<li>ReasoningOutput Options</li>
<li>Thinking AI Service</li>
</ul>
</div>
<div class="arch-card">
<h4>📊 Vector Operations</h4>
<ul>
<li>Vector Normalization</li>
<li>Cosine Similarity</li>
<li>Batch Embedding</li>
</ul>
</div>
</div>
</div>
<!-- Section 8: Flow -->
<div class="section" id="flow">
<h2>🔄 گام ۸: جریان پردازش درخواست</h2>
<h3>۸.۱ جریان پرسش ساده (AskText):</h3>
<div class="flow-diagram">
<span class="flow-step">Client Request</span>
<span class="flow-arrow">→</span>
<span class="flow-step">Controller</span>
<span class="flow-arrow">→</span>
<span class="flow-step">Validation</span>
<span class="flow-arrow">→</span>
<span class="flow-step">XAIServiceBase</span>
<span class="flow-arrow">→</span>
<span class="flow-step">GetHistory()</span>
<span class="flow-arrow">→</span>
<span class="flow-step">GetClient()</span>
<span class="flow-arrow">→</span>
<span class="flow-step">LLM API</span>
</div>
<h3>۸.۲ جریان پرسش با Context (Ask):</h3>
<div class="flow-diagram">
<span class="flow-step">Request + ProjectId + ConversationId</span>
<span class="flow-arrow">→</span>
<span class="flow-step">Load Project</span>
<span class="flow-arrow">→</span>
<span class="flow-step">Load Conversation</span>
<span class="flow-arrow">→</span>
<span class="flow-step">Load Messages</span>
<span class="flow-arrow">→</span>
<span class="flow-step">PrepareMemory()</span>
<span class="flow-arrow">→</span>
<span class="flow-step">Save User Message</span>
<span class="flow-arrow">→</span>
<span class="flow-step">AskLLM()</span>
<span class="flow-arrow">→</span>
<span class="flow-step">Save AI Response</span>
</div>
<h3>۸.۳ جریان Embedding:</h3>
<div class="flow-diagram">
<span class="flow-step">Text Input</span>
<span class="flow-arrow">→</span>
<span class="flow-step">GetEmbeddingGenerator()</span>
<span class="flow-arrow">→</span>
<span class="flow-step">GenerateAsync()</span>
<span class="flow-arrow">→</span>
<span class="flow-step">VectorHelper.Normalize()</span>
<span class="flow-arrow">→</span>
<span class="flow-step">float[] Result</span>
</div>
</div>
<!-- Section 9: DI -->
<div class="section" id="di">
<h2>🔗 گام ۹: مدیریت وابستگی‌ها (DI)</h2>
<h3>سرویس‌های ثبت شده در <code>Startup.ConfigureServices</code>:</h3>
<pre>// سرویس‌های پایه
services.AddXCommons();
services.AddXAppConfiguration(Configuration);
services.AddXCors(appConfiguration.AllowedOrigins);
services.AddXSwagger(Configuration, xmlPath);
services.AddXHttpService(Configuration);
services.AddXApiV1Versioning();
services.AddXAuthorization();
// سرویس‌های هویت و ذخیره‌سازی
services.AddXIdentityService(lifeTime, Configuration);
services.AddXStorageService(Configuration);
services.AddXPushService(lifeTime, Configuration);
// سرویس‌های داده
services.AddXDatabase(lifeTime, descriptor, Configuration);
services.AddXStringService&lt;XAiApiDbContext&gt;(lifeTime, repositoryType);
services.AddXTagService&lt;XAiApiDbContext&gt;(lifeTime, repositoryType);
services.AddXFileService&lt;XAiApiDbContext&gt;(lifeTime, repositoryType);
services.AddXAiDataService&lt;XAiApiDbContext&gt;(lifeTime, repositoryType);
// سرویس‌های AI اختصاصی
services.AddScoped&lt;IXDefaultAiService, XDefaultAiService&gt;();
services.AddScoped&lt;IXDefaultEmbeddingService, XDefaultEmbeddingService&gt;();
services.AddScoped&lt;IXDefaultThinkingAiService, XDefaultThinkingAiService&gt;();</pre>
<div class="alert alert-success">
<strong>✅ الگوی طراحی:</strong> استفاده از <strong>Extension Methods</strong> برای ثبت سرویس‌ها
کد را تمیز، قابل نگهداری و ماژولار نگه می‌دارد.
</div>
</div>
<!-- Section 10: Strengths -->
<div class="section" id="strengths">
<h2>💎 گام ۱۰: نقاط قوت و پیشنهادات بهبود</h2>
<h3>✅ نقاط قوت:</h3>
<ul style="padding-right: 25px; margin: 15px 0;">
<li><strong>معماری ماژولار:</strong> جداسازی واضح لایه‌ها و مسئولیت‌ها</li>
<li><strong>Provider Agnostic:</strong> قابلیت تعویض ارائه‌دهنده AI بدون تغییر کد</li>
<li><strong>Repository Pattern:</strong> پشتیبانی از EF, MongoDB, InMemory</li>
<li><strong>Streaming Support:</strong> پیاده‌سازی کامل SSE برای UX بهتر</li>
<li><strong>Multi-language:</strong> سیستم Resource-based برای چندزبانگی</li>
<li><strong>Real-time:</strong> یکپارچگی SignalR برای Notifications</li>
<li><strong>GraphQL Support:</strong> امکان پرس‌وجوی انعطاف‌پذیر</li>
<li><strong>Enrichment Pattern:</strong> جداسازی منطق غنی‌سازی داده‌ها</li>
</ul>
<h3>🔧 پیشنهادات بهبود:</h3>
<ul style="padding-right: 25px; margin: 15px 0;">
<li>پیاده‌سازی کامل DeepSeek و HuggingFace providers</li>
<li>افزودن Rate Limiting برای کنترل مصرف API</li>
<li>پیاده‌سازی Caching برای پاسخ‌های پرتکرار</li>
<li>افزودن Telemetry و Monitoring (OpenTelemetry)</li>
<li>پیاده‌سازی Unit of Work Pattern به صورت کامل‌تر</li>
<li>افزودن Health Checks برای پایش سرویس‌ها</li>
<li>پیاده‌سازی Circuit Breaker برای resilience</li>
<li>افزودن Unit Tests و Integration Tests</li>
</ul>
</div>
<!-- Section 11: Memory Summary -->
<div class="section" id="memory">
<h2>🧠 گام ۱۱: خلاصه ذخیره شده در حافظه</h2>
<div class="alert alert-success">
<strong>✅ تأیید ذخیره‌سازی:</strong> تحلیل کامل پروژه در حافظه من ذخیره شد و برای دستورات بعدی شما آماده است.
</div>
<h3>📌 نکات کلیدی که به خاطر سپرده‌ام:</h3>
<table>
<tr>
<th>موضوع</th>
<th>جزئیات</th>
</tr>
<tr>
<td><strong>معماری</strong></td>
<td>Clean Architecture + Modular + Repository Pattern</td>
</tr>
<tr>
<td><strong>فناوری پایه</strong></td>
<td>ASP.NET Core, Entity Framework, SignalR, GraphQL</td>
</tr>
<tr>
<td><strong>ارائه‌دهندگان AI</strong></td>
<td>OpenAI, Ollama, DeepSeek, HuggingFace</td>
</tr>
<tr>
<td><strong>مدل‌های پیش‌فرض</strong></td>
<td>Gemma (Chat), Embed (Embedding), Qwen (Reasoning)</td>
</tr>
<tr>
<td><strong>ساختار داده</strong></td>
<td>Project → Conversation → Message</td>
</tr>
<tr>
<td><strong>ویژگی‌های کلیدی</strong></td>
<td>Streaming, Memory, Multi-lang, Real-time, Reasoning</td>
</tr>
<tr>
<td><strong>الگوهای طراحی</strong></td>
<td>DI, Repository, Provider, Enricher, Hub</td>
</tr>
<tr>
<td><strong>فایل‌های کلیدی</strong></td>
<td>XAIServiceBase.cs, XAiDataProvider.cs, Startup.cs</td>
</tr>
</table>
<h3>🎯 آماده برای دستورات بعدی:</h3>
<div class="arch-grid">
<div class="arch-card">
<h4>🔧 توسعه ویژگی جدید</h4>
<ul>
<li>افزودن Provider جدید</li>
<li>پیاده‌سازی Endpoint جدید</li>
<li>افزودن Entity جدید</li>
</ul>
</div>
<div class="arch-card">
<h4>🐛 رفع اشکال</h4>
<ul>
<li>تحلیل خطاهای runtime</li>
<li>بهینه‌سازی performance</li>
<li>بررسی memory leaks</li>
</ul>
</div>
<div class="arch-card">
<h4>📚 مستندسازی</h4>
<ul>
<li>API Documentation</li>
<li>Architecture Diagrams</li>
<li>User Guides</li>
</ul>
</div>
<div class="arch-card">
<h4>🚀 استقرار</h4>
<ul>
<li>Configuration Management</li>
<li>Deployment Strategies</li>
<li>Scaling Considerations</li>
</ul>
</div>
</div>
<div class="alert alert-info">
<strong>💬 پیام به استاد:</strong> تحلیل کامل پروژه با موفقیت انجام شد و تمامی جزئیات معماری،
ساختار کد، الگوهای طراحی و ویژگی‌های پیاده‌سازی شده در حافظه من ثبت گردید. اکنون آماده دریافت
دستورات بعدی شما برای توسعه، بهبود، یا هرگونه تغییر در پروژه هستم.
</div>
</div>
</div>
<div class="footer">
<p><strong>👨‍💻 توسعه‌دهنده:</strong> هادی خزاعی اصل</p>
<p><strong>🏢 شرکت:</strong> فن آوران ساحر علم</p>
<p><strong>📅 تاریخ تهیه مستند:</strong> چهارشنبه ۸ مهر ۱۴۰۵</p>
<p style="margin-top: 15px; opacity: 0.8; font-size: 0.9em;">
🧠 تحلیل جامع معماری پروژه xAiApi - تمامی حقوق محفوظ است
</p>
</div>
</div>
</body>
</html>