gti
d21a9d1140
git-subtree-dir: fiscal git-subtree-mainline:d95165fc8fgit-subtree-split:102ba84500
4.9 KiB
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.