docs/archive/README-BALANCE-CALCULATION.md

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

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

---

🎯 شروع سریع

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

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

---

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

🌳 ساختار شبکه باینری

فایل: 01-BUSINESS/binary-tree-guide.md

محتوا:

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

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

---

📊 قوانین محاسبه تعادل

فایل: 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

محتوا:

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

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

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

---

💼 سیستم کمیسیون شبکه

فایل: 01-BUSINESS/network-commission-system.md

محتوا:

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

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

---

💰 سیستم خرید پکیج

فایل: 01-BUSINESS/package-purchase-system.md

محتوا:

• ✅ انواع پکیج‌ها
• ✅ فرآیند خرید
• ✅ شارژ کیف پول‌ها
• ✅ تبدیل به عضویت باشگاه

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

---

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

📋 تحلیل توضیحات جدید بیزینس

فایل: 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

محتوا:

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

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

---

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

🆕 آخرین تغییرات (2025-12-09)

فایل: CHANGELOG-2025-12-09.md

محتوا:

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

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

---

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

✅ Task های اصلاحی

فایل: 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
• Balance Calculation Rules
• 5-Level Examples
• Network Commission System

تحلیل و گزارش:

• Analysis Report
• New Requirements
• Changelog

Task ها:

• Task List
• Current Sprint
• Backlog

کد:

• CalculateWeeklyBalancesCommandHandler.cs
• 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