xSaherelmWorkspace/Documents/Docs/Developer/10.html

<!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>