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