# 📚 FourSat Project - فهرست جامع مستندات (نسخه تجمیع شده)

> **آخرین بروزرسانی**: ۲۸ آذر ۱۴۰۴ (18 دسامبر 2025)  
> **وضعیت**: ✅ بروزرسانی شده با Session امروز  
> **تحلیلگر**: GitHub Copilot (Claude Opus 4.5)

---

## 🆕 تغییرات امروز (۲۸ آذر) - Session 2

### ✅ سیستم مدیریت موجودی محصولات
- **CMS**: چک موجودی در `SubmitShopBuyOrderCommandHandler`
- **کاهش خودکار موجودی**: بعد از تکمیل سفارش `RemainingCount` کم می‌شود
- **افزایش SaleCount**: همزمان با کاهش موجودی
- **FrontOffice**: نمایش وضعیت موجودی در صفحه محصول
- **محدودیت خرید**: حداکثر تعداد = موجودی انبار

### ✅ ویژگی‌های باشگاه مشتریان (ClubFeatures)
- **حذف فیلدهای اضافی**: `DetailedDescriptionHtml`, `Icon`, `Color` از `UserClubFeature`
- **معماری صحیح**: داده‌های قالب در `ClubFeature`، داده‌های کاربر در `UserClubFeature`
- **FeaturesPage**: بازطراحی با لیست ساده (آیکون تیک + عنوان + دکمه جزئیات)
- **MembershipPage**: مزایای عضویت اصلاح شده (کیف پول ۵۶ میلیون، شبکه بازاریابی، جذب زیرمجموعه)

### ✅ بهبود مدال آدرس‌ها
- **رفع خطای Snackbar**: حذف inject تکراری (global در `_Imports.razor`)
- **رفع NullReferenceException**: اضافه کردن null check برای `dialog.Result`

### ✅ VAT Service
- **نرخ پیش‌فرض**: 9.99% برای تشخیص داده سرور از local
- **استفاده یکپارچه**: در تمام صفحات از `VATService` استفاده می‌شود

### ✅ CartService Authentication
- **EnsureInitializedAsync**: لود سبد خرید فقط برای کاربران لاگین‌شده
- **IsAuthenticatedAsync**: چک توکن در LocalStorage

---

## 🆕 تغییرات قبلی (۲۸ آذر) - Session 1

### ✅ نمودار درختی شبکه با d3-org-chart (FrontOffice)
- **کتابخانه**: d3-org-chart v3 + d3.js v7 + d3-flextree
- **OrganizationChart.razor**: بازنویسی کامل با JS Interop
- **امکانات**:
  - نمایش درختی باینری شبکه
  - کلیک روی نود → نمایش زیرمجموعه‌ها
  - دکمه‌های بازگشت و "درخت من"
  - انتخاب عمق درخت (2-10 سطح)
  - طراحی ریسپانسیو با MudBlazor

### ✅ API جدید: GetSubordinateTree
- **Proto**: `GetSubordinateTreeRequest` در `networkmembership.proto`
- **BFF Handler**: `GetSubordinateTreeQueryHandler`
- **Frontend Service**: `GetSubordinateTreeAsync(targetUserId, maxDepth)`

### ✅ بهبود Entity Configuration برای فارسی (CMS)
- **Geography Tables**: Country, State, City
- **تغییرات**: `nvarchar` با `Persian_100_CI_AI` collation
- **Migration**: `FixPersianCollation_Geography`

---

## 🆕 تغییرات قبلی (۲۲ آذر)

### ✅ تبدیل تاریخ‌ها به شمسی در UI
- **PersianDateTimeService**: سرویس تبدیل تاریخ میلادی به شمسی
- **3 صفحه آپدیت شده**: Dashboard, UserPayouts, WorkerControl
- **معماری**: تبدیل فقط در لایه نمایش، Backend میلادی باقی ماند

### ✅ بهبود سرویس اطلاعات شبکه
- **28+ فیلد جدید** در GetUserNetworkPosition
- **آمار کامل شبکه**: TotalNetworkSize, MaxDepth, ActiveMembers
- **آمار مالی**: کمیسیون کسب شده، پرداخت شده، در انتظار
- **UI بازنویسی شده**: 6 کارت اطلاعاتی با آیکون و رنگ‌بندی

### ✅ یکپارچه‌سازی محاسبه شماره هفته
- **Saturday-based**: همه سیستم‌ها از شنبه شروع می‌کنند
- **C# & SQL هماهنگ**: الگوریتم یکسان در GetWeekNumber
- **رفع Bug**: هفته 50 → هفته 49 (صحیح)

