Seyyed_arc/docs/AI_ADVANCED_SEARCH_SCENARIO.md

سناریوی جست‌وجوی پیشرفته (QueryInfo) برای AI

مشکل

در API حسابیکس، لیست‌های اصلی (اشخاص، فاکتور، کالا، چک، …) از QueryInfo پشتیبانی می‌کنند:

قابلیت	OpenAPI (schemas.py)	Backend (query_service.py / سرویس‌ها)	AI امروز
search + search_fields	✅	✅ (در بسیاری سرویس‌ها)	🟡 فقط search ساده؛ search_fields گاهی پیش‌فرض داخلی
filters[] با property, operator, value	✅	✅ (ناهمگون بین entityها)	🔴 تقریباً استفاده نمی‌شود
عملگرهای =, >, <, *, in, …	✅ مستند	✅ در QueryBuilder و سرویس‌های اختصاصی	🔴 مدل از وجودشان بی‌خبر است
sort / sort_by	✅	✅	🟡 محدود

علت: توضیحات toolهای AI (search_invoices, query_business_data, …) فقط فیلدهای تخت (from_date, person_id) دارند و filters به‌عنوان آرایهٔ FilterItem در schema/tool prompt نیامده. علاوه بر این، _build_list_query در ai_query_service.py کلید filters را به query سرویس forward نمی‌کرد (رفع شد در فاز ۱۰).

---

مدل دادهٔ استاندارد (مرجع OpenAPI)

{
  "take": 20,
  "skip": 0,
  "search": "علی",
  "search_fields": ["alias_name", "mobile", "code"],
  "sort_by": "created_at",
  "sort_desc": true,
  "filters": [
    {"property": "total_amount", "operator": ">=", "value": 1000000},
    {"property": "document_date", "operator": ">=", "value": "2024-01-01"},
    {"property": "description", "operator": "*", "value": "خرید"}
  ]
}

عملگرها (همان FilterOperator / QueryBuilder)

عملگر	معنی
=	برابر
!=	نابرابر
>, >=, <, <=	مقایسه عددی/تاریخ
*	شامل (LIKE %value%)
*?	شروع با
?*	پایان با
in	عضو مجموعه (value آرایه)
is_null / is_not_null	خالی / غیرخالی (در برخی سرویس‌ها)

همهٔ filters با AND ترکیب می‌شوند.

---

فازهای اجرایی پیشنهادی

فاز ۱۰ — زیرساخت AI + query_business_data (اولویت بالا) ✅ شروع شده

#	تحویل	توضیح
۱۰.۱	ai_query_filter_catalog.py	برای هر entity: ستون‌های قابل فیلتر + عملگرهای مجاز + فیلدهای جستجو
۱۰.۲	list_queryable_fields	tool: «برای invoice چه فیلترهایی دارم؟»
۱۰.۳	ai_query_filter_service.normalize_query_filters	اعتبارسنجی و نرمال‌سازی filters قبل از سرویس
۱۰.۴	اصلاح _build_list_query	پاس‌دادن filters, search_fields, sort
۱۰.۵	ADVANCED_QUERY_PROMPT_BLOCK در prompt سیستم	آموزش مدل برای ساخت filters
۱۰.۶	گسترش schemaی query_business_data.filters	توضیح ساختار FilterItem + مثال

فاز ۱۱ — toolهای اختصاصی ✅ (پیاده‌سازی شده)

entity	tool	کار
invoice/document	search_invoices	پارامتر filters + search_fields
person	search_persons	مهاجرت به get_persons_by_business + QueryInfo کامل
product	search_products	filters برای item_type, قیمت، …
check, transfer, expense_income	همان الگو

الگوی واحد: هر tool لیست، پارامترهای مشترک:

{
  "search": "string?",
  "search_fields": ["string"]?,
  "filters": [{"property","operator","value"}]?,
  "take", "skip", "sort_by", "sort_desc"
}

فاز ۱۲ — OpenAPI و UI (هم‌راستاسازی) ✅

#	کار	وضعیت
۱۲.۱	کامپوننت مشترک QueryInfo / DocumentListQuery در POST list	✅
۱۲.۲	مثال‌های فارسی در Swagger (json_schema_extra + Components)	✅
۱۲.۳	GET /api/v1/query-schema/{entity} برای کلاینت و AI	✅

فاز ۱۳ — کاتالوگ پویا (بلندمدت)

• استخراج خودکار فیلدهای مجاز از metadata مدل/SQLAlchemy یا registry UI
• تست قراردادی: «هر فیلد UI در گرید → در catalog AI»

---

جریان پیشنهادی برای مدل (بعد از فاز ۱۰)

کاربر: «فاکتورهای فروش بالای ۵ میلیون از تهران»
    ↓
۱. list_queryable_fields(entity=invoice)  [اختیاری اگر مطمئن نیست]
    ↓
۲. query_business_data(
     entity=invoice,
     filters=[
       {"property":"document_type","operator":"=","value":"invoice_sales"},
       {"property":"total_amount","operator":">=","value":5000000}
     ],
     search="تهران",
     search_fields=["description","extra_info"]
   )

یا برای اشخاص:

filters=[
  {"property":"person_types","operator":"*","value":"customer"},
  {"property":"balance","operator":">","value":0}
]

---

محدودیت‌ها و نکات

1. ناهمگونی سرویس‌ها: همه entityها از QueryBuilder یکسان استفاده نمی‌کنند؛ person_service منطق اختصاصی دارد؛ document_repository فقط برخی propertyها را در filters می‌شناسد. کاتالوگ AI باید فقط فیلدهای تأییدشده را نشان دهد.
2. فیلدهای مجازی: مثل project_name روی سند — در DB project_id است؛ catalog باید alias را مستند کند.
3. امنیت: اعتبارسنجی property در برابر whitelist (جلوگیری از فیلتر روی ستون‌های حساس).
4. حجم: سقف تعداد filters (مثلاً ۱۰) و take (۲۰۰ در AI).

---

معیار پذیرش

• مدل بتواند با query_business_data فاکتوری با total_amount >= X پیدا کند (در entityهای پشتیبانی‌شده).
• list_queryable_fields برای حداقل ۶ entity پرکاربرد فیلد برگرداند.
• Prompt سیستم به صراحت به filters و عملگرها اشاره کند.
• مستندات اجرایی در AI_EXECUTION_PHASES.md به‌روز شود.

---

فایل‌های مرتبط

موضوع	مسیر
Schema	adapters/api/v1/schemas.py → FilterItem, QueryInfo
Query builder	app/services/query_service.py
AI query	app/services/ai/ai_query_service.py
کاتالوگ فاز ۱۰	app/services/ai/ai_query_filter_catalog.py
نرمال‌ساز	app/services/ai/ai_query_filter_service.py