# Project Status & Backlog

**Current State:** TFB v1.7.0 secondary/ops reliability release, full regression verified on 2026-08-17.
**Last Update:** 2026-07-28

---

## 1. Phase & Release Checklist

| Version / Phase | Scope / Focus | Status |
|---|---|---|
| **v1.0.0** | Phase 1 & 2: Skeletal bootstrap & Web Installer | Done |
| **v1.1.0** | Phase 3 & 4: Webhook Pipeline, Middleware, Domain layer | Done |
| **v1.2.0** | Phase 5 & 6: Student quiz loop & Admin Telegram builder | Done |
| **v1.3.0** | Phase 7: Hardened Ops, Diagnostic Logs, Backup/Restore | Done |
| **v1.4.0** | Update Pack: Broadcast, Rotatable Links, Self-cleanup installer | Done |
| **v1.4.3** | Ops htaccess: Smart layered .htaccess security & Integrity Audit | Done |
| **v1.5.0** | Release Lock: Advanced Analytics, Rankings, Tags, Reminders, Duplicate, Back, Transition | Done |
| **v1.6.0** | Clean prompts, inline quiz/broadcast UX, scoped filters, slugs, gate/secondary content, truthful attribution, reminder/update hardening | Done |
| **v1.6.1** | Weak-host stability, JSON test transfer, safe edit recovery, manifest updates, metadata backup and streamed restore | Done |
| **v1.7.0** | Multistage secondary, idempotency/session guards, ops rollback, retention and host locks | Done |
| **v1.7.1** | Transition 0..5000 without webhook sleep; measured callback/ACK/query performance; perf trace | **Done** |

---

## 2. Fully Implemented Capabilities (Now Live)

### Student Funnel (Student UX)
- **Inline Options Only:** Options are rendered as full-width inline buttons. No bottom reply keyboards.
- **Leftover Keyboard Removal:** Tapping start/entering test instantly removes any leftover reply keyboards using `ReplyKeyboardRemove`.
- **In-Place Question Transition:** Answering edits the question message in place smoothly.
- **Bold Questions & Spacers:** Question text is always bold, and a trailing blank line spacer separates question text from options.
- **Best-Effort Wider Bubble:** Short question bubbles are padded with invisible RTL space characters to force a wider, more readable size.
- **Start Gate Toggle:** Add a per-test gate setting. When ON, shows online test details and a `🟥 شروع تست` button before first question.
- **Back Question:** When ON, student sees a `🔙 بازگشت` button on Q2+ that deletes last answer, steps back, and rescores deterministically.
- **Transition Effect:** When ON, tapping an option briefly edits the message to `⏳ در حال تحلیل…` (0.5s usleep) before rendering next question.
- **protect_content Setting:** When enabled, student-facing contents (quiz questions, result packs, reminders) cannot be forwarded or saved.

### Admin Panel (Admin UX)
- **Sticky Workspace Model:** Navigation edits the single sticky workspace message in-place, eliminating menu message spam.
- **Automatic Prompt Cleanup:** Wipes out temporary prompts and admin text/media inputs centrally on successful transitions.
- **Scoring Draft UI:** Live scoring (+/-) edits the workspace in-place. Saving or cancelling commits scores and redirects instantly to the Option view with a top notification.
- **Ranged Campaign Analytics:** Campaign detail metrics (Starts, New Users, Joins) are ranged (`۲۴ ساعت`, `۷ روز`, `۳۰ روز`, `کل`) and edit the workspace on click.
- **Comparative Rankings:** View top-performing tests and campaigns based on completes, CVR, attributed joins, and retention rate, filtered by minimum sample thresholds.
- **User Tags:** Add manual tags to users, view tags on user details, filter/search users by tag, and automatically tag users with winning profile titles upon quiz completion.
- **Targeted Broadcast:** Compose targeted broadcast audiences filtered by test starters, completers, abandoners, profile winners, tags, and combinations.
- **Incomplete Test Reminders:** Schedule exactly one reminder (delay 300s by default, settings-editable) when a test starts, which is automatically cancelled if completed.
- **Duplicate Test:** Tapping "ساخت آزمون مشابه" performs a deep, transaction-safe copy of test settings, profiles, questions, options (with updated jump references!), profile scores, results, and result media.
- **Secure Backup Deletion:** Backups list includes a secure, path-traversal-proof "Delete" button with a confirmation inline menu.

---

## 3. Operations & Hardening

* **Idempotent DB Auto-Migration:** Migrations are additive and fully managed by `Migrator::upgrade()` (v1.5.0), called on fresh install and in-bot update.
* **Smart Layered .htaccess Protection:** Blocks direct public access to system directories (`config/`, `src/`, `storage/`, etc.) and extensions (`.sql`, `.log`, `.bak`, `.env`, `.git`) with `403 Forbidden` but cleanly allows webhook POSTs and health GETs to flow to `/public/index.php`.

---

## 4. v1.6.0 verified behavior

* All admin text/media guides are tracked as a list and removed on save, retry, Back, Cancel, and stage transition.
* Student questions use escaped HTML bold text, numbered full option copy in the message, and short inline callback buttons.
* Linked re-entry abandons the old incomplete attempt and starts fresh; admins may use student deep links.
* Broadcast supports inline URL CTA only; test and profile/tag filters are functional and test-scoped.
* Tests/campaigns support current-only editable slugs; gates and global transition duration are configurable.
* Secondary content can contain multiple text/voice/document items and replaces quiz start while enabled.
* Campaign starts/completes/joins are distinct-user, event-attributed metrics; pre-campaign membership is not credited.
* The bounded reminder worker sends once and skips completed sessions; update/downgrade paths terminate with an explicit status.

## 5. Handoff to Next Agent

If you are picking up this project, please proceed with the following:
- Review the `docs/AGENT_HANDOFF.md` and strictly follow the **Permanent Agent Governance Protocol**.
- Keep all modifications minimal and surgically edit files.
- Before committing any code or packaging a ZIP, run all unit/smoke tests and ensure the status stamp (`docs/STATUS.json`), project status, and changelog are fully updated.