docs: consolidate 53 files into 15 structured files in 3 folders
- business/ (5): club-commission, payment, ecommerce, membership, content - technical/ (5): cms-arch, ui, deployment, migration, api - overview/ (5): flowcharts, index, changelog, glossary, roadmap - Removed all old folders: backoffice, cms, deployment, docs, frontoffice, migration, ui-modernization, business (old) - Updated internal links with relative folder paths
This commit is contained in:
masoodafar-web
@@ -0,0 +1,230 @@
|
||||
# 📖 واژهنامه، استانداردها و قراردادهای کد
|
||||
|
||||
> **اصطلاحات فارسی/انگلیسی، الگوهای نامگذاری و استانداردهای حرفهای**
|
||||
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
|
||||
|
||||
---
|
||||
|
||||
## ۱. واژهنامه اصلی (فارسی ↔ انگلیسی)
|
||||
|
||||
### ۱.۱ مفاهیم بیزینسی
|
||||
|
||||
| فارسی | انگلیسی | توضیح |
|
||||
|-------|---------|--------|
|
||||
| کارا بازار سلامت | 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 | فروشگاه ۳۰% تخفیف برای اعضا |
|
||||
| پرداخت ترکیبی | 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 | برای فروشگاه تخفیفی |
|
||||
| بارگذاری تنبل | Lazy Loading | لود محصولات ۱۲تایی |
|
||||
| صفحات سایت | 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 مناسب داشته باشد
|
||||
Reference in New Issue
Block a user