آرکان — وب‌سایت + چت‌بات RAG + CRM

وب‌سایت رسمی آرکان (مشاور استراتژی و رشد کسب‌وکار) به‌علاوه‌ی یک چت‌بات هوشمند با معماری RAG و چندکاناله. این مخزن فاز دوم پروژه است و شامل تمام محتوای فاز اول (وب‌سایت کامل) + چت‌بات می‌شود.

• 🌐 دموی زنده: arkan-website-chatbot.vercel.app
• 💬 صفحه‌ی چت: /consultant · ویجت روی صفحه‌ی اصلی · بات تلگرام @arkanchat_bot
• 🛠️ پنل مدیریت: /admin
• فاز ۱ (فقط وب‌سایت): github.com/siavash-smf/arkan-website

---

🎓 برای دانشجویان — این پروژه با پرامپت ساخته شده

این چت‌بات با کمک دستیار هوش مصنوعی (Claude Code) و دقیقاً همان پرامپتی که اینجا گذاشته‌ام ساخته شده است. همه‌چیز را قرار داده‌ام تا بتوانید بخوانید، یاد بگیرید و خودتان بازسازی کنید:

۱) پرامپت ساخت چت‌بات

📄 پرامپت استفاده شده / arkan-chatbot-claude-code-prompt.md

این همان پرامپتی است که برای ساخت کل چت‌بات (مغز RAG، سه کانال، پنل مدیریت) به Claude Code داده شد. کافی است آن را همراه اسناد مرجع به دستیار بدهید تا پروژه‌ی مشابه را بسازد.

۱ب) پرامپت‌های فاز ۱ و ۴ (وب‌سایت و CRM)

📄 arkan-website-claude-code-prompt.md — ساخت وب‌سایت شرکتی (فاز ۱) 📄 arkan-crm-claude-code-prompt.md — ساخت CRM کامل با پروپوزال و قرارداد (فاز ۴)

کل این اپ با این سه پرامپت ساخته شده؛ به ترتیب بدهید: وب‌سایت ← چت‌بات ← CRM. راهنمای کامل راه‌اندازی از صفر در README ریپوی arkan-crm است.

۲) فایل System Prompt چت‌بات

📄 arkan-chatbot-system-prompt.md

این فایل، system prompt پایه‌ی چت‌بات است (شخصیت، لحن، قوانین رفتاری و تفاوت‌های هر کانال). می‌توانید بخوانیدش تا ببینید رفتار بات چطور کنترل می‌شود. در عمل، این متن در جدول prompt_versions ذخیره می‌شود و از پنل مدیریت → پرسونا قابل ویرایش و نسخه‌بندی است.

۳) اسناد مرجع و داده‌ها

• 📁 اطلاعات و برند گاید شرکت/ — بریف کسب‌وکار و برند گاید (مبنای محتوا و لحن).
• 📁 knowledge-base/ — داده‌های واقعی شرکت در فرمت‌های گوناگون (md/yaml/csv/json/…) که با manifest.json به سیستم RAG تزریق می‌شوند.

۴) راهنمای ارزیابی چت‌بات (مرجع آموزشی)

• 📄 arkan-chatbot-evaluation-guide.md — چطور کیفیت یک چت‌بات RAG را اصولی بسنجیم.
• 📄 arkan-chatbot-test-set.md — مجموعه‌ی آزمون «خط‌کش» (Golden Set).
• 📄 arkan-chatbot-evaluation-report-template.md — قالب گزارش ارزیابی.

💡 چطور استفاده کنید: اسناد مرجع و knowledge-base/ را با اطلاعات کسب‌وکار خودتان جایگزین کنید، سپس پرامپت ساخت چت‌بات را به دستیار بدهید. خروجی را با همین مخزن مقایسه کنید.

---

معماری: «یک مغز، چند کانال»

یک هسته‌ی مرکزی همه‌ی منطق گفتگو، RAG و تماس با مدل را مدیریت می‌کند؛ کانال‌ها فقط لایه‌ی ورودی/نمایش‌اند.

