arc/docs/PRODUCT_MIGRATION_ANALYSIS.md

# تحلیل انتقال کالا و خدمات از hesabixOld به hesabixpy

## خلاصه اجرایی

این سند تحلیل نحوه انتقال کالا و خدمات (commodities/products) از دیتابیس قدیمی (`hesabixOld`) به دیتابیس جدید (`hesabixpy`) را ارائه می‌دهد.

## وضعیت فعلی

### دیتابیس قدیمی (hesabixOld)

#### جدول `commodity`
- **تعداد کالا/خدمات**: 213,565
- **تعداد کسب و کارهای دارای کالا**: 2,371
- **ساختار**:
  - `id`: شناسه یکتا
  - `bid_id`: شناسه کسب و کار (ارجاع به `business.id`)
  - `name`: نام کالا/خدمت
  - `code`: کد کالا/خدمت
  - `des`: توضیحات
  - `price_buy`: قیمت خرید (varchar)
  - `price_sell`: قیمت فروش (varchar)
  - `khadamat`: نوع (0 = کالا، 1 = خدمت، NULL = کالا)
  - `cat_id`: شناسه دسته‌بندی (ارجاع به `commodity_cat.id`)
  - `unit_id`: شناسه واحد (ارجاع به `commodity_unit.id`)
  - `order_point`: نقطه سفارش
  - `commodity_count_check`: بررسی موجودی
  - `min_order_count`: حداقل تعداد سفارش
  - `day_loading`: روز بارگذاری
  - `speed_access`: دسترسی سریع
  - `without_tax`: بدون مالیات
  - `barcodes`: بارکدها (longtext)
  - `tax_code`: کد مالیاتی
  - `tax_type`: نوع مالیات
  - `tax_unit`: واحد مالیات
  - `custom_code`: کد سفارشی
  - `tags`: تگ‌ها (JSON)

**توزیع نوع**:
- کالا (khadamat = 0): 206,291 (کل) / 196,246 (قابل انتقال - 96.6%)
- خدمت (khadamat = 1): 7,269 (کل) / 6,867 (قابل انتقال - 3.4%)
- NULL: 5 (کل) / 4 (قابل انتقال)

**دسته‌بندی (قابل انتقال)**:
- کالا/خدمات با دسته‌بندی: 68,710 (33.8%)
- کالا/خدمات بدون دسته‌بندی: 134,407 (66.2%)

**واحد**:
- همه کالا/خدمات واحد دارند (213,565)

#### جدول `commodity_cat`
- **ساختار**:
  - `id`: شناسه یکتا
  - `bid_id`: شناسه کسب و کار
  - `name`: نام دسته‌بندی
  - `upper`: دسته‌بندی والد
  - `root`: آیا ریشه است؟

#### جدول `commodity_unit`
- **ساختار**:
  - `id`: شناسه یکتا
  - `name`: نام واحد (مثل "عدد", "کیلوگرم", "لیتر")
  - `float_number`: تعداد اعشار

### دیتابیس جدید (hesabixpy)

#### جدول `products`
- **تعداد کالا/خدمات فعلی**: 3,453
- **ساختار**:
  - `id`: شناسه یکتا
  - `business_id`: شناسه کسب و کار (ارجاع به `businesses.id`)
  - `item_type`: نوع آیتم (ENUM: "کالا", "خدمت")
  - `code`: کد یکتا در هر کسب و کار
  - `name`: نام
  - `description`: توضیحات
  - `category_id`: شناسه دسته‌بندی (ارجاع به `categories.id`)
  - `main_unit`: واحد اصلی (varchar - نام واحد)
  - `secondary_unit`: واحد فرعی (varchar)
  - `unit_conversion_factor`: ضریب تبدیل واحد
  - `base_sales_price`: قیمت فروش پایه (decimal)
  - `base_purchase_price`: قیمت خرید پایه (decimal)
  - `track_inventory`: ردیابی موجودی (boolean)
  - `reorder_point`: نقطه سفارش مجدد (integer)
  - `min_order_qty`: حداقل تعداد سفارش (integer)
  - `lead_time_days`: زمان تحویل (integer)
  - `is_sales_taxable`: مالیات‌پذیر فروش (boolean)
  - `is_purchase_taxable`: مالیات‌پذیر خرید (boolean)
  - `sales_tax_rate`: نرخ مالیات فروش (decimal)
  - `purchase_tax_rate`: نرخ مالیات خرید (decimal)
  - `tax_type_id`: شناسه نوع مالیات
  - `tax_code`: کد مالیاتی
  - `tax_unit_id`: شناسه واحد مالیات
  - `inventory_mode`: حالت موجودی (varchar - پیش‌فرض: "bulk")
  - `track_serial`: ردیابی سریال (boolean)
  - `track_barcode`: ردیابی بارکد (boolean)
  - `created_at`: تاریخ ایجاد
  - `updated_at`: تاریخ به‌روزرسانی

