# 📖 واژه‌نامه، استانداردها و قراردادهای کد

> **اصطلاحات فارسی/انگلیسی، الگوهای نام‌گذاری و استانداردهای حرفه‌ای**  
> **آخرین بروزرسانی:** اسفند ۱۴۰۴

---

## ۱. واژه‌نامه اصلی (فارسی ↔ انگلیسی)

### ۱.۱ مفاهیم بیزینسی

| فارسی | انگلیسی | توضیح |
|-------|---------|--------|
| کارا بازار سلامت | FourSat | نام تجاری پلتفرم |
| باشگاه مشتریان | Club Membership | عضویت ویژه با پکیج طلایی |
| پکیج طلایی | Golden Package | بسته ۵۶M تومان برای ورود به باشگاه |
| درخت باینری | Binary Tree | ساختار شبکه‌ای ۲ شاخه‌ای |
| پای چپ / راست | Left Leg / Right Leg | دو شاخه هر نود در درخت |
| کمیسیون هفتگی | Weekly Commission | سهم از Pool بر اساس بالانس |
| بالانس هفتگی | Weekly Balance | MIN(فروش‌چپ, فروش‌راست) |
| سقف هفتگی | Weekly Cap | حداکثر ۳۰۰ واحد هر پا |
| باقیمانده | Carryover | فروش مازاد قابل‌انتقال به هفته بعد |
| Pool هفتگی | Weekly Commission Pool | مخزن کمیسیون قابل‌توزیع |
| هزینه فعالسازی | Activation Fee | ۲۵M تومان از Balance |
| واریز هدیه | Gift Value | ۲۵.۲M واریز به Pool |
| فروشگاه تخفیفی | Discount Store | فروشگاه با تخفیف per-product برای اعضا |
| پرداخت ترکیبی | Hybrid Payment | DiscountBalance + IPG |
| وام دایا | Daya Loan | وام آنلاین برای خرید پکیج |
| کد معرف | Referral Code | کد یکتا هر عضو برای دعوت |
| موجودی | Inventory | تعداد محصول در انبار |

### ۱.۲ مفاهیم فنی

| فارسی | انگلیسی | توضیح |
|-------|---------|--------|
| سامانه مدیریت محتوا | CMS Microservice | هسته اصلی backend |
| پنل مدیریت | BackOffice | رابط ادمین (Blazor WASM) |
| سایت کاربران | FrontOffice | رابط مشتری (Blazor Server) |
| درگاه پرداخت | Payment Gateway (IPG) | ZarinPal |
| سرویس پرداخت | PYMS | Payment Management Service |
| کیف‌پول نقدی | Balance Wallet | موجودی قابل‌خرج |
| کیف‌پول طلایی | Network Balance | برای محاسبه کمیسیون (شارژ نمی‌شود) |
| کیف‌پول تخفیفی | Discount Balance | برای فروشگاه تخفیفی (IPG و Daya: 112M — دو برابر BasePackageAmount) |
| بارگذاری تنبل | Lazy Loading | لود محصولات 12تایی (FO) / 10تایی (CMS default) |
| صفحات سایت | Site Pages | صفحات قابل‌ویرایش (Shopify-style) |
| ثوابت سیستمی | System Constants | تنظیمات key-value |
| پردازش پس‌زمینه | Background Job | Hangfire recurring/fire-and-forget |

---

## ۲. مخفف‌ها (Abbreviations)

| مخفف | کامل | توضیح |
|------|------|--------|
| **CMS** | Content Management System | مایکروسرویس اصلی |
| **BO** | BackOffice | پنل مدیریت |
| **FO** | FrontOffice | سایت کاربران |
| **BFF** | Backend-for-Frontend | حذف‌شده |
| **CQRS** | Command Query Responsibility Segregation | الگوی معماری |
| **gRPC** | Google Remote Procedure Call | پروتکل ارتباطی |
| **EF** | Entity Framework | ORM |
| **JWT** | JSON Web Token | احراز هویت |
| **IPG** | Internet Payment Gateway | درگاه پرداخت آنلاین |
| **PYMS** | Payment Management Service | سرویس مالی |
| **SP** | Stored Procedure | رویه ذخیره‌شده SQL |
| **OTP** | One-Time Password | رمز یکبار مصرف |
| **K8s** | Kubernetes | ارکستراسیون کانتینر |
| **CI/CD** | Continuous Integration/Deployment | خط لوله خودکار |
| **RTL** | Right-to-Left | راست‌به‌چپ (فارسی) |
| **WASM** | WebAssembly | فرمت اجرایی مرورگر |
| **PWA** | Progressive Web App | وب‌اپ پیشرفته |

---

## ۳. استانداردهای نام‌گذاری

### ۳.۱ C# / .NET

| نوع | الگو | مثال |
|-----|------|------|
| **Class** | PascalCase | `ProductService`, `CreateProductCommand` |
| **Interface** | I + PascalCase | `IProductService`, `ICurrentUserService` |
| **Method** | PascalCase + Async | `GetProductsAsync()`, `CreateOrderAsync()` |
| **Property** | PascalCase | `ProductName`, `IsActive` |
| **Private field** | _camelCase | `_dbContext`, `_logger` |
| **Parameter** | camelCase | `productId`, `userId` |
| **Constant** | PascalCase | `MaxNetworkLevel`, `ActivationFee` |
| **Enum** | PascalCase (singular) | `OrderStatus`, `PaymentType` |
| **Namespace** | Company.Project.Feature | `CMSMicroservice.Features.Products` |

