# Dashboard data contract (no-AI)

All updates use one envelope: `{"event": "<name>", "data": {...}}`.
- **Desktop (PyQt):** Python calls `window.__pyMsg(json)` via `runJavaScript` (see `bridge.py`).
  `bot_runner.py` turns the bot's output lines into `status`, `step` and `log` events, and keeps every raw line in `bot_raw.log`.
- **Web:** the page polls `GET {API_BASE}/dashboard` (returns `dashboard_data`) and
  `GET {API_BASE}/run/status` → `{"running": bool, "events": [envelope, ...]}`. Poll fast (2s) only while running.
- **No bot yet:** with `SAMPLE_DATA = true`, the page answers its own data actions with sample envelopes.

## Bot/backend → page

| event | data |
|---|---|
| `status` | `{state: "ready"\|"running"\|"done"\|"error", msg}` |
| `step` | `{label: <one of STEPS>, pct: 0-100}` |
| `log` | `{msg: <plain English>, type: "info"\|"success"\|"warn"\|"error"}` |
| `dashboard_data` | `{batches: [{batch_id, date, state: "completed"\|"inprogress"\|"notcompleted"\|"cleared", items_total, items_done, ...}]}` |
| `report_data` | `{rows: [{...REPORT_COLUMNS keys, status, bucket: "success"\|"attention"\|"failed"}]}` |
| `set_user` | `{username, emp_id, role}` |
| `apply_dark` | `{on: bool}` |

Optional sections (only if chosen) add `cpstate`, `admin_data` and `login_result`, and the actions `load_admin`, `assign_role`, `remove_role` and `login`. See `sections.md`.

## Page → bot/backend (Qt `@pyqtSlot` names / web `POST {API_BASE}/<slot-with-dashes>`)

`load_dashboard`, `start_automation`, `request_stop`, `load_latest_report`, `download_report`, `set_dark(on)`, `logout`.

## Rules (learned on Tebra)
- Log the raw bot line to a file/DB; show only **friendly** text on screen. Never hide an error line.
- Step markers: match the bot's printed lines by **specific** substring (e.g. `[step 3]`), not a bare word. A bare word matches unrelated lines.
- Derive `state`: Pending + today = `inprogress`; Pending + older day = `notcompleted`.
- Report `bucket`: success = {processed successfully, posted, completed}; failed = {error, failed}; everything else = attention.
- Run the bot in a **separate process** that writes to a log file, and have the UI tail that file. When pywinauto/UIA runs inside a Qt worker thread, its reads are unreliable (Tebra bug-094).