docs/archive/collected-docs/DataMigration/INDEX.md

📚 FourSat Data Migration Tool - Index

نگاه اجمالی

این پروژه یک ابزار یکبار مصرف برای مهاجرت داده‌های دیتابیس از ساختار قدیمی به جدید است.

تعداد کل جداول: 33
زمان تخمینی: 5-10 دقیقه
وضعیت: ✅ آماده برای Production

---

📁 ساختار پروژه

DataMigration/
│
├── 📖 مستندات (5 فایل)
│   ├── SUMMARY.md                    ⭐ شروع از اینجا
│   ├── QUICK-START.md               🚀 راهنمای سریع (3 قدم)
│   ├── README.md                     📖 راهنمای کامل
│   ├── TABLE-MAPPINGS.md             📋 لیست 33 جدول
│   └── POST-MIGRATION-TRANSFORMATION.md  🔄 Binary tree transformation
│
└── 💻 کد (FourSat.DataMigration/)
    ├── Program.cs                    # Entry point
    ├── appsettings.json              # 33 table mappings ✅
    ├── Models/
    │   └── MigrationModels.cs        # Settings, Mapping, QueueItem
    ├── Services/
    │   └── MigrationService.cs       # Migration + Post-Migration logic
    └── Scripts/
        └── PostMigration_DataTransformation.sql  # Binary tree conversion

---

🎯 راهنمای سریع

برای کاربران عجول (3 دقیقه):

👉 QUICK-START.md - 3 قدم ساده

برای خواندن کامل (10 دقیقه):

👉 SUMMARY.md - خلاصه کامل پروژه

برای جزئیات کامل (30 دقیقه):

👉 README.md - راهنمای جامع

---

📋 مستندات

1. SUMMARY.md ⭐ شروع از اینجا

307 خط - خلاصه کامل پروژه

• ✅ وضعیت فعلی
• ✅ آنچه انجام شد
• ✅ ساختار پروژه
• ✅ فیچرهای پیاده‌سازی شده
• ✅ نحوه استفاده (3 قدم)
• ✅ خروجی مورد انتظار
• ✅ چک‌لیست آمادگی
• ✅ آمار نهایی

زمان مطالعه: 5-10 دقیقه
مخاطب: همه

---

2. QUICK-START.md 🚀

147 خط - راهنمای سریع 3 قدمی

• قدم 1: ویرایش appsettings.json
• قدم 2: اجرای Migration
• قدم 3: بررسی Logs
• عیب‌یابی سریع
• تنظیمات پیشرفته

زمان مطالعه: 3 دقیقه
مخاطب: کسانی که می‌خواهند سریع شروع کنند

---

3. README.md 📖

425 خط - راهنمای کامل و جامع

• نگاه کلی
• ساختار پروژه
• تنظیمات (appsettings.json)
• نحوه اجرا
• جریان کار (Workflow)
• Retry Logic
• Error Handling
• مثال خروجی
• عیب‌یابی
• FAQ

زمان مطالعه: 15-20 دقیقه
مخاطب: Developers، DevOps

---

4. TABLE-MAPPINGS.md 📋

230 خط - لیست کامل 33 جدول

• جداول با تغییر نام (10 جدول)
• جداول بدون تغییر نام (23 جدول)
• ترتیب پیشنهادی Migration
• تغییرات ساختاری (Binary Tree)
• Configuration کامل
• چک‌لیست قبل از Migration
• آمار تخمینی

زمان مطالعه: 10 دقیقه
مخاطب: Database Admins، Developers

---

5. POST-MIGRATION-TRANSFORMATION.md 🔄

248 خط - توضیح تبدیل Binary Tree

• تغییرات اعمال شده
• جریان کار (بروزرسانی شده)
• تنظیمات جدید
• خروجی Migration (قبل/بعد)
• Validation Checks
• خطاها و عیب‌یابی
• غیرفعال کردن Transformation
• آمار نهایی
• تغییرات کد

زمان مطالعه: 10 دقیقه
مخاطب: Developers که می‌خواهند Binary Tree را درک کنند

---

💻 فایل‌های کد

1. FourSat.DataMigration/Program.cs

48 خط - Entry point با Serilog hosting

// Setup Serilog
// Configure DI
// Run MigrationService

---

2. FourSat.DataMigration/appsettings.json

75 خط - تنظیمات کامل

