71 lines
4.6 KiB
Markdown
71 lines
4.6 KiB
Markdown
# 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) در دسترس است.
|