arc/docs/AI_FUNCTION_CALLING_ANALYSIS.md

تحلیل Function Calling و Endpoint های سیستم

📋 Function های فعلی AI

✅ Function های موجود (5 function):

1. get_business_info (category: business)

   • دریافت اطلاعات کامل کسب‌وکار
   • دسترسی: USER, BUSINESS_OWNER, OPERATOR, ADMIN
   • Permission: ندارد

2. search_invoices (category: invoices)

   • جستجو و فیلتر فاکتورها
   • فیلترها: تاریخ، نوع، مشتری، سال مالی
   • دسترسی: USER, BUSINESS_OWNER, OPERATOR, ADMIN
   • Permission: invoices.read

3. search_products (category: products)

   • جستجو در محصولات و کالاها
   • فیلترها: نام، کد، دسته‌بندی، نوع
   • دسترسی: USER, BUSINESS_OWNER, OPERATOR, ADMIN
   • Permission: inventory.read

4. get_product_info (category: products)

   • دریافت اطلاعات کامل یک محصول
   • دسترسی: USER, BUSINESS_OWNER, OPERATOR, ADMIN
   • Permission: inventory.read

5. get_customer_info (category: persons)

   • دریافت اطلاعات مشتری/تامین‌کننده
   • دسترسی: USER, BUSINESS_OWNER, OPERATOR, ADMIN
   • Permission: persons.read

6. get_financial_summary (category: financial)

   • دریافت خلاصه مالی کسب‌وکار
   • دسترسی: USER, BUSINESS_OWNER, ADMIN
   • Permission: reports.read

---

🌐 Endpoint های موجود در سیستم

📦 Products & Inventory (موجود)

• ✅ GET /api/v1/products - لیست محصولات
• ✅ GET /api/v1/products/{id} - جزئیات محصول
• ✅ POST /api/v1/products - ایجاد محصول
• ✅ PUT /api/v1/products/{id} - ویرایش محصول
• ✅ DELETE /api/v1/products/{id} - حذف محصول
• ✅ GET /api/v1/warehouses - لیست انبارها
• ✅ GET /api/v1/warehouse-docs - اسناد انبار
• ✅ GET /api/v1/boms - Bill of Materials
• ✅ GET /api/v1/kardex - کاردکس
• ✅ GET /api/v1/categories - دسته‌بندی‌ها
• ✅ GET /api/v1/price-lists - لیست قیمت‌ها

📄 Invoices & Documents (موجود)

• ✅ GET /api/v1/invoices - لیست فاکتورها
• ✅ POST /api/v1/invoices - ایجاد فاکتور
• ✅ PUT /api/v1/invoices/{id} - ویرایش فاکتور
• ✅ DELETE /api/v1/invoices/{id} - حذف فاکتور
• ✅ GET /api/v1/documents - لیست اسناد
• ✅ GET /api/v1/invoices/installments - اقساط فاکتورها

👥 Persons & Customers (موجود)

• ✅ GET /api/v1/persons - لیست اشخاص
• ✅ GET /api/v1/persons/{id} - جزئیات شخص
• ✅ POST /api/v1/persons - ایجاد شخص
• ✅ PUT /api/v1/persons/{id} - ویرایش شخص
• ✅ DELETE /api/v1/persons/{id} - حذف شخص
• ✅ GET /api/v1/customers - لیست مشتریان

💰 Financial Operations (موجود)

• ✅ GET /api/v1/receipts-payments - دریافت/پرداخت‌ها
• ✅ POST /api/v1/receipts-payments - ایجاد دریافت/پرداخت
• ✅ GET /api/v1/transfers - انتقالات
• ✅ POST /api/v1/transfers - ایجاد انتقال
• ✅ GET /api/v1/expense-income - هزینه/درآمد
• ✅ POST /api/v1/expense-income - ایجاد هزینه/درآمد
• ✅ GET /api/v1/bank-accounts - حساب‌های بانکی
• ✅ GET /api/v1/cash-registers - صندوق‌ها
• ✅ GET /api/v1/petty-cash - صندوق خرد
• ✅ GET /api/v1/accounts - حساب‌های کل
• ✅ GET /api/v1/fiscal-years - سال‌های مالی

📊 Reports & Analytics (موجود)

• ✅ GET /api/v1/business-dashboard - داشبورد کسب‌وکار
• ✅ GET /api/v1/report-templates - قالب‌های گزارش
• ✅ GET /api/v1/persons/debtors - بدهکاران
• ✅ GET /api/v1/persons/creditors - بستانکاران
• ✅ GET /api/v1/persons/transactions - تراکنش‌های اشخاص

🔧 Other Services (موجود)