{
  "ConnectionStrings": { /* Source + Target */ },
  "MigrationSettings": { /* BatchSize, Retry, etc. */ },
  "TableMappings": { /* 33 table mappings */ },
  "Serilog": { /* Console + File */ }
}

---

3. FourSat.DataMigration/Models/MigrationModels.cs

39 خط - Data models

public class MigrationSettings { ... }
public class TableMapping { ... }
public class QueueItem { ... }

---

4. FourSat.DataMigration/Services/MigrationService.cs

288 خط - Migration engine اصلی

// GetSourceTablesAsync: کشف جداول
// ApplyTableMappings: نگاشت نام‌ها
// PopulateRecordCountsAsync: شمارش رکوردها
// MigrateTableAsync: Batch processing
// RunPostMigrationTransformationAsync: Binary tree conversion

فیچرها:

• ✅ Queue-based processing
• ✅ Concurrent tables (3 همزمان)
• ✅ Retry with Polly (5 attempts)
• ✅ Batch processing (1000 records)
• ✅ IDENTITY_INSERT handling
• ✅ Progress tracking
• ✅ Post-migration transformation

---

5. FourSat.DataMigration/Scripts/PostMigration_DataTransformation.sql

175 خط - Binary tree transformation

-- Step 1: Validate (max 2 children)
-- Step 2: Copy ParentId → NetworkParentId
-- Step 3: Assign LegPosition (Left/Right)
-- Step 4: Fix orphaned nodes
-- Step 5: Validate binary tree integrity
-- Step 6: Output statistics

Transaction-safe: ROLLBACK در صورت validation failure

---

📊 آمار پروژه

مورد	تعداد/مقدار
کل فایل‌های مستندات	5 (md)
کل فایل‌های کد	5 (cs, json, sql, csproj)
خطوط مستندات	~1,600
خطوط کد	~625
تعداد جداول	33
جداول با Rename	10
NuGet Packages	8
Build Status	✅ موفق
خطا	0
هشدار	0

---

🔄 جریان کار Migration

1. ویرایش appsettings.json
   ↓
2. dotnet run
   ↓
3. کشف 33 جدول از Source
   ↓
4. Apply mappings (10 rename + 23 keep)
   ↓
5. Migrate با Batch + Retry
   ├─ 3 table همزمان
   ├─ 1000 record per batch
   └─ 5 retry attempts
   ↓
6. Post-Migration Transformation
   ├─ ParentId → NetworkParentId
   ├─ LegPosition assignment
   └─ Binary tree validation
   ↓
7. گزارش نهایی + Statistics

---

✅ چک‌لیست استفاده

قبل از شروع

• مطالعه SUMMARY.md
• مطالعه QUICK-START.md
• Backup از Target database

تنظیمات

• ویرایش SourceDatabase connection string
• ویرایش TargetDatabase connection string
• بررسی TableMappings (33 جدول)
• تست اتصال به هر دو database

اجرا

• dotnet build (بدون خطا)
• dotnet run
• مشاهده progress در console
• بررسی Logs در Logs/migration-*.txt

بعد از Migration

• بررسی تعداد رکوردها (Source = Target)
• بررسی Binary tree integrity
• تست Application با database جدید
• Archive کردن Source database قدیمی

---

🆘 پشتیبانی

خطاهای رایج

• Login failed: README.md - Error Handling
• Table not found: TABLE-MAPPINGS.md
• Binary tree violation: POST-MIGRATION-TRANSFORMATION.md
• Timeout: QUICK-START.md - عیب‌یابی

منابع

• 📖 راهنمای کامل: README.md
• 🚀 شروع سریع: QUICK-START.md
• 📋 لیست جداول: TABLE-MAPPINGS.md

---

🎉 وضعیت نهایی

مورد	وضعیت
کد	✅ کامل
مستندات	✅ کامل
Build	✅ موفق
Table Mappings	✅ 33/33
Post-Migration	✅ پیاده‌سازی شده
Logging	✅ فعال
Retry	✅ پیاده‌سازی شده
Error Handling	✅ کامل

---

نسخه: 1.0
تاریخ: December 6, 2025
آماده برای: Production ✅
نیاز به: Username/Password در appsettings.json

---

🚀 مرحله بعدی

همین الان:

1. QUICK-START.md را بخوانید (3 دقیقه)
2. appsettings.json را ویرایش کنید (2 دقیقه)
3. dotnet run را اجرا کنید

تمام! 🎉