# Product & Behavior Rules (Authoritative)

This document is the single, absolute source of truth for the product behaviors and rules implemented in the **TFB Engine**. Where these rules conflict with older specifications, **these rules win**.

---

## 1. Zero ReplyKeyboardMarkup Policy

To ensure a modern, clean, and highly professional messaging experience:
* **Student Interface:** The student has **no bottom ReplyKeyboard at all** under any circumstances. All test questions and interactive option selections are rendered using **InlineKeyboardMarkup (glass buttons)**.
* **Admin Interface:** The admin panel is completely inline-driven. There is **exactly one** bottom ReplyKeyboard button: `/start` (for easy panel resets). No other bottom keyboard buttons may ever be rendered.
* **Leftover Keyboard Removal:** When entering student flows (test start) or the admin panel, the system actively removes any leftover bottom keyboard using `ReplyKeyboardRemove` and immediately deletes the temporary cleanup message.

---

## 2. No Intro / Description Shown to Students

* After a valid `/start` for an active test, the student goes **directly into the first question**.
* `tests.description`, `intro_image_file_id`, and `intro_voice_file_id` are **never read or sent** by the student runtime.
* `description` remains in the schema purely as an internal admin note displayed on the admin test management screen.

---

## 3. Slugs & Codes are Always Auto-Generated

* **Test Slugs:** Admins never type a test slug. `SlugService` auto-generates a lowercase, sanitized, transliterated slug from the test title.
* **Profile Codes:** Admins only provide a Persian title for a profile. `ProfileCodeGenerator` auto-generates an ASCII unique code within that test.

---

## 4. Question & Option Constraints

* **Questions:** Questions are text-only. Questions have no images or voice prompts in the student runtime, nor is the input offered in the admin builder.
* **Options:** Minimum of 2 options per question. Branching options default to "next question", but can be customized to "end test" or "jump to question ID".

---

## 5. Result Selection & Display Modes

`tests.result_display_mode` (`single` | `dual_on_close`) plus `tests.threshold` (defaulting to `settings.default_dual_threshold`) drive winner selection:

| Display Mode | Behavior |
|---|---|
| `single` | Highest-scoring profile wins. Exact tie for first → **one is picked at random** (random choice logged in metadata). |
| `dual_on_close` | Top-2 profiles compared. Score gap `<= threshold` → **both shown**. Gap `> threshold` → **only top-1 shown**. Exact tie → **both shown**. |

---

## 6. STRICT Result Delivery & CTA Rules (F5 Rule)

Result packages are independent, optional content blocks. No synthetic "placeholder" lines (such as "ویس تحلیل:") are sent.

### Content Ordering
When sending the result package, messages are sent strictly in this order:
1. **Text Analysis:** The results text (description) is sent first.
2. **File Attachments:** Attached files (PDF, Document, Image, Video) are sent second.
3. **Voice Note LAST:** If a voice note is attached, it is sent **strictly last** in the sequence.

### CTA Button Placement Priority
* **Glass Button Only:** The Call-To-Action (CTA) is an inline URL button attached directly to a result message.
* **No Plain-Text CTA:** The CTA button label or link is **never** repeated as plain text inside any message bubble (deleting the old duplicate text bug).
* **Only One CTA Button:** The CTA button appears **only once** on the very last content message of the delivery sequence.
* **Placement Priority Matrix:**
  1. If a **voice note** is sent (since it's last), the CTA inline keyboard is attached to the **voice note message**.
  2. Else, if a **file/document/image** is sent, the CTA inline keyboard is attached to the **file message**.
  3. Else, the CTA inline keyboard is attached to the **text analysis message**.

---

## 7. No Post-Funnel Footers / Spam

* **Silence Policy:** After the result and its CTA are delivered, the bot is **completely silent**.
* **Forbidden Messages:** It is strictly forbidden to send a trailing helper message like "برای استفاده مجدد /start یا /help را بزنید". The student's journey is complete after the CTA.
* **Garbage Input Handling:** If the student types anything after completing the quiz, the bot ignores it or sends a single neutral line, never prompting them to restart.

---

## 8. Unique Starts & Completions (F6 & F8 Rules)

To ensure high-precision analytics:
* Starts, completions, and joins are **unique per Telegram user**.
* If a single user starts/completes a test 10 times, the unique start/completion counts on the dashboard/analytics MUST remain `1`.
* **Abandons Unique (🚪 افت):** Calculated strictly as: distinct users starting a test in the selected range who have **no completions** in that same range.

---

## 9. v1.6.0 locked interaction rules

- Student answers are inline-only. The message body lists every full option as `1) ...`, `2) ...`; buttons contain only the short number and callback to the real option ID. Telegram buttons are not styled with fake CSS or claimed to be multi-line.
- Broadcast CTA buttons are inline URL buttons only and never echo label text into the bot chat.
- Reopening a test/campaign link abandons an incomplete attempt and starts from the beginning; no resume dialog is shown.
- Result order remains text → non-voice file/media → voice last, with one inline CTA and link preview disabled.
- Secondary mode sends only its ordered pack and creates no quiz start/completion metric.
- Test/campaign slugs are current-only. An old slug resolves to the safe invalid-link response, never another/default entity.
- Campaign joins require a genuine membership transition event attributed at that time; current membership alone is not join credit.

## 9.۰ قانون افکت انتقال و عملکرد

- `transition_effect_ms` بازه 0..5000 دارد و مقدار پیش‌فرض 300 است.
- این مقدار نباید به sleep چندثانیه‌ای داخل webhook تبدیل شود؛ تغییر UI سؤال بعدی سطح انتقال فعلی است.
- callbackهای تغییر‌یافته پس از dedupe و احراز مجوز ACK می‌شوند و side effect تکراری ممنوع است.

## 9.۱ قوانین محتوای فرعی نسخه ۱.۷

- فقط یک آزمون secondary می‌تواند روشن باشد.
- bare `/start` ابتدا secondary فعال را بررسی می‌کند و default test مانع آن نیست.
- multistage خاموش فقط دسته ۱؛ روشن یک دسته در هر action.
- ReplyKeyboard دانش‌آموز فقط در secondary و با سه برچسب قفل‌شده مجاز است؛ گزینه‌های quiz همیشه inline هستند.
- secondary هیچ completion آزمون ثبت نمی‌کند.

## 10. "Do Not Reintroduce" List (Regressors)

The following behaviors have been permanently banned and **MUST NEVER** be reintroduced into the codebase:
1. **No Blocking Force-Join Gates:** Showing results or CTA buttons must never be blocked, gated, or delayed by main channel membership checks. Membership is tracked purely for behind-the-scenes campaign conversion statistics.
2. **No Student ReplyKeyboardMarkup:** Students must never answer questions using ReplyKeyboard text buttons. Answering must always use inline glass buttons.
3. **No CTA Text Duplication:** Do not send the CTA button label or link as plain text in a separate bubble.
4. **No Test Intro Screens:** Students must never see test descriptions, intro images, or intro voice notes upon starting.
5. **No Empty Placeholders:** Never send empty or label-only messages like "تحلیل:" when no content is present.