This commit is contained in:
masoodafar-web
2026-01-03 18:27:49 +03:30
parent 0369292d7f
commit 5965b98728
156 changed files with 16082 additions and 0 deletions
+371
View File
@@ -0,0 +1,371 @@
# 📚 FourSat Project - فهرست جامع مستندات
> **نسخه**: 2.8
> **آخرین بروزرسانی**: ۱۱ دی ۱۴۰۴ (December 31, 2025)
> **وضعیت**: ✅ تجمیع و بازسازی کامل
---
## 🎯 راهنمای سریع (Quick Navigation)
### برای توسعه‌دهندگان:
- 🚀 **شروع سریع**: [`06-DEPLOYMENT/quick-start.md`](06-DEPLOYMENT/quick-start.md)
- 📋 **کارهای جاری**: [`05-TASKS/CURRENT-SPRINT.md`](05-TASKS/CURRENT-SPRINT.md)
- 🐛 **TODO های کد**: [`04-FRONTEND/FrontOffice/todo-commented-code.md`](04-FRONTEND/FrontOffice/todo-commented-code.md)
### برای معماران:
- 🏗️ **معماری سیستم**: [`02-ARCHITECTURE/`](02-ARCHITECTURE/)
- 📊 **Business Logic**: [`01-BUSINESS/`](01-BUSINESS/)
### برای مدیران:
-**وضعیت تحویل**: [`06-DEPLOYMENT/delivery-readiness.md`](06-DEPLOYMENT/delivery-readiness.md)
- 📈 **گزارش پیشرفت**: [`03-BACKEND/CMS/implementation-status.md`](03-BACKEND/CMS/implementation-status.md)
---
## 📊 وضعیت کلی پروژه
### Backend Services:
| سرویس | وضعیت | تکمیل | فایل مرجع |
|-------|------|------|-----------|
| **CMS Microservice** | ✅ Production Ready | 98% | [`03-BACKEND/CMS/implementation-status.md`](03-BACKEND/CMS/implementation-status.md) |
| **BackOffice.BFF** | ✅ Production Ready | 100% | [`03-BACKEND/BackOffice.BFF/handlers-status.md`](03-BACKEND/BackOffice.BFF/handlers-status.md) |
| **FrontOffice.BFF** | 🚧 In Progress | 60% | [`03-BACKEND/FrontOffice.BFF/README.md`](03-BACKEND/FrontOffice.BFF/README.md) |
### Frontend Applications:
| اپلیکیشن | وضعیت | تکمیل | فایل مرجع |
|---------|------|------|-----------|
| **BackOffice UI** | ✅ Production Ready | 100% | [`04-FRONTEND/BackOffice/ui-status.md`](04-FRONTEND/BackOffice/ui-status.md) |
| **FrontOffice UI** | 🚧 In Progress | 75% | [`04-FRONTEND/FrontOffice/README.md`](04-FRONTEND/FrontOffice/README.md) |
### آخرین دستاوردها (۱۱ دی):
-**Discount Shop BFF Complete**: پیاده‌سازی کامل لایه BFF شامل WebApi Services
-**Product Image Gallery**: گالری تصاویر محصولات فروشگاه تخفیفی (5 API)
-**Admin Order Reports**: گزارشات مدیریتی سفارشات (GetAll + SalesReport)
-**VAT Calculation**: محاسبه مالیات بر ارزش افزوده در سفارشات
-**gRPC Services**: DiscountProductService + DiscountOrderService
### دستاوردهای ۹ دی:
-**Commission Carryover Fix**: رفع مشکل نمایش 0 برای carryover در weekly-balance
-**WeekSelector Autocomplete**: انتخابگر هفته با جستجو در داشبورد کمیسیون
-**Responsive Commission Pages**: بهبود UI با MudGrid و Summary Stats
-**Merged Dashboard/History**: ادغام دو صفحه تکراری با dual routing
-**Terminology Cleanup**: جایگزینی کلمات MLM-حساس (کمیسیون→پاداش، شبکه→تیم)
### دستاوردهای ۷ دی:
-**SystemConstants**: انتقال مقادیر hardcode (56M) به کلاس مرکزی
-**SmsTemplates**: متمرکز کردن همه قالب‌های پیامک در یک فایل
-**Daya Loan SMS**: ارسال پیامک خودکار هنگام تأیید وام دایا
-**AppVersion UI Complete**: صفحه مدیریت نسخه با قابلیت افزودن جدید
-**Mapping Fixes**: رفع مشکلات Mapster (Unit→Empty, WeeklyPools)
-**Commission Status Refactor**: انتقال تبدیل Status از BFF به FrontOffice client
-**ProcessWithdrawal Fix**: رفع خطای "PayoutId invalid" در BackOffice
-**WeekDisplayName Fix**: نمایش "هفته چهلم" به جای "1404-W40"
-**Withdrawals Page Fix**: رفع مشکل لود نشدن صفحه تأیید برداشت‌ها
-**Network Balances Enhanced**: نمایش نام کاربر + Carryover breakdown با Tooltip
-**WeekDefinitionId Fix**: رفع مشکل ارسال 0 به جای مقدار صحیح (Int64Value.Value)
### دستاوردهای ۶ دی:
-**App Version Management**: سیستم کامل مدیریت نسخه اپلیکیشن‌های موبایل
-**ReferralCode در درخت**: نمایش کد معرف در نودهای درخت شبکه FrontOffice
-**BackOffice Settings Page**: صفحه `/settings/app-versions` با UI کامل
### دستاوردهای ۵ دی:
-**Chatika Enabled Flag**: قابلیت فعال/غیرفعال کردن Worker چتیکا از Config
-**DayaLoan Fix**: جلوگیری از استعلام مجدد مشتریان با قرارداد
-**BackOffice Tree Rewrite**: بازنویسی کامل صفحه درخت شبکه با d3-org-chart
-**Node Tooltip**: نمایش اطلاعات کاربر روی hover
-**Week Filter Visual**: تمایز بصری کاربران فعال شده در هفته فیلتر شده
-**GetNetworkTree SP**: Stored Procedure برای بهبود سرعت + حذف محدودیت عمق
---
## 🗂️ ساختار مستندات
### 📊 01-BUSINESS/ - منطق تجاری
قوانین کسب‌وکار، فرآیندها، و محاسبات مالی:
| فایل | موضوع | خلاصه |
|------|-------|-------|
| [`network-commission-system.md`](01-BUSINESS/network-commission-system.md) | شبکه + کمیسیون | Binary MLM Tree, Flash Out, Weekly Pool |
| [`discount-shop-business.md`](01-BUSINESS/discount-shop-business.md) | فروشگاه تخفیف | محصولات تخفیف‌دار، محدودیت DiscountBalance |
| [`package-purchase-system.md`](01-BUSINESS/package-purchase-system.md) | خرید پکیج طلایی | فعال‌سازی باشگاه، پرداخت 56M |
| [`daya-loan-integration.md`](01-BUSINESS/daya-loan-integration.md) | قرض‌الحسنه دایا | خرید الماس، انتقال NetworkBalance |
| [`balance-calculation-rules.md`](01-BUSINESS/balance-calculation-rules.md) | محاسبه موجودی | Carryover Logic, تعادل‌های باقیمانده |
| [`binary-tree-guide.md`](01-BUSINESS/binary-tree-guide.md) | ثبت‌نام در شبکه | قرارگیری در دست چپ/راست، Placement |
**کاربرد**: تحلیلگران کسب‌وکار، توسعه‌دهندگان Backend، تست‌نویس‌ها
---
### 🏗️ 02-ARCHITECTURE/ - معماری سیستم
**⚠️ در حال توسعه** - فعلاً به اسناد موجود در `CMS/` مراجعه کنید:
- معماری کلی: Clean Architecture (Domain → Application → Infrastructure)
- الگوی BFF: Backend for Frontend
- Microservices: CMS ↔ BFF ↔ UI
**Roadmap**:
- [ ] System Overview Diagram
- [ ] Microservices Communication Flow
- [ ] Database Schema (ERD)
- [ ] Security Architecture
---
### ⚙️ 03-BACKEND/ - Backend Services
#### 📦 CMS Microservice (Core Business Logic)
| فایل | موضوع | خلاصه |
|------|-------|-------|
| [`README.md`](03-BACKEND/CMS/README.md) | نمای کلی CMS | معرفی، تکنولوژی‌ها، Quick Start |
| [`implementation-status.md`](03-BACKEND/CMS/implementation-status.md) | پیشرفت پیاده‌سازی | Phase 1-12، 98% Complete، Daya API ✅ |
| [`entity-guide.md`](03-BACKEND/CMS/entity-guide.md) | راهنمای Entity ها | Domain Entities، Relations، Validations |
| [`commission-system.md`](03-BACKEND/CMS/commission-system.md) | ✨ سیستم کمیسیون | Entities, Proto Models, WeekDefinitionId Migration |
| [`api-coverage.md`](03-BACKEND/CMS/api-coverage.md) | پوشش API | لیست تمام gRPC Services و Handlers |
| [`email-sms-configuration.md`](03-BACKEND/CMS/email-sms-configuration.md) | Email & SMS | Kavenegar, MailKit, Templates |
| [`payment-gateway.md`](03-BACKEND/CMS/payment-gateway.md) | درگاه پرداخت | ZarinPal, Daya Integration |
| [`daya-api-implementation.md`](03-BACKEND/CMS/daya-api-implementation.md) | ✨ Daya API Guide | Complete Real API Implementation (Dec 6) |
| [`club-membership-migration.md`](03-BACKEND/CMS/club-membership-migration.md) | ✨ Migration Scripts | اسکریپت‌های مهاجرت باشگاه مشتریان (Dec 9) |
| [`chatika-integration.md`](03-BACKEND/CMS/chatika-integration.md) | 🤖 Chatika Integration | Worker خودکار فعال‌سازی حساب AI (Dec 23) |
| [`club-features-system.md`](03-BACKEND/CMS/club-features-system.md) | 🎁 Club Features | Enum، Handler ها، UserClubFeatures (Dec 23) |
| [`INVENTORY-SYSTEM-PLAN.md`](03-BACKEND/INVENTORY-SYSTEM-PLAN.md) | 📦 سیستم انبارداری | پلن یکپارچه‌سازی موجودی (Jan 1, 2026) |
| [`PRODUCT-BUNDLE-FEATURE.md`](03-BACKEND/CMS/PRODUCT-BUNDLE-FEATURE.md) | 📦 پکیج محصولات | ⏸️ Postponed - بسته‌بندی محصولات (Jan 1, 2026) |
| [`MANUAL-CLUB-MEMBERSHIP-TASKS.md`](03-BACKEND/CMS/MANUAL-CLUB-MEMBERSHIP-TASKS.md) | 👤 عضویت دستی | ⏳ تسک‌های پیاده‌سازی عضویت دستی باشگاه (Jan 1, 2026) |
**Key Stats**:
- **Entities**: 50+ Domain Entities
- **Commands**: 120+ CQRS Commands
- **Queries**: 80+ CQRS Queries
- **gRPC RPCs**: 150+ Remote Procedures
- **Build**: ✅ 0 errors, 287 warnings (pre-existing)
#### 🔌 BackOffice.BFF (Admin Gateway)
| فایل | موضوع | خلاصه |
|------|-------|-------|
| [`README.md`](03-BACKEND/BackOffice.BFF/README.md) | نمای کلی BFF | معماری، Communication با CMS |
| [`handlers-status.md`](03-BACKEND/BackOffice.BFF/handlers-status.md) | وضعیت Handler ها | 35 CQRS Handler، 100% Complete |
| [`cms-integration.md`](03-BACKEND/BackOffice.BFF/cms-integration.md) | یکپارچه‌سازی CMS | Protobuf, gRPC Client Configuration |
| [`discount-shop-integration.md`](03-BACKEND/BackOffice.BFF/discount-shop-integration.md) | ادغام فروشگاه تخفیف | 19 Handler برای مدیریت محصولات تخفیف |
**Key Stats**:
- **Handlers**: 35 CQRS (100% Production Ready)
- **gRPC Clients**: 5 Services
- **Pages Served**: 23 Blazor Pages
#### 🔌 FrontOffice.BFF (User Gateway)
| فایل | موضوع | خلاصه |
|------|-------|-------|
| [`README.md`](03-BACKEND/FrontOffice.BFF/README.md) | نمای کلی BFF | معماری، 12 Handler (9 + 3 new) |
| [`protobuf-mismatch.md`](03-BACKEND/FrontOffice.BFF/protobuf-mismatch.md) | ⚠️ مغایرت Proto | 6 Handler با مشکل، راهکارها |
**Key Stats**:
- **Handlers**: 12 CQRS (60% Complete)
- **New Today**: ClubMembership, NetworkMembership, Commission (3 modules)
- **Blockers**: Protobuf field name mismatches
---
### 🎨 04-FRONTEND/ - Frontend Applications
#### 🖥️ BackOffice (Admin Panel)
| فایل | موضوع | خلاصه |
|------|-------|-------|
| [`README.md`](04-FRONTEND/BackOffice/README.md) | نمای کلی BackOffice | Blazor Server، MudBlazor 8.14.0 |
| [`ui-status.md`](04-FRONTEND/BackOffice/ui-status.md) | وضعیت صفحات | 23 Pages + 8 Dialogs، 100% Complete |
**Pages**: Dashboard, User Management, Order Management, Commission Reports, Network Stats, Club Management, Discount Shop Management, Payment Gateways, Worker Control
#### 👤 FrontOffice (User Portal)
| فایل | موضوع | خلاصه |
|------|-------|-------|
| [`README.md`](04-FRONTEND/FrontOffice/README.md) | نمای کلی FrontOffice | 24 Pages، 75% Complete |
| [`gap-analysis.md`](04-FRONTEND/FrontOffice/gap-analysis.md) | تحلیل Gap | 12 Module، 7 نیاز به API واقعی |
| [`todo-commented-code.md`](04-FRONTEND/FrontOffice/todo-commented-code.md) | ⚠️ TODO های کد | 5 متد WalletService + 3 Mock Service |
| [`progress-report.md`](04-FRONTEND/FrontOffice/progress-report.md) | گزارش پیشرفت امروز | 7 صفحه + 3 سرویس + 3 BFF module |
**New Pages (Today)**:
- **Club**: `ClubInfo.razor`, `ActivateClub.razor`, `ClubFeatures.razor`
- **Network**: `Tree.razor`, `NetworkStats.razor`
- **Commission**: `WeeklyReport.razor`, `PayoutHistory.razor`
**Status**: Mock services → Need real API integration
---
### ✅ 05-TASKS/ - مدیریت وظایف
| فایل | موضوع | خلاصه |
|------|-------|-------|
| [`CURRENT-SPRINT.md`](05-TASKS/CURRENT-SPRINT.md) | اسپرینت جاری | TODO های High/Medium/Low Priority |
| [`BACKLOG.md`](05-TASKS/BACKLOG.md) | Backlog | کارهای آینده، Feature Requests |
| [`DISCOUNT-SHOP-COMPLETION-PLAN.md`](05-TASKS/DISCOUNT-SHOP-COMPLETION-PLAN.md) | تکمیل فروشگاه تخفیفی | گالری تصاویر، VAT، گزارش فروش |
| [`verification-template.md`](05-TASKS/verification-template.md) | چک‌لیست QA | تست‌های Business Verification |
**Current Sprint Highlights**:
- 🔥 **High Priority**: Discount Shop Completion (گالری، VAT، گزارش)
- 🔥 **High Priority**: FrontOffice UI Integration (7 صفحه)
- 🟡 **Medium**: WalletService Implementation (5 متد)
- 🟡 **Medium**: Package Purchase UI (4 صفحه)
---
### 🚀 06-DEPLOYMENT/ - استقرار و عملیات
| فایل | موضوع | خلاصه |
|------|-------|-------|
| [`quick-start.md`](06-DEPLOYMENT/quick-start.md) | راهنمای شروع | Setup محیط توسعه، Build، Run |
| [`delivery-readiness.md`](06-DEPLOYMENT/delivery-readiness.md) | آمادگی تحویل | چک‌لیست Production، Deployment Steps |
**Requirements**:
- .NET 9 SDK
- SQL Server 2019+
- Visual Studio 2022 / Rider
- Node.js (برای Frontend tooling)
---
### 📦 99-ARCHIVE/ - آرشیو اسناد قدیمی
فایل‌های منسوخ شده که دیگر استفاده نمی‌شوند:
| فایل | دلیل آرشیو | جایگزین |
|------|-----------|---------|
| `REMAINING-TASKS-OLD-2024-12-02.md` | منسوخ شده | `05-TASKS/BACKLOG.md` |
| `network-club-commission-system-OLD.md` | نسخه قدیمی | `01-BUSINESS/network-commission-system.md` |
| `implementation-progress-fa-OLD.md` | ترجمه ناقص | `03-BACKEND/CMS/implementation-status.md` |
| `monitoring-alerts-partial-OLD.md` | گزارش ناقص | در CMS موجود |
**راهنما**: [`99-ARCHIVE/ARCHIVE-INDEX.md`](99-ARCHIVE/ARCHIVE-INDEX.md)
---
## 🔍 جستجوی سریع
### موضوعات کلیدی:
| موضوع | فایل‌های مرتبط |
|-------|---------------|
| **باشگاه مشتریان** | `01-BUSINESS/network-commission-system.md`, `03-BACKEND/CMS/implementation-status.md` (Phase 9) |
| **شبکه باینری** | `01-BUSINESS/network-commission-system.md`, `01-BUSINESS/binary-tree-guide.md` |
| **کمیسیون هفتگی** | `01-BUSINESS/network-commission-system.md`, `03-BACKEND/CMS/implementation-status.md` (Phase 4) |
| **فروشگاه تخفیف** | `01-BUSINESS/discount-shop-business.md`, `03-BACKEND/CMS/implementation-status.md` (Phase 9) |
| **خرید پکیج** | `01-BUSINESS/package-purchase-system.md`, `03-BACKEND/CMS/implementation-status.md` (Phase 12) |
| **کیف پول سه‌گانه** | `01-BUSINESS/balance-calculation-rules.md`, `04-FRONTEND/FrontOffice/todo-commented-code.md` |
| **درگاه پرداخت** | `03-BACKEND/CMS/payment-gateway.md`, `01-BUSINESS/daya-loan-integration.md` |
| **Email & SMS** | `03-BACKEND/CMS/email-sms-configuration.md` |
| **gRPC Integration** | `03-BACKEND/BackOffice.BFF/cms-integration.md`, `03-BACKEND/FrontOffice.BFF/protobuf-mismatch.md` |
---
## 📈 آمار کلی مستندات
### قبل از تجمیع:
- **تعداد فایل**: 42 فایل .md
- **حجم کل**: ~33,000 خط
- **ساختار**: پراکنده در پوشه‌های مختلف
### بعد از تجمیع:
- **تعداد فایل فعال**: ~28 فایل
- **تعداد آرشیو شده**: 4 فایل
- **ساختار**: دسته‌بندی شده در 7 پوشه اصلی
- **کاهش تکرار**: ~16%
### پوشش مستندات:
-**Business Logic**: 6 سند جامع
-**Backend**: 12 سند (CMS + BFFs)
-**Frontend**: 7 سند (BackOffice + FrontOffice)
-**Tasks**: 3 سند (Sprint, Backlog, Verification)
-**Deployment**: 2 سند (Quick Start, Delivery)
-**Architecture**: در حال توسعه
---
## 🤝 مشارکت در مستندات
### به‌روزرسانی مستندات:
1. هر تغییر در کد → بروزرسانی سند مربوطه
2. TODO جدید → افزودن به `05-TASKS/CURRENT-SPRINT.md`
3. Feature جدید → ایجاد سند در پوشه مناسب
4. Bug Critical → ثبت در `CURRENT-SPRINT.md` با Priority 🔥
### قوانین نام‌گذاری:
- استفاده از `kebab-case` برای نام فایل‌ها
- زبان فارسی برای Business Docs
- زبان انگلیسی برای Technical Docs
- Emoji برای دسته‌بندی سریع (✅ 🚧 ⚠️ 🔥)
---
## 📞 پشتیبانی
برای سوالات و مشکلات:
- **مستندات فنی**: Backend Team
- **مستندات Business**: Product Owner
- **مستندات UI/UX**: Frontend Team
---
## 📝 تاریخچه تغییرات
### نسخه 2.8 (۱۱ دی ۱۴۰۴ / Dec 31, 2025):
-**Discount Shop BFF Complete**: پیاده‌سازی کامل لایه BFF شامل WebApi Services
-**Product Image Gallery**: گالری تصاویر محصولات (5 API جدید)
-**Admin Order Reports**: گزارشات مدیریتی سفارشات (GetAll + SalesReport)
-**VAT Calculation**: محاسبه مالیات بر ارزش افزوده
-**gRPC Services**: DiscountProductService + DiscountOrderService
- ✅ Changelog جدید: `CHANGELOG-2025-12-31.md`
### نسخه 2.7 (۹ دی ۱۴۰۴ / Dec 29, 2025):
-**Commission Carryover Fix**: رفع مشکل نمایش carryover
-**WeekSelector Autocomplete**: انتخابگر هفته با جستجو
-**Responsive Commission Pages**: بهبود UI با MudGrid
- ✅ Changelog جدید: `CHANGELOG-2025-12-29.md`
### نسخه 2.5 (۶ دی ۱۴۰۴ / Dec 26, 2025):
-**App Version Management**: سیستم کامل مدیریت نسخه اپلیکیشن‌های موبایل
-**BackOffice UI**: صفحه `/settings/app-versions` با MudBlazor
-**ReferralCode Display**: نمایش کد معرف در درخت شبکه FrontOffice
- ✅ Changelog جدید: `CHANGELOG-2025-12-26.md`
### نسخه 2.4 (۵ دی ۱۴۰۴ / Dec 25, 2025):
-**Chatika Enabled Flag**: قابلیت فعال/غیرفعال کردن Worker چتیکا
-**DayaLoan Fix**: جلوگیری از استعلام مجدد مشتریان با قرارداد
-**BackOffice Tree Rewrite**: بازنویسی کامل با d3-org-chart
-**Node Tooltip**: نمایش اطلاعات کاربر روی hover
-**GetNetworkTree SP**: Stored Procedure برای بهبود سرعت
- ✅ Changelog جدید: `CHANGELOG-2025-12-25.md`
### نسخه 2.3 (۳ دی ۱۴۰۴ / Dec 23, 2025):
-**Chatika Integration**: Worker خودکار فعال‌سازی حساب چتیکا
-**ClubFeatureType Enum**: جایگزینی hardcoded IDs با Enum قابل نگهداری
-**LegPosition Logic**: تنظیم خودکار دست چپ/راست در ثبت‌نام شبکه
-**Handler Sync**: همگام‌سازی AcceptContract و ActivateMembership
- ✅ مستندات جدید: `chatika-integration.md`, `club-features-system.md`
- ✅ Changelog جدید: `CHANGELOG-2025-12-23.md`
### نسخه 2.2 (۳۰ آذر ۱۴۰۴ / Dec 20, 2025):
- ✅ رفع باگ‌های /network/balances, /club/members, /club/statistics
- ✅ فعال‌سازی Products: CreateNew, Update, Gallery, Tags
- ✅ Changelog جدید: `CHANGELOG-2025-12-20.md`
### نسخه 2.0 (۱۴ آذر ۱۴۰۴):
- ✅ بازسازی کامل ساختار مستندات
- ✅ تجمیع اسناد تکراری
- ✅ آرشیو اسناد منسوخ
- ✅ ایجاد CURRENT-SPRINT.md
- ✅ به‌روزرسانی با کارهای امروز (7 صفحه + 3 BFF module)
### نسخه 1.0 (1 دسامبر 2025):
- INDEX.md اولیه با 24 فایل
---
**🎯 این مستندات همواره در حال به‌روزرسانی هستند. آخرین نسخه را از Git دریافت کنید.**