• ✅ GET /api/v1/wallet - کیف پول
• ✅ GET /api/v1/checks - چک‌ها
• ✅ GET /api/v1/currencies - ارزها
• ✅ GET /api/v1/tax-units - واحدهای مالیاتی
• ✅ GET /api/v1/tax-types - انواع مالیات

---

🎯 پیشنهاد Function های مهم برای AI (اولویت بالا)

1. Function های خواندن (Read Operations) - اولویت بالا

1.1. Search Persons (جستجوی اشخاص)

name: "search_persons"
description: "جستجو در مشتریان و تامین‌کنندگان بر اساس نام، کد، تلفن و فیلترهای دیگر"
parameters:
  - search (string, optional): متن جستجو
  - person_type (string, optional): "customer" | "supplier" | "both"
  - city (string, optional): شهر
  - fiscal_year_id (integer, optional): سال مالی

1.2. Get Invoice Details (جزئیات فاکتور)

name: "get_invoice_details"
description: "دریافت جزئیات کامل یک فاکتور شامل اقلام، مالیات و پرداخت‌ها"
parameters:
  - invoice_id (integer, required): شناسه فاکتور

1.3. Get Inventory Status (وضعیت موجودی)

name: "get_inventory_status"
description: "دریافت وضعیت موجودی محصولات در انبارها"
parameters:
  - product_id (integer, optional): شناسه محصول (اگر مشخص نشود، لیست تمام محصولات)
  - warehouse_id (integer, optional): شناسه انبار

1.4. Get Person Balance (موجودی شخص)

name: "get_person_balance"
description: "دریافت موجودی و بدهی/بستانکاری یک مشتری یا تامین‌کننده"
parameters:
  - person_id (integer, required): شناسه شخص
  - fiscal_year_id (integer, optional): سال مالی

1.5. Search Receipts Payments (جستجوی دریافت/پرداخت‌ها)

name: "search_receipts_payments"
description: "جستجو در دریافت/پرداخت‌ها بر اساس تاریخ، نوع، شخص و فیلترهای دیگر"
parameters:
  - from_date (string, optional): تاریخ شروع
  - to_date (string, optional): تاریخ پایان
  - person_id (integer, optional): شناسه شخص
  - type (string, optional): "receipt" | "payment"
  - account_type (string, optional): "bank" | "cash" | "petty_cash"

1.6. Get Financial Reports (گزارش‌های مالی)

name: "get_debtors_report"
description: "گزارش بدهکاران با جزئیات بدهی و تاریخچه"
parameters:
  - fiscal_year_id (integer, optional): سال مالی
  - min_balance (number, optional): حداقل بدهی

name: "get_creditors_report"
description: "گزارش بستانکاران با جزئیات بستانکاری و تاریخچه"
parameters:
  - fiscal_year_id (integer, optional): سال مالی
  - min_balance (number, optional): حداقل بستانکاری

1.7. Get Product Kardex (کاردکس محصول)

name: "get_product_kardex"
description: "دریافت کاردکس (گردش موجودی) یک محصول در انبار"
parameters:
  - product_id (integer, required): شناسه محصول
  - warehouse_id (integer, optional): شناسه انبار
  - from_date (string, optional): تاریخ شروع
  - to_date (string, optional): تاریخ پایان

---

2. Function های نوشتن (Write Operations) - اولویت متوسط

2.1. Create Person (ایجاد شخص)

name: "create_person"
description: "ایجاد یک مشتری یا تامین‌کننده جدید"
parameters:
  - name (string, required): نام
  - person_type (string, required): "customer" | "supplier"
  - phone (string, optional): تلفن
  - email (string, optional): ایمیل
  - address (string, optional): آدرس
  - tax_id (string, optional): شناسه ملی/کد اقتصادی

2.2. Create Invoice (ایجاد فاکتور)

name: "create_invoice"
description: "ایجاد یک فاکتور جدید (فروش، خرید و غیره)"
parameters:
  - document_type (string, required): نوع فاکتور
  - person_id (integer, optional): شناسه مشتری/تامین‌کننده
  - items (array, required): اقلام فاکتور
    - product_id (integer, required)
    - quantity (number, required)
    - unit_price (number, required)
  - due_date (string, optional): تاریخ سررسید

2.3. Create Receipt Payment (ایجاد دریافت/پرداخت)

name: "create_receipt_payment"
description: "ثبت دریافت یا پرداخت نقدی/بانکی"
parameters:
  - type (string, required): "receipt" | "payment"
  - person_id (integer, optional): شناسه شخص
  - amount (number, required): مبلغ
  - account_id (integer, required): حساب بانکی/نقدی
  - description (string, optional): توضیحات

2.4. Update Person (ویرایش شخص)

