# راهنمای ورود فایل مالی Excel

## قالب پذیرفته‌شده

فایل باید `xlsx` یا `xlsm` معتبر و حداکثر به اندازهٔ `MAX_UPLOAD_MB` باشد. اولین sheet دارای سطر header معتبر پردازش می‌شود. نام ستون‌ها با یکسان‌سازی حروف فارسی/عربی و فاصله‌ها شناسایی می‌شوند:

1. شماره پیش فاکتور
2. تاریخ پیش فاکتور
3. کد مشتری
4. عنوان مشتری
5. نوع فروش
6. کد کالا/خدمت
7. کالا/خدمت
8. واحد اصلی
9. مقدار-اصلی

گونه‌های رایج «ي/ی»، «ك/ک» و نیم‌فاصله پشتیبانی می‌شوند. شمارهٔ فاکتور، کد مشتری و کد کالا به‌صورت متن خوانده می‌شوند تا صفر ابتدای آن‌ها حفظ شود.

## اعتبارسنجی

- شماره فاکتور، تاریخ، کد و عنوان مشتری، نوع فروش، کد/نام کالا و واحد نباید خالی باشند.
- مقدار باید عددی بزرگ‌تر از صفر باشد.
- عنوان مشتری یا کالا نباید صرفاً عدد باشد.
- سطرهای footer یا جمع که با دادهٔ معتبر هم‌خوان نیستند رد می‌شوند و در CSV خطا می‌آیند.
- فرمول‌ها پذیرفته نمی‌شوند؛ سامانه هیچ فرمول یا ماکرویی را اجرا نمی‌کند.
- magic bytes، پسوند، MIME، اندازه و SHA-256 بررسی می‌شوند. فایل checksum تکراری دوباره import نمی‌شود.

## پیش‌نمایش و commit

پس از بارگذاری، سامانه تعداد سطر معتبر/ردشده، فاکتور جدید/به‌روزشده/بدون تغییر، کالای تغییرکرده و مغایرت را پیش‌نمایش می‌دهد. commit نهایی تراکنشی است: در خطای بحرانی، تغییر ناقص باقی نمی‌ماند. فایل اصلی در storage خصوصی نگهداری و مسیر آن در audit ثبت می‌شود.

## نسخه و مغایرت

هر تغییر مالی نسخهٔ جدید immutable می‌سازد و تفاوت هویت و اقلام ذخیره می‌شود. اگر نسخهٔ دستی وجود داشته باشد یا مقدار مالی از تحویل قطعی کمتر شود، مغایرت باز ایجاد می‌شود. تصمیم مدیر نسخهٔ resolved جدید می‌سازد و منبع انتخابی هر فیلد/قلم را نگه می‌دارد.

## کنترل نمونهٔ مستند

fixture خودکار پروژه دقیقاً ۱۸۰ ردیف معتبر، ۱۱۰ فاکتور و ۱۹ کالا تولید می‌کند و یک ردیف footer نامعتبر نیز دارد. آزمون‌ها گروه‌بندی، حفظ صفر ابتدا، رد footer، idempotency، نسخهٔ دوم و مغایرت را بررسی می‌کنند. فایل واقعی مرجع باید پیش از بهره‌برداری یک بار در staging نیز وارد و خروجی preview با واحد مالی تطبیق داده شود.