feat(missao-7): bloco C - roteiro de onboarding seguro e prontidao para primeiro cliente real
This commit is contained in:
gti
@@ -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).*
|
||||
Reference in New Issue
Block a user