docs/CHANGELOG-CLUB-FEATURES.md

CHANGELOG - Club Membership Auto-Features

Date: 2025-12-09
Version: 1.1.0
Component: CMS Microservice - Club Membership Module

---

🎯 Summary

افزودن قابلیت اختصاص خودکار ویژگی‌های باشگاه مشتریان (UserClubFeatures) به اعضای جدید هنگام فعالسازی.

---

✨ New Features

1. Auto-Grant Club Features on Activation

Location: CMSMicroservice.Application/ClubMembershipCQ/Commands/ActivateClubMembership/ActivateClubMembershipCommandHandler.cs

Changes:

// Step 8: اضافه کردن ویژگی‌های باشگاه (فقط برای اعضای جدید)
if (isNewMembership)
{
    var clubFeatures = await _context.ClubFeatures
        .Where(f => !f.IsDeleted && new long[] { 1, 2, 3, 4 }.Contains(f.Id))
        .ToListAsync(cancellationToken);

    if (clubFeatures.Any())
    {
        var userClubFeatures = clubFeatures.Select(feature => new UserClubFeature
        {
            UserId = user.Id,
            ClubMembershipId = entity.Id,
            ClubFeatureId = feature.Id,
            GrantedAt = activationDate,
            Notes = "اعطا شده به‌طور خودکار هنگام فعالسازی"
        }).ToList();

        _context.UserClubFeatures.AddRange(userClubFeatures);
        await _context.SaveChangesAsync(cancellationToken);
        
        _logger.LogInformation(
            "Granted {Count} club features to UserId {UserId}",
            clubFeatures.Count,
            user.Id
        );
    }
}

Behavior:

• ✅ فقط برای isNewMembership = true اجرا می‌شود (نه برای reactivation)
• ✅ 4 ویژگی پایه (ClubFeatureId IN (1,2,3,4)) به‌طور خودکار ثبت می‌شوند
• ✅ GrantedAt = تاریخ فعالسازی
• ✅ Logging کامل

---

📄 Migration Scripts

1. MigrateUsersToClubMembership.sql (Full Version)

Location: /dbbkup/MigrateUsersToClubMembership.sql
Size: 370 lines

Features:

• Query UserWalletChangeLogs برای محاسبه مجموع شارژ‌ها
• Fallback به Transactions اگر logs خالی بود
• Transaction-safe (هر کاربر = یک transaction مستقل)
• اختصاص خودکار 4 ویژگی باشگاه

SQL Logic:

-- برای هر کاربر:
BEGIN TRANSACTION;

1. INSERT INTO ClubMemberships 
   (UserId, ActivatedAt=FirstChargeDate, InitialContribution=25M)

2. INSERT INTO ClubMembershipHistories 
   (Action=0, Reason='فعال‌سازی خودکار - مهاجرت')

3. INSERT INTO UserClubFeatures (4 rows)
   SELECT @UserId, @MembershipId, cf.Id, @DateTime, 
          CAST(N'اعطا شده خودکار' AS NVARCHAR(500))
   FROM ClubFeatures cf
   WHERE cf.Id IN (1,2,3,4)

COMMIT TRANSACTION;

2. MigrateUsersToClubMembership_Simple.sql

Location: /dbbkup/MigrateUsersToClubMembership_Simple.sql
Size: 130 lines

Difference: بررسی موجودی فعلی (UserWallets.Balance) به‌جای تاریخچه شارژ

---

🔧 Technical Details

Schema Fixes

Issues Fixed:

1. ❌ User.ClubMembershipId → این ستون وجود نداره!
   • رابطه: ClubMemberships.UserId → Users.Id (یک‌طرفه)
2. ❌ Action = 'Activated' → باید INT باشه
   • Action = 0 (Activated enum value)
3. ❌ N'فارسی' در SELECT → encoding خراب می‌شه
   • CAST(N'فارسی' AS NVARCHAR(500))

Transaction Strategy

Before (Wrong):

SET XACT_ABORT ON;
BEGIN TRANSACTION;
  -- 100 INSERT...
