# Known Issues & Technical Backlog

## v1.7.1 performance residuals

- Normal callback UI still has a two-Telegram-call network floor: ACK + edit.
- Real latency varies with Telegram RTT, LiteSpeed/PHP worker scheduling and DB distance; local perf numbers are not host SLA.
- Completion with multiple result media necessarily performs multiple Telegram calls.
- OPcache may briefly serve old bytecode after deploy; verify `/admin` and `/start` on host.
- `perf_trace` adds one compact file write per traced request and must remain off outside measurement windows.

Verified fixed in v1.7.1: blocking transition sleep, extra analysis edit, late option/admin ACK, idle admin cleanup queries, repeated same-request user lookup.

## v1.6.1 residual limits

- Very large databases are memory-bounded during restore but can still exceed shared-host execution-time limits; keep frequent off-host backups.
- Imported Telegram `file_id` values are portable only within the same bot; cross-bot imports may need media re-upload.
- Rare shared-host OPcache configurations can briefly serve old bytecode after file copy; `/admin` and `/start` verification is mandatory after update.

## v1.6.0 residual limits

- Telegram has no CSS/multi-line button sizing API; v1.6.0 intentionally places full option copy in the message and uses short numeric inline buttons.
- Reminder precision is bounded by the cPanel cron frequency; a 10-second delay is exact only when the worker is invoked after that point.
- Secondary uploads currently support text, Telegram voice, and document, matching the update parser's supported media fields; photo can be added only after a dedicated photo accessor/storage path is implemented.
- Code swap is filesystem best-effort rather than an atomic directory rename on shared hosts; backups, per-file non-destructive copy, terminal status, and downgrade are the mitigations.

This document lists the currently known technical limitations, fragile areas, and residual risks in the **TFB Engine** codebase.

---

## 1. Verified & Handled Hotfixes (1.4.2 Release)

These major fragile areas have been successfully fixed and verified in the current release:

### A. Non-Member Broadcast Audience Selection (FIXED)
* **Old Bug:** Choosing "Send to non-members" included everyone because the SQL `u.main_channel_status != 'member'` evaluated to NULL (and thus false) for users with a default NULL status.
* **Fix:** The query now uses `(u.main_channel_status IS NULL OR u.main_channel_status != 'member')`, correctly including all non-members.

### B. Campaign Details "() and Campaign Not Found" (FIXED)
* **Old Bug:** `CampaignService::listActive` returned arrays but `AdminCampaignController::showList` tried to access values as object properties (e.g. `$campaign->title`), resulting in blank titles and missing IDs in button callbacks.
* **Fix:** Accessors converted to array syntax (`$campaign['title']`), fully restoring campaign views, stats, and test-binding.

### C. Profile Scoring Keyboard Spam (FIXED)
* **Old Bug:** Opening profile scoring sent a new message and left previous control buttons active and clickable in the chat history.
* **Fix:** Scoring keyboards now render directly on the **workspace message only**, and committing or cancelling scores redirects the admin immediately back to the option details with a clear, top-anchored notice.

### D. Dirty Admin Chats (FIXED)
* **Old Bug:** Admin chats became littered with stale "Enter title..." prompts and admin inputs.
* **Fix:** A centralized cleanup routine (`cleanupTemps`) deletes all prompt messages in `prompt_ids` and deletes user inputs upon transition.

### E. Bot Silent with .htaccess Active (FIXED)
* **Old Bug:** The root `.htaccess` used an unconditional `Require all denied` which recursively blocked all incoming webhook traffic to `/public/index.php` on hosts where the DocumentRoot was set to the project root.
* **Fix:** Rewrote `.htaccess` with smart, layered rules that rewrite requests to `/public/index.php` while maintaining strict security checks for sensitive system files and folders, and added `Require all granted` at the top of `/public/.htaccess`.

---

## 2. Residual Risks & Backlog (Technical Debt)

### A. Telegram Channel Member Updates (`chat_member` Webhook)
* **Risk:** The bot relies on receiving `chat_member` updates from Telegram to update database membership statuses and record unique joins.
* **Caveat:** For this to work, the bot MUST be added as an **administrator** of the channel with permission to invite/manage members. If the operator removes the bot's admin permissions, or if Telegram drops webhook updates under high load, the local DB membership state may become stale.
* **Mitigation:** The "Rebuild Stats" tool in the backup/health screen can re-aggregate counts, and a future phase can add an optional, rate-limited background membership sync job.

### B. CTA Click-Tracking
* **Risk:** The CTA button currently redirects students directly to the target URL. The event `AnalyticsEvents::CTA_CLICKED` remains defined-but-unwritten because no tracking redirect endpoint exists in the public runtime yet.
* **Backlog:** A simple HTTP redirect endpoint (e.g. `public/redirect.php?url=...`) can be added in a future phase to write the click event to the database before redirecting.

### C. Large-Scale Broadcast Progress-Edit Rate Limits
* **Risk:** During a massive broadcast, Telegram's API can rate-limit message-editing if the progress message is edited too frequently.
* **Mitigation:** We've throttled progress updates using `broadcast_progress_every` (default 5). If sending to extremely large lists, keep this value at `10` or higher to stay well within limits.

### D. Multi-Admin Workspace Collisions
* **Risk:** If multiple admins navigate the bot concurrently, they will have their own workspaces since `admin_workspace_message_id` is tracked *per user* in the `users` table. This is robust!
* **Caveat:** However, if they are editing the *same* test, they may overwrite each other's changes. Multi-user concurrent edit locking is currently out of scope.