diff --git a/docs/ONBOARDING_PRIMEIRO_CLIENTE_REAL.md b/docs/ONBOARDING_PRIMEIRO_CLIENTE_REAL.md new file mode 100644 index 0000000..01c7d01 --- /dev/null +++ b/docs/ONBOARDING_PRIMEIRO_CLIENTE_REAL.md @@ -0,0 +1,97 @@ +# 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).*