feat(blog): جدول — ستون‌ها قابل تغییر اندازه/افزودن و حذف؛ لینک کپشن تصویر؛ هدینگ‌های نسخه انگلیسی بزرگ‌تر

chatbot/README.md

@@ -33,18 +33,27 @@
   └─ تولید پاسخ فارسی با LLM (قواعد تکیه بر داده + معرفی صفحه مرتبط + پیام جایگزین مشخص)
 ```
 
-ایندکس از محتوای PostgreSQL سایت ساخته می‌شود (`articles` منتشرشده، `projects`، `services`،
-`faqs`، `brand`، `offices`، `investment_models`، `process_steps`، `why_us`، `team`،
-`testimonials`، `timeline`، `story`). متن‌های بلند به قطعات ~۷۰۰ نویسه‌ای هم‌پوشان برش می‌خورند.
+ایندکس از محتوای PostgreSQL سایت ساخته می‌شود (`articles` منتشرشده + پرسش‌وپاسخ‌های
+پایان مقاله، `projects` با مشخصات کامل، `services`، `faqs`، `brand`، `offices`،
+`investment_models`، `process_steps`، `why_us`، `team`، `testimonials`، `timeline`،
+`story`، و متن‌های مدیریت محتوا: `stats`، `hero`، `page_heroes`، `section_headings`،
+`footer`، `before_after`). سطرهای جای‌گاه‌خالی (متن زیر ~۳۰ نویسه) ایندکس نمی‌شوند.
+متن‌های بلند به قطعات ~۷۰۰ نویسه‌ای هم‌پوشان برش می‌خورند.
 
 - **ایندکس برداری در pgvector**: جدول `chatbot_chunks` در دیتابیس اختصاصی
   `aramesh_chatbot` (روی همان نمونه Postgres) با ستون `embedding vector(384)` و
-  ایندکس HNSW کسینوسی؛ هر قطعه `doc_id` پایدار و `content_hash` دارد و همگام‌سازی
-  فقط سطرهای جدید/تغییریافته را امبد می‌کند. دیتابیس و جدول در شروع سرویس خودکار ساخته می‌شوند.
+  ایندکس HNSW کسینوسی؛ هر قطعه `doc_id` پایدار (شامل url: `type:url-key:occ:chunk`)
+  و `content_hash` دارد و همگام‌سازی فقط سطرهای جدید/تغییریافته را امبد می‌کند.
+  دیتابیس و جدول در شروع سرویس خودکار ساخته می‌شوند.
+- **تیتر در متن قطعه**: در سندهای تک‌قطعه‌ای که تیترشان در متن نیست (مثلاً نام پروژه)،
+  تیتر به ابتدای متن می‌چسبد تا BM25 و جست‌وجوی معنایی پیدایش کنند.
 - **بازسازی خودکار**: یک حلقهٔ پس‌زمینه هر `INDEX_REFRESH_SECONDS` ثانیه محتوا را چک
   می‌کند و اگر ادمین چیزی را در پنل عوض کرده باشد، فقط تغییرات همگام می‌شود
   (امبد اجباری همه: `POST /chat/reindex`).
 - **ماندگاری گفتگو**: در حافظهٔ همان پروسه (MemorySaver لنگ‌گراف) — با ری‌استارت پاک می‌شود.
+- **گزارش گفتگوها**: هر پاسخ (به‌همراه تعداد سند بازیابی‌شده، تشخیص «پاسخی نبود» و تأخیر)
+  در جدول `chat_logs` همان دیتابیس ذخیره می‌شود تا پرسش‌های بی‌پاسخ — یعنی شکاف‌های
+  دانش — قابل کشف باشند؛ `GET /chat/stats` جمع‌بندی می‌دهد.
 
 ## متغیرهای محیطی (در `.env` ریشه پروژه)
 
@@ -75,15 +84,29 @@
 
 | مسیر | توضیح |
 |---|---|
-| `GET /chat/stream?message=…&thread_id=…` | استریم SSE توکن‌به‌توکن پاسخ (`{"content": …}` و در پایان `{"done": true}`) |
+| `GET /chat/stream?message=…&thread_id=…` | استریم SSE توکن‌به‌توکن پاسخ (`{"content": …}` و در پایان `{"done": true, "fallback": true|false}`) |
 | `GET /chat/suggestions` | ۴ پیشنهاد پرسش (کش ۱۰ دقیقه؛ جایگزین: خود سؤالات متداول) |
-| `GET /chat/eval?message=…` | مخصوص ارزیابی RAGAS — پاسخ + اسناد بازیابی‌شده با thread تازه |
+| `GET /chat/eval?message=…` | مخصوص ارزیابی — پاسخ + اسناد بازیابی‌شده با thread تازه |
+| `GET /chat/stats` | آمار گفتگوها (کل، ۷ روز اخیر، نرخ پیام جایگزین)؛ فهرست پرسش‌های بی‌پاسخ اخیر فقط با هدر `X-Reindex-Token` |
 | `GET /chat/healthz` | وضعیت ایندکس/LLM/تعداد اسناد |
 | `POST /chat/reindex` | بازسازی اجباری ایندکس (هدر `X-Reindex-Token`) |
 
 مسیرهای `GET /chat/{scope}/stream|eval|suggestions` هم برای سازگاری با اسکریپت
 `eval_ragas.py` قدیمی موجود است — کافی است `--url` را به نشانی این سرویس بدهید.
 
+## ارزیابی
+
+مجموعه طلایی `eval_set.json` (پرسش‌های واقعی از محتوای دیتابیس + یک کنترل مثبت برای
+«نباید قیمت بسازد») با `eval_run.py` اجرا می‌شود — داخل کانتینر:
+
+```bash
+docker exec aramesh-site-chatbot-1 python /srv/chatbot/eval_run.py --out /tmp/report.md
+docker exec aramesh-site-chatbot-1 cat /tmp/report.md
+```
+
+خروجی: وضعیت هر پرسش (`pass` / `miss` / `manual` / `fallback-expected` / `unexpected-fallback`)،
+منابع بازیابی‌شده و زمان پاسخ — برای سنجش اثر تغییرات دانش و کشف پسرفت‌ها.
+
 ## اجرا
 
 با داکر (بخشی از استک اصلی است — `docker compose up -d --build`):