# Control Panel Final Pre-Deploy Fixes V1 Implementation Plan

> **For agentic workers:** Execute inline; the operator mission authorizes autonomous completion. Steps use checkbox syntax for tracking.

**Goal:** Reconcile fiscal coverage counts, correct the fixture gap, and apply the narrowly scoped login/Agent-list/Agent-detail presentation fixes before deploy freeze.

**Architecture:** Preserve the FastAPI/Jinja2/CSS/vanilla-JS panel and fiscal/Agent behavior. Add a derived, explicitly named `unclassified_products` residual from snapshot coverage, expose a consistency flag for over-counted categories, correct only fixture counts that are known synthetic gaps, and make requested UI-only changes.

**Tech Stack:** Python 3.12, FastAPI, Jinja2, SQLAlchemy, CSS, pytest, Docker Compose local runtime.

## Global Constraints

- Do not deploy, alter fiscal engine/requiredness, call AI, enable Firebird writes, change architecture, add SPA, modify Proxmox, or integrate GTI Gerenciador.
- A product coverage state is counted at installation/snapshot grain; existing distinct blocker registry totals remain separately labeled.
- Define `UNCLASSIFIED = TOTAL - COMPLETE - SAFE_BLOCKED - FAILED_PRODUCTS` only when nonnegative; show an inconsistency warning and fail `coverage_invariant_pass` when the explicit categories exceed total.
- Do not use an unexplained generic “other” label; the residual is “Não classificados (sem estado informado)” and documentation says precisely that snapshot telemetry did not assign a known state.
- Keep Agent percentage and technical IDs in detail/API; remove UUID only from the main Agents table.
- Do not modify Firebird databases or run fixture generation against production/client data.

---

### Task 1: Prove coverage gap and add view-model/UI tests

**Files:**
- Modify `central/tests/test_operational_view_models.py`
- Modify `central/tests/test_control_panel_fixture.py`
- Modify `central/tests/test_control_panel_pages.py`
- Add focused assertions to `central/tests/test_control_plane.py` only if needed.

- [ ] Test coverage partition arithmetic for normal, residual, and over-counted snapshots.
- [ ] Test dashboard sums total/complete/snapshot-safe-blocked/failed and explicit residual; require nonnegative invariant pass only when components do not exceed total.
- [ ] Test Agent detail/list expose explicit residual and the fiscal percentage.
- [ ] Test fixture total equals complete + safe-blocked + failed + residual; assert fixture residual zero after correction.
- [ ] Test login form labels/container, Agent list does not contain technical UUID, detail shows missing fields as `Não informado`/`Desconhecida`, and no empty green anchor/button exists in company card.
- [ ] Run targeted tests and capture expected failures before implementation.

### Task 2: Implement reconciled coverage view-models and fixture

**Files:**
- Modify `central/app/control_plane.py`
- Modify `central/scripts/generate_control_panel_fixture.py`
- Modify dashboard, Agent list, and Agent detail templates.

**Interfaces:**
- Add a single helper returning `complete`, `safe_blocked`, `failed`, `unclassified`, `total`, `consistent`, and `overcount` for a snapshot.
- Agent view adds `unclassified_products`, `coverage_invariant_pass`, `coverage_overcount_products`.
- Dashboard returns `safe_blocked_coverage_products`, `unclassified_products`, `coverage_invariant_pass`, and `coverage_overcount_products`; retain registry `safe_blocked_products` as a separately labeled blocker metric if displayed.

- [ ] Implement arithmetic with explicit consistency behavior; do not clamp or silently hide over-count.
- [ ] Dashboard SQL aggregate sums snapshot fields and computes residual at presentation/query aggregation without loading products.
- [ ] Fixture sets complete to `total - safe_blocked - failed_products`; set coverage percentage from complete/total rounded one decimal.
- [ ] Add template rows/cards for safe-blocked coverage, failed technical products, and unclassified products; display inconsistency warning when needed.
- [ ] Agent list explains the remaining percentage beside complete/blocked/failed/unclassified counts.
- [ ] Run targeted model/fixture/page tests green.

### Task 3: Minimal visual fixes and technical missing values

**Files:**
- Modify `central/templates/login.html`
- Modify `central/templates/agents.html`
- Modify `central/templates/agent_detail.html`
- Modify `central/static/control-panel.css`
- Modify `central/tests/test_control_panel_pages.py`

- [ ] Add a login wrapper/card sizing and center layout, explicit `for`/`id` labels, spacing, responsive width, and existing accent colors.
- [ ] Remove the installation UUID secondary text from the Agents table; retain it in detail technical IDs/API.
- [ ] Replace empty/unknown technical displays with `Não informado` and `Desconhecida`; do not invent Firebird version/ODS or version drift.
- [ ] Investigate green empty control: confirm rendered anchor is a real reprocess link with visible text; if visually empty due styles, correct styles; if action absent, remove element. Add assertion for non-empty accessible name/text.
- [ ] Run focused page tests green.

### Task 4: Documentation and final verification

**Files:**
- Modify `docs/CONTROL_PANEL_V1.md` and/or `docs/CONTROL_PANEL_OPERATIONAL_UX_V1.md` only if required to define the residual precisely.

- [ ] Document that unclassified is the snapshot residual without a supplied operational state, not a fiscal rule.
- [ ] Run exactly `python -m pytest tests -q`, `python -m pytest central/tests -q`, and `python -m pytest agent/tests -q`.
- [ ] Rebuild only local Compose `fiscal-hub`; verify PostgreSQL healthy and Hub `/health` 200.
- [ ] Smoke `/login`, `/`, `/agents`, `/agents/{id}`; check coverage reconciliation, login, UUID removal, visible reprocess control, and missing technical values.
- [ ] Measure route latency and record maximum.
- [ ] Verify flags, no deploy/Firebird operations, diff check, commits, and clean worktree; report exact requested final fields.