name: "update_person"
description: "ویرایش اطلاعات یک مشتری یا تامین‌کننده"
parameters:
  - person_id (integer, required): شناسه شخص
  - name (string, optional): نام جدید
  - phone (string, optional): تلفن جدید
  - email (string, optional): ایمیل جدید

---

3. Function های تحلیل و گزارش (Analytics) - اولویت متوسط

3.1. Get Sales Report (گزارش فروش)

name: "get_sales_report"
description: "گزارش فروش بر اساس تاریخ، محصول، مشتری"
parameters:
  - from_date (string, required): تاریخ شروع
  - to_date (string, required): تاریخ پایان
  - product_id (integer, optional): فیلتر بر اساس محصول
  - person_id (integer, optional): فیلتر بر اساس مشتری
  - group_by (string, optional): "day" | "month" | "product" | "customer"

3.2. Get Purchase Report (گزارش خرید)

name: "get_purchase_report"
description: "گزارش خرید بر اساس تاریخ، محصول، تامین‌کننده"
parameters:
  - from_date (string, required): تاریخ شروع
  - to_date (string, required): تاریخ پایان
  - product_id (integer, optional): فیلتر بر اساس محصول
  - person_id (integer, optional): فیلتر بر اساس تامین‌کننده

3.3. Get Inventory Valuation (ارزش موجودی)

name: "get_inventory_valuation"
description: "محاسبه ارزش موجودی کالاها در انبار"
parameters:
  - warehouse_id (integer, optional): فیلتر بر اساس انبار
  - valuation_method (string, optional): "fifo" | "average" | "lifo"

3.4. Get Cash Flow (گردش نقدی)

name: "get_cash_flow"
description: "گزارش گردش نقدی (ورودی/خروجی) در دوره زمانی"
parameters:
  - from_date (string, required): تاریخ شروع
  - to_date (string, required): تاریخ پایان
  - account_type (string, optional): "bank" | "cash" | "all"

---

4. Function های پیشنهادی برای راحتی بیشتر (Nice to Have)

4.1. Calculate Tax (محاسبه مالیات)

name: "calculate_tax"
description: "محاسبه مالیات بر اساس مبلغ و نوع"
parameters:
  - amount (number, required): مبلغ
  - tax_type_id (integer, optional): نوع مالیات
  - tax_unit_id (integer, optional): واحد مالیاتی

4.2. Get Product Price (قیمت محصول)

name: "get_product_price"
description: "دریافت قیمت محصول از لیست قیمت"
parameters:
  - product_id (integer, required): شناسه محصول
  - price_list_id (integer, optional): شناسه لیست قیمت
  - person_id (integer, optional): برای لیست قیمت اختصاصی مشتری

4.3. Search Warehouse Documents (جستجوی اسناد انبار)

name: "search_warehouse_documents"
description: "جستجو در اسناد انبار (ورود، خروج، انتقال)"
parameters:
  - from_date (string, optional): تاریخ شروع
  - to_date (string, optional): تاریخ پایان
  - warehouse_id (integer, optional): شناسه انبار
  - document_type (string, optional): نوع سند

---

📊 اولویت‌بندی پیشنهادی

🔥 اولویت بسیار بالا (باید اضافه شود):

1. ✅ search_persons - جستجوی اشخاص
2. ✅ get_invoice_details - جزئیات فاکتور
3. ✅ get_person_balance - موجودی شخص
4. ✅ get_inventory_status - وضعیت موجودی

⚡ اولویت بالا (بسیار مفید):

5. ✅ search_receipts_payments - جستجوی دریافت/پرداخت
6. ✅ get_debtors_report - گزارش بدهکاران
7. ✅ get_creditors_report - گزارش بستانکاران
8. ✅ get_product_kardex - کاردکس محصول

💡 اولویت متوسط (مفید برای عملیات):

9. ✅ create_person - ایجاد شخص
10. ✅ create_invoice - ایجاد فاکتور
11. ✅ create_receipt_payment - ثبت دریافت/پرداخت
12. ✅ update_person - ویرایش شخص

🌟 اولویت پایین (برای تحلیل پیشرفته):

13. ✅ get_sales_report - گزارش فروش
14. ✅ get_purchase_report - گزارش خرید
15. ✅ get_inventory_valuation - ارزش موجودی
16. ✅ get_cash_flow - گردش نقدی

---

🎯 نتیجه‌گیری

Function های فعلی: 6 function (فقط خواندن)

Function های پیشنهادی:

• اولویت بالا: 8 function (خواندن + گزارش)
• اولویت متوسط: 4 function (نوشتن)
• اولویت پایین: 4 function (تحلیل)

توصیه: شروع با function های اولویت بالا که بیشترین کاربرد را دارند و AI می‌تواند با آنها کارهای مهم‌تری انجام دهد.