docs: record operational view model task 2

2026-09-22 17:37:46 -03:00
parent d72971047b
commit 34744ac75a
1 changed files with 78 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Task 2 Report: Bounded Operational Query View-Models
+
+## Status
+
+Implemented Task 2 only. The control-plane query layer now supplies bounded operational view-models while preserving the existing JSON keys and technical health derivation. No fiscal logic, database schema, Firebird access, or remote write capability was changed.
+
+## RED Evidence
+
+Added `central/tests/test_operational_view_models.py` before changing production code.
+
+Command:
+
+```text
+python -m pytest central/tests/test_operational_view_models.py -q
+```
+
+Result before implementation: `6 failed`.
+
+The failures were the expected missing-contract failures: `dashboard_summary` did not accept `now`, `list_installations` did not accept `sort`, `list_jobs` did not accept `client`, `list_blockers` did not accept `client`, and `blocker_detail` did not exist. This confirmed the tests exercised the new behavior rather than existing behavior.
+
+## GREEN Evidence
+
+Focused Task 2 tests:
+
+```text
+python -m pytest central/tests/test_operational_view_models.py -q
+```
+
+Result: `6 passed`.
+
+Focused compatibility tests:
+
+```text
+python -m pytest central/tests/test_operational_view_models.py central/tests/test_control_plane.py central/tests/test_jobs.py -q
+```
+
+Result: `21 passed`.
+
+Central regression suite:
+
+```text
+python -m pytest central/tests -q
+```
+
+Result: `248 passed, 1 warning`.
+
+The warning is the pre-existing `openpyxl` print-area warning from `central/tests/test_bootstrap_v1_extra.py`. The pytest environment also emits the existing `pytest-asyncio` fixture-loop-scope deprecation warning.
+
+Additional verification:
+
+```text
+git diff --check
+```
+
+Result: no whitespace errors. Git reported only its existing LF/CRLF normalization notice for the edited Python files.
+
+## Changed Files
+
+- `central/app/control_plane.py`: added bounded dashboard aggregates and attention items; enriched installation, job, and blocker view-models; added filters, stable pagination, worst-coverage sorting, presentation fields, and bounded blocker detail relations.
+- `central/tests/test_operational_view_models.py`: added focused TDD coverage for health reconciliation, distinct safe-blocked products, attention ordering/cap, fiscal/technical separation, job identity/duration, blocker filters/priorities, and detail relations.
+
+## Contract Notes
+
+- Dashboard health counts preserve lowercase compatibility keys and add uppercase `health_counts`.
+- `safe_blocked_products` counts distinct active `(tenant_id, product_code)` pairs; `open_blockers` counts active rows.
+- Safe fiscal blockers do not alter `technical_health`.
+- API timestamps remain ISO UTC values; presentation fields use Task 1 helpers.
+- Collection queries use joins/aggregates. Blocker detail related events, jobs, and audit rows are bounded and bulk-loaded.
+- Existing `resolved` behavior remains supported while `status` adds explicit `OPEN`, `RESOLVED`, and `ALL` handling.
+
+## Commit
+
+Implementation commit: `d729710` (`feat: add bounded operational view models`).
+
+## Concerns
+
+- `BlockedProduct` has no persisted installation foreign key. Blocker list/detail identity therefore uses the lowest-ID installation for the tenant as the representative context; agent and installation filters check tenant installation membership without duplicating blocker rows.
+- The existing non-failing pytest environment warnings remain as noted above.