**📄 مستند کامل**: [SESSION-2025-12-12-PERSIAN-DATE-AND-NETWORK-INFO-IMPROVEMENTS.md](SESSION-2025-12-12-PERSIAN-DATE-AND-NETWORK-INFO-IMPROVEMENTS.md)

---

## 📊 وضعیت کلی پروژه (بروزرسانی لحظه‌ای)

### **بررسی صحت مستندات موجود:**

#### ✅ مستندات معتبر و به‌روز:
- `CMS/implementation-progress.md` ✅ (3060 خط - تا 12 دسامبر 2025)
  - Phase 9: Club Discount Shop ✅ Complete (100%)
  - Phase 12: Package Purchase System ✅ Complete (100%)
  - **بیلد موفق**: 0 error, 465 warnings
  - **جدید**: GetUserNetworkPosition با 42 فیلد
  
- `BackOffice/development-plan.md` ✅ (1462 خط - 12 دسامبر 2025)
  - 23 صفحه UI کامل
  - 35 Handler در BFF
  - **جدید**: PersianDateTimeService برای نمایش شمسی
  - **Production Ready**: 100%
  
- `SESSION-2025-12-12-PERSIAN-DATE-AND-NETWORK-INFO-IMPROVEMENTS.md` ⭐ جدید
  - تبدیل تاریخ شمسی (3 صفحه)
  - بهبود سرویس شبکه (28+ فیلد)
  - یکپارچه‌سازی محاسبه هفته

#### ⚠️ مستندات نیاز به بروزرسانی:
- `REMAINING-TASKS-CONSOLIDATED.md` - آخرین بروزرسانی: 2 دسامبر
  - **نیاز**: بروزرسانی با Phase 9 و 12
  - **نیاز**: افزودن TODO های FrontOffice

- `INDEX.md` - آخرین بروزرسانی: 1 دسامبر
  - **نیاز**: افزودن اسناد FrontOffice جدید
  - **نیاز**: بروزرسانی وضعیت Phase ها

#### 🔴 مستندات منسوخ/تکراری:
- `REMAINING-TASKS.md` ❌ (خود این فایل می‌گوید منسوخ است)
  - محتوا مشابه REMAINING-TASKS-CONSOLIDATED.md
  - **اقدام**: انتقال به ARCHIVE

---

## 🗂️ ساختار جدید پیشنهادی

```
totalDoc/
├── 00-INDEX.md                          # این فایل (فهرست اصلی)
├── 01-BUSINESS/                         # 📊 منطق تجاری
│   ├── club-membership-business.md      # باشگاه مشتریان
│   ├── network-binary-tree.md           # شبکه دودویی
│   ├── commission-system.md             # سیستم کمیسیون
│   ├── discount-shop-business.md        # فروشگاه تخفیف
│   ├── package-purchase-system.md       # خرید پکیج طلایی
│   └── daya-loan-integration.md         # قرض‌الحسنه دایا
│
├── 02-ARCHITECTURE/                     # 🏗️ معماری
│   ├── system-overview.md               # نمای کلی سیستم
│   ├── microservices-structure.md       # ساختار Microservice
│   ├── bff-pattern.md                   # الگوی BFF
│   └── database-schema.md               # طراحی دیتابیس
│
├── 03-BACKEND/                          # ⚙️ Backend
│   ├── CMS/
│   │   ├── README.md                    # نمای کلی + Quick Start
│   │   ├── implementation-status.md     # وضعیت پیاده‌سازی (95%)
│   │   ├── api-coverage.md              # پوشش API
│   │   └── entity-guide.md              # راهنمای Entity ها
│   ├── BackOffice.BFF/
│   │   ├── README.md                    # نمای کلی
│   │   ├── handlers-status.md           # 35 Handler
│   │   └── cms-integration.md           # یکپارچه‌سازی با CMS
│   └── FrontOffice.BFF/
│       ├── README.md                    # نمای کلی
│       ├── handlers-status.md           # 12 Handler
│       └── protobuf-mismatch.md         # مغایرت Proto با CMS
│
├── 04-FRONTEND/                         # 🎨 Frontend
│   ├── BackOffice/
│   │   ├── README.md                    # نمای کلی (23 صفحه)
│   │   └── ui-status.md                 # وضعیت صفحات
│   └── FrontOffice/
│       ├── README.md                    # نمای کلی (24 صفحه)
│       ├── ui-pages-guide.md            # راهنمای صفحات
│       └── todo-commented-code.md       # کدهای کامنت شده
│
├── 05-TASKS/                            # ✅ وظایف
│   ├── CURRENT-SPRINT.md                # اسپرینت جاری
│   ├── BACKLOG.md                       # کارهای آینده
│   ├── COMPLETED.md                     # انجام شده
│   └── BLOCKERS.md                      # موانع
│
├── 06-DEPLOYMENT/                       # 🚀 استقرار
│   ├── quick-start.md                   # راهنمای شروع سریع
│   ├── delivery-readiness.md            # آمادگی تحویل
│   └── monitoring-alerts.md             # مانیتورینگ و هشدارها
│
└── 99-ARCHIVE/                          # 📦 آرشیو
    ├── ARCHIVE-INDEX.md                 # فهرست آرشیو با دلیل
    └── old-docs/                        # اسناد قدیمی
```

