chore: establish project baseline

2026-09-21 15:51:47 -03:00
commit 9dcc263217
459 changed files with 447890 additions and 0 deletions
@@ -0,0 +1,18 @@
+GTI Fiscal Agent 1.0.0-rc1 - pacote Windows
+==========================================
+
+Arquitetura: Hub central --HTTPS--> Agent Windows --local--> Firebird do SGV. O Hub nunca acessa o Firebird.
+Este pacote NAO contem segredos (token do Agent e senha do Firebird sao informados localmente).
+
+Requisitos no host do cliente: Python 3.12 (64 bits) no PATH, cliente Firebird (fbclient.dll, o mesmo do SGV),
+acesso HTTPS ao Hub, uma conta Firebird somente leitura.
+
+Passo a passo (PowerShell como Administrador, dentro desta pasta):
+  .\gti-agent.ps1 install        cria o venv, instala as dependencias, registra o servico "GTIFiscalAgent" (nao inicia)
+  .\gti-agent.ps1 configure      (ou: configure -FromTemplate .\pilot-construcao.env.example) grava o .env local com ACL restrita
+  .\gti-agent.ps1 preflight      PREFLIGHT=PASS|FAIL e os bloqueios, se houver
+  .\gti-agent.ps1 start          so inicia se o preflight passar
+  .\gti-agent.ps1 status | stop | restart | uninstall [-Purge]
+
+Modo do piloto: FISCAL_MODE=DRY_RUN e FIREBIRD_WRITES=0. Nesse modo o Agent e tecnicamente incapaz de escrever no Firebird.
+Detalhes: docs/PILOT_DEPLOYMENT.md e docs/OPERATIONS.md do repositorio.
@@ -0,0 +1,22 @@
+# GTI Fiscal Agent - generic installation template
+# NO SECRETS in this file. Copy to <install>\.env (gti-agent configure -FromTemplate) and fill AGENT_TOKEN / FB_PASSWORD locally.
+GTI_HUB_URL=https://fiscal.example.gti
+AGENT_TOKEN=
+AGENT_ID=
+
+# Company context (deterministic resolver; never the first row of C000004)
+COMPANY_CODE=
+COMPANY_CNPJ=
+# AUTO = resolve automatically ONLY when there is no CRT conflict; otherwise preflight FAILS until EMISSOR or C000004 is chosen explicitly
+COMPANY_CRT_SOURCE=AUTO
+# COMPANY_UF= is an explicit override only when the database proves nothing; it never replaces the resolver silently.
+
+# Real path of the client's SGV database ON THIS HOST (do not reuse the path of any local copy)
+FIREBIRD_DATABASE_PATH=
+FB_USER=
+FB_PASSWORD=
+
+FISCAL_MODE=DRY_RUN
+FIREBIRD_WRITES=0
+POLL_INTERVAL_SECONDS=5
+AGENT_VERSION=1.0.0-rc1
@@ -0,0 +1,3 @@
+@echo off
+rem GTI Fiscal Agent - launcher: gti-agent.cmd install|configure|preflight|start|stop|restart|status|uninstall
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0gti-agent.ps1" %*
@@ -0,0 +1,127 @@
+<#
+  GTI Fiscal Agent - Windows operations script (RC1). No Python editing needed.
+
+  Usage (elevated PowerShell for install/start/stop/restart/uninstall):
+    .\gti-agent.ps1 install                       create venv, install dependencies, register the Windows Service (does NOT start it)
+    .\gti-agent.ps1 configure [-FromTemplate f]   write <install>\.env (secrets are prompted, never echoed, never stored in the package)
+    .\gti-agent.ps1 preflight                     PREFLIGHT=PASS|FAIL with blockers (read-only)
+    .\gti-agent.ps1 start | stop | restart        service control (start refuses to run when preflight fails)
+    .\gti-agent.ps1 status                        service state + last log lines
+    .\gti-agent.ps1 uninstall [-Purge]            remove the service; -Purge also deletes venv/logs/state (never the .env unless -Purge)
+
+  The package folder is the install folder. Requires Python 3.12 (64-bit) on PATH and the Firebird client (fbclient.dll) already used by the SGV.
+#>
+param(
+    [Parameter(Position = 0, Mandatory = $true)]
+    [ValidateSet('install', 'configure', 'preflight', 'start', 'stop', 'restart', 'status', 'uninstall')]
+    [string]$Command,
+    [string]$FromTemplate,
+    [switch]$Purge
+)
+
+$ErrorActionPreference = 'Stop'
+$Root = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ServiceName = 'GTIFiscalAgent'
+$Venv = Join-Path $Root 'venv'
+$Py = Join-Path $Venv 'Scripts\python.exe'
+$EnvFile = Join-Path $Root '.env'
+$LogFile = Join-Path $Root 'agent\logs\agent.log'
+
+function Assert-Admin {
+    $principal = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
+    if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { throw 'Run this command from an elevated (Administrator) PowerShell.' }
+}
+
+function Read-Plain([string]$Prompt, [string]$Default = '') {
+    $suffix = if ($Default) { " [$Default]" } else { '' }
+    $value = Read-Host "$Prompt$suffix"
+    if ([string]::IsNullOrWhiteSpace($value)) { return $Default } else { return $value.Trim() }
+}
+
+function Read-Secret([string]$Prompt) {
+    $secure = Read-Host $Prompt -AsSecureString
+    $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
+    try { return [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr) } finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) }
+}
+
+switch ($Command) {
+    'install' {
+        Assert-Admin
+        if (-not (Get-Command python -ErrorAction SilentlyContinue)) { throw 'Python 3.12 (64-bit) is required on PATH.' }
+        if (-not (Test-Path $Py)) { python -m venv $Venv }
+        & $Py -m pip install --upgrade pip | Out-Null
+        & $Py -m pip install -r (Join-Path $Root 'requirements-agent.txt')
+        $post = Join-Path $Venv 'Scripts\pywin32_postinstall.py'
+        if (Test-Path $post) { & $Py $post -install | Out-Null }
+        $svc = Join-Path $Root 'agent\service\gti_agent_windows_service.py'
+        & $Py $svc --startup=auto install
+        sc.exe failure $ServiceName reset= 86400 actions= restart/60000/restart/60000/restart/60000 | Out-Null
+        Write-Host "Service $ServiceName registered (Automatic). Next: .\gti-agent.ps1 configure ; .\gti-agent.ps1 preflight ; .\gti-agent.ps1 start"
+    }
+    'configure' {
+        if ($FromTemplate) {
+            Copy-Item -Path $FromTemplate -Destination $EnvFile -Force
+            Write-Host "Template copied to $EnvFile. Fill the empty secret values (AGENT_TOKEN, FB_PASSWORD) with a text editor, then run preflight."
+        } else {
+            $hub = Read-Plain 'Hub URL (https://...)'
+            $token = Read-Secret 'AGENT_TOKEN (from register_agent.py)'
+            $agentId = Read-Plain 'AGENT_ID (label for this installation)'
+            $db = Read-Plain 'FIREBIRD_DATABASE_PATH (real path of the SGV .FDB on THIS host)'
+            $fbUser = Read-Plain 'FB_USER (read-only account)' 'SYSDBA'
+            $fbPass = Read-Secret 'FB_PASSWORD'
+            $code = Read-Plain 'COMPANY_CODE (C000004.CODIGO; empty = auto when unambiguous)'
+            $cnpj = Read-Plain 'COMPANY_CNPJ (digits; optional alternative to COMPANY_CODE)'
+            $crtSource = Read-Plain 'COMPANY_CRT_SOURCE (AUTO | EMISSOR | C000004)' 'AUTO'
+            $lines = @(
+                "GTI_HUB_URL=$hub", "AGENT_TOKEN=$token", "AGENT_ID=$agentId",
+                "COMPANY_CODE=$code", "COMPANY_CNPJ=$cnpj", "COMPANY_CRT_SOURCE=$crtSource",
+                "FIREBIRD_DATABASE_PATH=$db", "FB_USER=$fbUser", "FB_PASSWORD=$fbPass",
+                'FISCAL_MODE=DRY_RUN', 'FIREBIRD_WRITES=0', 'POLL_INTERVAL_SECONDS=5', 'AGENT_VERSION=1.0.0-rc1'
+            )
+            Set-Content -Path $EnvFile -Value $lines -Encoding UTF8
+        }
+        # Only Administrators and SYSTEM may read the file that holds the secrets.
+        icacls $EnvFile /inheritance:r /grant:r 'Administrators:(F)' 'SYSTEM:(F)' | Out-Null
+        Write-Host "Configuration saved to $EnvFile (restricted ACL). Secrets are not part of the package."
+    }
+    'preflight' {
+        if (-not (Test-Path $Py)) { throw 'Run install first.' }
+        & $Py (Join-Path $Root 'agent\scripts\preflight.py') --env-file $EnvFile
+        exit $LASTEXITCODE
+    }
+    'start' {
+        Assert-Admin
+        & $Py (Join-Path $Root 'agent\scripts\preflight.py') --env-file $EnvFile
+        if ($LASTEXITCODE -ne 0) { throw 'PREFLIGHT=FAIL: fix the blockers above before starting the service.' }
+        Start-Service $ServiceName
+        Write-Host "$ServiceName started."
+    }
+    'stop' { Assert-Admin; Stop-Service $ServiceName -Force; Write-Host "$ServiceName stopped." }
+    'restart' {
+        Assert-Admin
+        & $Py (Join-Path $Root 'agent\scripts\preflight.py') --env-file $EnvFile
+        if ($LASTEXITCODE -ne 0) { throw 'PREFLIGHT=FAIL: not restarting.' }
+        Restart-Service $ServiceName -Force
+        Write-Host "$ServiceName restarted."
+    }
+    'status' {
+        $svc = Get-Service $ServiceName -ErrorAction SilentlyContinue
+        if ($null -eq $svc) { Write-Host 'Service not installed.'; exit 1 }
+        Write-Host ("Service {0}: {1} (StartType {2})" -f $svc.Name, $svc.Status, $svc.StartType)
+        if (Test-Path $LogFile) { Write-Host '--- last log lines ---'; Get-Content $LogFile -Tail 15 }
+    }
+    'uninstall' {
+        Assert-Admin
+        $svcScript = Join-Path $Root 'agent\service\gti_agent_windows_service.py'
+        if (Get-Service $ServiceName -ErrorAction SilentlyContinue) {
+            Stop-Service $ServiceName -Force -ErrorAction SilentlyContinue
+            if (Test-Path $Py) { & $Py $svcScript remove }
+        }
+        if ($Purge) {
+            foreach ($p in @($Venv, (Join-Path $Root 'agent\logs'), (Join-Path $Root 'agent\agent_state.sqlite'), $EnvFile)) { if (Test-Path $p) { Remove-Item $p -Recurse -Force } }
+            Write-Host 'Service removed; venv, logs, state and .env deleted.'
+        } else {
+            Write-Host 'Service removed. Configuration (.env), logs and state were kept (use -Purge to delete them).'
+        }
+    }
+}
@@ -0,0 +1,22 @@
+# GTI Fiscal Agent - PILOT PROFILE: CONSTRUCAO (materiais de construcao). Audited: company 000001, UF BA, CRT 1, AUTO_RESOLVED, confidence HIGH
+# NO SECRETS in this file. Copy to <install>\.env (gti-agent configure -FromTemplate) and fill AGENT_TOKEN / FB_PASSWORD locally.
+GTI_HUB_URL=https://fiscal.example.gti
+AGENT_TOKEN=
+AGENT_ID=
+
+# Company context (deterministic resolver; never the first row of C000004)
+COMPANY_CODE=000001
+COMPANY_CNPJ=
+# AUTO is enough here: EMISSOR.EMITENTE_CRT and C000004.CRT agree (1). The host preflight must confirm UF=BA / CRT=1.
+COMPANY_CRT_SOURCE=AUTO
+# COMPANY_UF= is an explicit override only when the database proves nothing; it never replaces the resolver silently.
+
+# Real path of the client's SGV database ON THIS HOST (do not reuse the path of any local copy)
+FIREBIRD_DATABASE_PATH=
+FB_USER=
+FB_PASSWORD=
+
+FISCAL_MODE=DRY_RUN
+FIREBIRD_WRITES=0
+POLL_INTERVAL_SECONDS=5
+AGENT_VERSION=1.0.0-rc1
@@ -0,0 +1,22 @@
+# GTI Fiscal Agent - PLANNED PROFILE (not installed): MMMODAS (moda). C000004.CRT=2 vs EMISSOR.EMITENTE_CRT=1
+# NO SECRETS in this file. Copy to <install>\.env (gti-agent configure -FromTemplate) and fill AGENT_TOKEN / FB_PASSWORD locally.
+GTI_HUB_URL=https://fiscal.example.gti
+AGENT_TOKEN=
+AGENT_ID=
+
+# Company context (deterministic resolver; never the first row of C000004)
+COMPANY_CODE=000001
+COMPANY_CNPJ=
+# REQUIRED: CRT sources conflict (EMISSOR=1, C000004=2); the emission programs read EMISSOR.
+COMPANY_CRT_SOURCE=EMISSOR
+# COMPANY_UF= is an explicit override only when the database proves nothing; it never replaces the resolver silently.
+
+# Real path of the client's SGV database ON THIS HOST (do not reuse the path of any local copy)
+FIREBIRD_DATABASE_PATH=
+FB_USER=
+FB_PASSWORD=
+
+FISCAL_MODE=DRY_RUN
+FIREBIRD_WRITES=0
+POLL_INTERVAL_SECONDS=5
+AGENT_VERSION=1.0.0-rc1
@@ -0,0 +1,22 @@
+# GTI Fiscal Agent - PLANNED PROFILE (not installed): RINCAO (restaurante). C000004 has 3 company rows; EMISSOR.EMITENTE_CRT=3 vs C000004(row 000001).CRT=1
+# NO SECRETS in this file. Copy to <install>\.env (gti-agent configure -FromTemplate) and fill AGENT_TOKEN / FB_PASSWORD locally.
+GTI_HUB_URL=https://fiscal.example.gti
+AGENT_TOKEN=
+AGENT_ID=
+
+# Company context (deterministic resolver; never the first row of C000004)
+COMPANY_CODE=000001
+COMPANY_CNPJ=
+# REQUIRED: CRT sources conflict (EMISSOR=3, C000004=1); the emission programs read EMISSOR. COMPANY_CODE=000001 is the row whose CNPJ equals the EMISSOR CNPJ.
+COMPANY_CRT_SOURCE=EMISSOR
+# COMPANY_UF= is an explicit override only when the database proves nothing; it never replaces the resolver silently.
+
+# Real path of the client's SGV database ON THIS HOST (do not reuse the path of any local copy)
+FIREBIRD_DATABASE_PATH=
+FB_USER=
+FB_PASSWORD=
+
+FISCAL_MODE=DRY_RUN
+FIREBIRD_WRITES=0
+POLL_INTERVAL_SECONDS=5
+AGENT_VERSION=1.0.0-rc1
@@ -0,0 +1,22 @@
+# GTI Fiscal Agent - PLANNED PROFILE (not installed): UNIAO (mercado). C000004.CRT=3 vs EMISSOR.EMITENTE_CRT=1
+# NO SECRETS in this file. Copy to <install>\.env (gti-agent configure -FromTemplate) and fill AGENT_TOKEN / FB_PASSWORD locally.
+GTI_HUB_URL=https://fiscal.example.gti
+AGENT_TOKEN=
+AGENT_ID=
+
+# Company context (deterministic resolver; never the first row of C000004)
+COMPANY_CODE=000001
+COMPANY_CNPJ=
+# REQUIRED: CRT sources conflict (EMISSOR=1, C000004=3; OPTANTE_SIMPLES=S); the emission programs read EMISSOR.
+COMPANY_CRT_SOURCE=EMISSOR
+# COMPANY_UF= is an explicit override only when the database proves nothing; it never replaces the resolver silently.
+
+# Real path of the client's SGV database ON THIS HOST (do not reuse the path of any local copy)
+FIREBIRD_DATABASE_PATH=
+FB_USER=
+FB_PASSWORD=
+
+FISCAL_MODE=DRY_RUN
+FIREBIRD_WRITES=0
+POLL_INTERVAL_SECONDS=5
+AGENT_VERSION=1.0.0-rc1
@@ -0,0 +1,3 @@
+httpx>=0.27,<1
+fdb>=2.0.2,<3
+pywin32>=306; sys_platform == "win32"