#### جدول `categories`
- **ساختار**:
  - `id`: شناسه یکتا
  - `business_id`: شناسه کسب و کار
  - `parent_id`: شناسه دسته‌بندی والد
  - `title_translations`: عناوین چندزبانه (JSON - {"fa": "...", "en": "..."})
  - `description`: توضیحات
  - `sort_order`: ترتیب نمایش
  - `is_active`: فعال بودن
  - `created_at`: تاریخ ایجاد
  - `updated_at`: تاریخ به‌روزرسانی

## استراتژی انتقال

### تبدیل فیلدها

| فیلد قدیمی | فیلد جدید | تبدیل |
|------------|-----------|-------|
| `id` | - | نگه‌داری در mapping table (اختیاری) |
| `bid_id` | `business_id` | نگاشت از business_id_mapping |
| `name` | `name` | مستقیم |
| `code` | `code` | مستقیم |
| `des` | `description` | مستقیم |
| `price_buy` | `base_purchase_price` | تبدیل varchar به decimal |
| `price_sell` | `base_sales_price` | تبدیل varchar به decimal |
| `khadamat` | `item_type` | 0 یا NULL → "کالا", 1 → "خدمت" |
| `cat_id` | `category_id` | نگاشت از category_id_mapping |
| `unit_id` | `main_unit` | نگاشت از unit_id به unit name |
| `order_point` | `reorder_point` | تبدیل varchar به integer |
| `commodity_count_check` | `track_inventory` | تبدیل boolean |
| `min_order_count` | `min_order_qty` | تبدیل varchar به integer |
| `day_loading` | `lead_time_days` | تبدیل varchar به integer |
| `without_tax` | `is_sales_taxable`, `is_purchase_taxable` | معکوس boolean |
| `barcodes` | - | حذف (یا در جدول جداگانه) |
| `tax_code` | `tax_code` | مستقیم |
| `tax_type` | `tax_type_id` | نیاز به mapping |
| `tax_unit` | `tax_unit_id` | نیاز به mapping |
| `tags` | - | حذف (یا در جدول جداگانه) |

### تبدیل khadamat به item_type

**الگوریتم**:
```python
def convert_khadamat_to_item_type(khadamat: int | None) -> str:
    """
    تبدیل khadamat به item_type
    
    Args:
        khadamat: مقدار khadamat از دیتابیس قدیمی (0 = کالا، 1 = خدمت، NULL = کالا)
    
    Returns:
        "کالا" یا "خدمت"
    """
    if khadamat == 1:
        return "خدمت"
    return "کالا"  # پیش‌فرض برای 0 و NULL
```

### تبدیل قیمت‌ها

**الگوریتم**:
```python
def convert_price(price_str: str | None) -> Decimal | None:
    """
    تبدیل قیمت از varchar به decimal
    
    Args:
        price_str: قیمت به صورت string (مثل "5250000" یا "0")
    
    Returns:
        Decimal یا None
    """
    if not price_str or not price_str.strip():
        return None
    
    try:
        # حذف فاصله و کاراکترهای غیرعددی (به جز نقطه و منفی)
        cleaned = price_str.strip().replace(',', '').replace(' ', '')
        if not cleaned or cleaned == '0':
            return None
        return Decimal(cleaned)
    except (ValueError, InvalidOperation):
        return None
```

### نگاشت category_id

**چالش**: 
- در قدیمی: `commodity_cat` با `bid_id` و `name`
- در جدید: `categories` با `business_id` و `title_translations` (JSON)

