arc/docs/INVOICE_IMPORT_EXCEL_GUIDE.md

راهنمای استفاده از فایل Excel برای ایمپورت فاکتورها

📋 ساختار فایل Excel

فایل Excel تمپلیت دارای یک Sheet است که در آن هر ردیف = یک ردیف فاکتور است.

نکته مهم: گروه‌بندی فاکتورها

• ردیف‌هایی که invoice_number یکسان دارند، متعلق به یک فاکتور هستند
• برای هر فاکتور می‌توانید چند ردیف (چند کالا/خدمت) وارد کنید
• اطلاعات هدر فاکتور (مثل نوع فاکتور، تاریخ، مشتری) باید فقط در ردیف اول هر فاکتور وارد شوند
• در ردیف‌های بعدی همان فاکتور، ستون‌های هدر می‌توانند خالی باشند (سیستم از ردیف اول استفاده می‌کند)
• فقط invoice_number و اطلاعات ردیف (product_code, quantity, ...) در همه ردیف‌ها باید وارد شوند

---

📊 ستون‌های فایل Excel

ستون‌های هدر فاکتور (در همه ردیف‌های یک فاکتور یکسان)

ستون	نام	الزامی	توضیحات	مثال
invoice_number	شماره فاکتور	✅	شناسه یکتا برای گروه‌بندی ردیف‌ها	INV-001
invoice_type	نوع فاکتور	✅	sales, purchase, sales_return, purchase_return, direct_consumption, production, waste	sales
document_date	تاریخ فاکتور	✅	فرمت: YYYY-MM-DD یا YYYY/MM/DD	2024-01-15
currency_code	کد ارز	✅	کد ارز موجود در سیستم	IRR, USD
is_proforma	پیش‌فاکتور	❌	TRUE یا FALSE (پیش‌فرض: FALSE)	FALSE
description	توضیحات فاکتور	❌	توضیحات کلی فاکتور	فاکتور فروش نمونه
person_code	کد مشتری/تامین‌کننده	⚠️	برای sales و purchase الزامی است	CUST-001
seller_code	کد فروشنده/بازاریاب	❌	برای محاسبه کارمزد	SELLER-001
due_date	تاریخ سررسید	❌	فرمت: YYYY-MM-DD	2024-02-15
post_inventory	ثبت انبار	❌	TRUE یا FALSE (پیش‌فرض: TRUE)	TRUE

ستون‌های ردیف فاکتور (برای هر کالا/خدمت)

ستون	نام	الزامی	توضیحات	مثال
product_code	کد کالا/خدمت	✅	کد محصول موجود در سیستم	P1001
quantity	تعداد	✅	مقدار کالا/خدمت	10
unit	واحد	❌	main یا secondary (پیش‌فرض: main)	main
unit_price	قیمت واحد	✅	قیمت به ازای واحد انتخابی	100000
discount_type	نوع تخفیف	❌	percent یا amount (پیش‌فرض: amount)	amount
discount_value	مقدار تخفیف	❌	درصد یا مبلغ (بسته به نوع)	5000
tax_rate	نرخ مالیات	❌	درصد مالیات (پیش‌فرض: 0)	9
line_description	توضیحات ردیف	❌	توضیحات این ردیف خاص	ردیف اول
movement	جهت حرکت	⚠️	in یا out (فقط برای فاکتور تولید)	out
warehouse_code	کد انبار	❌	کد انبار موجود در سیستم	WH-001

---

📝 مثال عملی

مثال 1: فاکتور فروش با 2 ردیف

فرض کنید می‌خواهید یک فاکتور فروش با 2 کالا ایجاد کنید:

invoice_number	invoice_type	document_date	currency_code	is_proforma	description	person_code	seller_code	due_date	post_inventory	product_code	quantity	unit	unit_price	discount_type	discount_value	tax_rate	line_description	movement	warehouse_code
INV-001	sales	2024-01-15	IRR	FALSE	فاکتور فروش	CUST-001		2024-02-15	TRUE	P1001	10	main	100000	amount	5000	9	ردیف اول		WH-001
INV-001										P1002	5	main	200000	percent	10	9	ردیف دوم		WH-001

