docs: specify control panel v1 architecture
This commit is contained in:
gti
@@ -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.
|
||||||
Reference in New Issue
Block a user