# 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:
     ```cmd
     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:
1. **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.
2. **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.
3. **Conferência de Integridade do Catálogo**: Ausência de propostas contraditórias entre produtos do mesmo grupo/família.
4. **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:

1. **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).*
2. **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).*
3. **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).*
4. **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).*