Last ...

2026-10-03 18:04:36 +03:30
parent 92988ea155
commit 81b900b887
20 changed files with 48612 additions and 4 deletions
@@ -0,0 +1,441 @@
+<!DOCTYPE html>
+<html lang="fa" dir="rtl">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>رفع خطای وابستگی چرخشی (Circular Dependency) در سرویس OCR - فن آوران ساحر علم</title>
+<style>
+    :root {
+        --primary: #1e3a8a;
+        --secondary: #3b82f6;
+        --accent: #f59e0b;
+        --success: #10b981;
+        --danger: #ef4444;
+        --warning: #f97316;
+        --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;
+    }
+    .header h1 { font-size: 2.1em; margin-bottom: 10px; }
+    .header .subtitle { font-size: 1.1em; opacity: 0.95; }
+    .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.5em;
+        margin-bottom: 20px;
+        padding-bottom: 10px;
+        border-bottom: 2px solid var(--border);
+    }
+    .section h3 { color: var(--secondary); font-size: 1.2em; margin: 20px 0 12px; }
+    pre {
+        background: var(--bg-code);
+        color: #e2e8f0;
+        padding: 18px;
+        border-radius: 8px;
+        overflow-x: auto;
+        direction: ltr;
+        text-align: left;
+        font-family: 'Consolas', monospace;
+        font-size: 0.85em;
+        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;
+    }
+    th { background: var(--primary); color: white; padding: 12px; text-align: right; }
+    td { padding: 12px; border-bottom: 1px solid var(--border); }
+    .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-danger { background: #fee2e2; border-color: var(--danger); color: #991b1b; }
+    .footer { background: var(--primary); color: white; padding: 25px; text-align: center; }
+    .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; }
+    .file-change { background: #f0f9ff; border-right: 4px solid var(--secondary); padding: 15px; margin: 10px 0; border-radius: 8px; }
+    .file-change .path { font-family: 'Consolas', monospace; color: var(--primary); font-weight: bold; direction: ltr; display: inline-block; }
+    .badge-modify { background: var(--warning); color: white; padding: 2px 8px; border-radius: 4px; font-size: 0.75em; margin-right: 8px; }
+</style>
+</head>
+<body>
+<div class="container">
+
+    <div class="header">
+        <h1>🔗 رفع خطای وابستگی چرخشی (Circular Dependency)</h1>
+        <div class="subtitle">تحلیل و رفع چرخه وابستگی بین IXFileContentExtractor و IXDefaultAIOCRService</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> xAiApi</div>
+    </div>
+
+    <div class="content">
+
+        <div class="toc">
+            <h3>📑 فهرست مطالب</h3>
+            <ol>
+                <li><a href="#analysis">تحلیل ریشه خطا</a></li>
+                <li><a href="#solution">استراتژی رفع خطا</a></li>
+                <li><a href="#step1">گام ۱: اصلاح Interface سرویس OCR</a></li>
+                <li><a href="#step2">گام ۲: بازنویسی مستقل کلاس XDefaultAIOCRService</a></li>
+                <li><a href="#step3">گام ۳: بررسی ثبت در Dependency Injection</a></li>
+            </ol>
+        </div>
+
+        <!-- Section 1: Analysis -->
+        <div class="section" id="analysis">
+            <h2>🔍 گام ۱: تحلیل ریشه خطا</h2>
+            <p>پیغام خطای DI به وضوح یک <strong>وابستگی چرخشی (Circular Dependency)</strong> را نشان می‌دهد:</p>
+            <div class="alert alert-danger">
+                <code>IXFileContentExtractor</code> ➔ <code>XVisionFileContentExtractor</code> ➔ <code>IXDefaultAIOCRService</code> ➔ <code>XDefaultAIOCRService</code> ➔ <code>XAIServiceBase</code> ➔ <code>IXFileContentExtractor</code>
+            </div>
+            <p><strong>چرا این اتفاق افتاد؟</strong></p>
+            <ul style="padding-right: 25px; margin-top: 15px;">
+                <li>کلاس <code>XVisionFileContentExtractor</code> برای انجام OCR به <code>IXDefaultAIOCRService</code> نیاز دارد.</li>
+                <li>کلاس <code>XDefaultAIOCRService</code> از <code>XAIServiceBase</code> ارث‌بری کرده است.</li>
+                <li>سازنده (Constructor) کلاس <code>XAIServiceBase</code> به <code>IXFileContentExtractor</code> نیاز دارد.</li>
+            </ul>
+            <p>این زنجیره باعث می‌شود کانتینر DI در یک حلقه بی‌نهایت گیر کند و نتواند هیچ‌یک از این سرویس‌ها را مقداردهی اولیه نماید.</p>
+        </div>
+
+        <!-- Section 2: Solution -->
+        <div class="section" id="solution">
+            <h2>💡 گام ۲: استراتژی رفع خطا</h2>
+            <p>برای شکستن این چرخه، باید <strong>وابستگی <code>XDefaultAIOCRService</code> به <code>XAIServiceBase</code> را حذف کنیم</strong>. </p>
+            <p>سرویس OCR فقط نیاز به برقراری ارتباط با مدل زبانی (LLM) برای استخراج متن از تصویر دارد و به هیچ‌وجه به <code>IXFileContentExtractor</code>، <code>IXFileProvider</code> یا <code>IXAiDataProvider</code> نیاز ندارد. بنابراین، با حذف ارث‌بری از <code>XAIServiceBase</code> و پیاده‌سازی مستقیم منطق ساخت <code>IChatClient</code> درون همین کلاس، چرخه وابستگی کاملاً شکسته می‌شود.</p>
+        </div>
+
+        <!-- Section 3: Step 1 -->
+        <div class="section" id="step1">
+            <h2>🛠️ گام ۳: اصلاح Interface سرویس OCR</h2>
+            <p>ابتدا باید ارث‌بری غیرضروری <code>IXAiServiceBase</code> را از اینترفیس حذف کنیم، زیرا این سرویس فقط وظیفه OCR را بر عهده دارد و نیازی به متدهای مدیریت پروژه، مکالمه و پیام ندارد.</p>
+
+            <div class="file-change">
+                <span class="badge-modify">MODIFY</span>
+                <span class="path">xAiApi/Interfaces/IXDefaultAIOCRService.cs</span>
+            </div>
+
+<pre>using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using System.Collections.Generic;
+
+namespace xAiApi.Interfaces
+{
+    /// &lt;summary&gt;
+    /// سرویس اختصاصی برای انجام OCR بر روی محتوای تصویری ...
+    /// &lt;/summary&gt;
+    public interface IXDefaultAIOCRService
+    {
+        /// &lt;summary&gt;
+        /// درخواست انجام OCR بر روی محتوای داده شده ...
+        /// &lt;/summary&gt;
+        Task&lt;string&gt; RequestOCRAsync(
+            IList&lt;ChatMessage&gt; messages,
+            CancellationToken cancellationToken = default
+        );
+
+        /// &lt;summary&gt;
+        /// درخواست انجام OCR بر روی محتوای داده شده به صورت Stream ...
+        /// &lt;/summary&gt;
+        IAsyncEnumerable&lt;string&gt; RequestOCRAsEnumerable(
+            IList&lt;ChatMessage&gt; messages,
+            CancellationToken cancellationToken = default
+        );
+    }
+}</pre>
+        </div>
+
+        <!-- Section 4: Step 2 -->
+        <div class="section" id="step2">
+            <h2>⚙️ گام ۴: بازنویسی مستقل کلاس XDefaultAIOCRService</h2>
+            <p>اکنون کلاس پیاده‌سازی را بازنویسی می‌کنیم تا دیگر از <code>XAIServiceBase</code> ارث‌بری نکند. منطق ساخت <code>IChatClient</code> (که قبلاً در کلاس پایه بود) به صورت مستقیم و تمیز درون این کلاس قرار می‌گیرد.</p>
+
+            <div class="file-change">
+                <span class="badge-modify">MODIFY</span>
+                <span class="path">xAiApi/Providers/XDefaultAIOCRService.cs</span>
+            </div>
+
+<pre>using System;
+using System.Linq;
+using System.Net.Http;
+using System.Threading;
+using System.Threading.Tasks;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+using OpenAI;
+using OllamaSharp;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using xAiApi.Configurations;
+using xAiApi.Constants;
+using xAiApi.Extensions;
+using xAiModels.Constants;
+using xAiModels.Extensions;
+using xCommons.Extensions;
+using xExceptions.Constants;
+
+namespace xAiApi.Providers
+{
+    /// &lt;summary&gt;
+    /// پیاده‌سازی مستقل سرویس OCR بدون وابستگی به XAIServiceBase ...
+    /// &lt;/summary&gt;
+    public class XDefaultAIOCRService : IXDefaultAIOCRService
+    {
+        private readonly string prompt;
+        private readonly XAiModelDescriptor descriptor;
+        private readonly ILogger&lt;XDefaultAIOCRService&gt; logger;
+
+        public XDefaultAIOCRService(
+            ILogger&lt;XDefaultAIOCRService&gt; logger,
+            XAiApiConfiguration configuration,
+            string model = null,
+            string prompt = null
+        )
+        {
+            this.logger = logger;
+
+            // ۱. دریافت پیکربندی مدل
+            if (model.IsNullOrEmpty())
+            {
+                model = XAiApiConstants.XAiDefaultVisionModelName;
+            }
+
+            descriptor = configuration.GetModel(model);
+            if (descriptor.IsNullOrDefault())
+            {
+                XException.InvalidData.Throw("Invalid OCR Model Configuration");
+            }
+
+            // ۲. دریافت پرامپت استخراج
+            if (prompt.IsNullOrEmpty())
+            {
+                prompt = configuration.GetPrompt(
+                    name: XAiApiConstants.XAiApiContentExtractionPromptName,
+                    @params: null
+                );
+            }
+
+            this.prompt = prompt;
+            if (this.prompt.IsNullOrEmpty())
+            {
+                XException.InvalidArgs.Throw("OCR Prompt cannot be empty");
+            }
+        }
+
+        public virtual async Task&lt;string&gt; RequestOCRAsync(
+            IList&lt;ChatMessage&gt; messages,
+            CancellationToken cancellationToken = default
+        )
+        {
+            if (!messages.HasChild())
+            {
+                XException.InvalidArgs.Throw();
+            }
+
+            using var client = GetClient();
+
+            var pMessage = new ChatMessage(ChatRole.System, prompt);
+            messages = [pMessage, .. messages];
+
+            var response = await client.GetResponseAsync(
+                messages: messages,
+                cancellationToken: cancellationToken
+            );
+
+            if (!response.IsValid())
+            {
+                XException.ActionFailed.Throw();
+            }
+
+            return response.Text;
+        }
+
+        public virtual async IAsyncEnumerable&lt;string&gt; RequestOCRAsEnumerable(
+            IList&lt;ChatMessage&gt; messages,
+            [EnumeratorCancellation] CancellationToken cancellationToken = default
+        )
+        {
+            if (!messages.HasChild())
+            {
+                XException.InvalidArgs.Throw();
+            }
+
+            using var client = GetClient();
+
+            var pMessage = new ChatMessage(ChatRole.System, prompt);
+            messages = [pMessage, .. messages];
+
+            var enumerable = client.GetStreamingResponseAsync(
+                options: null,
+                messages: messages
+            );
+
+            await foreach (var res in enumerable)
+            {
+                if (cancellationToken.IsCancellationRequested)
+                {
+                    yield break;
+                }
+                yield return res.Text;
+            }
+        }
+
+        /// &lt;summary&gt;
+        /// ساخت کلاینت ارتباط با LLM (جایگزین متد GetClient در XAIServiceBase) ...
+        /// &lt;/summary&gt;
+        private IChatClient GetClient()
+        {
+            var model = descriptor.LLM;
+            var apiKey = descriptor.ApiKey;
+            var url = new Uri(descriptor.Url);
+            var httpClient = new HttpClient { BaseAddress = url, Timeout = Timeout.InfiniteTimeSpan };
+
+            IChatClient result = null;
+            switch (descriptor.Provider)
+            {
+                case XAiModelProviderType.Ollama:
+                    var ollamaClient = new OllamaApiClient(httpClient, model);
+                    result = new ChatClientBuilder(ollamaClient).UseFunctionInvocation().Build();
+                    break;
+                case XAiModelProviderType.OpenAI:
+                    var openAiClient = new OpenAIClient(
+                        new ApiKeyCredential(apiKey.IsNullOrEmpty() ? XAiApiConstants.XOpenAINoKey : apiKey),
+                        new OpenAIClientOptions
+                        {
+                            Endpoint = url,
+                            Transport = new HttpClientPipelineTransport(httpClient)
+                        }
+                    );
+                    result = new ChatClientBuilder(openAiClient.GetChatClient(model).AsIChatClient()).UseFunctionInvocation().Build();
+                    break;
+                default:
+                    XException.InvalidData.Throw($"Unsupported provider: {descriptor.Provider}");
+                    break;
+            }
+
+            if (result == null)
+            {
+                XException.InvalidData.Throw("Failed to create Chat Client");
+            }
+
+            return result;
+        }
+    }
+}</pre>
+        </div>
+
+        <!-- Section 5: Step 3 -->
+        <div class="section" id="step3">
+            <h2>🔌 گام ۵: بررسی ثبت در Dependency Injection</h2>
+            <p>با توجه به تغییرات فوق، ثبت سرویس در فایل <code>Startup.cs</code> بدون هیچ تغییری به درستی کار خواهد کرد، زیرا امضای Constructor اکنون ساده‌تر شده و فقط به <code>ILogger</code> و <code>XAiApiConfiguration</code> وابسته است که هر دو از قبل در DI ثبت شده‌اند.</p>
+
+            <div class="alert alert-success">
+                <strong>✅ تأییدیه:</strong><br>
+                خط <code>services.AddScoped&lt;IXDefaultAIOCRService, XDefaultAIOCRService&gt;();</code> در <code>Startup.cs</code> کاملاً معتبر است و دیگر باعث ایجاد چرخه وابستگی نمی‌شود.
+            </div>
+
+            <h3>خلاصه دستاوردهای این اصلاح:</h3>
+            <table>
+                <tr>
+                    <th>مزیت</th>
+                    <th>توضیح</th>
+                </tr>
+                <tr>
+                    <td>🚫 حذف Circular Dependency</td>
+                    <td>چرخه معیوب بین Extractor و سرویس OCR کاملاً شکسته شد.</td>
+                </tr>
+                <tr>
+                    <td>⚡ افزایش عملکرد (Performance)</td>
+                    <td>سرویس OCR دیگر بار اضافی مقداردهی اولیه DataProvider و FileProvider را تحمل نمی‌کند.</td>
+                </tr>
+                <tr>
+                    <td>🎯 اصل تک‌وظیفه‌ای (SRP)</td>
+                    <td>کلاس <code>XDefaultAIOCRService</code> اکنون فقط و فقط مسئول ارتباط با مدل برای OCR است.</td>
+                </tr>
+                <tr>
+                    <td>🧪 قابلیت تست‌پذیری (Testability)</td>
+                    <td>تزریق وابستگی‌های کمتر، نوشتن Unit Test برای این سرویس را بسیار ساده‌تر می‌کند.</td>
+                </tr>
+            </table>
+        </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>