This commit is contained in:
2026-10-01 01:16:52 +03:30
parent 2eb1daf923
commit e9deaaa4b1
9 changed files with 45227 additions and 1 deletions
+977
View File
@@ -0,0 +1,977 @@
<!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>