### ۳.۲ Protobuf

| نوع | الگو | مثال |
|-----|------|------|
| **Service** | PascalCase + Service | `ProductService` |
| **Method** | PascalCase | `GetProducts`, `CreateOrder` |
| **Message** | PascalCase + Message/Request/Response | `ProductMessage`, `GetProductsRequest` |
| **Field** | snake_case | `product_name`, `is_active` |
| **Enum** | PascalCase | `ORDER_STATUS_PENDING` |

### ۳.۳ Blazor / UI

| نوع | الگو | مثال |
|-----|------|------|
| **Page** | PascalCase.razor + .razor.cs | `Products.razor`, `Products.razor.cs` |
| **Component** | PascalCase.razor | `AppImage.razor`, `ProductCard.razor` |
| **Parameter** | [Parameter] PascalCase | `[Parameter] public string Title` |
| **CSS class** | kebab-case | `product-card`, `hero-section` |

### ۳.۴ Database

| نوع | الگو | مثال |
|-----|------|------|
| **Table** | PascalCase (plural) | `Products`, `Users`, `Orders` |
| **Column** | PascalCase | `ProductName`, `CreatedAt` |
| **FK** | {Entity}Id | `ProductId`, `UserId` |
| **SP** | SP_ / sp_ + PascalCase | `SP_GetNetworkTree` |
| **Schema** | [CMS] | `[CMS].Products` |

---

## ۴. الگوهای معماری

### ۴.۱ CQRS Pattern

```
Command (نوشتن):
    CreateProductCommand → CreateProductCommandHandler → DB Write

Query (خواندن):
    GetProductsQuery → GetProductsQueryHandler → DB Read

قوانین:
    ✅ Command نباید data برگرداند (فقط Id یا void)
    ✅ Query نباید state تغییر دهد
    ✅ هر Handler فقط یک مسئولیت
    ✅ Validation در Validator (FluentValidation)
```

### ۴.۲ gRPC Client Pattern (FrontOffice/BackOffice)

```
Service Layer:
    1. Inject GrpcClient via DI
    2. Map UI model → Proto Request
    3. Call gRPC method
    4. Map Proto Response → UI model
    5. Handle RpcException → user-friendly message
```

### ۴.۳ Hangfire Job Pattern

```
Recurring Job:
    1. Register in Startup: RecurringJob.AddOrUpdate<T>(...)
    2. Implement Execute() method
    3. Use Polly for retry
    4. Log start/end/error
    5. Idempotent — safe to re-run
```

---

## ۵. Git Workflow

### ۵.۱ شاخه‌ها

| شاخه | کاربرد | Deploy Target |
|------|--------|--------------|
| `kub-stage` | توسعه فعال | Staging server |
| `production` | محیط نهایی | Production server |
| `main` | مستندات (totalDoc) | — |

### ۵.۲ مخازن

| مخزن | Remote | شاخه اصلی |
|------|--------|-----------|
| CMS | `gitea` → git.se.kbs1.ir | `kub-stage` |
| BackOffice | `kub-stage` → git.se.kbs1.ir | `kub-stage` |
| FrontOffice | `kub-stage` → git.se.kbs1.ir | `kub-stage` |
| Docs (totalDoc) | `foursatDocs` → git.se.kbs1.ir/admin/docs | `main` |

### ۵.۳ Commit Convention

```
feat: add lazy loading for products
fix: correct counter animation on landing
docs: consolidate 53 files into 15
refactor: remove BFF layer
chore: update MudBlazor to v8
```

---

## ۶. ساختار پروژه

```
FourSat/                          ← Root workspace
├── CMS/                          ← مایکروسرویس اصلی (.NET 9)
│   ├── src/CMSMicroservice/      ← کد اصلی
│   └── Dockerfile
├── BackOffice/                   ← پنل مدیریت (Blazor WASM)
│   └── src/BackOffice/
├── FrontOffice/                  ← سایت کاربران (Blazor Server)
│   └── src/FrontOffice/
├── DataMigration/                ← ابزار مهاجرت داده
├── deployment/                   ← اسکریپت‌های استقرار
│   ├── k8s-manifests/
│   └── docker-compose.yml
├── dbbkup/                       ← SQL scripts و backup
├── totalDoc/                     ← 📚 مستندات (15 فایل)
│   ├── business/                 ← بیزینسی (5 فایل)
│   ├── technical/                ← فنی (5 فایل)
│   └── overview/                 ← کلان (5 فایل)
└── nupkg/                        ← Proto NuGet packages
```

---

## ۷. Definition of Done (DoD)

هر فیچر قبل از merge باید:

- [ ] کد review شده باشد
- [ ] بیلد موفق باشد (CI green)
- [ ] خطای compile نداشته باشد
- [ ] در Staging تست شده باشد
- [ ] مستندات بروز شده باشد
- [ ] RTL درست کار کند
- [ ] Error handling مناسب داشته باشد