# procurement_ai_agent — ایجنت هوشمند بله برای سامانه ERP

بات پیام‌رسان بله (Bale Messenger Bot) که پیام‌های صوتی و متنی فارسی کاربران را دریافت کرده و با استفاده از مدل‌های هوش مصنوعی (DeepSeek NLU + Whisper STT) آن‌ها را به اقدامات و پیش‌نویس‌های استعلام در سامانه ERP تبدیل می‌کند.

---

## 🏗️ وضعیت استقرار در استک ERP

این ایجنت **به صورت سرویس بومی (`procurement-bot`) مستقیماً درون `docker-compose.yml` ریشه پروژه** تعریف شده است و نیازی به نصب یا راه‌اندازی دستی ندارد.

* **نوع اتصال:** Long-polling از سرور بله (`tapi.bale.ai`) — بدون نیاز به باز کردن پورت خارجی، وب‌هوک یا TLS.
* **ارتباط با بک‌اند:** به صورت مستقیم و درون‌شبکه‌ای با سرویس `api` در آدرس `http://api:8000/api/v1`.
* **پایگاه داده:** استفاده از جدول `bot_drafts` در پایگاه‌داده مشترک PostgreSQL.

```text
کاربر (بله: متن یا صوت) 
         │  getUpdates (Long-polling)
         ▼
┌─────────────────────────────────┐
│     procurement_ai_agent        │
│  ffmpeg → STT تبدیل صوت به متن   │
│  LLM → استخراج نیت و موجودیت‌ها │
│  Fuzzy Match → انطباق با ERP   │
│  ایجاد پیش‌نویس در bot_drafts    │
└────────────────┬────────────────┘
                 │
                 ├── ثبت نهایی از بله با دکمه تایید
                 └── یا باز کردن مستقیم در ویزارد وب:
                     /wizard?draft=<UUID>
```

---

## 🌟 قابلیت‌ها و کاربردها

| فعالیت | نمونه پیام (صوت یا متن) | اقدام نهایی |
|---|---|---|
| **ثبت استعلام جدید** | «سازان نو برای پروژه برج آسمان ۵۰۰ کیلو میلگرد A3 سایز ۱۴، هر کیلو ۴۵ تومن، پرداخت ۳ فاز» | `POST /quotes` |
| **تعریف تأمین‌کننده** | «تأمین‌کننده جدید پروفیل بر، دسته لوله و اتصالات، تلفن ۰۹۱۲…» | `POST /suppliers` |
| **تعریف متریال جدید** | «کالای جدید میلگرد A3 سایز ۱۸ با واحد کیلوگرم» | `POST /materials` |
| **استعلام وضعیت** | «استعلام‌های در انتظار؟» / «کدام‌ها به‌زودی منقضی می‌شوند؟» | `GET /quotes` |
| **پذیرش استعلام** | «استعلام سازان نو را قبول کن» | `PATCH /quotes/{id}/accept` |

---

## 🔗 حلقه پیش‌نویس و تایید (Draft-First Loop)

1. کاربر پیام صوتی یا متنی می‌فرستد. صوت به متن تبدیل شده و مدل هوش مصنوعی موجودیت‌ها را استخراج می‌کند.
2. اسامی تامین‌کننده، متریال، پروژه و واحدها با کاتالوگ ERP تطبیق داده می‌شوند.
3. کارت مرور پیش‌نویس همراه با فیلدهای مشخص‌شده و اقلام خالی («چه چیزهایی ناقص است») برای کاربر ارسال می‌شود.
4. **دو روش برای تکمیل و ثبت نهایی وجود دارد:**
   * **از طریق چت بله:** با ارسال پیام‌های اصلاحی و در نهایت لمس دکمه «✅ ثبت نهایی».
   * **از طریق پنل وب ویزارد:** با کلیک روی لینک مستقیم `/wizard?draft=<UUID>` که اطلاعات به صورت خودکار در فرم ۵ مرحله‌ای ویزارد بارگذاری می‌شود و کاربر می‌تواند فایل فاکتور را نیز ضمیمه کند.

---

## ⚙️ متغیرهای محیطی و پیکربندی

تنظیمات بات از طریق فایل `.env` در ریشه پروژه خوانده می‌شود:

```env
BALE_BOT_TOKEN=توکن_دریافتی_از_بات_فادر_بله
BALE_API_BASE=https://tapi.bale.ai
AI_BASE_URL=https://api.deepseek.com
AI_API_KEY=کلید_سرویس_هوش_مصنوعی
AI_LLM_MODEL=deepseek-flash
BALE_ADMIN_CHAT_IDS=شناسه_عددی_مدیران_در_بله
```

راهنمای گام‌به‌گام اتصال و عیب‌یابی در [docs/SETUP.md](docs/SETUP.md) در دسترس است.