last ...

Documents/Markdown/README.md

@@ -0,0 +1,172 @@
+# ‫برنامه کاربردی RpkRem2Fo
+
+## ‫خلاصه اجرایی و معرفی
+
+‫برنامه کاربردی RpkRem2Fo یک نمونه عملی (Proof of Concept) از پیاده‌سازی یک API Gateway پویا در بستر ASP.NET Core است که با استفاده از ماژول RpkProxyPkg ساخته شده است. این برنامه به عنوان یک Reverse Proxy هوشمند عمل می‌کند که درخواست‌های ورودی از کلاینت‌ها (معمولاً Frontend های مبتنی بر React/Vue) را دریافت کرده و بر اساس پیکربندی‌های تعریف شده، آن‌ها را به سرویس‌های Backend مناسب مسیریابی می‌کند.
+
+## RpkProxyPkg
+
+‫ماژول RpkProxyPkg به عنوان یک کتابخانه قابل استفاده مجدد (Reusable Library) طراحی شده است که منطق پیچیده مسیریابی، مدیریت توکن، استخراج پارامترها و ارتباط با Service Broker را در خود جای داده است. برنامه‌های کاربردی مانند RpkRem2Fo صرفاً با تنظیم پیکربندی و ثبت سرویس‌ها، می‌توانند از تمام قابلیت‌های این ماژول بهره‌مند شوند.
+
+## اهداف برنامه
+
+1. ‫یکپارچه‌سازی API ها
+    ‫ارائه یک نقطه ورود واحد برای تمام سرویس‌های Backend و ساده‌سازی ارتباط Frontend با Backend.
+
+2. ‫مدیریت احراز هویت
+    ‫استخراج و اعتبارسنجی توکن JWT و انتقال امن اطلاعات کاربر به سرویس‌های مقصد.
+
+3. ‫مسیریابی پویا
+    ‫امکان تعریف مسیرهای جدید بدون نیاز به تغییر کد، صرفاً با ویرایش فایل تنظیمات.
+
+4. ‫مدیریت CORS
+    ‫کنترل کامل بر هدرهای Cross-Origin برای ارتباط امن با Frontend های مختلف.
+
+## معماری کلی برنامه
+
+‫برنامه RpkRem2Fo از یک معماری لایه‌ای استاندارد پیروی می‌کند که در آن ماژول RpkProxyPkg به عنوان یک لایه میانجی (Middleware Layer) بین کلاینت و سرویس‌های Backend قرار می‌گیرد.
+
+```md
+┌─────────────────────────────────────────────────────────────────┐
+│                        Frontend (React/Vue)                     │
+│                         (Browser Client)                        │
+└────────────────────────────┬────────────────────────────────────┘
+                             │ HTTP Requests
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│              RpkRem2Fo (ASP.NET Core Application)               │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │              RpkProxyPkg Module (Reusable)                │  │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │  │
+│  │  │  Middleware  │→ │   Services   │→ │ Extensions   │     │  │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘     │  │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │  │
+│  │  │ Configurations│ │  Contracts   │→ │  Constants   │     │  │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘     │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│                     appsettings.json                            │
+└──────────┬──────────────────────────────────┬───────────────────┘
+           │                                  │
+           ▼                                  ▼
+┌──────────────────────┐          ┌──────────────────────┐
+│   Direct Targets     │          │   Service Broker     │
+│  (BoardManagementApi,│          │  (7 Architectural    │
+│   ...,               │          │      Layers)         │
+│   )                  │          │  ┌────────────────┐  │
+│                      │          │  │ Rem2 Module    │  │
+└──────────────────────┘          │  │ (Layer 6)      │  │
+                                  │  └────────────────┘  │
+                                  └──────────────────────┘
+```
+
+‫یکی از مهم‌ترین جنبه‌های طراحی این سیستم، جداسازی کامل بین ماژول و برنامه کاربردی است. این طراحی بر اساس اصل "Separation of Concerns" و "Reusability" انجام شده است.
+
+| جنبه | ماژول <span dir="ltr">RpkProxyPkg</span> | برنامه <span dir="ltr">RpkRem2Fo</span> |
+|------|------------------------------------------|-----------------------------------------|
+| <strong>نقش</strong> | ارائه‌دهنده قابلیت‌های پروکسی | مصرف‌کننده قابلیت‌های ماژول |
+| <strong>مسئولیت</strong> | منطق مسیریابی، مدیریت توکن، CORS | راه‌اندازی، پیکربندی، تنظیمات خاص دامنه |
+| <strong>قابلیت استفاده مجدد</strong> | کاملاً مستقل و قابل استفاده در پروژه‌های مختلف | مختص دامنه Rem2 (مدیریت برد) |
+| <strong>تغییرات</strong> | تغییرات نادر (فقط برای افزودن قابلیت جدید) | تغییرات مکرر (افزودن مسیر، Target جدید) |
+| <strong>وابستگی</strong> | مستقل از دامنه تجاری | وابسته به ماژول + Framework های شرکت |
+
+### مزیت این طراحی
+
+&#x202b;با این رویکرد، برای ساخت یک برنامه کاربردی جدید (مثلاً RpkHrFo برای منابع انسانی یا RpkFinanceFo برای مالی)، کافی است یک پروژه جدید ASP.NET Core ایجاد کرده، ماژول RpkProxyPkg را به آن اضافه کرده و پیکربندی خاص آن دامنه را در appsettings.json تعریف کنیم. هیچ خط کدی در ماژول نیاز به تغییر ندارد!
+
+### وابستگی فنی
+
+&#x202b;این ماژول به ماژول rpk.fwk وابستگی فنی دارد.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <Nullable>enable</Nullable>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Version>1.0.0</Version>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="rpk.fwk" Version="3.6.6" />
+  </ItemGroup>
+  
+</Project>
+```
+
+## مراحل گام‌به‌گام استفاده از ماژول
+
+&#x202b;در این بخش، مراحل کامل ایجاد یک برنامه کاربردی جدید با استفاده از ماژول RpkProxyPkg تشریح می‌شود. این مراحل بر اساس پیاده‌سازی موفق RpkRem2Fo استخراج شده‌اند.
+
+1. &#x202b;ایجاد پروژه ASP.NET Core Web API
+    &#x202b;ابتدا یک پروژه جدید از نوع ASP.NET Core Web API با حداقل نسخه .NET 8 ایجاد کنید. این پروژه نقطه ورود برنامه کاربردی شما خواهد بود.
+
+2. &#x202b;افزودن مرجع به ماژول RpkProxyPkg
+    &#x202b;ماژول RpkProxyPkg را به عنوان یک Project Reference یا NuGet Package به پروژه خود اضافه کنید.
+
+3. &#x202b;پیکربندی برنامه بر اساس نیازمندی های موجود
+    &#x202b;با توجه به این مهم که ماژول RpkProxyPkg داری نیازمندی به rpk.fwk است و همهخ پروژه ها در سازمان داری نیازمندی فنی به rpk.fwk هستند، لازم نیست ارجاع مستقیم به rpk.fwk صورت بگیر. تنها در این گام لازم است سرویس های فریمورک را بر اساس استاندارد درج کنید.
+
+```cs
+// Initialize Configuration ...
+ConfigurationHelper.Initialize(builder.Configuration);
+
+// Register Data Service ...
+var connectionStringDict = new Dictionary<string, string>() { };
+
+// Framework Registration ...
+var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFilename);
+builder.AddServicesFwk(connectionStringDict, xmlFilePath);
+...
+// Register Services ...
+builder.Services.AddRpkProxyConfiguration();
+builder.Services.AddHttpClient(RpkProxyParams.ProxyHttpClient);
+builder.Services.AddRpkProxy();
+...
+// Using RpkProxy ...
+app.UseRpkProxy();
+app.AddMiddelwareFwk();
+...
+```
+
+&#x202b;نکته مهم: حتما میان UseRpkProxy را قبل از AddMiddlewareFwk فراخوانی کنید.
+
+4. &#x202b;تعریف پیکربندی الگوی مسیرها در appsettings.json
+    &#x202b;مهم‌ترین مرحله: تعریف Targets، Templates و Requests در فایل تنظیمات. این بخش قلب تپنده برنامه است.
+
+```json
+{
+  "ProxyConfiguration": {
+    "Targets": [
+      { "Name": "MyApi", "Url": "http://localhost:5000" }
+    ],
+    "Templates": [
+      {
+        "Name": "GuidId",
+        "Template": "{id}",
+        "PathVariable": "ID",
+        "RegularExpression": "[0-9a-fA-F]{8}-...",
+        "ExtractionType": "GUID"
+      }
+    ],
+    "Requests": [
+      {
+        "Name": "GetItem",
+        "Type": "Proxy",
+        "HttpMethod": "GET",
+        "Path": "/api/items/{id}",
+        "Templates": ["GuidId"],
+        "ServiceBrokerInfo": {
+          "Layer": 6,
+          "Module": "MyModule",
+          "Method": "GetItem"
+        }
+      }
+    ]
+  }
+}
+```
+
+5. &#x202b;اجرا و تست برنامه
+    &#x202b;برنامه را اجرا کرده و مسیرهای تعریف شده را تست کنید. لاگ‌های برنامه اطلاعات کاملی از پردازش هر درخواست ارائه می‌دهند.