forked from hesabix/arc
212 lines
13 KiB
Markdown
Executable file
212 lines
13 KiB
Markdown
Executable file
# راهنمای استفاده از فایل 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
|
|
|