Refactor code structure for improved readability and maintainability
This commit is contained in:
masoodafar-web
@@ -0,0 +1,251 @@
|
||||
# 📁 معماری مدیریت فایل و تصاویر — CMS
|
||||
|
||||
> **تاریخ:** ۱۴۰۴/۱۱/۲۸ (February 17, 2026)
|
||||
> **وضعیت:** ✅ عملیاتی
|
||||
> **Build:** 0 Error (هر ۳ پروژه) ✅
|
||||
|
||||
---
|
||||
|
||||
## ۱. پیشزمینه
|
||||
|
||||
سیستم قبلی از **FMS (File Management Service)** در آدرس `https://dl.afrino.co` استفاده میکرد که غیرقابل دسترس/ناسازگار شده بود. در چندین فاز، معماری فایلها به صورت کامل بازنویسی شد:
|
||||
|
||||
| فاز | شرح | وضعیت |
|
||||
|-----|------|-------|
|
||||
| ۱. حذف FMS | حذف کامل ۳ فایل مرده FMS | ✅ |
|
||||
| ۲. حالت base64 | ذخیره data URI مستقیم در DB | ✅ (بازنشسته) |
|
||||
| ۳. ذخیره دیسکی | فایل در دیسک + مسیر در DB + تبدیل به base64 هنگام serve | ✅ |
|
||||
| ۴. **سرو HTTP عمومی** | **اندپوینت `/uploads/{path}` + Fallback FMS** | **✅ جدید** |
|
||||
|
||||
---
|
||||
|
||||
## ۲. معماری نهایی
|
||||
|
||||
```
|
||||
BackOffice (Blazor WASM)
|
||||
│
|
||||
│ MudFileUpload → IBrowserFile → byte[] → gRPC ImageFileModel
|
||||
│
|
||||
▼
|
||||
CMS gRPC Service
|
||||
│
|
||||
│ proto ImageFileModel → Command.ImageFileBytes
|
||||
│
|
||||
▼
|
||||
MediatR Handler
|
||||
│
|
||||
│ IFileManager.UploadImageAsync(folder, bytes, mime, name)
|
||||
│
|
||||
▼
|
||||
LocalFileManager
|
||||
│
|
||||
├─ Main Image → Uploads/Images/{folder}/{guid}.jpg (1200×1200, JPEG Q75)
|
||||
├─ Thumbnail → Uploads/Images/{folder}/{guid}_thumb.jpg (300×300, JPEG Q75)
|
||||
│
|
||||
│ Returns: { Main.Path, Thumbnail.Path } (relative paths stored in DB)
|
||||
│
|
||||
▼
|
||||
ImagePathResolverInterceptor (gRPC response)
|
||||
│
|
||||
│ Walks all response fields → reads file from disk → data:{mime};base64,{bytes}
|
||||
│
|
||||
▼
|
||||
BackOffice / FrontOffice ← receives base64 data URI directly in proto fields
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۳. اجزای کلیدی
|
||||
|
||||
### ۳.۱ `IFileManager` — Interface
|
||||
|
||||
**مسیر:** `Application/Common/FileManager/IFileManager.cs`
|
||||
|
||||
```csharp
|
||||
public interface IFileManager
|
||||
{
|
||||
Task<UploadResult> UploadAsync(string folder, byte[] file, string mime, string? fileName, CancellationToken ct);
|
||||
Task<ImageUploadResult> UploadImageAsync(string folder, byte[] file, string mime, string? fileName, CancellationToken ct);
|
||||
Task DeleteAsync(string path, CancellationToken ct);
|
||||
string? ResolveImageUrl(string? path);
|
||||
}
|
||||
```
|
||||
|
||||
- **`UploadAsync`** — آپلود فایل خام
|
||||
- **`UploadImageAsync`** — بهینهسازی + ساخت thumbnail خودکار (SixLabors.ImageSharp)
|
||||
- **`ResolveImageUrl`** — تبدیل مسیر نسبی به data URI (base64)
|
||||
|
||||
### ۳.۲ `LocalFileManager` — پیادهسازی
|
||||
|
||||
**مسیر:** `Infrastructure/Services/LocalFileManager.cs`
|
||||
|
||||
| ویژگی | مقدار |
|
||||
|-------|-------|
|
||||
| ریشه آپلود | `FileStorage:UploadPath` یا `AppContext.BaseDirectory/Uploads` |
|
||||
| فرمت تصویر اصلی | JPEG, Quality 75, حداکثر 1200×1200 |
|
||||
| فرمت thumbnail | JPEG, Quality 75, حداکثر 300×300 |
|
||||
| نامگذاری فایل | `{Guid}.jpg` + `{Guid}_thumb.jpg` |
|
||||
| DI Registration | `services.AddSingleton<IFileManager, LocalFileManager>()` |
|
||||
|
||||
### ۳.۳ `ImagePathResolverInterceptor` — gRPC Interceptor
|
||||
|
||||
**مسیر:** `WebApi/Interceptors/ImagePathResolverInterceptor.cs`
|
||||
|
||||
اینترسپتور **خودکار** تمام فیلدهای تصویری را در responseهای gRPC پیدا کرده و مسیر نسبی را به data URI تبدیل میکند.
|
||||
|
||||
**فیلدهای شناساییشده:**
|
||||
- `image_path`, `thumbnail_path`, `image_thumbnail_path`
|
||||
- `featured_image_path`, `featured_image_thumbnail_path`
|
||||
- `hero_image_path`, `product_thumbnail_path`
|
||||
- `avatar_path`, `avatar_url`
|
||||
|
||||
**قابلیتها:**
|
||||
- Walk بازگشتی پیامهای proto
|
||||
- پشتیبانی از `string` ساده و `Google.Protobuf.WellKnownTypes.StringValue`
|
||||
- پشتیبانی از فیلدهای `repeated` (collectionهای تو در تو)
|
||||
- اگر مقدار `data:` یا `http` باشد → رد میشود (تبدیل نمیشود)
|
||||
|
||||
### ۳.۴ `LoggingBehaviour` — پاکسازی لاگ
|
||||
|
||||
**مسیر:** `WebApi/Common/Behaviours/LoggingBehaviour.cs`
|
||||
|
||||
- فرمت لاگ: `JsonFormatter.Default.Format()` به جای `{@Request}`
|
||||
- پاکسازی فیلدهای باینری با regex (`File`, `ImageFile`, `image_file`, `file`)
|
||||
- محدودیت طول لاگ: حداکثر 2000 کاراکتر
|
||||
|
||||
### ۳.۵ `UploadsController` — سرو عمومی فایلها (HTTP) 🆕
|
||||
|
||||
**مسیر:** `WebApi/Controllers/UploadsController.cs`
|
||||
|
||||
اندپوینت عمومی REST برای سرو مستقیم تصاویر بدون نیاز به base64. مناسب برای بارگذاری تصاویر در تگ `<img>` و کاهش پهنای باند.
|
||||
|
||||
| ویژگی | مقدار |
|
||||
|-------|-------|
|
||||
| مسیر | `GET /uploads/{**path}` |
|
||||
| احراز هویت | `[AllowAnonymous]` — عمومی |
|
||||
| کش مرورگر | `ResponseCache 86400` ثانیه (۲۴ ساعت) |
|
||||
| Content-Type | تشخیص خودکار از پسوند فایل (`FileExtensionContentTypeProvider`) |
|
||||
| Range Requests | ✅ فعال (`enableRangeProcessing: true`) |
|
||||
| محافظت مسیر | جلوگیری از path traversal (`..`, `\`, `Path.GetFullPath` validation) |
|
||||
|
||||
**FMS Fallback:**
|
||||
اگر فایل محلی وجود نداشته باشد و تنظیم `FMS:Address` پر باشد:
|
||||
1. فایل از `{FMS:Address}/{relativePath}` دانلود میشود
|
||||
2. Content-Type بررسی میشود (فقط `image/*` و `application/pdf` مجاز)
|
||||
3. فایل روی دیسک محلی ذخیره و کش میشود
|
||||
4. سپس فایل محلی سرو میشود
|
||||
|
||||
```
|
||||
Client → GET /uploads/Images/BlogPosts/abc.jpg
|
||||
│
|
||||
├─ فایل محلی وجود دارد? → سرو مستقیم از دیسک
|
||||
│
|
||||
└─ فایل محلی وجود ندارد?
|
||||
└─ FMS:Address تنظیم شده?
|
||||
├─ بله → دانلود از dl.afrino.co → ذخیره محلی → سرو
|
||||
└─ خیر → 404 Not Found
|
||||
```
|
||||
|
||||
**وابستگیها:**
|
||||
- `IHttpClientFactory` با named client `"FMS"` (timeout: 30 ثانیه)
|
||||
- ثبت در `Program.cs`: `builder.Services.AddHttpClient("FMS", ...)`
|
||||
|
||||
---
|
||||
|
||||
## ۴. Proto Messages — ImageFileModel
|
||||
|
||||
هر حوزه (DiscountProduct, BlogPost, SitePage) پیام مستقل `ImageFileModel` خود را دارد:
|
||||
|
||||
### DiscountProduct
|
||||
```protobuf
|
||||
message ImageFileModel {
|
||||
bytes file = 1;
|
||||
string mime = 2;
|
||||
string file_name = 3;
|
||||
}
|
||||
```
|
||||
**استفاده در:** `CreateDiscountProductRequest`, `UpdateDiscountProductRequest`
|
||||
|
||||
### BlogPost
|
||||
```protobuf
|
||||
message BlogImageFileModel {
|
||||
bytes file = 1;
|
||||
string mime = 2;
|
||||
string file_name = 3;
|
||||
}
|
||||
```
|
||||
**استفاده در:** `CreateBlogPostRequest`, `UpdateBlogPostRequest`
|
||||
|
||||
### SitePage
|
||||
```protobuf
|
||||
message SitePageImageFileModel {
|
||||
bytes file = 1;
|
||||
string mime = 2;
|
||||
string file_name = 3;
|
||||
}
|
||||
```
|
||||
**استفاده در:** `UpdateSitePageRequest`, `CreateSitePageSectionRequest`, `UpdateSitePageSectionRequest`
|
||||
|
||||
---
|
||||
|
||||
## ۵. جریان آپلود تصویر (مثال: BlogPost)
|
||||
|
||||
```
|
||||
1. کاربر در BackOffice → MudFileUpload → انتخاب فایل
|
||||
2. BlogPostEditDialog.OnImageSelected()
|
||||
→ IBrowserFile.OpenReadStream() → byte[] + ContentType + FileName
|
||||
→ پیشنمایش base64 در UI
|
||||
3. Submit → BlogPostEditDto { ImageFile = bytes, ImageMime, ImageFileName }
|
||||
4. BlogPostService.CreateAsync()
|
||||
→ BlogImageFileModel { File = ByteString.CopyFrom(bytes), Mime, FileName }
|
||||
→ gRPC CreateBlogPostRequest
|
||||
5. CMS BlogPostService (gRPC) → CreateBlogPostCommand
|
||||
{ ImageFileBytes = request.ImageFile.File.ToByteArray(), ... }
|
||||
6. CreateBlogPostCommandHandler.Handle()
|
||||
→ _fileManager.UploadImageAsync("Images/BlogPosts", bytes, mime, name)
|
||||
→ post.FeaturedImagePath = result.Main.Path
|
||||
→ post.FeaturedImageThumbnailPath = result.Thumbnail.Path
|
||||
7. Response → ImagePathResolverInterceptor
|
||||
→ featured_image_path → data:image/jpeg;base64,...
|
||||
→ featured_image_thumbnail_path → data:image/jpeg;base64,...
|
||||
8. BackOffice / FrontOffice → نمایش مستقیم base64 data URI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۶. فایلهای حذفشده (کد مرده FMS)
|
||||
|
||||
| فایل | شرح |
|
||||
|------|------|
|
||||
| `Infrastructure/Services/FmsFileManager.cs` | پیادهسازی قدیمی FMS (HTTP upload) |
|
||||
| `Application/Common/FileManager/FileManagementService.cs` | سرویس قدیمی مدیریت فایل |
|
||||
| `Application/Common/FileManager/IFileManagementService.cs` | اینترفیس قدیمی |
|
||||
|
||||
---
|
||||
|
||||
## ۷. تنظیمات
|
||||
|
||||
### `appsettings.json` (CMS)
|
||||
```json
|
||||
{
|
||||
"FileStorage": {
|
||||
"UploadPath": "/app/Uploads"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### محدودیت حجم gRPC
|
||||
```csharp
|
||||
// Program.cs
|
||||
services.AddGrpc(o => o.MaxReceiveMessageSize = 50 * 1024 * 1024); // 50MB
|
||||
```
|
||||
|
||||
### FrontOffice — `UrlUtility.GetImageUrl()`
|
||||
```csharp
|
||||
public static string GetImageUrl(string? path)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(path)) return string.Empty;
|
||||
if (path.StartsWith("data:") || path.StartsWith("http")) return path;
|
||||
return $"{DownloadUrl?.TrimEnd('/')}/{path.TrimStart('/')}";
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user