# دستیار یکپارچهٔ مارکت‌پلیس پلانک

دستیار در همان پروژهٔ مارکت‌پلیس اجرا می‌شود. پنجره و آیکون موجود سایت حفظ شده‌اند و برای استفاده از آن به اجرای پروژهٔ جداگانه یا پورت ۴۱۷۳ نیاز نیست. انتشار عمومی انجام نشده است.

## اجرا در VS Code

پوشهٔ `planck-marketplace` را باز کنید و در ترمینال اجرا کنید:

```sh
npm run dev -- --host 127.0.0.1 --port 3000
```

پیش‌نمایش: `http://localhost:3000/#faq`.

## تنظیم مدل

کلید و مدل در فایل خصوصی و نادیده‌گرفته‌شدهٔ `.env` همین پروژه قرار می‌گیرند:

```dotenv
OPENAI_API_KEY=YOUR_PRIVATE_KEY
OPENAI_MODEL=gpt-4.1-mini
OPENAI_TIMEOUT_MS=15000
```

مقدار کلید را در گفتگو، Git، پوشهٔ عمومی یا متغیرهای `VITE_` و `NEXT_PUBLIC_` قرار ندهید. پس از تغییر تنظیمات، مارکت‌پلیس را بازراه‌اندازی کنید. کلید و مدل قبلی برای توسعهٔ محلی به همین فایل منتقل شده‌اند؛ نمونهٔ عمومی `.env.example` فاقد کلید است.

## منطق و مرجع

- `lib/assistant/engine.mjs`: پاسخ‌گویی، کنترل حریم، جست‌وجوی محلی و اتصال Responses API؛ بدون وابستگی به مسیر Desktop، فایل‌خوانی هنگام درخواست یا سرور جداگانه.
- `lib/assistant/data/public_faq.json`: فقط مرجع عمومی مجاز؛ فیلتر وضعیت `approved` و دامنهٔ پلانک همچنان اعمال می‌شود.
- `lib/assistant/data/assistant.json`: عنوان، خوشامدگویی، سؤال‌های پیشنهادی و تماس عمومی.
- `lib/assistant-service.ts`: کنترل مبدأ، اندازهٔ درخواست، محدودیت تعداد درخواست و مسیرهای وب‌چت.

در حالت مدل، همهٔ گزیده‌های مجاز مرجع کوچک فعلی برای فهم سؤال‌های طبیعی در اختیار مدل قرار می‌گیرند؛ نبود تطابق لفظی باعث حذف سؤال نمی‌شود. تاریخچه فقط زمینهٔ گفتگو است و منبع واقعیت‌های شرکت نیست. شناسه‌های پاسخ مدل در سرور با همان مرجع مجاز کنترل می‌شوند. برچسب «منبع» در رابط نمایش داده نمی‌شود.

چهار پرسش شروع برای خریداران توکن و سرمایه‌گذاران تنظیم شده‌اند: بررسی پیش از خرید، پشتوانه و ریسک، امکان فروش و پیگیری دارایی‌ها. پس از پاسخ، حداکثر سه پرسش مرتبط از مرجع عمومی پیشنهاد می‌شود؛ انتخاب آن‌ها به سؤال فعلی، موضوع پاسخ و زمینهٔ گفتگو بستگی دارد. سؤال‌های اخیر و موضوع پاسخ‌داده‌شده تکرار نمی‌شوند و با تغییر موضوع، پیشنهادها نیز تغییر می‌کنند. این انتخاب در سرور انجام می‌شود و درخواست جداگانه‌ای به مدل اضافه نمی‌کند.

بدون کلید/مدل، پاسخ محلی با `mode: reference` می‌آید. شکست مدل، پاسخ محافظه‌کارانه با `mode: fallback` دارد. فقط `mode: openai` در پاسخ همان درخواست، دریافت پاسخ واقعی مدل را نشان می‌دهد. قبولی آزمون کد به معنی ارزیابی موفق مدل نیست. خطاهای مدل تنها با دسته‌بندی ثابت در گزارش سرور ثبت می‌شوند؛ کلید، متن گفتگو و پاسخ خام خطا ثبت نمی‌شوند.

خطای شبکه یا پاسخ 5xx مدل فقط یک بار و در همان مهلت زمانی دوباره امتحان می‌شود؛ لغو گفتگو، تلاش مجدد را نیز لغو می‌کند. خطای کلید، محدودیت سرویس یا پاسخ نامعتبر تکرار نمی‌شود. محدودیت محلی گفتگو ۳۰ درخواست در دقیقه برای هر نمونهٔ سرور است.

## قرارداد و حریم

- `POST /api/chat`: `{message, history}`؛ پیام حداکثر ۱۵۰۰ نویسه و تاریخچه حداکثر شش پیام `user` یا `assistant`. پاسخ: `{answer, mode, sources, suggestions}`.
- `GET /api/chat/config`: فقط تنظیمات عمومی گفتگو.
- `POST /api/assistant`: نام جایگزین همان مسیر گفتگو.
- هیچ کوکی حساب، شناسه کاربر، موجودی، مدرک یا توکن ورود به مدل ارسال نمی‌شود. کلید فقط برای احراز سرور به OpenAI استفاده می‌شود.
- دستیار به حساب، پرداخت و تیکت دسترسی عملیاتی ندارد. دکمهٔ تیکت سایت مسیر مستقل و نیازمند ورود دارد.
- تاریخچه موقت است و با گفتگوی تازه پاک می‌شود. دانش کامل، گزارش‌های داخلی و Word به این پروژه منتقل نشده‌اند. مرجع عمومی در گراف واردات سرور است، نه در پوشهٔ `public` یا فایل‌های کلاینت.

## بررسی و انتشار بعدی

```sh
node --test tests/assistant-engine.test.mjs tests/assistant-api.test.mjs tests/assistant-chat.test.mjs tests/assistant-suggestions.test.mjs
npm run typecheck
```

آزمون واقعی باید با متوقف‌بودن سرویس قدیمی ۴۱۷۳، از مسیر سایت انجام شود: چهار سؤال پیشنهادی، سؤال ادامه‌دار، تغییر موضوع از خرید توکن به بازار اختصاصی یا شبکه‌ها، و محدودیت‌های اطلاعات حساب/تعرفه. پیشنهادهای مرتبط باید در حالت پاسخ محلی نیز قابل استفاده باشند.

فعلاً فقط localhost است. پیش از انتشار، کلید با سازوکار secrets میزبان تنظیم شود و محدودیت درخواست توزیع‌شده در ورودی قابل اعتماد بررسی شود؛ محدودیت حافظه‌ای فعلی در هر پردازش/نمونه است و در اجرای چندنمونه‌ای سراسری نیست. اتصال کانال‌هایی مثل تلگرام می‌تواند بعداً از همین موتور پاسخ‌گویی استفاده کند.