**راه‌حل**:
1. برای هر کسب و کار، دسته‌بندی‌های قدیمی را بخوان
2. در دیتابیس جدید جستجو کن (بر اساس business_id و name)
3. اگر پیدا نشد: ایجاد کن با `title_translations = {"fa": name, "en": name}`
4. mapping را ذخیره کن

**الگوریتم**:
```python
def get_or_create_category(
    old_cat_id: int | None,
    old_cat_name: str | None,
    new_business_id: int,
    category_mapping: Dict[int, int]
) -> int | None:
    """
    دریافت یا ایجاد دسته‌بندی
    
    Returns:
        شناسه دسته‌بندی جدید یا None
    """
    if not old_cat_id or not old_cat_name:
        return None
    
    # بررسی mapping
    if old_cat_id in category_mapping:
        return category_mapping[old_cat_id]
    
    # جستجو در دیتابیس جدید
    query = text("""
        SELECT id FROM categories
        WHERE business_id = :business_id
        AND JSON_EXTRACT(title_translations, '$.fa') = :name
        LIMIT 1
    """)
    result = db.execute(query, {
        "business_id": new_business_id,
        "name": old_cat_name
    }).fetchone()
    
    if result:
        category_mapping[old_cat_id] = result[0]
        return result[0]
    
    # ایجاد دسته‌بندی جدید
    query = text("""
        INSERT INTO categories (
            business_id, title_translations,
            sort_order, is_active,
            created_at, updated_at
        ) VALUES (
            :business_id, :title_translations,
            0, 1,
            :created_at, :updated_at
        )
    """)
    
    title_translations = json.dumps({"fa": old_cat_name, "en": old_cat_name})
    db.execute(query, {
        "business_id": new_business_id,
        "title_translations": title_translations,
        "created_at": datetime.utcnow(),
        "updated_at": datetime.utcnow()
    })
    db.commit()
    
    # دریافت شناسه جدید
    new_cat_id = db.lastrowid
    category_mapping[old_cat_id] = new_cat_id
    return new_cat_id
```

### نگاشت unit_id به main_unit

**چالش**:
- در قدیمی: `unit_id` (ارجاع به `commodity_unit.id`)
- در جدید: `main_unit` (varchar - نام واحد)

**راه‌حل**:
1. ایجاد mapping بین `unit_id` و `unit.name`
2. استفاده از نام واحد به عنوان `main_unit`

**الگوریتم**:
```python
def create_unit_mapping() -> Dict[int, str]:
    """ایجاد mapping بین unit_id و unit name"""
    query = text("SELECT id, name FROM hesabixOld.commodity_unit")
    results = old_db.execute(query).fetchall()
    
    mapping = {}
    for row in results:
        mapping[row.id] = row.name
    
    return mapping
```

### تبدیل سایر فیلدها

**order_point → reorder_point**:
```python
def convert_order_point(order_point: str | None) -> int | None:
    if not order_point or not order_point.strip():
        return None
    try:
        return int(float(order_point.strip()))
    except (ValueError, TypeError):
        return None
```

**commodity_count_check → track_inventory**:
```python
def convert_track_inventory(check: int | None) -> bool:
    return bool(check) if check is not None else False
```

**without_tax → is_sales_taxable/is_purchase_taxable**:
```python
def convert_taxable(without_tax: int | None) -> tuple[bool, bool]:
    """
    تبدیل without_tax به is_sales_taxable و is_purchase_taxable
    
    Returns:
        (is_sales_taxable, is_purchase_taxable)
    """
    if without_tax == 1:
        return (False, False)  # بدون مالیات
    return (True, True)  # با مالیات (پیش‌فرض)
```

## الگوریتم انتقال

### مرحله 1: آماده‌سازی

1. **ایجاد business_id_mapping**: از انتقال کسب و کارها
2. **ایجاد unit_mapping**: mapping بین unit_id و unit name
3. **ایجاد category_mapping**: برای هر کسب و کار

### مرحله 2: فیلتر کالا/خدمات برای انتقال

**شرایط انتقال**:
1. کالا/خدمت باید `bid_id` داشته باشد
2. `bid_id` باید در `business_id_mapping` وجود داشته باشد
3. کالا/خدمت نباید در دیتابیس جدید وجود داشته باشد (بر اساس business_id و code)

