kamidso-back/kamidso/native_connectors/providers/didar/guidance.md

Didar Semantic Guidance — compact provider guidance

این فایل برای تزریق کامل به System Prompt نیست. Runtime باید فقط بخش کوتاه و مرتبط را inject کند.

قواعد قطعی

1. وضعیت فعلی معامله فقط از Status خوانده می‌شود:
   • Pending = جاری
   • Won = موفق
   • Lost = ناموفق
2. IsDeleted یک بعد جدا است. حذف‌شده را با Lost یکی نکن.
3. از ChangeToWonTime، PipelineStageId، Probability یا Label برای استنتاج Won/Pending استفاده نکن.
4. Response.List در search_deals فقط صفحه فعلی است. برای شمارش کل از aggregateهای Response مانند WonDealsCount استفاده کن.
5. «فروش در بازه» یعنی معاملات موفق‌شده در آن بازه، نه معاملات ایجادشده در آن بازه.
6. «معاملات ثبت‌شده/ایجادشده در بازه» بر اساس RegisterTime است و وضعیت نمایش‌داده‌شده باید وضعیت فعلی Status باشد.
7. «معاملات موفق در بازه» بر اساس ChangeToWonTime است.
8. «معاملات ناموفق در بازه» بر اساس ChangeToLossTime است.
9. برای نام کاربران OwnerId را با get_users resolve کن؛ قرارداد اتصال را با Golden Test واقعی کنترل کن.
10. برای نام کاریز/مرحله از get_deal_pipelines استفاده کن.

تاریخ

• ورودی فارسی مثل «مهر ۱۴۰۵» را در Asia/Tehran و تقویم جلالی resolve کن.
• بازه را [start, end) نگه دار و سپس به UTC تبدیل کن.
• در پاسخ مدیریتی مبنای تاریخ را صریح کن: «مبنای بازه: تاریخ موفق‌شدن» یا «مبنای بازه: تاریخ ثبت».

پول

• بدون mapping معتبر CurrencyId هرگز اسم واحد پول را حدس نزن.
• مبالغ چند CurrencyId را خام با هم جمع نکن.
• گزارش‌های پنل دیدار از قابلیت چندارزی و ارز مبنا استفاده می‌کنند؛ برابری aggregate API با پنل باید با Golden Reconciliation برای اکانت تأیید شود.
• تا قبل از Reconciliation، FinalAdjustmentPrice فقط انتخاب موقت رکوردی است و نباید به‌عنوان تعریف ابدی «فروش خالص دیدار» hard-code شود.

Lead

• Function مستقلی مثل get_leads یا search_leads وجود ندارد؛ آن را اختراع نکن.
• API فیلدهای lead/contact را در Person/Contact نشان می‌دهد، اما یک فرمول عمومی و قطعی برای «تعداد لیدها» در مستندات عمومی تعریف نشده.
• lead_count تا زمانی که با پنل واقعی حساب reconcile نشده disabled بماند.

Recovery

• اگر raw function validation failed شد، همان function را با schema برگشتی اصلاح کن.
• اگر semantic operation accuracy guard داد، به endpoint دیگری نپر تا فقط عددی تولید شود؛ دلیل عدم قطعیت را حفظ کن.