src/lib/rag/            ← مغز مرکزی (مستقل از کانال)
  config.ts             پیکربندی مدل/embedding/پرسونا از دیتابیس
  embeddings.ts         تبدیل متن به بردار (Cohere چندزبانه)
  chunking.ts           قطعه‌بندی متن
  ingest.ts             استخراج متن چندفرمتی + ذخیره در pgvector
  retrieve.ts           جست‌وجوی برداری + citations
  generate.ts           تولید استریمی از طریق OpenRouter
  chat.ts               ارکستریتور (handleChatTurn / getReplyText) + ابزارها
  policy.ts             محافظ تزریق پرامپت، ماسک اطلاعات تماس، ساعات کاری
  ratelimit.ts          سقف نرخ پایدار (شمارش در دیتابیس، نه در حافظه)
  summarize.ts          خلاصه‌ی خودکار گفتگو
  analytics.ts          آمار داشبورد

کانال‌ها:
  src/app/consultant/   صفحه‌ی چت تمام‌صفحه (استریمی)
  public/widget.js + src/app/widget/   ویجت قابل‌جاسازی روی هر سایت
  src/app/api/telegram/webhook/         کانال تلگرام

استک فنی

• Next.js 14 (App Router) + TypeScript + Tailwind (RTL کامل)
• Supabase + pgvector برای ذخیره و جست‌وجوی برداری (مشترک با وب‌سایت)
• OpenRouter برای تولید پاسخ (یک کلید، همه‌ی مدل‌ها — پیش‌فرض Gemini 3.5 Flash، استریمی)
• Cohere embed-multilingual-v3.0 برای embedding چندزبانه (۱۰۲۴ بعدی)
• Telegram Bot API با Webhook
• آماده‌ی استقرار روی Vercel

پنل مدیریت (/admin)

ناوبری گروهی: داشبورد · CRM · چت‌بات (گفتگوها، پایگاه دانش، مدل‌ها، پرسونا، پلی‌گراند، بازخورد، سؤال‌های بی‌پاسخ) · تنظیمات (تنظیمات چت‌بات، ویجت، تلگرام، کاربران).

قابلیت‌های عملیاتی چت‌بات

این‌ها همان چیزهایی‌اند که یک چت‌بات «کار می‌کند» را از یک دموی کلاسی جدا می‌کنند. همه از پنل قابل تنظیم‌اند و در هر سه کانال اعمال می‌شوند.

قابلیت	کجا تنظیم می‌شود	چه مشکلی را حل می‌کند
پیکربندی مدل به‌ازای هر کانال	/admin/models (تب وب/ویجت/تلگرام)	ویجت معمولاً پاسخ کوتاه‌تر و ارزان‌تر می‌خواهد؛ صفحه‌ی چت پاسخ کامل‌تر
سقف نرخ پایدار	/admin/settings	شمارنده‌ی درون‌حافظه‌ای روی سرورلس بی‌اثر است — هر درخواست به instance دیگری می‌رسد. شمارش با تابع bump_rate_limit در دیتابیس انجام می‌شود
سقف پیام هر گفتگو	/admin/settings	جلوی نشست‌های بی‌پایان و پرامپت متورم را می‌گیرد
تحویل به انسان	/admin/settings + /admin/conversations	مدل ابزار request_human دارد؛ گفتگو با وضعیت «نیازمند انسان» علامت می‌خورد، خلاصه‌اش ساخته می‌شود و در پنل فیلتر دارد
سؤال‌های پیشنهادی	/admin/widget	مهم‌ترین اهرم شروع‌شدن گفتگو؛ مشترک بین ویجت و صفحه‌ی چت
سؤال‌های بی‌پاسخ	/admin/gaps	هر سؤالی که بازیابی برایش منبع مرتبطی پیدا نکرد ثبت می‌شود — این فهرستِ کارِ پایگاه دانش است
Reranker	/admin/models	جست‌وجوی برداری «شبیه‌ترین» را می‌آورد، نه «مرتبط‌ترین»؛ سه برابر top_k بازیابی می‌شود و Cohere Rerank دوباره مرتب می‌کند
خلاصه‌ی خودکار گفتگو	/admin/settings	با مدل fallback (ارزان‌تر) هر N پیام یک‌بار؛ در لیست گفتگوها و CRM دیده می‌شود
محافظ تزریق پرامپت	/admin/settings	تلاش برای بیرون‌کشیدن system prompt قبل از فراخوانی مدل رد می‌شود — هم امن‌تر، هم بدون هزینه‌ی توکن
ماسک اطلاعات تماس	/admin/settings	شماره و ایمیل در لاگ‌ها و جدول سؤالات بی‌پاسخ ماسک می‌شوند (متن گفتگو دست‌نخورده می‌ماند چون capture_lead به شماره‌ی واقعی نیاز دارد)
ساعات کاری	/admin/settings	خارج از بازه، ربات همچنان پاسخ می‌دهد ولی انتظار کاربر را درست تنظیم می‌کند (ساعت تهران، هفته‌ی ایرانی)

