docs/archive/00-INDEX.md

# 📚 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 دریافت کنید.**