COMMIT TRANSACTION;

❌ با cursor سازگار نیست → log file overflow

After (Correct):

WHILE @@FETCH_STATUS = 0
BEGIN
    BEGIN TRANSACTION;
      -- INSERT ClubMembership
      -- INSERT History
      -- INSERT UserClubFeatures (x4)
    COMMIT TRANSACTION;
END

✅ هر کاربر مستقل → partial success ممکنه

---

📊 Data Impact

Affected Tables:

1. ClubMemberships - رکوردهای جدید برای کاربران مهاجرت شده
2. ClubMembershipHistories - یک رکورد Action=0 برای هر کاربر
3. UserClubFeatures - 4 رکورد (ویژگی‌های 1,2,3,4) برای هر کاربر

Example: اگر 100 کاربر مهاجرت کنند:

• 100 row در ClubMemberships
• 100 row در ClubMembershipHistories
• 400 row در UserClubFeatures (100 × 4)

---

🧪 Testing

Validation Queries

1. تعداد ویژگی‌های ثبت شده:

SELECT 
    cm.UserId,
    COUNT(ucf.Id) AS FeaturesCount
FROM ClubMemberships cm
LEFT JOIN UserClubFeatures ucf ON ucf.ClubMembershipId = cm.Id
WHERE cm.Created >= '2025-12-09'
GROUP BY cm.UserId
HAVING COUNT(ucf.Id) != 4;  -- باید خالی باشه!

2. چک کردن History:

SELECT COUNT(*)
FROM ClubMembershipHistories
WHERE Action = 0
  AND CreatedBy = 'MigrationScript'
  AND Created >= '2025-12-09';

3. لیست اعضای جدید:

SELECT 
    u.Id,
    u.FirstName + ' ' + u.LastName AS FullName,
    cm.ActivatedAt,
    cm.InitialContribution,
    COUNT(ucf.Id) AS FeaturesGranted
FROM Users u
INNER JOIN ClubMemberships cm ON cm.UserId = u.Id
LEFT JOIN UserClubFeatures ucf ON ucf.ClubMembershipId = cm.Id
WHERE cm.Created >= '2025-12-09'
GROUP BY u.Id, u.FirstName, u.LastName, cm.ActivatedAt, cm.InitialContribution;

---

📝 Configuration

Constants:

@InitialContribution = 25,000,000  -- سهم استخر
@ChargeAmount = 56,000,000          -- حداقل شارژ
@ClubFeatureIds = (1, 2, 3, 4)     -- ویژگی‌های پایه

Adjustable: می‌توان این مقادیر را در اسکریپت تغییر داد

---

🚀 Deployment Steps

1. ✅ Review Script: بررسی MigrateUsersToClubMembership.sql
2. ✅ Backup Database: پشتیبان‌گیری قبل از اجرا
3. ✅ Test on Staging: اجرای آزمایشی روی staging
4. ✅ Run Migration: اجرای production
5. ✅ Validate Results: اجرای validation queries
6. ✅ Monitor Logs: بررسی لاگ‌های SQL Server

---

🐛 Known Issues

None - تمام مشکلات شناسایی شده در مراحل توسعه رفع شدند.

---

📖 Documentation Updates

Files Modified/Created:

1. implementation-status.md - افزودن بخش Recent Updates (2025-12-09)
2. club-membership-migration.md - مستند جامع migration scripts (NEW)
3. 00-INDEX.md - اضافه کردن لینک به migration docs
4. CHANGELOG-CLUB-FEATURES.md - این فایل (NEW)

---

👥 Contributors

• Developer: GitHub Copilot
• Review: N/A
• Date: 2025-12-09

---

🔗 Related Issues

• Feature Request: "اختصاص خودکار ویژگی‌های باشگاه"
• Task: "مهاجرت کاربران موجود به سیستم باشگاه"

---

Version History:

• 1.1.0 (2025-12-09): Auto-grant club features + Migration scripts
• 1.0.0 (2024-12-04): Initial club membership implementation