در سمت کاربر هم: دکمه‌ی توقف پاسخ (با AbortController)، گفتگوی جدید، کپی پاسخ، و بازخورد 👎 که دلیل می‌پرسد — در هر دو کانال وب و ویجت.

🎓 نکته‌ی آموزشی — باگی که ارزیابی فاز ۵ پیدا کرد: مقدار max_tokens روی ۸۰۰ بود و پاسخ‌ها وسط جمله قطع می‌شدند. علت: مدل‌های reasoning بخشی از همین بودجه را صرف استدلال می‌کنند و چون این مقدار متغیر است، طول پاسخ هم غیرقطعی می‌شود. مقدار امن ۲۰۰۰ به بالا است. درس کلی: عددی که در دمو کار می‌کند لزوماً در تولید کار نمی‌کند؛ باید سنجیده شود.

ماژول CRM (فاز ۴)

CRM کامل بر پایه‌ی جریان کلاسیک Lead → Convert → Contact/Company/Deal (الگوی Salesforce/HubSpot):

• لیدها — صف ورودی از فرم سایت و چت‌بات (دست‌نخورده) + دکمه‌ی «تبدیل به مخاطب» + ✨ امتیازدهی AI (۰–۱۰۰ با توضیح)
• مخاطبان — پروفایل با نمای ۳۶۰ درجه: تایم‌لاین یکپارچه‌ی ثبت لید، گفتگوی چت‌بات، فعالیت‌ها و تغییر مراحل + ✨ خلاصه‌سازی AI گفتگو (نیازها/دغدغه‌ها/سیگنال خرید)
• شرکت‌ها — ساخت خودکار از نام کسب‌وکار لید هنگام تبدیل
• معاملات — برد کانبان با درگ‌انددراپ بومی (بدون کتابخانه)، مراحل config-driven از جدول pipeline_stages، مبلغ به تومان، برد/باخت خودکار + ✨ پیشنهاد اقدام بعدی AI
• فعالیت‌ها — تماس/جلسه/یادداشت/وظیفه با سررسید و هایلایت «معوق»
• گزارش‌ها — قیف تبدیل، ارزش پایپ‌لاین به تفکیک مرحله، منابع لید، درآمد ماهانه (تقویم فارسی)
• پروپوزال‌ها — پیشنهاد همکاری از ۵ قالب خدمات آرکان (دستی یا از روی مخاطب)، پیش‌نمایش زنده‌ی A4، دانلود PDF، ارسال با ایمیل (PDF پیوست)، انتخاب بسته و تأیید/درخواست تغییر کلاینت در /proposal/[token]، تبدیل به قرارداد
• قراردادها — قرارداد ۱۳ ماده‌ای آرکان (پیش‌پر از پروپوزال)، پیش‌نمایش A4 و PDF، ارسال با ایمیل، تأیید آنلاین کلاینت با نام/زمان/IP و ایمیل خودکار نسخه‌ی تأییدشده. PDF در مرورگر ساخته می‌شود (jsPDF + html2canvas-pro). جزئیات در README ریپوی arkan-crm
• کاربران و لاگ — احراز هویت چندکاربره (ایمیل + رمز scrypt، بدون کتابخانه‌ی اضافه) با نقش‌های owner/admin/editor/operator/viewer (بیننده فقط‌خواندنی) + audit log همه‌ی عملیات

راه‌اندازی چندکاربره: تا وقتی کاربری نساخته‌اید، ورود با همان ADMIN_PASSWORD قدیمی کار می‌کند؛ از صفحه‌ی ورود «ایجاد اولین حساب مالک» را بزنید (رمز فعلی = کد راه‌اندازی). پس از آن ورود فقط با ایمیل و رمز است.