---

## 📋 گزارش تحلیل اولیه

### 1️⃣ اسناد موجود (42 فایل .md)

#### دسته‌بندی بر اساس موضوع:

**A. Business Logic (8 فایل):**
- ✅ `CMS/network-club-commission-system-v1.1.md` (آخرین نسخه)
- ⚠️ `CMS/network-club-commission-system.md` (نسخه قدیمی - **آرشیو**)
- ✅ `CMS/discount-shop-system.md`
- ✅ `CMS/package-purchase-system.md`
- ✅ `CMS/balance-calculation-carryover-logic.md`
- ✅ `CMS/daya-loan-integration.md`
- ✅ `CMS/manual-payment-system.md`
- ✅ `CMS/binary-tree-registration-guide.md`

**B. Implementation Status (5 فایل):**
- ✅ `CMS/implementation-progress.md` (اصلی - 3060 خط)
- ⚠️ `CMS/implementation-progress-fa.md` (تکراری - **ادغام**)
- ✅ `BackOffice/development-plan.md` (1462 خط)
- ✅ `FrontOffice/README.md` (جدید)
- ✅ `FrontOffice/BFF-CMS-PROTOBUF-MISMATCH-ANALYSIS.md`

**C. Configuration & Guide (6 فایل):**
- ✅ `CMS/email-sms-configuration-guide.md`
- ✅ `CMS/migration-network-parent-guide.md`
- ✅ `CMS/payment-gateway-integration.md`
- ✅ `CMS/payment-architecture-pyms.md`
- ✅ `BackOffice.BFF/cms-integration.md`
- ✅ `BackOffice.BFF/discount-shop-integration-plan.md`

**D. Analysis & Reports (5 فایل):**
- ✅ `CMS/ANALYSIS-CONTRADICTIONS-AND-ISSUES.md`
- ⚠️ `CMS/monitoring-alerts-implementation-report.md` (تکراری)
- ⚠️ `CMS/monitoring-alerts-consolidated-report.md` (ادغام شده)
- ✅ `FrontOffice/FRONTOFFICE-ANALYSIS.md`
- ✅ `FrontOffice/PROGRESS-REPORT-1404-09-14.md`

**E. Tasks & Planning (4 فایل):**
- ⚠️ `REMAINING-TASKS.md` ❌ (منسوخ)
- ✅ `REMAINING-TASKS-CONSOLIDATED.md` (اصلی)
- ✅ `BUSINESS-VERIFICATION-TEMPLATE.md`
- ✅ `DELIVERY-READINESS-REPORT.md`

**F. General (5 فایل):**
- ⚠️ `README.md` (ساده - نیاز به بروزرسانی)
- ⚠️ `INDEX.md` (نیاز به بروزرسانی)
- ✅ `QUICK-START-DEVELOPMENT.md`
- ✅ `CMS-API-COVERAGE.md`
- ✅ `BACKOFFICE-UI-STATUS.md`

**G. Others (9 فایل):**
- `BackOffice/README.md`
- `BackOffice.BFF/README.md`
- `FrontOffice.BFF/README.md`
- `FrontOffice/TODO-COMMENTED-CODE.md`
- `FrontOffice/mudblazor_classes.md`
- `CMS/README.md`
- `CMS/cms-data-and-business.md`
- `CMS/ENTITY-NAMING-REFACTORING-PLAN.md`
- `BackOffice.BFF/.github/git-commit-instructions.md`

---

### 2️⃣ یافته‌های کلیدی از بررسی

#### ✅ موارد تایید شده:

