# 📚 راهنمای کامل Documentation - محاسبات تعادل شبکه

**تاریخ**: 2025-12-09  
**موضوع**: مستندات کامل سیستم محاسبه تعادل باینری  
**وضعیت**: ✅ به‌روز و تکمیل شده

---

## 🎯 شروع سریع

اگر برای اولین بار هستید، این ترتیب را دنبال کنید:

1. **مفاهیم اصلی**: [`binary-tree-guide.md`](./01-BUSINESS/binary-tree-guide.md)
2. **قوانین محاسبه**: [`balance-calculation-rules.md`](./01-BUSINESS/balance-calculation-rules.md)
3. **مثال‌های عملی**: [`balance-calculation-examples-5-levels.md`](./01-BUSINESS/balance-calculation-examples-5-levels.md)
4. **تحلیل جدید**: [`ANALYSIS-NEW-BUSINESS-REQUIREMENTS.md`](./ANALYSIS-NEW-BUSINESS-REQUIREMENTS.md)
5. **تغییرات اخیر**: [`CHANGELOG-2025-12-09.md`](./CHANGELOG-2025-12-09.md)

---

## 📖 مستندات بیزینس (Business Documentation)

### 🌳 ساختار شبکه باینری
**فایل**: [`01-BUSINESS/binary-tree-guide.md`](./01-BUSINESS/binary-tree-guide.md)

**محتوا**:
- ✅ قوانین Binary Tree (حداکثر 2 فرزند)
- ✅ Position validation (Left/Right)
- ✅ NetworkPlacementService API
- ✅ محدودیت‌ها و قوانین

**زمان مطالعه**: 10 دقیقه

---

### 📊 قوانین محاسبه تعادل
**فایل**: [`01-BUSINESS/balance-calculation-rules.md`](./01-BUSINESS/balance-calculation-rules.md)

**محتوا**:
- ✅ 4 مرحله محاسبات (تعادل → باقیمانده → سقف → فلش)
- ✅ فرمول‌های کامل
- ✅ Configuration-based calculation
- ✅ مثال‌های عددی
- ✅ مقایسه قبل و بعد

**آخرین به‌روزرسانی**: 2025-12-09  
**وضعیت**: ✅ Verified & Implemented

**زمان مطالعه**: 20 دقیقه

---

### 🎯 مثال‌های عملی 5 لول
**فایل**: [`01-BUSINESS/balance-calculation-examples-5-levels.md`](./01-BUSINESS/balance-calculation-examples-5-levels.md)

**محتوا**:
- ✅ درخت 63 کاربره (6 لول عمق)
- ✅ محاسبات دقیق Level به Level
- ✅ جدول جمع‌بندی
- ✅ محاسبه صندوق و توزیع
- ✅ سناریوهای پیچیده (نامتعادل، سقف، Carryover)
- ✅ 10+ مثال عددی مختلف

**تاریخ ایجاد**: 2025-12-09  
**وضعیت**: ✅ جامع و کامل

**زمان مطالعه**: 30 دقیقه

---

### 💼 سیستم کمیسیون شبکه
**فایل**: [`01-BUSINESS/network-commission-system.md`](./01-BUSINESS/network-commission-system.md)

**محتوا**:
- ✅ مفاهیم کلیدی (کیف پول‌ها، فعال‌سازی)
- ✅ موجودیت‌های Domain
- ✅ فرآیند کامل ثبت نام تا پرداخت
- ✅ History & Audit tables

**زمان مطالعه**: 40 دقیقه

---

### 💰 سیستم خرید پکیج
**فایل**: [`01-BUSINESS/package-purchase-system.md`](./01-BUSINESS/package-purchase-system.md)

**محتوا**:
- ✅ انواع پکیج‌ها
- ✅ فرآیند خرید
- ✅ شارژ کیف پول‌ها
- ✅ تبدیل به عضویت باشگاه

**زمان مطالعه**: 15 دقیقه

---

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

### 📋 تحلیل توضیحات جدید بیزینس
**فایل**: [`ANALYSIS-NEW-BUSINESS-REQUIREMENTS.md`](./ANALYSIS-NEW-BUSINESS-REQUIREMENTS.md)

**محتوا**:
- ✅ مقایسه با Documentation موجود (95% سازگاری)
- ✅ مقایسه با کد فعلی (100% Balance Logic)
- ✅ تناقضات شناسایی شده
- ✅ لیست Task های لازم برای اصلاح
- ✅ جدول مقایسه تفصیلی

**تاریخ**: 2025-12-08  
**آخرین به‌روزرسانی**: 2025-12-09

**زمان مطالعه**: 25 دقیقه

---

### 📝 توضیحات جدید بیزینس (خام)
**فایل**: [`01-BUSINESS/new-business-requirements-2025-12-08.md`](./01-BUSINESS/new-business-requirements-2025-12-08.md)

**محتوا**:
- ✅ خلاصه‌سازی متن شفاهی صاحب پروژه
- ✅ 10 بخش کامل
- ✅ جدول مقایسه حالات مختلف
- ✅ فرآیند کامل فعال‌سازی

**زمان مطالعه**: 20 دقیقه

---

## 📌 تغییرات و به‌روزرسانی‌ها

### 🆕 آخرین تغییرات (2025-12-09)
**فایل**: [`CHANGELOG-2025-12-09.md`](./CHANGELOG-2025-12-09.md)

**محتوا**:
- ✅ اصلاح کد محاسبه تعادل (قبل و بعد)
- ✅ مقایسه نتایج
- ✅ فایل‌های تغییر یافته
- ✅ یادداشت‌های مهم برای Developer
- ✅ Query های تست