نکته‌ی امنیتی (نکته‌ی آموزشی خوب برای کلاس): نشست‌ها کوکی امضاشده‌ی stateless هستند (۳۰ روز). یعنی (۱) بعد از ساخت اولین مالک، ADMIN_SESSION_SECRET را به مقداری مستقل از ADMIN_PASSWORD تنظیم/چرخش دهید تا کوکی‌های قدیمی تک‌کاربره باطل شوند؛ (۲) غیرفعال‌کردن یا تغییر نقش کاربر روی نشست‌های صادرشده‌ی قبلی تا انقضایشان اثر ندارد — برای ابطال فوری، ADMIN_SESSION_SECRET را عوض کنید (همه logout می‌شوند). راه‌حل صنعتی‌تر (بررسی نشست در DB در هر درخواست) تمرین خوبی برای هفته‌های بعد است.

---

راه‌اندازی

npm install
cp .env.local.example .env.local   # سپس کلیدها را وارد کنید
npm run dev

متغیرهای محیطی (.env.local)

NEXT_PUBLIC_SUPABASE_URL= / SUPABASE_SERVICE_ROLE_KEY=   # دیتابیس
ADMIN_PASSWORD= / ADMIN_SESSION_SECRET=                  # ورود پنل
OPENROUTER_API_KEY=                                      # تولید پاسخ
COHERE_API_KEY= (+ EMBEDDING_PROVIDER/MODEL)             # embedding
TELEGRAM_BOT_TOKEN= / TELEGRAM_WEBHOOK_SECRET=           # کانال تلگرام
RESEND_API_KEY= / RESEND_FROM=                           # ایمیل کمپین، پروپوزال و قرارداد (دامنه‌ی تأییدشده در Resend)
CRM_NOTIFY_EMAIL=                                        # (اختیاری) اعلان پاسخ کلاینت و نسخه‌ی تأییدشده

پایگاه داده (در SQL Editor سوپابیس اجرا کنید — به همین ترتیب)

0. supabase/00-arkan-schema.sql — ساخت اسکیمای arkan و دسترسی service_role (بعدش در Project Settings → Data API → Exposed schemas، arkan را اضافه کنید)
1. supabase/schema.sql — جدول leads
2. supabase/chatbot-schema.sql — pgvector + جداول چت‌بات + match_chunks
3. supabase/widget-schema.sql — پیکربندی ویجت
4. supabase/crm-schema.sql — CRM: شرکت‌ها، مخاطبان، مراحل پایپ‌لاین، معاملات، فعالیت‌ها + فعال‌سازی admin_users/audit_log
5. supabase/contracts-schema.sql — قراردادها + توکن عمومی
6. supabase/campaigns-schema.sql — کمپین‌های ایمیلی
7. supabase/chatbot-upgrade.sql — قابلیت‌های عملیاتی: chat_settings، unanswered_questions، rate_limits + تابع bump_rate_limit، ستون‌های تحویل به انسان، سؤال‌های پیشنهادی، و اصلاح max_tokens به ۲۰۰۰
8. supabase/proposals-schema.sql — پروپوزال‌ها و گفت‌وگوی کلاینت + ستون‌های تازه‌ی قرارداد (اسکیمای arkan، با grant صریح برای service_role)

⚠️ اسکیما: همه‌ی جدول‌ها در اسکیمای arkan هستند نه public (دیتابیس می‌تواند با پروژه‌های دیگر مشترک باشد). کلاینت اپ و اسکریپت‌ها با db: { schema: "arkan" } ساخته می‌شوند و همه‌ی فایل‌های SQL هم با همین اسکیما نوشته شده‌اند. در SQL Editor جلوی نام جدول‌ها arkan. بگذارید؛ کوئری روی public.conversations خطای «relation does not exist» می‌دهد.

بارگذاری پایگاه دانش

node scripts/ingest-kb.mjs   # اسناد knowledge-base را با Cohere ایندکس می‌کند

نصب ویجت روی هر سایت

<script src="https://arkan-website-chatbot.vercel.app/widget.js" async></script>

---

© آرکان — مشاور استراتژی و رشد کسب‌وکار · ساخته‌شده با Next.js و Claude Code