نکات:

• هر دو ردیف invoice_number یکسان دارند (INV-001) → متعلق به یک فاکتور
• ردیف اول: اطلاعات هدر کامل وارد شده است
• ردیف دوم: ستون‌های هدر خالی هستند (سیستم از ردیف اول استفاده می‌کند)
• فقط invoice_number و اطلاعات ردیف (product_code, quantity, unit_price, ...) در ردیف دوم وارد شده است

مثال 2: فاکتور خرید با 1 ردیف

invoice_number	invoice_type	document_date	currency_code	is_proforma	description	person_code	seller_code	due_date	post_inventory	product_code	quantity	unit	unit_price	discount_type	discount_value	tax_rate	line_description	movement	warehouse_code
INV-002	purchase	2024-01-16	IRR	FALSE	فاکتور خرید	SUPP-001			TRUE	P1003	20	main	50000	amount	0	9			WH-001

مثال 3: فاکتور تولید با 3 ردیف (2 خروجی + 1 ورودی)

invoice_number	invoice_type	document_date	currency_code	is_proforma	description	person_code	seller_code	due_date	post_inventory	product_code	quantity	unit	unit_price	discount_type	discount_value	tax_rate	line_description	movement	warehouse_code
INV-003	production	2024-01-17	IRR	FALSE	فاکتور تولید				TRUE	P2001	5	main	0	amount	0	0	مواد اولیه 1	out	WH-001
INV-003	production	2024-01-17	IRR	FALSE	فاکتور تولید				TRUE	P2002	3	main	0	amount	0	0	مواد اولیه 2	out	WH-001
INV-003	production	2024-01-17	IRR	FALSE	فاکتور تولید				TRUE	P3001	2	main	0	amount	0	0	محصول نهایی	in	WH-001

نکات:

• برای فاکتور تولید، movement الزامی است
• ردیف‌های با movement: out = مواد اولیه (خروجی از انبار)
• ردیف‌های با movement: in = محصول نهایی (ورودی به انبار)
• باید حداقل یک ردیف out و یک ردیف in داشته باشید

---

✅ مراحل وارد کردن اطلاعات

مرحله 1: دانلود تمپلیت

1. در صفحه لیست فاکتورها، روی دکمه "ایمپورت از اکسل" کلیک کنید
2. در Dialog باز شده، روی "دانلود تمپلیت" کلیک کنید
3. فایل Excel را ذخیره کنید

مرحله 2: پر کردن فایل Excel

برای هر فاکتور:

1. تعیین شماره فاکتور: یک invoice_number یکتا انتخاب کنید (مثلاً INV-001)

2. وارد کردن اطلاعات هدر فاکتور (فقط در ردیف اول):

   • invoice_type: نوع فاکتور (sales, purchase, ...)
   • document_date: تاریخ فاکتور
   • currency_code: کد ارز
   • is_proforma: پیش‌فاکتور یا قطعی
   • description: توضیحات (اختیاری)
   • person_code: کد مشتری/تامین‌کننده (برای sales/purchase)
   • due_date: تاریخ سررسید (اختیاری)
   • post_inventory: ثبت انبار یا نه

   ⚠️ توجه: در ردیف‌های بعدی همان فاکتور، این ستون‌ها می‌توانند خالی باشند.

3. وارد کردن ردیف‌های فاکتور (برای هر کالا/خدمت یک ردیف):

   • product_code: کد کالا/خدمت
   • quantity: تعداد
   • unit: واحد (main/secondary)
   • unit_price: قیمت واحد
   • discount_type: نوع تخفیف (percent/amount)
   • discount_value: مقدار تخفیف
   • tax_rate: نرخ مالیات
   • line_description: توضیحات ردیف (اختیاری)
   • warehouse_code: کد انبار (اختیاری)
   • movement: جهت حرکت (فقط برای فاکتور تولید)

4. ردیف‌های بعدی همان فاکتور:

   • فقط invoice_number را وارد کنید (باید همان شماره فاکتور باشد)
   • ستون‌های هدر را خالی بگذارید
   • فقط اطلاعات ردیف (product_code, quantity, unit_price, ...) را وارد کنید

