masoodafar-web
aef6861e21
Matches code fix — IPG now charges DiscountBalance = BasePackageAmount × 2 Same as DayaLoan and ManualPayment. Total for all methods: 56M + 112M = 168M
231 lines
9.3 KiB
Markdown
231 lines
9.3 KiB
Markdown
# 📖 واژهنامه، استانداردها و قراردادهای کد
|
||
|
||
> **اصطلاحات فارسی/انگلیسی، الگوهای نامگذاری و استانداردهای حرفهای**
|
||
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
|
||
|
||
---
|
||
|
||
## ۱. واژهنامه اصلی (فارسی ↔ انگلیسی)
|
||
|
||
### ۱.۱ مفاهیم بیزینسی
|
||
|
||
| فارسی | انگلیسی | توضیح |
|
||
|-------|---------|--------|
|
||
| کارا بازار سلامت | 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 مناسب داشته باشد
|