**زمان مطالعه**: 10 دقیقه

---

## 📋 Task ها و اولویت‌ها

### ✅ Task های اصلاحی
**فایل**: [`05-TASKS/NEW-BUSINESS-REQUIREMENTS-TASKS.md`](./05-TASKS/NEW-BUSINESS-REQUIREMENTS-TASKS.md)

**محتوا**:
- ✅ Task #0: اصلاح محاسبات (Complete ✅)
- 🔥 Task #1: DeleteInactiveUsersWorker (6h)
- 🔥 Task #2: الزامی دیالوگ باشگاه (8h)
- 🔥 Task #3: شرط لینک معرفی (4h)
- ⚠️ Task #4: Validation 2 فرزند فعال (4h)
- ⚠️ Task #5: پیغام کد معرف پر (3h)
- 📝 Task #6: Update Documentation (3h)

**جمع زمان باقیمانده**: 28 ساعت (~4 روز)

**زمان مطالعه**: 15 دقیقه

---

## 🎓 مسیر یادگیری پیشنهادی

### برای Developer تازه‌کار:
```
1. binary-tree-guide.md (مفاهیم پایه)
   ↓
2. network-commission-system.md (کل سیستم)
   ↓
3. balance-calculation-rules.md (قوانین محاسبه)
   ↓
4. balance-calculation-examples-5-levels.md (مثال‌های عملی)
   ↓
5. کد: CalculateWeeklyBalancesCommandHandler.cs (پیاده‌سازی)
```

**زمان کل**: 2-3 ساعت

---

### برای Senior Developer:
```
1. CHANGELOG-2025-12-09.md (آخرین تغییرات)
   ↓
2. balance-calculation-rules.md (قوانین دقیق)
   ↓
3. ANALYSIS-NEW-BUSINESS-REQUIREMENTS.md (تحلیل کامل)
   ↓
4. 05-TASKS/NEW-BUSINESS-REQUIREMENTS-TASKS.md (Task ها)
   ↓
5. کد: بررسی Implementation
```

**زمان کل**: 1-2 ساعت

---

### برای Business Analyst:
```
1. new-business-requirements-2025-12-08.md (توضیحات اولیه)
   ↓
2. balance-calculation-examples-5-levels.md (مثال‌های عملی)
   ↓
3. ANALYSIS-NEW-BUSINESS-REQUIREMENTS.md (تحلیل)
   ↓
4. network-commission-system.md (کل سیستم)
```

**زمان کل**: 1.5-2 ساعت

---

## 🔗 لینک‌های سریع

### مستندات اصلی:
- [Binary Tree Guide](./01-BUSINESS/binary-tree-guide.md)
- [Balance Calculation Rules](./01-BUSINESS/balance-calculation-rules.md)
- [5-Level Examples](./01-BUSINESS/balance-calculation-examples-5-levels.md)
- [Network Commission System](./01-BUSINESS/network-commission-system.md)

### تحلیل و گزارش:
- [Analysis Report](./ANALYSIS-NEW-BUSINESS-REQUIREMENTS.md)
- [New Requirements](./01-BUSINESS/new-business-requirements-2025-12-08.md)
- [Changelog](./CHANGELOG-2025-12-09.md)

### Task ها:
- [Task List](./05-TASKS/NEW-BUSINESS-REQUIREMENTS-TASKS.md)
- [Current Sprint](./05-TASKS/CURRENT-SPRINT.md)
- [Backlog](./05-TASKS/BACKLOG.md)

### کد:
- [CalculateWeeklyBalancesCommandHandler.cs](../CMS/src/CMSMicroservice.Application/CommissionCQ/Commands/CalculateWeeklyBalances/CalculateWeeklyBalancesCommandHandler.cs)
- [CalculateWeeklyCommissionPoolCommandHandler.cs](../CMS/src/CMSMicroservice.Application/CommissionCQ/Commands/CalculateWeeklyCommissionPool/CalculateWeeklyCommissionPoolCommandHandler.cs)

---

## 📊 آمار مستندات

```
تعداد فایل‌ها: 10+
تعداد خطوط: 2000+
تاریخ آخرین به‌روزرسانی: 2025-12-09
وضعیت: ✅ 95% Complete
```

### Coverage:
- ✅ Business Logic: 100%
- ✅ Examples: 100%
- ✅ Code Implementation: 100%
- ⚠️ User Flow: 60%
- ❌ Background Workers: 0%

---

## 🎯 نکات کلیدی

### 🔥 حیاتی:
1. **ترتیب 4 مرحله** در محاسبات تعادل دست نخورده باشد
2. **باقیمانده جداگانه** (چپ و راست) ذخیره شود
3. **فلش از دو طرف** محاسبه شود

### ⚠️ مهم:
4. سقف 300 روی **امتیاز نهایی** است، نه تعادل اولیه
5. هر کاربر **مستقل** محاسبه می‌شود
6. باقیمانده‌ها برای **هفته بعد** نگهداری می‌شوند

### 💡 توصیه:
7. قبل از تغییر کد، حتماً مستندات را بخوانید
8. بعد از تغییر، مثال‌های 5 لول را تست کنید
9. Documentation را همزمان با کد به‌روز کنید

---

## 📞 ارتباط

برای سوال یا پیشنهاد در مورد مستندات:
- مستندات را در `totalDoc/` قرار دهید
- Changelog ها را در ریشه `totalDoc/` نگه دارید
- مثال‌ها را در `01-BUSINESS/` اضافه کنید

---

**آخرین به‌روزرسانی**: 2025-12-09  
**نسخه**: 2.0  
**نگهدارنده**: AI Assistant