# کارهای باقی‌مانده - پروژه FourSat **⚠️ توجه: این فایل منسوخ شده است** **📄 فایل جدید (تجمیع کامل):** 👉 **[REMAINING-TASKS-CONSOLIDATED.md](REMAINING-TASKS-CONSOLIDATED.md)** 👈 فایل جدید شامل: - ✅ تجمیع کامل تسک‌های CMS - ✅ تجمیع کامل تسک‌های BackOffice.BFF - ✅ تجمیع کامل تسک‌های BackOffice UI - ✅ تجمیع کامل تسک‌های FrontOffice.BFF - ✅ تجمیع کامل تسک‌های FrontOffice UI - ✅ اولویت‌بندی دقیق - ✅ تخمین زمان واقعی - ✅ جزئیات کامل هر تسک **تاریخ به‌روزرسانی**: 1403/09/11 (2024-12-02) --- ## 📊 خلاصه سریع (برای مراجعه سریع) ### 🔴 اولویت فوری: 1. **Payment Gateway Integration** (70% → 100%) - 1 هفته 2. **CRUD های اضافی** (Tag, Product Bulk, Order) - 3 روز 3. **Manual Payment System** - 2 روز ### 🟡 اولویت متوسط: 4. **VAT System** - 2 روز 5. **Public Messages** - 1 روز ### 🟢 اولویت پایین: 6. **RBAC (Role-Based Access)** - 1.5 هفته 7. **Club Shop** - 2 هفته (موکول شده) ### 📋 BackOffice UI (منتظر CMS): - صفحه مدیریت تراکنش‌ها - 2 روز - نمایش VAT - 1 روز - Menu Filtering (RBAC) - 1 روز - Public Messages UI - 1 روز - Manual Payment UI - 1 روز - Withdrawal Reports - 2 روز ### 📱 FrontOffice (آخرین اولویت): - FrontOffice.BFF APIs - 2 هفته - FrontOffice UI Pages - 3 هفته **زمان کل**: 9 هفته (45 روز کاری) --- **برای جزئیات کامل، لطفاً به [REMAINING-TASKS-CONSOLIDATED.md](REMAINING-TASKS-CONSOLIDATED.md) مراجعه کنید.** --- ## 🎯 اولویت‌بندی توسعه ### مسیر پیشنهادی: ``` 1️⃣ CMS (Microservice/Backend) → تکمیل کامل تمام APIها و Business Logic → ✅ داکیومنت کامل هر تغییر 2️⃣ BackOffice.BFF (Gateway مدیریت) → تطبیق با تغییرات CMS → اضافه کردن Handlerهای جدید → ✅ داکیومنت یکپارچه‌سازی 3️⃣ BackOffice (Admin UI) → تطبیق با BFF → پیاده‌سازی صفحات جدید → ✅ داکیومنت UI Components 4️⃣ FrontOffice.BFF (Gateway مشتری) → پیاده‌سازی APIهای مشتری 5️⃣ FrontOffice (Customer UI) → رابط کاربری نهایی ``` ### ⚠️ قانون طلایی: داکیومنت همزمان - ✅ **بعد از هر تسک**: داکیومنت آپدیت شود - ✅ **قبل از commit**: مقایسه داکیومنت با کد - ✅ **هر feature**: داکیومنت Business Logic - ✅ **هر API**: داکیومنت Request/Response - ✅ **هر تغییر**: داکیومنت در `implementation-progress.md` --- ## 📊 خلاصه وضعیت ### ✅ تکمیل شده (7 فاز) - Domain Layer - Club Membership - Binary Network Tree - **Commission & Worker (MVP)** - Protobuf gRPC Services - History & Configuration - Database Migration & Seed Data ### 🟡 نیمه‌کامل (1 فاز) - Withdrawal & Settlement (40%) ### ❌ شروع نشده (4 فاز/ویژگی) - Club Shop & Product Integration - Testing (موکول شده) - **🆕 سیستم مالیات بر ارزش افزوده (VAT)** - **🆕 مدیریت نقش‌ها و دسترسی‌ها (RBAC)** --- ## 🆕 ویژگی‌های جدید اضافه شده ### 🧾 سیستم مالیات بر ارزش افزوده (VAT System) **اولویت**: 🟡 متوسط | **زمان**: 2 روز **توضیح**: یک فیلد ساده `VatPercentage` که در سفارشات ذخیره و در سمت مشتری (FrontOffice) نمایش داده می‌شود. **شامل**: - فیلد `VatPercentage` در Entity سفارش - مقدار پیش‌فرض در Configuration (مثلاً 10%) - نمایش در UI مشتری: "شامل 10% مالیات بر ارزش افزوده" --- ### 🔐 مدیریت نقش‌ها و دسترسی‌ها (RBAC) **اولویت**: 🟡 متوسط | **زمان**: 1.5 هفته **توضیح**: سیستم کنترل دسترسی مبتنی بر نقش (Role-Based Access Control) با 3 نقش اصلی: 1. **SuperAdmin** (سوپر ادمین): - دسترسی کامل به تمام بخش‌ها - مدیریت کاربران و نقش‌ها - تنظیمات سیستم 2. **Admin** (ادمین): - دسترسی به اکثر بخش‌ها - مدیریت محتوا و سفارشات - بدون دسترسی به تنظیمات حساس 3. **Inspector** (بازرس): - **فقط مشاهده** (Read-Only) - **بدون هیچ عملیات ویرایش/حذف/ایجاد** - دسترسی محدود به: * ✅ Dashboard * ✅ گزارش‌ها * ✅ مشاهده سفارشات * ✅ مشاهده درخت شبکه * ❌ تنظیمات * ❌ مدیریت کاربران * ❌ عملیات مالی **پیاده‌سازی**: - استخراج نقش از JWT Token در Frontend - محدودسازی منوها بر اساس نقش - غیرفعال کردن دکمه‌ها و فیلدها برای Inspector - Authorization در Backend APIs - صفحه مدیریت نقش‌ها (فقط SuperAdmin) --- ## 🏗️ تسک‌های هر سرویس (به ترتیب اولویت) ### 1️⃣ CMS (Microservice) - اولویت اول **مرجع کامل**: `totalDoc/CMS-API-COVERAGE.md` (مقایسه دقیق CMS vs BFF) #### 🔴 فاز 1: Transaction System - 3 روز **وضعیت**: 0% - **ضروری برای Launch** **توضیح**: سیستم تراکنش‌های مالی برای **دریافت نتیجه پرداخت از Gateway** و ادامه عملیات در CMS **⚠️ نکته مهم - جریان پرداخت**: ``` 1. User کلیک "خرید پکیج" در CMS 2. CMS: CreateTransaction (Status: Pending, RefId) 3. Redirect به Gateway/PYMS با RefId 4. Gateway: اتصال به بانک → پرداخت 5. Gateway: Callback به CMS با RefId + نتیجه 6. CMS: VerifyTransaction → تایید + فعال‌سازی ``` **خلاصه**: درگاه اینترنتی در Gateway/PYMS است. CMS فقط **نتیجه را دریافت** و **عملیات بعدی (فعال‌سازی، اضافه PV، Wallet) را انجام** می‌دهد. **تسک‌ها در CMS**: - [ ] Proto: `transactions.proto` موجود است ✅ - [ ] Entity: Transaction (با فیلدهای ReferenceId, Amount, Status, Gateway) - [ ] Commands: - [ ] CreateTransactionCommand - [ ] VerifyTransactionCommand (callback از درگاه) - [ ] RefundTransactionCommand - [ ] Queries: - [ ] GetTransactionQuery - [ ] GetAllTransactionsByFilterQuery - [ ] GetTransactionByReferenceQuery - [ ] GetUserTransactionsQuery - [ ] ✅ **داکیومنت**: `CMS/payment-gateway-integration.md` **تأثیر روی سایر سرویس‌ها**: - BackOffice.BFF: 7 Handler جدید - TransactionHandler (CRUD) - VerifyPaymentHandler - RefundHandler - GetUserTransactionsHandler - BackOffice: صفحات جدید - لیست تراکنش‌ها (با فیلتر) - جزئیات تراکنش - عملیات Refund **سطوح دسترسی**: - SuperAdmin: همه عملیات + Refund ✅ - Admin: مشاهده تراکنش‌ها (بدون Refund) ✅ - Inspector: فقط مشاهده ✅ --- #### 🟡 فاز 2: Shopping Cart System - 2 روز **وضعیت**: 0% **توضیح**: سیستم سبد خرید برای مدیریت سبدهای کاربران **تسک‌ها در CMS**: - [ ] Proto: `usercarts.proto` موجود است ✅ - [ ] Commands: - [ ] AddToCartCommand - [ ] UpdateCartItemCommand - [ ] RemoveFromCartCommand - [ ] ClearCartCommand - [ ] MergeCartCommand (مهمان → لاگین) - [ ] Queries: - [ ] GetUserCartQuery - [ ] GetAllCartsQuery (برای مدیریت) - [ ] ✅ **داکیومنت**: `CMS/shopping-cart-system.md` **تأثیر روی سایر سرویس‌ها**: - BackOffice.BFF: 6 Handler جدید - BackOffice: صفحه مدیریت سبدهای خرید (مشاهده سبدهای فعال) **سطوح دسترسی**: - SuperAdmin: مشاهده + پاک کردن سبدهای متروکه ✅ - Admin: مشاهده سبدها ✅ - Inspector: فقط مشاهده ✅ --- #### 🟡 فاز 3: Products & Orders تکمیل - 2 روز **وضعیت**: 70% (ناقص) **توضیح**: تکمیل APIهای محصولات و سفارشات **تسک‌ها در CMS**: **Products (Tags)**: - [ ] Proto: `tag.proto`, `producttag.proto` موجود است ✅ - [ ] Commands: - [ ] CreateTagCommand - [ ] UpdateTagCommand - [ ] DeleteTagCommand - [ ] AssignTagToProductCommand - [ ] Queries: - [ ] GetAllTagsQuery - [ ] GetProductsByTagQuery **Products (Bulk)**: - [ ] BulkUpdateProductsCommand (به‌روزرسانی دسته‌ای قیمت/موجودی) - [ ] GetLowStockProductsQuery (هشدار کم موجودی) - [ ] ToggleProductStatusCommand (فعال/غیرفعال) **Orders**: - [ ] CancelOrderCommand - [ ] UpdateOrderStatusCommand - [ ] GetOrdersByDateRangeQuery - [ ] ApplyDiscountToOrderCommand - [ ] CalculateOrderPVQuery **تأثیر روی سایر سرویس‌ها**: - BackOffice.BFF: 12 Handler جدید - BackOffice: صفحات - مدیریت Tags - به‌روزرسانی دسته‌ای محصولات - لغو سفارش - اعمال تخفیف **سطوح دسترسی**: - SuperAdmin: همه عملیات ✅ - Admin: همه عملیات محصولات/سفارشات ✅ - Inspector: فقط مشاهده ✅ --- #### 🟡 فاز 4: Public Messages System - 1 روز **وضعیت**: 0% **توضیح**: سیستم اعلانات عمومی برای اطلاع‌رسانی به کاربران **تسک‌ها در CMS**: - [ ] Proto: `public_messages.proto` موجود است ✅ - [ ] Commands: - [ ] CreatePublicMessageCommand - [ ] UpdatePublicMessageCommand - [ ] DeletePublicMessageCommand - [ ] PublishMessageCommand - [ ] ArchiveMessageCommand - [ ] Queries: - [ ] GetAllPublicMessagesQuery - [ ] GetPublicMessageQuery - [ ] GetActiveMessagesQuery - [ ] ✅ **داکیومنت**: `CMS/public-messages-system.md` **تأثیر روی سایر سرویس‌ها**: - BackOffice.BFF: 6 Handler جدید - BackOffice: صفحات - لیست اعلانات - ایجاد/ویرایش اعلان - انتشار اعلان **سطوح دسترسی**: - SuperAdmin: همه عملیات ✅ - Admin: Create, Update, Publish ✅ - Inspector: فقط مشاهده ✅ --- #### 🟡 فاز 5: سیستم مالیات (VAT) - 2 روز **وضعیت**: 0% (بدون تغییر - قبلاً مستند شده) --- #### 🟡 فاز 6: سیستم RBAC (1.5 هفته) **وضعیت**: 0% (بدون تغییر - قبلاً مستند شده) --- #### 🟢 فاز 7: فروشگاه باشگاه (2 هفته) **وضعیت**: 0% (بدون تغییر - قبلاً مستند شده) --- #### 🟢 فاز 8: Contracts (اختیاری) - 2 روز **وضعیت**: 0% **توضیح**: مدیریت قراردادهای عضویت/خرید خاص **تسک‌ها در CMS**: - [ ] Proto: `contract.proto`, `usercontract.proto` موجود است ✅ - [ ] Commands: Create, Update, Delete, Assign, Revoke - [ ] Queries: GetAll, Get, GetUserContracts - [ ] ✅ **داکیومنت**: `CMS/contracts-system.md` **اولویت**: فقط در صورت نیاز بیزینسی --- ### 2️⃣ BackOffice.BFF (Gateway) - اولویت دوم **منتظر تکمیل CMS**: - [ ] PaymentHandler (بعد از CMS فاز 1) - [ ] OrderVatHandler (بعد از CMS فاز 2) - [ ] AuthorizationHandler (بعد از CMS فاز 3) - [ ] ✅ **داکیومنت**: هر Handler در `cms-integration.md` --- ### 3️⃣ BackOffice (Admin UI) - اولویت سوم **منتظر تکمیل BFF**: - [ ] صفحه مدیریت تراکنش‌ها - [ ] نمایش VAT در لیست سفارشات - [ ] Menu filtering بر اساس Role - [ ] ✅ **داکیومنت**: هر صفحه در `development-plan.md` --- ### 4️⃣ FrontOffice.BFF (Gateway مشتری) - اولویت چهارم **تسک‌های اصلی**: - [ ] Authentication APIs - [ ] Order APIs - [ ] Profile APIs - [ ] ✅ **داکیومنت**: `FrontOffice.BFF/README.md` --- ### 5️⃣ FrontOffice (Customer UI) - اولویت پنجم **تسک‌های اصلی**: - [ ] صفحه ثبت‌نام/ورود - [ ] پروفایل کاربری - [ ] سبد خرید (با نمایش VAT) - [ ] ✅ **داکیومنت**: `FrontOffice/README.md` --- ## 🔴 اولویت بالا (High Priority) - CMS ### 1. تکمیل درگاه پرداخت (Phase 10) - 1 هفته **وضعیت**: 70% تکمیل ✅ #### ✅ انجام شده: - Commands: RequestWithdrawal, ProcessWithdrawal, ApproveWithdrawal, RejectWithdrawal - Database: UserCommissionPayout, CommissionPayoutHistory - ProcessedBy tracking (مدیر تأییدکننده) - ✅ **IPaymentGatewayService Interface** - یکپارچه‌سازی با درگاه‌های پرداخت - ✅ **MockPaymentGatewayService** - Mock برای تست محیط Development - ✅ **DayaPaymentService** (Skeleton) - آماده برای API واقعی دایا - ✅ **ProcessWithdrawalCommandHandler** - یکپارچه با Payment Gateway - روش Diamond: شارژ کیف پول تخفیف ✅ - روش BankTransfer: فراخوانی ProcessPayoutAsync ✅ - Error Handling: وضعیت PaymentFailed ✅ - Logging: ثبت موفقیت/خطا ✅ - ✅ **Entity Updates**: - BankReferenceId, BankTrackingCode, PaymentFailureReason در UserCommissionPayout - PaymentFailed در CommissionPayoutStatus Enum #### ❌ باقی‌مانده (30%): 1. **یکپارچه‌سازی با درگاه پرداخت واقعی** (2-3 روز) - پیاده‌سازی DayaPaymentService با API واقعی - تست تراکنش‌های واقعی - مدیریت callback و webhook 2. **رابط کاربری مدیریت (BackOffice)** (2 روز) - صفحه لیست درخواست‌های برداشت - دکمه‌های تأیید/رد - نمایش جزئیات تراکنش (BankReferenceId, TrackingCode) - نمایش وضعیت PaymentFailed و دلیل - فیلترینگ و جستجو 3. **گزارش‌های مالی** (2 روز) - گزارش روزانه/هفتگی/ماهانه - خروجی Excel/PDF - نمودارهای مالی - آمار تجمیعی **تخمین زمان باقی‌مانده**: 6-7 روز کاری --- ### 2. تنظیمات Production (30 دقیقه) **وضعیت**: نیاز به تنظیم دستی #### کارهای مورد نیاز: **الف. تنظیم Email (Gmail)** 1. ورود به Google Account Security 2. فعال‌سازی 2-Step Verification 3. ایجاد App Password 4. کپی پسورد 16 رقمی 5. آپدیت `appsettings.Production.json`: ```json "Email": { "SmtpUsername": "foursat@gmail.com", "SmtpPassword": "xxxx xxxx xxxx xxxx" } ``` **ب. تنظیم SMS (کاوه‌نگار)** 1. ثبت‌نام در [Kavenegar.com](https://kavenegar.com) 2. کپی API Key از پنل 3. دریافت شماره Sender 4. آپدیت `appsettings.Production.json`: ```json "Sms": { "KavenegarApiKey": "YOUR_API_KEY", "Sender": "10008663" } ``` **ج. تنظیم Connection String** ```json "ConnectionStrings": { "DefaultConnection": "Server=PRODUCTION_SERVER;Database=Foursat_CMS;..." } ``` **تخمین زمان**: 30 دقیقه --- ## 🟡 اولویت متوسط (Medium Priority) ### 3. فروشگاه باشگاه (Phase 9) - 2 هفته **وضعیت**: 0% (شروع نشده) #### ویژگی‌های مورد نیاز: 1. **کاتالوگ محصولات** (2 روز) - لیست پکیج‌های عضویت - قیمت‌گذاری (1 ماهه، 3 ماهه، 6 ماهه، سالانه) - تخفیف‌های خرید چندماهه - نمایش ویژگی‌ها 2. **سبد خرید** (2 روز) - افزودن به سبد - ویرایش تعداد - محاسبه تخفیف - پیش‌نمایش قیمت نهایی 3. **فرآیند خرید** (3 روز) - اتصال به درگاه پرداخت - تأیید پرداخت - فعال‌سازی خودکار عضویت - ارسال رسید به ایمیل/SMS 4. **یادآوری تمدید** (2 روز) - کرون‌جاب بررسی انقضا - ارسال SMS/Email 30 روز قبل - ارسال یادآوری 7 روز قبل - ارسال پیام انقضا 5. **پنل مدیریت** (3 روز) - مدیریت محصولات - تنظیم قیمت‌ها و تخفیف‌ها - گزارش فروش - آمار تمدیدها **تخمین زمان کل**: 2 هفته کاری --- ## 🟢 اولویت پایین (Low Priority) ### 4. تست‌نویسی (Phase 7) - موکول شده **وضعیت**: 0% (Postponed) #### انواع تست مورد نیاز: 1. **Unit Tests** (1 هفته) - تست logic محاسبات کمیسیون - تست Binary Tree placement - تست Commands/Queries - تست Validators - Coverage حداقل 70% 2. **Integration Tests** (3 روز) - تست gRPC endpoints - تست Database transactions - تست Background Worker - تست Notification Service 3. **Load Testing** (2 روز) - تست همزمانی Background Worker - تست تعداد کاربران زیاد در Binary Tree - تست حجم بالای درخواست‌های API - بررسی Memory Leaks **تخمین زمان کل**: 2 هفته کاری **توصیه**: بعد از launch اولیه انجام شود --- ## ⚙️ بهبودهای اختیاری (Optional Enhancements) ### 5. Redis Distributed Locks **زمان نیاز**: زمانی که سیستم روی چند سرور deploy شود **مزایا**: - جلوگیری از اجرای همزمان Background Worker روی چند سرور - قفل توزیع‌شده برای تراکنش‌های بحرانی **پیاده‌سازی**: ```bash dotnet add package StackExchange.Redis dotnet add package DistributedLock.Redis ``` --- ### 6. Sentry Error Tracking **زمان نیاز**: 1 ساعت **مراحل**: 1. ثبت‌نام در [Sentry.io](https://sentry.io) 2. دریافت DSN 3. آپدیت `appsettings.json`: ```json "Monitoring": { "SentryEnabled": true, "SentryDsn": "https://xxx@sentry.io/yyy" } ``` --- ### 7. Slack Notifications **زمان نیاز**: 30 دقیقه **مراحل**: 1. ایجاد Slack App 2. ایجاد Incoming Webhook 3. آپدیت `appsettings.json`: ```json "Monitoring": { "SlackEnabled": true, "SlackWebhookUrl": "https://hooks.slack.com/services/..." } ``` **کاربرد**: دریافت alert در صورت خطا در Background Worker --- ### 8. Firebase Cloud Messaging (Push Notifications) **زمان نیاز**: 2 روز **مراحل**: 1. ثبت پروژه در Firebase Console 2. دریافت Server Key 3. نصب `FirebaseAdmin` package 4. پیاده‌سازی PushNotificationService 5. افزودن FCM Token به User entity 6. ارسال notification همزمان با Email/SMS --- ### 9. سیستم مالیات بر ارزش افزوده (VAT System) - ساده **زمان نیاز**: 2 روز **وضعیت**: 0% (شروع نشده) **توضیح**: فقط یک فیلد `VatPercentage` که روی سفارش نمایش داده می‌شه. **بدون گزارش‌گیری پیچیده**. --- #### الف. Backend (CMS) - 1 روز **مدت**: 1 روز 1. **Migration: اضافه کردن فیلد VatPercentage** ```csharp // در UserOrder (سفارش/فاکتور) public decimal VatPercentage { get; set; } // مثلاً 10 (یعنی 10%) // در FactorDetail (جزئیات فاکتور) - اختیاری public decimal VatPercentage { get; set; } // اگه نیاز بود ``` 2. **Seed Data یا Configuration** ```csharp // یک مقدار پیش‌فرض در SystemConfiguration Key: "shop_vat_percentage" Value: "10" // 10% ``` 3. **CreateOrderCommand - محاسبه ساده** ```csharp // در زمان ثبت سفارش: var vatPercentage = await _configService.GetVatPercentage(); order.VatPercentage = vatPercentage; // محاسبه TotalPrice با مالیات (اختیاری): // order.TotalPrice = order.SubTotal * (1 + vatPercentage/100); ``` 4. **Protobuf: اضافه کردن فیلد** ```protobuf message OrderResponse { int64 id = 1; double total_price = 2; double vat_percentage = 3; // 👈 فیلد جدید // ... سایر فیلدها } ``` --- #### ب. BFF (اختیاری - اگه نیاز باشه) - 2 ساعت **مدت**: 2 ساعت اگه BFF درخواست جزئیات سفارش می‌ده، فقط فیلد `VatPercentage` رو هم بگیره و بده به Frontend: ```csharp // در OrderDto public decimal VatPercentage { get; set; } ``` **خیلی ساده**: فقط mapping فیلد از gRPC به DTO --- #### ج. Frontend (FrontOffice) - 4 ساعت **مدت**: 4 ساعت (نصف روز) **نمایش در صفحات:** 1. **صفحه سبد خرید (Cart)** ```razor شامل @order.VatPercentage% مالیات بر ارزش افزوده ``` 2. **صفحه جزئیات سفارش / فاکتور** ```razor قیمت کل: @order.TotalPrice تومان (شامل @order.VatPercentage% مالیات بر ارزش افزوده) ``` 3. **رسید خرید (Receipt)** ```razor
مالیات بر ارزش افزوده: @order.VatPercentage%
``` **همین!** خیلی ساده، فقط نمایش یه عدد درصد. --- **تخمین زمان کل**: 2 روز کاری (1 روز Backend + 4 ساعت Frontend) --- ### 10. سیستم مدیریت نقش‌ها و دسترسی‌ها (Role-Based Access Control) **زمان نیاز**: 1.5 هفته (CMS: 2 روز + BFF: 1 روز + Frontend: 3 روز + Testing: 1 روز) **وضعیت**: 0% (شروع نشده) #### الف. تعریف نقش‌ها (Roles) **مدت**: 1 روز **نقش‌های اصلی**: 1. **SuperAdmin** (سوپر ادمین) - دسترسی کامل به تمام بخش‌ها - مدیریت کاربران و نقش‌ها - تنظیمات سیستم 2. **Admin** (ادمین) - دسترسی به اکثر بخش‌ها - مدیریت محتوا و سفارشات - بدون دسترسی به تنظیمات حساس 3. **Inspector** (بازرس) - **فقط مشاهده** (Read-Only) - دسترسی به گزارش‌ها و Dashboard - **بدون هیچ عملیات ویرایش/حذف** - محدودیت دسترسی به صفحات: * ❌ Settings (تنظیمات) * ❌ User Management (مدیریت کاربران) * ❌ Financial Operations (عملیات مالی) * ✅ Reports (گزارش‌ها) * ✅ Dashboard (داشبورد) * ✅ Orders (فقط مشاهده) * ✅ Network Tree (فقط مشاهده) #### ب. پیاده‌سازی در Backend (CMS) **مدت**: 2 روز 1. **Entity: Role** (در صورت عدم وجود) ```csharp public class Role { public long Id { get; set; } public string Name { get; set; } // SuperAdmin, Admin, Inspector public string DisplayName { get; set; } // "سوپر ادمین", "ادمین", "بازرس" public string Description { get; set; } public List Permissions { get; set; } } public class Permission { public long Id { get; set; } public string Resource { get; set; } // Users, Orders, Reports, Settings public string Action { get; set; } // View, Create, Edit, Delete public long RoleId { get; set; } public Role Role { get; set; } } ``` 2. **JWT Token Claims** ```csharp // در GenerateJwtTokenService var claims = new List { new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()), new Claim(ClaimTypes.Name, user.Mobile), new Claim(ClaimTypes.Role, role.Name), // "SuperAdmin", "Admin", "Inspector" new Claim("Permissions", JsonSerializer.Serialize(permissions)) }; ``` 3. **Authorization Attributes** ```csharp // Backend API Authorization [Authorize(Roles = "SuperAdmin,Admin")] public async Task UpdateUser(UpdateUserRequest request) [Authorize(Roles = "SuperAdmin")] public async Task DeleteUser(DeleteUserRequest request) [Authorize(Roles = "SuperAdmin,Admin,Inspector")] public async Task GetUser(GetUserRequest request) ``` #### ج. لایه BFF (BackOffice.BFF) **مدت**: 1 روز 1. **AuthorizationHandler** ```csharp public class AuthorizationHandler : IAuthorizationHandler { private readonly CmsAuthClient _cmsAuthClient; public async Task CheckPermission(string userId, string resource, string action) { // gRPC call to CMS var request = new CheckPermissionRequest { UserId = userId, Resource = resource, Action = action }; var response = await _cmsAuthClient.CheckPermissionAsync(request); return response.HasPermission; } public async Task GetUserRole(string userId) { var request = new GetUserRoleRequest { UserId = userId }; var response = await _cmsAuthClient.GetUserRoleAsync(request); return new UserRoleDto { RoleName = response.RoleName, Permissions = response.Permissions.Select(p => new PermissionDto { Resource = p.Resource, Action = p.Action }).ToList() }; } } ``` 2. **RoleManagementHandler** ```csharp public class RoleManagementHandler : IRoleManagementHandler { private readonly CmsUserClient _cmsUserClient; public async Task> GetRoles() { var response = await _cmsUserClient.GetRolesAsync(new Empty()); return response.Roles.Select(r => new RoleDto { Id = r.Id, Name = r.Name, DisplayName = r.DisplayName, Permissions = r.Permissions.Select(p => new PermissionDto { Resource = p.Resource, Action = p.Action }).ToList() }).ToList(); } public async Task AssignRole(long userId, string roleName) { var request = new AssignRoleRequest { UserId = userId, RoleName = roleName }; var response = await _cmsUserClient.AssignRoleAsync(request); return response.Success; } } ``` 3. **API Endpoints** ```csharp // Controllers/AuthorizationController.cs [ApiController] [Route("api/authorization")] public class AuthorizationController : ControllerBase { private readonly IAuthorizationHandler _authHandler; [HttpGet("check-permission")] public async Task CheckPermission( [FromQuery] string resource, [FromQuery] string action) { var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value; var hasPermission = await _authHandler.CheckPermission(userId, resource, action); return Ok(new { hasPermission }); } [HttpGet("user-role")] public async Task GetUserRole() { var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value; var role = await _authHandler.GetUserRole(userId); return Ok(role); } } // Controllers/RoleManagementController.cs [ApiController] [Route("api/roles")] [Authorize(Roles = "SuperAdmin")] public class RoleManagementController : ControllerBase { private readonly IRoleManagementHandler _roleHandler; [HttpGet] public async Task GetRoles() { var roles = await _roleHandler.GetRoles(); return Ok(roles); } [HttpPost("assign")] public async Task AssignRole([FromBody] AssignRoleDto dto) { var success = await _roleHandler.AssignRole(dto.UserId, dto.RoleName); return Ok(new { success }); } } ``` 4. **Authorization Middleware** ```csharp public class PermissionMiddleware { private readonly RequestDelegate _next; public async Task InvokeAsync(HttpContext context, IAuthorizationHandler authHandler) { // Extract resource and action from endpoint metadata var endpoint = context.GetEndpoint(); var requiredPermission = endpoint?.Metadata .GetMetadata(); if (requiredPermission != null) { var userId = context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value; var hasPermission = await authHandler.CheckPermission( userId, requiredPermission.Resource, requiredPermission.Action ); if (!hasPermission) { context.Response.StatusCode = 403; return; } } await _next(context); } } ``` #### د. پیاده‌سازی در Frontend (BackOffice) **مدت**: 3 روز 1. **AuthService Enhancement** ```csharp public class AuthService { private ClaimsPrincipal _user; public string GetUserRole() { return _user?.FindFirst(ClaimTypes.Role)?.Value; } public bool HasPermission(string resource, string action) { var permissions = GetUserPermissions(); return permissions.Any(p => p.Resource == resource && p.Action == action); } public bool IsInRole(params string[] roles) { var userRole = GetUserRole(); return roles.Contains(userRole); } } ``` 2. **Component-Level Authorization** ```razor @* صفحه Users.razor *@ @if (AuthService.IsInRole("SuperAdmin", "Admin")) { ایجاد کاربر جدید } @* برای Inspector فقط جدول نمایش داده شود *@ @* ... *@ ``` 3. **Navigation Menu Filtering** ```csharp // در MainLayout.razor.cs private List GetFilteredMenuItems() { var role = AuthService.GetUserRole(); var allMenuItems = new List { new NavMenuItem { Title = "داشبورد", Icon = Icons.Dashboard, Url = "/" }, new NavMenuItem { Title = "سفارشات", Icon = Icons.ShoppingCart, Url = "/orders" }, new NavMenuItem { Title = "کاربران", Icon = Icons.People, Url = "/users", RequiredRoles = new[] { "SuperAdmin", "Admin" } }, new NavMenuItem { Title = "تنظیمات", Icon = Icons.Settings, Url = "/settings", RequiredRoles = new[] { "SuperAdmin" } }, }; return allMenuItems .Where(item => item.RequiredRoles == null || item.RequiredRoles.Contains(role)) .ToList(); } ``` 4. **UI Element Disabling for Inspector** ```razor @* در هر صفحه *@ @code { private bool IsReadOnly => AuthService.GetUserRole() == "Inspector"; } ذخیره ``` #### د. صفحه مدیریت نقش‌ها (Role Management) **مدت**: 1 روز **فقط برای SuperAdmin** 1. **لیست نقش‌ها** - جدول نقش‌ها (Name, DisplayName, Description) - دکمه‌های ویرایش/حذف 2. **ویرایش نقش** - CheckBox Tree برای انتخاب دسترسی‌ها: ``` ☐ کاربران ☑ مشاهده ☑ ایجاد ☐ ویرایش ☐ حذف ☐ سفارشات ☑ مشاهده ☐ ویرایش ☐ لغو ``` 3. **اختصاص نقش به کاربر** - در صفحه User Edit - Dropdown انتخاب نقش - فقط SuperAdmin می‌تواند تغییر دهد #### ه. تست سناریوها **مدت**: 1 روز 1. **تست Inspector** - ✅ می‌تواند وارد سیستم شود - ✅ Dashboard را می‌بیند - ✅ گزارش‌ها را می‌بیند - ✅ لیست سفارشات را می‌بیند - ❌ نمی‌تواند سفارش ایجاد/ویرایش/حذف کند - ❌ صفحه Settings را نمی‌بیند - ❌ نمی‌تواند کاربر ایجاد/حذف کند 2. **تست Admin** - ✅ می‌تواند اکثر عملیات را انجام دهد - ❌ نمی‌تواند Settings سیستم را تغییر دهد - ❌ نمی‌تواند نقش‌ها را مدیریت کند 3. **تست SuperAdmin** - ✅ دسترسی کامل به همه چیز **تخمین زمان کل**: 1.5 هفته کاری (CMS: 2 روز + BFF: 1 روز + UI: 3 روز + Testing: 1 روز) --- ## 📊 جدول اولویت‌بندی (به‌روز شده) | کار | اولویت | زمان | وضعیت | وابستگی | |-----|--------|------|-------|---------| | درگاه پرداخت | 🔴 بالا | 1 هفته | 40% | - | | تنظیمات Production | 🔴 بالا | 30 دقیقه | 0% | - | | **سیستم مالیات (VAT)** | 🟡 متوسط | 2 روز (CMS: 1 روز + UI: 4 ساعت) | 0% | - | | **مدیریت نقش‌ها (RBAC)** | 🟡 متوسط | 1.5 هفته (CMS: 2 روز + BFF: 1 روز + UI: 3 روز + Test: 1 روز) | 0% | - | | فروشگاه باشگاه | 🟡 متوسط | 2 هفته | 0% | درگاه پرداخت | | تست‌نویسی | 🟢 پایین | 2 هفته | 0% | - | | Redis Locks | ⚪ اختیاری | 1 روز | 0% | Multi-server | | Sentry | ⚪ اختیاری | 1 ساعت | 0% | - | | Slack | ⚪ اختیاری | 30 دقیقه | 0% | - | | FCM Push | ⚪ اختیاری | 2 روز | 0% | - | --- ## 🎯 برنامه پیشنهادی (Roadmap) ### هفته 1: تکمیل درگاه پرداخت - روز 1-3: API Integration (فقط Daya برای Payout) - روز 4-5: BackOffice UI (Approval interface) ### هفته 2: تنظیمات Production & Launch - روز 1: تنظیم Email/SMS - روز 2: تست کامل سیستم - روز 3-5: Soft Launch + Monitoring ### هفته 3-4: فروشگاه باشگاه (اگر نیاز باشد) - هفته 3: Product Catalog + Cart - هفته 4: Purchase Flow + Renewal Reminders ### هفته 5-6: سیستم مالیات و دسترسی‌ها - **هفته 5 (روز 1-2)**: VAT System (مالیات بر ارزش افزوده) ⚡ خیلی ساده - روز 1: CMS (فیلد VatPercentage + Seed Data) - روز 2 (صبح): Frontend (نمایش در Cart + Invoice) - **هفته 5-6 (بقیه)**: RBAC (Role-Based Access Control) - روز 2.5-3: CMS Layer (Roles + Permissions + JWT) - روز 4: BFF Layer (Authorization Handlers + Middleware) - روز 5-7: Frontend (Menu Filtering + UI Authorization + Role Management) - روز 8: Testing (3 role scenarios) ### هفته 7+: بهبودها و تست - تست‌نویسی - بهینه‌سازی Performance - اضافه کردن بهبودهای اختیاری --- ## ✅ Checklist قبل از Launch ### Backend - [x] Domain Layer - [x] Binary Tree - [x] Commission Calculation - [x] Background Worker (Hangfire) - [x] Email/SMS Notifications - [x] Health Checks - [x] Database Migrations - [ ] Payment Gateway Integration - [ ] Production Configuration (Email/SMS) ### Frontend - [ ] User Registration with Email - [ ] User Profile (Edit Email) - [ ] Club Shop (if needed) - [ ] Withdrawal Request UI - [ ] BackOffice Approval Interface - [ ] **VAT Display in Cart & Invoice** - [ ] **Role-Based UI Authorization (Inspector, Admin, SuperAdmin)** ### Business Logic - [ ] **VAT Calculation System** - [ ] **Role-Based Access Control (RBAC)** - [ ] Payment Gateway Integration - [ ] Club Shop Integration ### DevOps - [ ] Production Server Setup - [ ] SSL Certificate - [ ] Backup Strategy - [ ] Monitoring (Sentry/Slack - optional) - [ ] CI/CD Pipeline (optional) ### Documentation - [x] Implementation Progress - [x] Email/SMS Configuration Guide - [x] README with Quick Start - [ ] ⭐ **داکیومنت هر Feature جدید** - [ ] ⭐ **مقایسه داکیومنت با کد (هر هفته)** - [ ] API Documentation (Swagger/gRPC) - [ ] User Manual (فارسی) - [ ] Admin Manual --- ## 📝 چک‌لیست داکیومنت (بعد از هر تسک) ### ✅ الزامی قبل از Commit: #### 1. داکیومنت Business Logic - [ ] آیا Business Logic در `CMS/network-club-commission-system-v1.1.md` به‌روز شده؟ - [ ] آیا فرمول‌ها و محاسبات صحیح هستند؟ - [ ] آیا مثال‌های عملی اضافه شده؟ #### 2. داکیومنت پیشرفت - [ ] آیا `CMS/implementation-progress.md` آپدیت شده؟ - [ ] آیا درصد پیشرفت به‌روز شده؟ - [ ] آیا فاز جدید اضافه شده؟ #### 3. داکیومنت API - [ ] آیا Protobuf messages داکیومنت شده‌اند؟ - [ ] آیا Request/Response نمونه اضافه شده؟ - [ ] آیا Error Codes مستند شده‌اند؟ #### 4. مقایسه کد با داکیومنت - [ ] آیا کد با Business Logic تطبیق دارد؟ - [ ] آیا Entity های کد با Entity های داکیومنت یکسان است؟ - [ ] آیا نام‌گذاری‌ها مشابه هستند؟ #### 5. داکیومنت تأثیرات - [ ] آیا تأثیر روی BackOffice.BFF مستند شده؟ - [ ] آیا تأثیر روی BackOffice UI مستند شده؟ - [ ] آیا Migration Guide نوشته شده؟ --- ## 📊 گزارش مقایسه داکیومنت vs کد ### چک‌لیست بررسی هفتگی: ```bash # 1. بررسی Entity ها cd CMS/src grep -r "public class.*Entity" --include="*.cs" | wc -l # مقایسه با تعداد Entity های مستند شده # 2. بررسی Commands/Queries find . -name "*Command.cs" -o -name "*Query.cs" | wc -l # مقایسه با لیست Commands در داکیومنت # 3. بررسی API Endpoints grep -r "\[HttpGet\]\|\[HttpPost\]" --include="*.cs" | wc -l # مقایسه با API های مستند شده ``` ### نمونه گزارش: ```markdown ## گزارش هفتگی - 2025-12-01 ### ✅ تطبیق کامل: - Entity های UserOrder, UserOrderDetail - Commission Calculation Logic - Binary Tree Placement ### ⚠️ نیاز به به‌روزرسانی داکیومنت: - [ ] فیلد VatPercentage به Entity اضافه شده ولی داکیومنت نشده - [ ] CreateOrderCommand تغییر کرده ولی در داکیومنت قدیمی است ### ❌ اختلاف Business Logic: - هیچ موردی ``` - [x] README with Quick Start - [ ] API Documentation (Swagger/gRPC) - [ ] User Manual (فارسی) - [ ] Admin Manual --- ## 📞 نکات مهم ### 1. قبل از Production Deploy ```bash # بررسی Build dotnet build --configuration Release # اجرای Migrations dotnet ef database update # تست Health Check curl http://YOUR_SERVER/health # تست Hangfire Dashboard # باز کردن: http://YOUR_SERVER/hangfire # تست Manual Trigger curl -X POST http://YOUR_SERVER/api/admin/trigger-weekly-calculation ``` ### 2. Monitoring در Production ```bash # Log Files tail -f /var/log/cms/application.log # Database Connections SELECT * FROM sys.dm_exec_sessions WHERE database_id = DB_ID('Foursat_CMS') # Hangfire Jobs # Dashboard: /hangfire/recurring # Worker Execution Log SELECT TOP 10 * FROM WorkerExecutionLog ORDER BY StartTime DESC ``` ### 3. Backup Strategy - Database: روزانه Full Backup + Hourly Transaction Log - Configuration Files: Git repository - User Data: Weekly full export --- ## ⚠️ بیزینس‌های کلیدی - چک‌لیست الزامی > **هشدار**: این بیزینس‌ها **نباید هیچ‌وقت** گم بشند! قبل از هر Release باید تطبیق کامل با کد داشته باشند. ### 🎯 بیزینس 1: Binary Tree (درخت دودویی) **قوانین اصلی** (از دکتر): - ✅ هر User دقیقاً 2 زیرمجموعه مستقیم دارد (Left, Right) - ✅ Spillover: وقتی پر شد، زیرمجموعه بعدی به اولین جای خالی در سطح بعد می‌رود - ✅ محاسبه عمق (Depth): از ریشه تا آن Node - ✅ Parent تغییر نمی‌کند (فقط در ثبت‌نام تنظیم می‌شود) **چک‌لیست تطبیق**: ```bash # 1. بررسی کد cd CMS/src/CMSMicroservice.Domain/Entities grep -A 20 "class User" User.cs | grep -E "Parent|Left|Right" # 2. بررسی منطق Placement cd ../Application/UserCQ grep -A 50 "PlaceInBinaryTree" CreateUserCommand.cs # 3. تست # آیا با 7 کاربر، Tree به شکل زیر است؟ # 1 # / \ # 2 3 # /| |\ # 4 5 6 7 ``` **فایل داکیومنت مرتبط**: - `totalDoc/CMS/binary-tree-registration-guide.md` ✅ - `totalDoc/CMS/network-club-commission-system-v1.1.md` (بخش Binary Tree) --- ### 💰 بیزینس 2: محاسبه کمیسیون (از دکتر) **قوانین اصلی**: - ✅ محاسبه هر **یکشنبه ساعت 00:05 UTC** - ✅ فرمول: `Commission = TotalPV × Percentage` - ✅ شرط دریافت: `MinimumPV` باید رعایت شود - ✅ CarryOver: مانده به هفته بعد منتقل می‌شود - ✅ MaxCommission: سقف کمیسیون در هفته **چک‌لیست تطبیق**: ```bash # 1. بررسی Worker cd CMS/src/CMSMicroservice.Application/BackgroundWorkers grep -A 30 "CalculateCommission" CommissionCalculationWorker.cs # 2. بررسی فرمول grep "TotalPV.*Percentage" -r . # 3. بررسی Cron Job grep "Cron.*Sunday" -r . | grep "00:05" # 4. تست # با PV=1000 و Percentage=10%، آیا Commission=100 است؟ ``` **فایل داکیومنت مرتبط**: - `totalDoc/CMS/network-club-commission-system-v1.1.md` (بخش Commission) ✅ - `totalDoc/CMS/balance-calculation-carryover-logic.md` ✅ --- ### 🏆 بیزینس 3: سطوح باشگاه (Club Levels) **قوانین اصلی** (از دکتر): - ✅ 4 سطح: Bronze, Silver, Gold, Platinum - ✅ شرط ارتقا: تعداد PV یا تعداد زیرمجموعه فعال - ✅ سطح پایین نمی‌آید (یک طرفه) - ✅ مدت‌زمان عضویت (Duration): ماهانه یا سالانه **چک‌لیست تطبیق**: ```bash # 1. بررسی Entity cd CMS/src/CMSMicroservice.Domain/Entities grep -A 10 "ClubLevel" ClubMembership.cs # 2. بررسی منطق ارتقا cd ../Application/ClubMembershipCQ grep -A 50 "UpgradeLevel" *.cs # 3. تست # آیا Bronze → Silver با شرایط مشخص اتفاق می‌افتد؟ ``` **فایل داکیومنت مرتبط**: - `totalDoc/CMS/network-club-commission-system-v1.1.md` (بخش Club) --- ### 💳 بیزینس 4: برداشت (Withdrawal) - از شما **قوانین اصلی**: - ✅ حداقل موجودی برای برداشت: مثلاً 100,000 تومان - ✅ کارمزد برداشت: مثلاً 2% - ✅ وضعیت‌ها: Pending → Approved/Rejected - ✅ فقط مدیر می‌تواند Approve/Reject کند - ✅ پس از Approve: واریز به حساب **چک‌لیست تطبیق**: ```bash # 1. بررسی Commands cd CMS/src/CMSMicroservice.Application/WithdrawalCQ ls -1 *Command.cs # 2. بررسی حداقل موجودی grep "MinimumWithdrawal" -r . # 3. بررسی کارمزد grep "WithdrawalFee" -r . ``` **فایل داکیومنت مرتبط**: - `totalDoc/CMS/implementation-progress.md` (Phase 10) --- ### 📧 بیزینس 5: ارسال اطلاع‌رسانی **قوانین اصلی**: - ✅ Email: برای تأیید ثبت‌نام، کمیسیون، فعال‌سازی باشگاه - ✅ SMS: برای تأیید موبایل، اطلاعیه‌های مهم - ✅ زمان ارسال: بلافاصله بعد از event - ✅ Template: HTML برای Email، متن ساده برای SMS **چک‌لیست تطبیق**: ```bash # 1. بررسی NotificationService cd CMS/src/CMSMicroservice.Application/Common/Services ls -1 *Notification* # 2. بررسی Template ها find . -name "*.html" -o -name "*Template*" # 3. تست # آیا بعد از Commission calculation، Email ارسال می‌شود؟ ``` **فایل داکیومنت مرتبط**: - `totalDoc/CMS/email-sms-configuration-guide.md` ✅ --- ### 🛒 بیزینس 6: سفارش و فاکتور (Order & Factor) **قوانین اصلی**: - ✅ هر سفارش یک فاکتور (UserOrder) دارد - ✅ هر فاکتور شامل چند FactorDetail است - ✅ محاسبه PV از سفارش - ✅ وضعیت سفارش: Pending → Paid → Processing → Completed - ✅ مالیات (VAT): یک درصد ثابت روی کل سفارش **چک‌لیست تطبیق**: ```bash # 1. بررسی Entity cd CMS/src/CMSMicroservice.Domain/Entities grep -A 20 "class UserOrder" UserOrder.cs grep -A 20 "class FactorDetail" FactorDetail.cs # 2. بررسی محاسبه PV cd ../Application/OrderCQ grep "CalculatePV" -A 30 CreateOrderCommand.cs # 3. بررسی VAT grep "VatPercentage" -r . ``` **فایل داکیومنت مرتبط**: - `totalDoc/CMS/network-club-commission-system-v1.1.md` (بخش Orders) - `totalDoc/REMAINING-TASKS.md` (VAT System) --- ## 📋 چک‌لیست بررسی ماهانه بیزینس **هر ماه یکبار این چک‌لیست را اجرا کن**: ### ماه: _________ | تاریخ بررسی: _________ - [ ] **Binary Tree**: Placement و Spillover صحیح کار می‌کند؟ - [ ] **Commission**: فرمول محاسبه درست است؟ Cron Job اجرا می‌شود؟ - [ ] **CarryOver**: مانده به هفته بعد منتقل می‌شود؟ - [ ] **Club Levels**: ارتقا به سطح بالاتر صحیح است؟ - [ ] **Withdrawal**: فرآیند برداشت کامل کار می‌کند؟ - [ ] **Email/SMS**: تمام Notification ها ارسال می‌شوند؟ - [ ] **Order/Factor**: PV محاسبه می‌شود؟ VAT اضافه می‌شود؟ ### نتیجه بررسی: ``` ✅ همه بیزینس‌ها OK ⚠️ نیاز به بررسی بیشتر: _________________ ❌ مشکل یافت شد: _________________ ``` --- ## 📊 تخمین زمان کل (به‌روز شده) | دسته | زمان | شامل | |------|------|------| | اولویت بالا | 1 هفته + 30 دقیقه | درگاه پرداخت، تنظیمات Production | | اولویت متوسط | 3.5 هفته | فروشگاه (2 هفته) + VAT (2 روز) + RBAC (1.5 هفته) | | اولویت پایین | 2 هفته | تست‌نویسی (موکول شده) | | بهبودهای اختیاری | 1 هفته | Redis, Sentry, Slack, FCM | | **جمع کل (بدون تست)** | **4.5-5.5 هفته** | --- ## 🎉 وضعیت فعلی **MVP: 100% آماده** ✅ **Production Ready: 95%** ✅ **آماده Launch: بله** (با تکمیل درگاه پرداخت + تنظیمات) سیستم فعلی می‌تواند: - کاربران را در Binary Tree قرار دهد - کمیسیون هفتگی محاسبه کند - Email/SMS ارسال کند - درخواست‌های برداشت را مدیریت کند فقط نیاز است: - درگاه پرداخت متصل شود (برای واریز خودکار) - تنظیمات Email/SMS در Production انجام شود **توصیه**: می‌توان با MVP فعلی launch کرد و Phase 9 (فروشگاه) را بعداً اضافه کرد.