Roteiro de Onboarding Seguro e Prontidão para o Primeiro Cliente Real — GTI Fiscal

Este documento estabelece as salvaguardas operacionais, os requisitos técnicos e o protocolo de segurança para a ativação do primeiro cliente real (~70 clientes da carteira), preservando a regra de ouro de não causar impacto no ERP operacional e não efetuar escrita sem aprovação prévia.

1. Checklist de Onboarding Seguro (C.1)

Requisitos de Rede e Conectividade

Comunicação 100% Outbound: O Agent necessita exclusivamente de saída HTTPS (porta 443 TCP) para o endereço público do Hub (https://hub.gtisistemas.com.br ou IP público configurado).
Sem Portas Abertas Inbound: Nenhuma porta de entrada precisa ser liberada no roteador/firewall do cliente.
Sem Necessidade de VPN: O tráfego trafega encapsulado via TLS 1.3 com autenticação mútua baseada em tokens HMAC / JWT por instalação.

Impacto de Leitura no Firebird do Cliente

Modo de Transação Estritamente Não-Bloqueante:
- Parâmetros de transação no driver Firebird (fdb): read_committed, rec_version (Record Versioning), read_only e wait=5 (timeout máximo de 5 segundos).
- Nunca bloqueia transações de escrita do PDV/SGV (concorrência limpa com MVCC do Firebird).
Throttling e Lotes Controlados:
- Consulta de produtos particionada em lotes pequenos de 50 a 100 produtos por job.
- Pausa forçada (throttling) de 50ms a 100ms entre os lotes, liberando os ciclos de CPU e buffers do Firebird Server.
Horário de Carga Inicial:
- A varredura completa inicial do catálogo de produtos deve ser programada para horário de baixo movimento ou encerramento do expediente (ex.: após as 19h ou antes das 08h).
- Durante o expediente comercial, o Agent opera exclusivamente em modo incremental (sincronizando apenas produtos com alteração de data/hora no C000025).

Comportamento sob Carga ou Conflito no Firebird

Caso o Firebird Server retorne erro de lock (lock conflict on no wait transaction), deadlock ou timeout:
- O Agent aborta imediatamente a transação de leitura (ROLLBACK automático).
- Aciona backoff exponencial com jitter (15s, 30s, 60s, até 5 minutos).
- O Agent jamais insiste em loop fechado e jamais trava o processo do SGV.
- Registra evento de severidade WARNING no heartbeat para notificação no painel do Hub.

Plano de Contingência e Rollback Imediato

Se o operador ou a equipe do cliente relatar qualquer lentidão no PDV ou no ERP:
1. Pausa Instantânea via Hub: Na tela da instalação no Hub, clicar em "Pausar processamento" (o Agent mantém apenas heartbeat passivo de 60s sem executar nenhum job no Firebird).
2. Interrupção de Serviço Local: No Windows do cliente, via PowerShell/Prompt administrativo:
```
net stop GTIFiscalAgent
```
3. Desinstalação Rápida e Limpa: Executar C:\Program Files\GTI Fiscal Agent\uninstall.exe /S. O Agent é completamente desacoplado (processo externo ao ERP, sem triggers, sem procedures e sem DLLs injetadas no banco de dados).

2. Revisão de Segurança da Comunicação Agent-Hub (C.2)

Autenticação por Instalação:
- Cada instalação possui installation_id único (UUID v4) e segredo criptográfico provisionado durante o enrollment.
- O token de enrollment é temporário, descartável e expira em 1 hora ou após o primeiro uso.
Rotação e Expiração de Credenciais:
- Sessões de comunicação utilizam tokens assinados com renovação periódica via heartbeat.
Protocolo em Caso de Vazamento de Token:
- No Hub, o administrador aciona o botão "Revogar Instalação" (Revoke Installation).
- A instalação tem seu status alterado para REVOKED no banco PostgreSQL.
- O Hub recusa imediatamente qualquer chamada subsequente daquele token com HTTP 401/403, sem expor metadados internos.
Rate Limit por Instalação:
- Middleware de proteção no Hub limita requisições de heartbeat e sincronização por instalação (máximo de 60 requisições/minuto por IP/instalação), prevenindo tempestades de requisições ou ataques de negação de serviço.
Higienização de Logs (Data Privacy):
- O Agent e o Hub são configurados para registrar apenas metadados técnicos (código interno do produto, NCM, tipo de job, latência).
- Zero dados sensíveis: É estritamente vedado o registro em logs de senhas de banco, tokens de autenticação completos, CPF/CNPJ de consumidores de notas fiscais, ou dados de pagamento.

3. Modo de Operação Recomendado para o Primeiro Cliente (C.3)

Protocolo Inicial: Somente Leitura e DRY-RUN

Para o primeiro cliente piloto, o sistema deve ser configurado com:
- enrichment_mode = 'DRY_RUN' (Simulação ativa no Hub, geração de propostas e auditoria em memória, sem emissão de payload de gravação).
- corrector_enabled = False (Sem correção automática de catálogo histórico).
- write_allowlist desativada (WRITE_ALLOWED = False para todos os campos).

Número de Execuções e Período de Observação (`N`)

Duração Recomendada: Mínimo de N = 3 sincronizações completas ou 7 dias de operação contínua.

Critérios Objetivos de Saída do Modo Dry-Run

A transição do modo DRY_RUN para autorização de gravação assistida exige o cumprimento de 100% dos seguintes critérios:

Zero Impacto no Firebird: Nenhuma ocorrência de timeout de conexão, lock conflict ou queixa de lentidão pelos operadores de caixa nos 7 dias.
Revisão Humana das Propostas: 100% das propostas fiscais geradas pelo motor no relatório de simulação revisadas e aprovadas pelo operador/contador responsável.
Conferência de Integridade do Catálogo: Ausência de propostas contraditórias entre produtos do mesmo grupo/família.
Assinatura do Termo de Homologação: Aval formal do responsável contábil do cliente atestando que a parametrização atende ao regime tributário do estabelecimento.

4. Critérios de Seleção do Primeiro Cliente Piloto (C.4)

O operador deve avaliar as seguintes perguntas objetivas para selecionar a primeira loja piloto:

Porte e Volume de Dados:
- A loja possui catálogo pequeno a moderado (menos de 2.000 itens ativos) e até 3 caixas emissores?
- (Recomendação: Evitar redes grandes ou supermercados com mais de 10.000 itens para o primeiro piloto).
Regime Tributário (CRT):
- O cliente é optante pelo Simples Nacional (CRT 1) e não é contribuinte de IPI?
- (Recomendação: CRT 1 possui regras operacionais mais estáveis e menor complexidade de débitos/créditos em relação ao Regime Normal).
Nicho de Atuação:
- O cliente atua em segmento de comércio varejista simples (ex.: mercearia, papelaria, conveniência, pet shop) com produtos industrializados portadores de código de barras comercial (EAN-13)?
- (Recomendação: Evitar açougues puros ou padarias com 100% de produtos pesáveis sem GTIN no primeiro teste).
Relacionamento e Abertura do Cliente:
- O proprietário da loja e a assessoria contábil estão cientes e concordam em participar do piloto tecnológico, com canal de comunicação direto para feedback?
- (Recomendação: O cliente piloto deve ser parceiro próximo, acessível e receptivo).

7.3 KiB Raw Blame History