5. تکرار برای فاکتور بعدی:

   • یک invoice_number جدید انتخاب کنید
   • مراحل 2، 3 و 4 را تکرار کنید

مرحله 3: ذخیره و ایمپورت

1. فایل Excel را ذخیره کنید
2. در Dialog ایمپورت، فایل را انتخاب کنید
3. روی "بررسی (Dry Run)" کلیک کنید تا خطاها را ببینید
4. پس از رفع خطاها، روی "ایمپورت واقعی" کلیک کنید

---

⚠️ نکات مهم

1. کدهای موجود در سیستم

• product_code: باید کد محصولی باشد که قبلاً در سیستم ثبت شده است
• person_code: باید کد مشتری/تامین‌کننده‌ای باشد که قبلاً در سیستم ثبت شده است
• currency_code: باید کد ارزی باشد که در سیستم وجود دارد
• warehouse_code: باید کد انباری باشد که در سیستم وجود دارد

2. فرمت تاریخ

• فرمت‌های پشتیبانی شده: YYYY-MM-DD یا YYYY/MM/DD
• مثال: 2024-01-15 یا 2024/01/15

3. مقادیر Boolean

• برای is_proforma و post_inventory: TRUE یا FALSE
• می‌توانید از 1/0 یا بله/خیر هم استفاده کنید

4. واحدها

• main: واحد اصلی محصول
• secondary: واحد فرعی محصول
• اگر خالی بگذارید، پیش‌فرض main است

5. تخفیف

• discount_type: amount → discount_value به صورت مبلغ (مثلاً 5000 ریال)
• discount_type: percent → discount_value به صورت درصد (مثلاً 10 درصد)

6. فاکتور تولید

• باید حداقل یک ردیف با movement: out (مواد اولیه) داشته باشید
• باید حداقل یک ردیف با movement: in (محصول نهایی) داشته باشید
• برای فاکتور تولید، person_code نیاز نیست

---

🔍 مثال کامل در Excel

Row 1 (Header):
invoice_number | invoice_type | document_date | currency_code | is_proforma | description | person_code | seller_code | due_date | post_inventory | product_code | quantity | unit | unit_price | discount_type | discount_value | tax_rate | line_description | movement | warehouse_code

Row 2 (ردیف اول فاکتور INV-001):
INV-001 | sales | 2024-01-15 | IRR | FALSE | فاکتور فروش | CUST-001 | | 2024-02-15 | TRUE | P1001 | 10 | main | 100000 | amount | 5000 | 9 | ردیف اول | | WH-001

Row 3 (ردیف دوم فاکتور INV-001 - ستون‌های هدر خالی):
INV-001 | | | | | | | | | | P1002 | 5 | main | 200000 | percent | 10 | 9 | ردیف دوم | | WH-001

Row 4 (ردیف اول فاکتور INV-002):
INV-002 | purchase | 2024-01-16 | IRR | FALSE | فاکتور خرید | SUPP-001 | | | TRUE | P1003 | 20 | main | 50000 | amount | 0 | 9 | | | WH-001

---

❓ سوالات متداول

Q: آیا می‌توانم چند فاکتور را در یک فایل Excel وارد کنم؟

A: بله! فقط کافی است invoice_number متفاوت برای هر فاکتور استفاده کنید.

Q: اگر یک فاکتور چند ردیف داشته باشد، باید چه کنم؟

A: برای هر ردیف، یک سطر در Excel ایجاد کنید و invoice_number را یکسان نگه دارید.

Q: آیا می‌توانم ستون‌های اختیاری را خالی بگذارم؟

A: بله، ستون‌های اختیاری می‌توانند خالی باشند. مقادیر پیش‌فرض اعمال می‌شود.

Q: اگر کد محصول یا مشتری را اشتباه وارد کنم چه می‌شود؟

A: در مرحله "بررسی (Dry Run)" خطا نمایش داده می‌شود و می‌توانید قبل از ایمپورت واقعی آن را اصلاح کنید.

---

آخرین به‌روزرسانی: 2024