docs/00-INDEX.md

📚 FourSat Project - فهرست جامع مستندات

نسخه: 2.8
آخرین بروزرسانی: ۱۱ دی ۱۴۰۴ (December 31, 2025)
وضعیت: ✅ تجمیع و بازسازی کامل

---

🎯 راهنمای سریع (Quick Navigation)

برای توسعه‌دهندگان:

• 🚀 شروع سریع: 06-DEPLOYMENT/quick-start.md
• 📋 کارهای جاری: 05-TASKS/CURRENT-SPRINT.md
• 🐛 TODO های کد: 04-FRONTEND/FrontOffice/todo-commented-code.md

برای معماران:

• 🏗️ معماری سیستم: 02-ARCHITECTURE/
• 📊 Business Logic: 01-BUSINESS/

برای مدیران:

• ✅ وضعیت تحویل: 06-DEPLOYMENT/delivery-readiness.md
• 📈 گزارش پیشرفت: 03-BACKEND/CMS/implementation-status.md

---

📊 وضعیت کلی پروژه

Backend Services:

سرویس	وضعیت	تکمیل	فایل مرجع
CMS Microservice	✅ Production Ready	98%	03-BACKEND/CMS/implementation-status.md
BackOffice.BFF	✅ Production Ready	100%	03-BACKEND/BackOffice.BFF/handlers-status.md
FrontOffice.BFF	🚧 In Progress	60%	03-BACKEND/FrontOffice.BFF/README.md

Frontend Applications:

اپلیکیشن	وضعیت	تکمیل	فایل مرجع
BackOffice UI	✅ Production Ready	100%	04-FRONTEND/BackOffice/ui-status.md
FrontOffice UI	🚧 In Progress	75%	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	شبکه + کمیسیون	Binary MLM Tree, Flash Out, Weekly Pool
discount-shop-business.md	فروشگاه تخفیف	محصولات تخفیف‌دار، محدودیت DiscountBalance
package-purchase-system.md	خرید پکیج طلایی	فعال‌سازی باشگاه، پرداخت 56M
daya-loan-integration.md	قرض‌الحسنه دایا	خرید الماس، انتقال NetworkBalance
balance-calculation-rules.md	محاسبه موجودی	Carryover Logic, تعادل‌های باقیمانده
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	نمای کلی CMS	معرفی، تکنولوژی‌ها، Quick Start
implementation-status.md	پیشرفت پیاده‌سازی	Phase 1-12، 98% Complete، Daya API ✅
entity-guide.md	راهنمای Entity ها	Domain Entities، Relations، Validations
commission-system.md	✨ سیستم کمیسیون	Entities, Proto Models, WeekDefinitionId Migration
api-coverage.md	پوشش API	لیست تمام gRPC Services و Handlers
email-sms-configuration.md	Email & SMS	Kavenegar, MailKit, Templates
payment-gateway.md	درگاه پرداخت	ZarinPal, Daya Integration
daya-api-implementation.md	✨ Daya API Guide	Complete Real API Implementation (Dec 6)
club-membership-migration.md	✨ Migration Scripts	اسکریپت‌های مهاجرت باشگاه مشتریان (Dec 9)
chatika-integration.md	🤖 Chatika Integration	Worker خودکار فعال‌سازی حساب AI (Dec 23)
club-features-system.md	🎁 Club Features	Enum، Handler ها، UserClubFeatures (Dec 23)
INVENTORY-SYSTEM-PLAN.md	📦 سیستم انبارداری	پلن یکپارچه‌سازی موجودی (Jan 1, 2026)
PRODUCT-BUNDLE-FEATURE.md	📦 پکیج محصولات	⏸️ Postponed - بسته‌بندی محصولات (Jan 1, 2026)
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	نمای کلی BFF	معماری، Communication با CMS
handlers-status.md	وضعیت Handler ها	35 CQRS Handler، 100% Complete
cms-integration.md	یکپارچه‌سازی CMS	Protobuf, gRPC Client Configuration
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	نمای کلی BFF	معماری، 12 Handler (9 + 3 new)
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	نمای کلی BackOffice	Blazor Server، MudBlazor 8.14.0
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	نمای کلی FrontOffice	24 Pages، 75% Complete
gap-analysis.md	تحلیل Gap	12 Module، 7 نیاز به API واقعی
todo-commented-code.md	⚠️ TODO های کد	5 متد WalletService + 3 Mock Service
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	اسپرینت جاری	TODO های High/Medium/Low Priority
BACKLOG.md	Backlog	کارهای آینده، Feature Requests
DISCOUNT-SHOP-COMPLETION-PLAN.md	تکمیل فروشگاه تخفیفی	گالری تصاویر، VAT، گزارش فروش
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	راهنمای شروع	Setup محیط توسعه، Build، Run
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

---

🔍 جستجوی سریع

موضوعات کلیدی:

موضوع	فایل‌های مرتبط
باشگاه مشتریان	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 دریافت کنید.