1. **CMS: 95% تکمیل**
   - Phase 1-12 تکمیل شده (به جز Testing)
   - 0 خطا در Build
   - Phase 9 (Discount Shop) ✅
   - Phase 12 (Package Purchase) ✅

2. **BackOffice: 100% Production Ready**
   - 23 صفحه UI کامل
   - 35 Handler در BFF
   - 5 gRPC Service

3. **FrontOffice: 60% BFF / 40% UI**
   - 12 Handler در BFF (3 جدید امروز)
   - 24 صفحه UI موجود
   - **Gap**: UI برای Club/Network/Commission

#### ⚠️ موارد نیازمند توجه:

1. **مستندات تکراری**:
   - `implementation-progress.md` (EN) vs `implementation-progress-fa.md` (FA)
   - `monitoring-alerts-*.md` (2 نسخه)
   - `network-club-commission-system.md` vs `v1.1.md`

2. **TODO های پراکنده**:
   - در `FrontOffice/TODO-COMMENTED-CODE.md`: 5 متد کامنت شده
   - در `FrontOffice.BFF/`: 27 Handler TODO
   - در `REMAINING-TASKS-CONSOLIDATED.md`: Task ها قدیمی

3. **اسناد بدون تاریخ**:
   - برخی فایل‌ها تاریخ آخرین بروزرسانی ندارند
   - نیاز به Metadata یکپارچه

---

### 3️⃣ اولویت‌های تجمیع

#### فاز 1: تجمیع Business Logic (اولویت بالا 🔴)
```
[ ] ادغام network-club-commission-system.md + v1.1.md
    → 01-BUSINESS/network-commission-system.md (نسخه نهایی)

[ ] استخراج Club از implementation-progress.md
    → 01-BUSINESS/club-membership-business.md

[ ] استخراج Discount Shop
    → 01-BUSINESS/discount-shop-business.md

[ ] استخراج Package Purchase
    → 01-BUSINESS/package-purchase-system.md

[ ] نگه‌داشتن:
    - daya-loan-integration.md
    - balance-calculation-carryover-logic.md
    - manual-payment-system.md
```

#### فاز 2: تجمیع Backend Docs (اولویت بالا 🔴)
```
[ ] CMS/
    - implementation-progress.md → implementation-status.md
    - ادغام implementation-progress-fa.md
    - cms-data-and-business.md → entity-guide.md
    - CMS-API-COVERAGE.md → api-coverage.md

[ ] BackOffice.BFF/
    - development-plan.md → handlers-status.md
    - cms-integration.md (بدون تغییر)

[ ] FrontOffice.BFF/
    - README.md (جدید)
    - BFF-CMS-PROTOBUF-MISMATCH-ANALYSIS.md → protobuf-mismatch.md
```

#### فاز 3: تجمیع Frontend Docs (اولویت متوسط 🟡)
```
[ ] BackOffice/
    - BACKOFFICE-UI-STATUS.md → ui-status.md
    - README.md (به‌روزرسانی)

[ ] FrontOffice/
    - README.md (جدید - امروز)
    - FRONTOFFICE-ANALYSIS.md → ui-analysis.md
    - TODO-COMMENTED-CODE.md (بدون تغییر)
```

#### فاز 4: تجمیع Tasks (اولویت بالا 🔴)
```
[ ] CURRENT-SPRINT.md (جدید)
    - استخراج از REMAINING-TASKS-CONSOLIDATED.md
    - TODO های فعال FrontOffice
    - TODO های باقی‌مانده CMS

[ ] BACKLOG.md
    - Feature های آینده (RBAC, VAT, etc.)
    - بهبودهای اختیاری

[ ] COMPLETED.md
    - Phase 1-12 CMS
    - BackOffice UI (23 صفحه)
    - FrontOffice BFF (12 Handler)
```

#### فاز 5: آرشیو (اولویت پایین 🟢)
```
[ ] انتقال به 99-ARCHIVE/:
    - REMAINING-TASKS.md (منسوخ)
    - network-club-commission-system.md (نسخه قدیمی)
    - implementation-progress-fa.md (ادغام شد)
    - monitoring-alerts-implementation-report.md (ادغام شد)
    - PROGRESS-REPORT-1404-09-14.md (گزارش موقت)
```

---

## 🔍 صحت‌سنجی محتوا (Validation)

### چک‌لیست برای هر سند:

