admin/docs

Files

T

masoodafar-web 6b6173e2be docs: rename 'تخفیفی' to 'اعتباری' across all documentation

- 9 files updated: BUSINESS-01/02/03/04, TECH-02, OVERVIEW-01/03/04, MAGIC-WALLET-SPEC
- فروشگاه تخفیفی → فروشگاه اعتباری
- کیف‌پول تخفیفی → کیف‌پول اعتباری
- Consistent naming with FrontOffice UI

2026-02-22 20:57:05 +03:30

9.8 KiB

Raw Permalink Blame History

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

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

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

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

فارسی	انگلیسی	توضیح
کارا بازار سلامت	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	تعداد محصول در انبار
کیف‌پول جادویی	Magic Wallet	حالت ویژه: Balance=0 → شارژ ×2.5 از درگاه
حالت جادویی	Magic Mode	WalletMode=1 — کمیسیون غیرفعال
ضریب شارژ	Magic Multiplier	واریز × 2.5 = اعتبار Balance
سقف دور	Per-Cycle Cap	100M تومان واریز → 250M اعتبار
دوره عضویت	Membership Cycle	ClubMembershipCycle — هر خرید پکیج = یک دور

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

فارسی	انگلیسی	توضیح
سامانه مدیریت محتوا	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 مناسب داشته باشد

9.8 KiB Raw Permalink Blame History Unescape Escape

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

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

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

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

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

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

۳.۱ C# / .NET

۳.۲ Protobuf

۳.۳ Blazor / UI

۳.۴ Database

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

۴.۱ CQRS Pattern

۴.۲ gRPC Client Pattern (FrontOffice/BackOffice)

۴.۳ Hangfire Job Pattern

۵. Git Workflow

۵.۱ شاخه‌ها

۵.۲ مخازن

۵.۳ Commit Convention

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

۷. Definition of Done (DoD)

9.8 KiB

Raw Permalink Blame History