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](QUICK-START.md)** - 3 قدم ساده

### برای خواندن کامل (10 دقیقه):
👉 **[SUMMARY.md](SUMMARY.md)** - خلاصه کامل پروژه

### برای جزئیات کامل (30 دقیقه):
👉 **[README.md](README.md)** - راهنمای جامع

---

## 📋 مستندات

### 1. [SUMMARY.md](SUMMARY.md) ⭐ **شروع از اینجا**
**307 خط** - خلاصه کامل پروژه
- ✅ وضعیت فعلی
- ✅ آنچه انجام شد
- ✅ ساختار پروژه
- ✅ فیچرهای پیاده‌سازی شده
- ✅ نحوه استفاده (3 قدم)
- ✅ خروجی مورد انتظار
- ✅ چک‌لیست آمادگی
- ✅ آمار نهایی

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

---

### 2. [QUICK-START.md](QUICK-START.md) 🚀
**147 خط** - راهنمای سریع 3 قدمی
- قدم 1: ویرایش appsettings.json
- قدم 2: اجرای Migration
- قدم 3: بررسی Logs
- عیب‌یابی سریع
- تنظیمات پیشرفته

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

---

### 3. [README.md](README.md) 📖
**425 خط** - راهنمای کامل و جامع
- نگاه کلی
- ساختار پروژه
- تنظیمات (`appsettings.json`)
- نحوه اجرا
- جریان کار (Workflow)
- Retry Logic
- Error Handling
- مثال خروجی
- عیب‌یابی
- FAQ

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

---

### 4. [TABLE-MAPPINGS.md](TABLE-MAPPINGS.md) 📋
**230 خط** - لیست کامل 33 جدول
- جداول با تغییر نام (10 جدول)
- جداول بدون تغییر نام (23 جدول)
- ترتیب پیشنهادی Migration
- تغییرات ساختاری (Binary Tree)
- Configuration کامل
- چک‌لیست قبل از Migration
- آمار تخمینی

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

---

### 5. [POST-MIGRATION-TRANSFORMATION.md](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
```csharp
// Setup Serilog
// Configure DI
// Run MigrationService
```

---

### 2. `FourSat.DataMigration/appsettings.json`
**75 خط** - تنظیمات کامل
```json
{
  "ConnectionStrings": { /* Source + Target */ },
  "MigrationSettings": { /* BatchSize, Retry, etc. */ },
  "TableMappings": { /* 33 table mappings */ },
  "Serilog": { /* Console + File */ }
}
```

---

### 3. `FourSat.DataMigration/Models/MigrationModels.cs`
**39 خط** - Data models
```csharp
public class MigrationSettings { ... }
public class TableMapping { ... }
public class QueueItem { ... }
```

---

### 4. `FourSat.DataMigration/Services/MigrationService.cs`
**288 خط** - Migration engine اصلی
```csharp
// 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
```sql
-- 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](SUMMARY.md)
- [ ] مطالعه [QUICK-START.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](README.md#error-handling)
- **Table not found**: [TABLE-MAPPINGS.md](TABLE-MAPPINGS.md)
- **Binary tree violation**: [POST-MIGRATION-TRANSFORMATION.md](POST-MIGRATION-TRANSFORMATION.md)
- **Timeout**: [QUICK-START.md - عیب‌یابی](QUICK-START.md#عیب-یابی-سریع)

### منابع
- 📖 **راهنمای کامل**: [README.md](README.md)
- 🚀 **شروع سریع**: [QUICK-START.md](QUICK-START.md)
- 📋 **لیست جداول**: [TABLE-MAPPINGS.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](QUICK-START.md) را بخوانید (3 دقیقه)
2. `appsettings.json` را ویرایش کنید (2 دقیقه)
3. `dotnet run` را اجرا کنید

**تمام! 🎉**