```
✅ implementation-progress.md:
    - تاریخ: 2024-12-04 ✅
    - Phase 9: Complete ✅
    - Phase 12: Complete ✅
    - Build Status: 0 error ✅
    - **نتیجه**: معتبر و به‌روز

✅ development-plan.md:
    - تاریخ: 2025-12-01 ✅
    - 23 صفحه: تایید شده ✅
    - 35 Handler: تایید شده ✅
    - **نتیجه**: معتبر و به‌روز

✅ FrontOffice/README.md:
    - تاریخ: امروز ✅
    - 24 صفحه: تایید شده ✅
    - 12 Handler: تایید شده ✅
    - Build: 0 error ✅
    - **نتیجه**: معتبر و به‌روز

⚠️ REMAINING-TASKS-CONSOLIDATED.md:
    - تاریخ: 2024-12-02 ⚠️
    - Phase 9: ذکر نشده ❌
    - Phase 12: ذکر نشده ❌
    - **نتیجه**: نیاز به بروزرسانی

⚠️ INDEX.md:
    - تاریخ: 2025-12-01 ⚠️
    - FrontOffice docs: ناقص ❌
    - **نتیجه**: نیاز به بروزرسانی
```

---

## 📊 آمار نهایی

### اسناد موجود:
- **کل**: 42 فایل .md
- **معتبر**: 32 فایل ✅
- **نیاز به بروزرسانی**: 5 فایل ⚠️
- **منسوخ/تکراری**: 5 فایل ❌

### پس از تجمیع (تخمین):
- **01-BUSINESS**: 6 فایل
- **02-ARCHITECTURE**: 4 فایل
- **03-BACKEND**: 9 فایل (3 + 3 + 3)
- **04-FRONTEND**: 6 فایل (3 + 3)
- **05-TASKS**: 4 فایل
- **06-DEPLOYMENT**: 3 فایل
- **99-ARCHIVE**: 5 فایل

**جمع جدید**: ~30-35 فایل فعال

---

## ⏱️ تخمین زمان تجمیع کامل

| فاز | مدت زمان | وضعیت |
|-----|---------|-------|
| فاز 1: Business Logic | 3-4 ساعت | ⏳ در انتظار |
| فاز 2: Backend Docs | 2-3 ساعت | ⏳ در انتظار |
| فاز 3: Frontend Docs | 2 ساعت | ⏳ در انتظار |
| فاز 4: Tasks | 2-3 ساعت | ⏳ در انتظار |
| فاز 5: آرشیو | 1 ساعت | ⏳ در انتظار |
| فاز 6: INDEX جامع | 1-2 ساعت | ⏳ در انتظار |
| **جمع کل** | **11-15 ساعت** | |

---

## 🚀 مراحل بعدی پیشنهادی

### مرحله A: تایید ساختار (15 دقیقه)
```
[ ] بررسی ساختار پیشنهادی (01-BUSINESS, 02-ARCHITECTURE, ...)
[ ] تایید نام‌گذاری پوشه‌ها
[ ] تایید اولویت‌بندی
```

### مرحله B: شروع تجمیع (3 ساعت)
```
[ ] فاز 1: Business Logic
[ ] فاز 2: Backend Docs (CMS)
```

### مرحله C: ادامه تجمیع (4 ساعت)
```
[ ] فاز 2: Backend Docs (BFFs)
[ ] فاز 3: Frontend Docs
```

### مرحله D: TODO ها (3 ساعت)
```
[ ] فاز 4: Tasks (CURRENT-SPRINT, BACKLOG, COMPLETED)
[ ] بروزرسانی با TODO های FrontOffice
```

### مرحله E: نهایی‌سازی (2 ساعت)
```
[ ] فاز 5: آرشیو
[ ] فاز 6: INDEX جامع با لینک‌ها
[ ] تست تمام لینک‌ها
```

---

## ❓ سوالات برای تایید

قبل از ادامه، لطفا تایید کنید:

1. ✅ آیا ساختار پیشنهادی (01-BUSINESS, ..., 99-ARCHIVE) مناسب است؟
2. ✅ آیا اولویت‌بندی (Business → Backend → Frontend → Tasks) درست است؟
3. ✅ آیا فایل‌های شناسایی شده برای آرشیو صحیح هستند؟
4. ✅ آیا می‌خواهید همه را همین الان انجام دهم یا گام به گام؟

---

**📝 نتیجه**: 

این سند یک نقشه راه کامل برای تجمیع و بازسازی مستندات است. 
پس از تایید شما، من می‌توانم شروع به اجرای مرحله به مرحله کنم.

**منتظر دستور شما هستم** 🎯