Protokol — protocolos operacionais e checklists com evidência

Operações com várias unidades — franquias, redes de lojas, cozinhas, clínicas — vivem do mesmo ritual: procedimentos padrão (POPs) que precisam ser executados todo dia, em todo local, do jeito certo. Na prática, isso vira papel na parede e planilha desatualizada. O Protokol transforma esse ritual em software: o operador escaneia o QR Code do local, executa o checklist com evidências, e o gestor enxerga tudo em tempo real.

O problema

Checklist em papel não prova nada: não diz quem executou, quando, onde, nem como. E quando uma tarefa crítica atrasa, ninguém fica sabendo até virar problema. Faltava uma ferramenta que fizesse o caminho completo — da definição do protocolo à evidência da execução, com cobrança automática de SLA.

Como funciona

• Protocolos com SLA embutido: atividades ordenadas, recorrência (diária/semanal/mensal), horário-limite, tolerância e regra de escalação.
• Execução mobile: escaneou o QR do local → abre o checklist → cada item recebe status, foto de evidência, comentário. A execução carrega geolocalização e assinatura digital.
• Notificações proativas em três estágios: "vai vencer" → "venceu" → "escalou pro chefe". Entrega por SignalR (tempo real), e-mail e Web Push próprio (VAPID, sem Firebase).
• Offline de verdade: o operador em campo sem sinal continua executando; a fila offline (IndexedDB) guarda até as fotos como blobs e faz replay do pipeline completo quando a rede volta.
• Billing por unidade (Stripe): a cobrança escala com o número de locais, com trial que degrada para somente-leitura em vez de bloquear o acesso.

Arquitetura

Monorepo com frontend React (PWA) e API .NET, PostgreSQL e MinIO (storage S3-compatível para evidências), tudo deployado no Railway com CI/CD via GitHub Actions.

Visão de componentes e infraestrutura (4 serviços no Railway):

Fluxo de execução com evidência (inclusive offline):

O isolamento multi-tenant é resolvido por claim no JWT em um middleware dedicado, com sub-escopo opcional por cliente — um mesmo usuário pode operar dados de clientes distintos sem vazamento entre contextos.

Decisões técnicas que valem a pena contar

Read-only em vez de paywall. Trial expirou? Em vez de trancar o app (e perder o usuário), um middleware gateia apenas métodos de escrita com HTTP 402 — leitura continua liberada. O dado do cliente nunca fica refém.

Fila offline que não perde a prova. O ponto mais crítico do produto é a evidência. A fila offline replica o pipeline completo (URL pré-assinada → upload no MinIO → registro da execução) com backoff e limite de tentativas, e carrega geolocalização e assinatura junto — nada é descartado silenciosamente por falta de rede.

Webhooks Stripe idempotentes de verdade. Stripe reentrega eventos; cada EventId processado é registrado, e retries simultâneos são resolvidos pela restrição de unicidade — o processamento repetido vira um no-op logado, mantendo a cobrança consistente.

Evidências servidas por URL pública normalizada. As URLs de evidência são normalizadas para o CDN público de forma idempotente no boot, com backfill de registros legados — migração de dados como código, sem script manual.

Stack

.NET · ASP.NET Core · EF Core + PostgreSQL · SignalR · React + Vite · TanStack Query · Tailwind + shadcn/ui · Workbox (PWA) · MinIO · Stripe · Railway · xUnit + Vitest no CI.

Status

Publicado em protokol.com.br, com onboarding, biblioteca pública de modelos de protocolo, i18n pt-BR/en-US e demo seedada. Evolução contínua — próximos passos incluem timezone por tenant nas avaliações de SLA e relatórios mais ricos.