From 304a916890d0479a3d0b80da3e1f5fd6af9131e7 Mon Sep 17 00:00:00 2001 From: gti Date: Tue, 22 Sep 2026 15:05:12 -0300 Subject: [PATCH] docs: specify control panel v1 architecture --- ...9-22-gti-fiscal-control-panel-v1-design.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-22-gti-fiscal-control-panel-v1-design.md diff --git a/docs/superpowers/specs/2026-09-22-gti-fiscal-control-panel-v1-design.md b/docs/superpowers/specs/2026-09-22-gti-fiscal-control-panel-v1-design.md new file mode 100644 index 0000000..b416ccc --- /dev/null +++ b/docs/superpowers/specs/2026-09-22-gti-fiscal-control-panel-v1-design.md @@ -0,0 +1,108 @@ +# GTI Fiscal Control Panel V1 Design + +## Scope + +Build the operational control plane and web panel in the existing FastAPI Hub. +The implementation has two ordered blocks: a backend foundation and a +server-rendered interface. Fiscal decision logic remains unchanged, AI writes +remain disabled, and no remote Firebird write control is exposed. + +## Architecture + +The Hub remains the single application boundary. SQLAlchemy models and Alembic +migrations store installation identity, operational snapshots, structured +events, human administrators, sessions, and audit entries. FastAPI exposes two +strictly separate authentication paths: + +- Agent routes continue using the existing Bearer token principal. +- Human routes use an opaque, expiring HttpOnly cookie backed by a server-side + session record and a CSRF token for mutations. + +The interface uses Jinja2 templates, project-owned CSS, and small progressive +enhancement JavaScript. No SPA, React, Vue, Node build chain, or duplicated +frontend API is introduced. + +## Identity And Registration + +`installation_id` is a UUID generated once by the Agent install/configuration +flow and persisted in local Agent state. Registration sends it explicitly and +the Hub treats it as the stable installation key. `agent_id` remains the Hub +Agent record identity. Hostname, IP, display name, customer code, and company +context are metadata and never replace the installation identity. + +Registration and heartbeat accept only allowlisted operational metadata. CNPJ +is masked before storage/display, database path is sanitized, and credentials, +tokens, passwords, and keys are rejected or discarded. + +## Operational Model + +The Hub stores a current per-installation snapshot rather than recalculating +product or event tables on every page request. The snapshot includes product +counts, coverage, blocker aggregates, latest job outcomes, heartbeat, health, +version drift, company context, Firebird metadata, capabilities, and dataset +versions. + +Health is deterministic: + +- `UNKNOWN`: registered but no usable heartbeat/snapshot yet. +- `OFFLINE`: last heartbeat is older than the configured threshold. +- `FAILED`: persistent technical failure prevents processing. +- `DEGRADED`: technical/job failures are relevant but processing remains + possible. +- `ONLINE`: recent heartbeat with no critical technical failure. + +Fiscal `SAFE_BLOCKED` counts never independently cause `DEGRADED` or `FAILED`. +Offline threshold is configurable and defaults to three heartbeat intervals when +the configured interval is available. + +## Events, Redaction, And Retention + +Agents submit structured operational events, not raw log files. The Hub +redacts case-insensitive secret keys and credentials embedded in strings, +limits event message/context size, and persists severity, type, timestamps, +installation, optional job/product/blocker references, and structured context. + +Default retention is 90 days via `AGENT_EVENT_RETENTION_DAYS`. A maintenance +operation removes only non-audit events older than the retention period. Write +audit, blocker history, and critical audit records are preserved. + +## Human Actions + +Human mutations require an authenticated session, valid CSRF token, explicit +confirmation in the UI, and an audit event. Allowed operations are reprocess +all, reprocess selected products/blockers, resolve a blocker with explicit +context, display-name/customer/notes edits, and CSV exports. The panel cannot +change Firebird write flags, AI flags, credentials, Firebird paths or CRT, +execute SQL, run a shell, or restart a Windows service. + +## APIs And UI + +The panel APIs provide summary, installation list/detail/health/coverage, +blockers, jobs, and events with real pagination and filters. Global blockers and +jobs reuse the same query services. The UI includes dashboard, agent list, +installation detail tabs, global blockers, global jobs, and event timelines. +Every primary row uses client, display name, and hostname; UUIDs remain in +technical details. + +## Performance + +Indexes cover tenant, installation, health, heartbeat, version, event time and +severity/type, job agent/status/time, and blocker agent/status/type/time. +Dashboard cards use snapshot aggregates and bounded grouped queries. Detail and +global lists use limit/offset pagination for V1, with bounded page sizes and no +N+1 relationship loading. + +## Verification + +Tests cover persistent installation identity, sanitized registration and +heartbeat metadata, health/offline transitions, snapshot aggregation, event +redaction and size limits, retention, admin hashing/login/session/CSRF, API +filters and pagination, safe action audit trails, templates, and the existing +main/central/agent suites. A non-production fixture generator creates 100 +varied installations without auto-seeding production. + +## Explicit Non-Goals + +No fiscal rule changes, AI invocation, AI writes, Firebird writes, production +deployment, real-client installation, remote Agent update, raw log upload, +shell execution, or SPA frontend.