23 KiB
پیشرفت پیادهسازی سیستم شبکه-باشگاه مشتریان
آخرین بهروزرسانی: 2025-11-29 - روز ۷ فاز ۳
📊 وضعیت کلی
- فاز فعلی: فاز ۳ - ClubMembershipCQ (CQRS)
- پیشرفت کلی:
- ✅ فاز ۱: 100% تکمیل شد (Domain Layer)
- ✅ فاز ۲ - ConfigurationCQ: 100% تکمیل شد
- ✅ فاز ۳ - ClubMembershipCQ: 100% تکمیل شد
✅ کارهای انجام شده
روز ۱: آمادهسازی و Enums (✅ کامل)
1. ✅ آمادهسازی پروژه
- ایجاد Branch:
feature/network-club-system - ایجاد ساختار پوشهها در Domain:
Entities/Club/Entities/Network/Entities/Commission/Entities/Configuration/Entities/History/Enums/
Commit: Initial structure setup
2. ✅ پیادهسازی Enums (7 فایل)
CommissionPayoutStatus.cs- وضعیت پرداخت کمیسیون- Pending, Paid, WithdrawRequested, Withdrawn, Cancelled
WithdrawalMethod.cs- روش برداشت- Cash, Diamond
NetworkLeg.cs- موقعیت در شبکه- Left, Right
ClubMembershipAction.cs- عملیات عضویت (History)- Activated, Deactivated, Updated, ManualFix
NetworkMembershipAction.cs- عملیات شبکه (History)- Join, Move, Remove
CommissionPayoutAction.cs- عملیات کمیسیون (History)- Created, Paid, WithdrawRequested, Withdrawn, Cancelled, ManualFix
ConfigurationScope.cs- محدوده تنظیمات- System, Network, Club, Commission
- بهروزرسانی
TransactionType.cs:- NetworkCommission
- ClubActivation
- DiscountWalletCharge
Commit: 462ae5d - feat: Add enums for network-club system
روز ۲-۳: Core Entities (✅ کامل)
3. ✅ پیادهسازی Core Entities (7 فایل)
Configuration:
SystemConfiguration.cs- تنظیمات پویای سیستم- Scope, Key, Value, DataType, Description, IsActive
Club Management:
ClubMembership.cs- عضویت باشگاه- UserId, IsActive, ActivatedAt, InitialContribution, TotalEarned
ClubFeature.cs- فیچرهای باشگاه- Title, Description, IsActive, RequiredPoints, SortOrder
UserClubFeature.cs- جدول واسط کاربر-فیچر- UserId, ClubMembershipId, ClubFeatureId, GrantedAt, Notes
Network:
NetworkWeeklyBalance.cs- تعادلهای هفتگی- UserId, WeekNumber, LeftLegBalances, RightLegBalances, TotalBalances
- WeeklyPoolContribution, CalculatedAt, IsExpired
Commission:
WeeklyCommissionPool.cs- استخر کارمزد هفتگی- WeekNumber, TotalPoolAmount, TotalBalances, ValuePerBalance
- IsCalculated, CalculatedAt
UserCommissionPayout.cs- پرداخت کمیسیون- UserId, WeekNumber, WeeklyPoolId, BalancesEarned, ValuePerBalance
- TotalAmount, Status, PaidAt, WithdrawalMethod, IbanNumber, WithdrawnAt
4. ✅ پیادهسازی History Entities (4 فایل)
ClubMembershipHistory.cs- تاریخچه عضویت- ClubMembershipId, UserId, OldIsActive, NewIsActive
- OldInitialContribution, NewInitialContribution
- Action, Reason, PerformedBy
NetworkMembershipHistory.cs- تاریخچه شبکه- UserId, OldParentId, NewParentId, OldLegPosition, NewLegPosition
- Action, Reason, PerformedBy
CommissionPayoutHistory.cs- تاریخچه کمیسیون- UserCommissionPayoutId, UserId, WeekNumber
- AmountBefore, AmountAfter, OldStatus, NewStatus
- Action, PerformedBy, Reason
SystemConfigurationHistory.cs- تاریخچه تنظیمات- ConfigurationId, Scope, Key, OldValue, NewValue
- Reason, PerformedBy
5. ✅ بهروزرسانی Entity های موجود
-
User.cs:- ✅ افزودن
NetworkParentId(شناسه والد در شبکه) - ✅ افزودن
NetworkParentNavigation Property - ✅ افزودن
LegPosition(NetworkLeg enum) - ✅ افزودن Navigation Properties:
NetworkChildren- فرزندان در شبکهClubMembership- عضویت باشگاهUserClubFeatures- فیچرهای کاربرNetworkWeeklyBalances- تعادلهای هفتگیCommissionPayouts- پرداختهای کمیسیون
- ✅ افزودن
-
UserWallet.cs:- ✅ افزودن
NetworkBalance- کیف پول طلایی (کارمزد) - ✅ افزودن
DiscountBalance- کیف پول تخفیف (فقط برای باشگاه) - ✅ بهروزرسانی کامنتها
- ✅ افزودن
-
Products.cs:- ✅ افزودن
IsClubExclusive- محصولات اختصاصی باشگاه - ✅ افزودن
ClubDiscountPercent- درصد تخفیف (0-100)
- ✅ افزودن
-
GlobalUsings.cs:- ✅ افزودن namespace های جدید:
CMSMicroservice.Domain.Entities.ClubCMSMicroservice.Domain.Entities.NetworkCMSMicroservice.Domain.Entities.CommissionCMSMicroservice.Domain.Entities.ConfigurationCMSMicroservice.Domain.Entities.HistoryCMSMicroservice.Domain.Enums
- ✅ افزودن namespace های جدید:
Commit: d20dc86 - feat: Add core entities and history tables for network-club system
روز ۴-۵: EF Configurations و Migration (✅ کامل)
6. ✅ پیادهسازی EF Core Configurations (11 فایل)
Core Configurations:
SystemConfigurationConfiguration.cs- Composite Index:
(Scope, Key)- Unique - Index:
IsActive
- Composite Index:
ClubMembershipConfiguration.cs- رابطه یکبهیک با User
- Index Unique:
UserId - Index:
IsActive
ClubFeatureConfiguration.cs- Composite Index:
(IsActive, SortOrder)
- Composite Index:
UserClubFeatureConfiguration.cs- روابط: User, ClubMembership, ClubFeature
- Composite Index Unique:
(UserId, ClubFeatureId) - Index:
ClubMembershipId
NetworkWeeklyBalanceConfiguration.cs- رابطه با User
- Composite Index Unique:
(UserId, WeekNumber) - Index:
WeekNumber,IsExpired
WeeklyCommissionPoolConfiguration.cs- Index Unique:
WeekNumber - Index:
IsCalculated
- Index Unique:
UserCommissionPayoutConfiguration.cs- روابط: User, WeeklyCommissionPool
- Composite Index Unique:
(UserId, WeekNumber) - Index:
WeeklyPoolId,Status,WeekNumber
History Configurations:
ClubMembershipHistoryConfiguration.cs- رابطه با ClubMembership
- Composite Index:
(UserId, Created) - Index:
ClubMembershipId,Action
NetworkMembershipHistoryConfiguration.cs- Composite Index:
(UserId, Created) - Index:
Action
- Composite Index:
CommissionPayoutHistoryConfiguration.cs- رابطه با UserCommissionPayout
- Composite Index:
(UserId, Created) - Index:
UserCommissionPayoutId,WeekNumber,Action
SystemConfigurationHistoryConfiguration.cs- رابطه با SystemConfiguration
- Composite Index:
(ConfigurationId, Created) - Index:
(Scope, Key)
7. ✅ بهروزرسانی Configuration های موجود
-
UserConfiguration.cs:- ✅ افزودن
NetworkParentIdconfiguration - ✅ افزودن رابطه با
NetworkParentوNetworkChildren - ✅ Index:
NetworkParentId - ✅ Index:
LegPosition - ✅ OnDelete: Restrict (جلوگیری از Cascade Delete)
- ✅ افزودن
-
UserWalletConfiguration.cs:- ✅ افزودن
DiscountBalancefield
- ✅ افزودن
-
ProductsConfiguration.cs:- ✅ افزودن
IsClubExclusivefield - ✅ افزودن
ClubDiscountPercentfield - ✅ Index:
IsClubExclusive
- ✅ افزودن
8. ✅ بهروزرسانی Infrastructure
-
ApplicationDbContext.cs:- ✅ افزودن 11 DbSet جدید:
- SystemConfigurations, SystemConfigurationHistories
- ClubMemberships, ClubFeatures, UserClubFeatures, ClubMembershipHistories
- NetworkWeeklyBalances, NetworkMembershipHistories
- WeeklyCommissionPools, UserCommissionPayouts, CommissionPayoutHistories
- ✅ دستهبندی با کامنتهای واضح
- ✅ افزودن 11 DbSet جدید:
-
GlobalUsings.cs(Infrastructure):- ✅ افزودن Domain.Entities namespace ها
- ✅ افزودن Domain.Enums
9. ✅ Migration
- حذف Migration قبلی (
AddNetworkClubSystem) - ایجاد Migration جدید:
AddNetworkClubSystemV2 - بررسی Migration Script (4267+ خط تغییر)
- Migration شامل:
- 11 جدول جدید با تمام Index ها
- بهروزرسانی 3 جدول موجود (User, UserWallet, Products)
- Foreign Key ها با OnDelete Restrict
- Unique Constraints
Commit: 04bc593 - feat: Add EF configurations and migration for network-club system
📈 آماری
فایلهای ایجاد شده
- Enums: 7 فایل + 1 بهروزرسانی
- Core Entities: 7 فایل
- History Entities: 4 فایل
- Entity Updates: 3 فایل (User, UserWallet, Products)
- EF Configurations: 11 فایل جدید + 3 بهروزرسانی
- Infrastructure: 2 فایل بهروزرسانی (DbContext, GlobalUsings)
- Migration: 2 فایل (Migration + Designer)
- جمع کل: 40 فایل ایجاد/بهروزرسانی شده
خطوط کد اضافه شده
- Domain Layer: ~650 خط کد C#
- Infrastructure Layer: ~1,400 خط Configuration
- Migration: ~4,267 خط SQL/C#
- جمع کل: ~6,300+ خط کد
Commits انجام شده
462ae5d- Add enums for network-club system (8 files)d20dc86- Add core entities and history tables (15 files)04bc593- Add EF configurations and migration (19 files)
🎯 اهداف فاز ۱
✅ انجام شده (60%)
- ✅ Enums (100%)
- ✅ Core Entities (100%)
- ✅ History Entities (100%)
- ✅ Entity Updates (100%)
🔄 در حال انجام (0%)
- ⏳ EF Configurations (0%)
- ⏳ Migration (0%)
⏳ باقیمانده (40%)
- EF Configurations
- Index ها
- Migration
- Test Migration
📝 نکات مهم
تصمیمات معماری
- ✅ استفاده از
BaseAuditableEntityبرای تمام جداول جدید - ✅ جدا کردن History tables برای Audit Trail کامل
- ✅ استفاده از
ConfigurationScopeenum برای دستهبندی تنظیمات - ✅ Navigation Properties دوطرفه برای روابط
مشکلات حل شده
- ✅ Build Error: Missing using directives
- راهحل: بهروزرسانی
GlobalUsings.csبا namespace های جدید (Domain)
- راهحل: بهروزرسانی
- ✅ Build Error: Missing using directives in Infrastructure
- راهحل: بهروزرسانی
GlobalUsings.csدر Infrastructure با Domain namespaces
- راهحل: بهروزرسانی
- ✅ Migration Conflict: Migration با نام مشابه وجود داشت
- راهحل: حذف Migration قبلی و ایجاد با نام جدید (V2)
یادداشتها
- تمام Entity ها با XML Documentation کامنتگذاری شدهاند
- تمام فیلدهای nullable به درستی تعریف شدهاند
- Navigation Properties با
virtualبرای Lazy Loading - تمام Configuration ها با Index های بهینه
- Foreign Key ها با
OnDelete: Restrictبرای جلوگیری از Cascade Delete - Composite Index ها برای Query های پرکاربرد
روز ۶: فاز ۲ - ConfigurationCQ (✅ کامل)
1. ✅ ساختار پوشهها
- ایجاد
ConfigurationCQ/Commands/SetConfigurationValue/ - ایجاد
ConfigurationCQ/Commands/DeactivateConfiguration/ - ایجاد
ConfigurationCQ/Queries/GetConfigurationByKey/ - ایجاد
ConfigurationCQ/Queries/GetAllConfigurations/ - ایجاد
ConfigurationCQ/Queries/GetConfigurationHistory/
2. ✅ Commands (6 فایل)
SetConfigurationValueCommand:
SetConfigurationValueCommand.cs- Create/Update configuration- Properties: Scope, Key, Value, Description, ChangeReason
- Returns: ConfigurationId
SetConfigurationValueCommandValidator.cs- Scope: IsInEnum
- Key: NotEmpty, MaxLength(100), Regex pattern
- Value: NotEmpty, MaxLength(2000)
SetConfigurationValueCommandHandler.cs- Upsert logic (Insert or Update)
- History recording to SystemConfigurationHistory
- SaveChanges twice (entity + history)
DeactivateConfigurationCommand:
DeactivateConfigurationCommand.cs- Deactivate configuration- Properties: ConfigurationId, Reason
DeactivateConfigurationCommandValidator.cs- ConfigurationId: GreaterThan(0)
- Reason: MaxLength(500) when provided
DeactivateConfigurationCommandHandler.cs- Set IsActive = false
- History recording
- Idempotent (no error if already inactive)
3. ✅ Queries (13 فایل)
GetConfigurationByKeyQuery:
GetConfigurationByKeyQuery.cs- Parameters: Scope, Key
- Returns: ConfigurationDto (nullable)
GetConfigurationByKeyQueryValidator.csGetConfigurationByKeyQueryHandler.cs- AsNoTracking for read-only
- Returns null if not found
ConfigurationDto.cs- 8 properties با Timestamps
GetAllConfigurationsQuery:
GetAllConfigurationsQuery.cs- Filter: Scope, KeyContains, IsActive
- Pagination + Sorting
GetAllConfigurationsQueryValidator.csGetAllConfigurationsQueryHandler.cs- Dynamic filtering
- Pagination با MetaData
GetAllConfigurationsResponseDto.cs
GetConfigurationHistoryQuery:
GetConfigurationHistoryQuery.cs- Parameters: ConfigurationId
- Pagination + Sorting (default: -Created)
GetConfigurationHistoryQueryValidator.csGetConfigurationHistoryQueryHandler.cs- Check configuration exists (NotFoundException)
- Order by Created DESC
- Maps Reason → ChangeReason, PerformedBy → ChangedBy
GetConfigurationHistoryResponseDto.cs
4. ✅ Infrastructure Updates
-
بهروزرسانی
IApplicationDbContext.cs:- اضافه شدن 11 DbSet جدید:
- SystemConfigurations
- SystemConfigurationHistories
- ClubMemberships
- ClubMembershipHistories
- ClubFeatures
- UserClubFeatures
- NetworkWeeklyBalances
- NetworkMembershipHistories
- WeeklyCommissionPools
- UserCommissionPayouts
- CommissionPayoutHistories
- اضافه شدن 11 DbSet جدید:
-
بهروزرسانی
Application/GlobalUsings.cs:- CMSMicroservice.Domain.Entities.Club
- CMSMicroservice.Domain.Entities.Network
- CMSMicroservice.Domain.Entities.Commission
- CMSMicroservice.Domain.Entities.Configuration
- CMSMicroservice.Domain.Entities.History
- CMSMicroservice.Domain.Enums
5. ✅ Features پیادهسازی شده
- ✅ CQRS Pattern کامل
- ✅ FluentValidation برای تمام Commands و Queries
- ✅ History Tracking اتوماتیک
- ✅ Pagination و Sorting
- ✅ Filtering پویا
- ✅ Null-safe implementations
- ✅ DTO Pattern برای Data Transfer
- ✅ Idempotent Commands
- ✅ Proper exception handling
Commit: f6fa070 - feat: Add ConfigurationCQ - Phase 2 Application Layer
آمار:
- 20 فایل جدید/تغییریافته
- 612+ خط کد اضافه شده
- 2 Command + 3 Query + 4 DTO
- Build: ✅ موفق (0 error, 184 warnings در Legacy code)
روز ۷: فاز ۳ - ClubMembershipCQ (✅ کامل)
1. ✅ ساختار پوشهها
- ایجاد
ClubMembershipCQ/Commands/ActivateClubMembership/ - ایجاد
ClubMembershipCQ/Commands/DeactivateClubMembership/ - ایجاد
ClubMembershipCQ/Commands/AssignClubFeature/ - ایجاد
ClubMembershipCQ/Queries/GetClubMembership/ - ایجاد
ClubMembershipCQ/Queries/GetAllClubMemberships/ - ایجاد
ClubMembershipCQ/Queries/GetClubMembershipHistory/
2. ✅ Commands (9 فایل)
ActivateClubMembershipCommand:
ActivateClubMembershipCommand.cs- Activate/Create membership- Properties: UserId, ActivationDate (nullable), Reason
- Returns: ClubMembershipId
- Idempotent: creates new or reactivates existing
ActivateClubMembershipCommandValidator.cs- UserId: GreaterThan(0)
- Reason: MaxLength(500)
ActivateClubMembershipCommandHandler.cs- Check user exists (NotFoundException)
- Create new: ActivatedAt = now, InitialContribution = 0
- Reactivate: Update ActivatedAt only
- History: OldIsActive, NewIsActive, Action.Activated
DeactivateClubMembershipCommand:
DeactivateClubMembershipCommand.cs- Deactivate membership- Properties: UserId, Reason
DeactivateClubMembershipCommandValidator.cs- UserId: GreaterThan(0)
- Reason: MaxLength(500)
DeactivateClubMembershipCommandHandler.cs- Set IsActive = false (no DeactivationDate field in entity)
- Idempotent: return if already inactive
- History: OldIsActive=true, NewIsActive=false
AssignClubFeatureCommand:
AssignClubFeatureCommand.cs- Assign feature to user- Properties: UserId, FeatureId, GrantedAt (nullable), Notes
- Returns: UserClubFeatureId
AssignClubFeatureCommandValidator.cs- UserId: GreaterThan(0)
- FeatureId: GreaterThan(0)
- Notes: MaxLength(500)
AssignClubFeatureCommandHandler.cs- Validate active membership exists
- Validate ClubFeature exists and active
- Upsert logic: Update Notes if exists, create new otherwise
- Uses: ClubMembershipId, ClubFeatureId, GrantedAt (DateTime)
3. ✅ Queries (12 فایل)
GetClubMembershipQuery:
GetClubMembershipQuery.cs- Parameter: UserId
- Returns: ClubMembershipDto (nullable)
GetClubMembershipQueryValidator.cs- UserId: GreaterThan(0)
GetClubMembershipQueryHandler.cs- AsNoTracking read-only
- Returns null if not found
ClubMembershipDto.cs- Properties: Id, UserId, IsActive, ActivatedAt (DateTime?), InitialContribution, TotalEarned, Created, LastModified
GetAllClubMembershipsQuery:
GetAllClubMembershipsQuery.cs- Filter: UserId, IsActive, ActivationDateFrom, ActivationDateTo
- Pagination + Sorting
GetAllClubMembershipsQueryValidator.cs- Date validation: From <= To
GetAllClubMembershipsQueryHandler.cs- Dynamic filtering on ActivatedAt field
- Pagination with MetaData
GetAllClubMembershipsResponseDto.cs- ResponseModel: Id, UserId, IsActive, ActivatedAt, InitialContribution, TotalEarned, Created, LastModified
GetClubMembershipHistoryQuery:
GetClubMembershipHistoryQuery.cs- Parameters: MembershipId (nullable), UserId (nullable)
- At least one required
- Pagination + Sorting (default: -Created)
GetClubMembershipHistoryQueryValidator.cs- Custom validation: at least one ID required
GetClubMembershipHistoryQueryHandler.cs- Filter by ClubMembershipId OR UserId
- Order by Created DESC
- Maps complete history entity
GetClubMembershipHistoryResponseDto.cs- ResponseModel: ClubMembershipId, UserId, OldIsActive, NewIsActive, OldInitialContribution, NewInitialContribution, Action (enum), Reason, PerformedBy, Created
4. ✅ Property Alignment
Fixed all property name mismatches between Domain entities and Application handlers:
- ClubMembership:
- ❌ Handlers: ActivationDate, DeactivationDate, LastActivationDate
- ✅ Entity: ActivatedAt (DateTime?)
- UserClubFeature:
- ❌ Handlers: MembershipId, FeatureId, StartDate, EndDate
- ✅ Entity: ClubMembershipId, ClubFeatureId, GrantedAt, Notes
- ClubMembershipHistory:
- ❌ Handlers: MembershipId, Details
- ✅ Entity: ClubMembershipId, Reason (+ required: OldIsActive, NewIsActive)
5. ✅ Features پیادهسازی شده
- ✅ CQRS Pattern کامل
- ✅ FluentValidation برای تمام Commands و Queries
- ✅ Complete History Tracking با تمام فیلدهای Audit
- ✅ Pagination و Sorting
- ✅ Filtering پویا با Date Ranges
- ✅ Null-safe implementations
- ✅ Idempotent Commands (Activate, Deactivate)
- ✅ Upsert pattern (AssignClubFeature)
- ✅ Proper exception handling (NotFoundException)
- ✅ Entity validation (active membership, active feature)
Commit: fe66d47 - feat: Add ClubMembershipCQ - Phase 3 Application Layer
آمار:
- 21 فایل جدید
- 732 خط کد اضافه شده
- 3 Command + 3 Query + 4 DTO
- Build: ✅ موفق (0 error, 193 warnings در Legacy code)
🚀 مراحل بعدی
فاز ۴: NetworkMembershipCQ (روز ۸-۹) - بعدی:
Priority: HIGH (نیاز به پیادهسازی شبکه دوتایی و محاسبات)
- ایجاد پوشه
NetworkMembershipCQدر Application - پیادهسازی Commands:
JoinNetworkCommand+ Handler + Validator- افزودن کاربر به شبکه (تعیین Parent و Leg)
- Validation: Parent باید عضو باشد
- Validation: Leg باید خالی باشد
MoveInNetworkCommand+ Handler + Validator- جابجایی در شبکه
RemoveFromNetworkCommand+ Handler + Validator- حذف از شبکه (Soft delete)
- پیادهسازی Queries:
GetNetworkTreeQuery+ Handler (Binary Tree visualization)GetUserNetworkPositionQuery+ HandlerGetNetworkChildrenQuery+ HandlerGetNetworkMembershipHistoryQuery+ Handler
- ایجاد DTOs
- تست Unit
- Commit
فاز ۵: CommissionCQ (روز ۱۰-۱۲)
Priority: MEDIUM (نیاز به محاسبات پیچیده)
📞 مسائل و سوالات
سوالات باز
- هیچ
Blockers
- هیچ
وضعیت فعلی: ✅ فاز ۳ - ClubMembershipCQ کامل شد - آماده شروع NetworkMembershipCQ
Build Status: ✅ موفق
آخرین Commit: fe66d47
Migration Status: ✅ آماده اجرا
تعداد Warning: 193 (مربوط به کدهای قبلی - برای کدهای جدید: 0)
🎉 فاز ۱ با موفقیت تکمیل شد!
دستاوردها:
✅ 7 Enum جدید + 1 بهروزرسانی
✅ 11 Entity جدید (7 Core + 4 History)
✅ 3 Entity موجود بهروزرسانی شد
✅ 14 Configuration کامل (11 جدید + 3 بهروزرسانی)
✅ Migration کامل با 11 جدول جدید
✅ بیش از 6,300 خط کد اضافه شده
✅ 4 Commit با پیامهای واضح
🎉 فاز ۲ - ConfigurationCQ با موفقیت تکمیل شد!
دستاوردها:
✅ 2 Command (Create/Update, Deactivate)
✅ 3 Query (ByKey, GetAll, History)
✅ 6 Validator
✅ 6 Handler
✅ 4 DTO
✅ History Tracking اتوماتیک
✅ 612+ خط کد اضافه شده
✅ 1 Commit با پیام واضح
✅ Build موفق بدون Error
🎉 فاز ۳ - ClubMembershipCQ با موفقیت تکمیل شد!
دستاوردها:
✅ 3 Command (Activate, Deactivate, AssignFeature)
✅ 3 Query (Get, GetAll, History)
✅ 6 Validator
✅ 6 Handler
✅ 4 DTO
✅ Complete History Tracking
✅ Property alignment با Domain entities
✅ Idempotent design patterns
✅ 732 خط کد اضافه شده
✅ 1 Commit با پیام واضح
✅ Build موفق بدون Error
آماده برای:
🚀 فاز ۴: NetworkMembershipCQ (Binary Network Management)