**SQL برای انتخاب**:
```sql
SELECT c.*
FROM hesabixOld.commodity c
INNER JOIN business_id_mapping m ON c.bid_id = m.old_business_id
WHERE NOT EXISTS (
    SELECT 1 FROM hesabixpy.products new
    WHERE new.business_id = m.new_business_id
      AND new.code = c.code
)
ORDER BY c.bid_id, c.id;
```

### مرحله 3: پردازش هر کالا/خدمت

**مراحل**:
1. نگاشت `bid_id` → `business_id`
2. تبدیل `khadamat` → `item_type`
3. تبدیل `price_buy` و `price_sell` → `base_purchase_price` و `base_sales_price`
4. نگاشت `cat_id` → `category_id` (با ایجاد در صورت نیاز)
5. نگاشت `unit_id` → `main_unit` (نام واحد)
6. تبدیل سایر فیلدها
7. درج در دیتابیس جدید

### مرحله 4: مدیریت موارد خاص

**سناریو 1: category_id نامعتبر**
- عمل: `category_id = NULL`
- لاگ: ثبت در لاگ

**سناریو 2: unit_id نامعتبر**
- عمل: `main_unit = NULL` یا پیش‌فرض "عدد"
- لاگ: ثبت در لاگ

**سناریو 3: قیمت‌های نامعتبر**
- عمل: `base_sales_price = NULL` یا `base_purchase_price = NULL`
- لاگ: ثبت در لاگ

**سناریو 4: کد تکراری**
- عمل: skip کردن با reason "duplicate_code"
- لاگ: ثبت در لاگ

## آمار و ارقام

### توزیع داده‌ها

- **کل کالا/خدمات**: 213,565
- **کالا (khadamat = 0)**: 206,291 (96.6%)
- **خدمت (khadamat = 1)**: 7,269 (3.4%)
- **کالا/خدمات با دسته‌بندی**: 77,160 (36.1%)
- **کالا/خدمات بدون دسته‌بندی**: 136,405 (63.9%)
- **کسب و کارهای دارای کالا**: 2,371

### قابل انتقال

- **کسب و کارهای منتقل شده**: 3,812
- **کسب و کارهای دارای کالا که منتقل شده‌اند**: 2,146
- **کالا/خدمات قابل انتقال**: 203,117
- **کالا/خدمات غیرقابل انتقال**: 10,448 (کسب و کار owner منتقل نشده)

## نکات مهم

1. **حجم زیاد داده**: 213,565 کالا/خدمات - نیاز به پردازش batch به batch
2. **دسته‌بندی‌ها**: باید برای هر کسب و کار ایجاد شوند
3. **واحدها**: باید از ID به نام تبدیل شوند
4. **قیمت‌ها**: باید از varchar به decimal تبدیل شوند
5. **کد یکتا**: کد باید در هر کسب و کار یکتا باشد

## ریسک‌ها و راه‌حل‌ها

### ریسک 1: حجم زیاد داده
**راه‌حل**: پردازش batch به batch با اندازه مناسب (100-500 در هر batch)

### ریسک 2: دسته‌بندی‌های تکراری
**راه‌حل**: بررسی وجود قبل از ایجاد

### ریسک 3: کدهای تکراری
**راه‌حل**: بررسی unique constraint قبل از درج

### ریسک 4: قیمت‌های نامعتبر
**راه‌حل**: تبدیل با مدیریت خطا و استفاده از NULL

### ریسک 5: واحدهای نامعتبر
**راه‌حل**: استفاده از پیش‌فرض "عدد" در صورت عدم وجود

## نتیجه‌گیری

انتقال کالا و خدمات نیاز به:
- ✅ نگاشت business_id
- ✅ تبدیل item_type
- ✅ تبدیل قیمت‌ها
- ✅ ایجاد/نگاشت دسته‌بندی‌ها
- ✅ تبدیل واحدها
- ✅ پردازش batch به batch به دلیل حجم زیاد

**تخمین زمان**: با batch size 500، حدود 406 batch نیاز است که می‌تواند 30-60 دقیقه طول بکشد.

**آمار دقیق قابل انتقال**:
- کالا: 196,246
- خدمت: 6,867
- با دسته‌بندی: 68,710
- بدون دسته‌بندی: 134,407
- کسب و کارهای دارای کالا: 2,146