Como a integração funciona

Esta seção é para quem precisa fazer um sistema conversar com o no ciclo operacional: o (o Conexão CIODES e o app de smartphone) e um sistema de atendimento e — qualquer . Ela entra pelos casos de uso, mostra cada um pelo SDK TypeScript e depois em REST e WebSocket crus, e termina na referência.

• A regra que explica as outras
• Quem é quem
• Onde está a especificação
• Os casos de uso

A regra que explica as outras

O Geohub é a fonte da verdade do que acontece em campo, e funciona sem

(RDT-025). O policial tem o app, a central tem as telas, e a atravessa o ciclo inteiro sem que nenhum sistema externo

participe. O integrador é um originador a mais, pela mesma porta.

A integração faz duas coisas, e só duas:

1. o integrador age no Geohub, em nome dele próprio, chamando os verbos dos plugins de e de ocorrência. Todo comando leva a integrador;
2. o Geohub devolve o que aconteceu, em , pelo : o que o seu CAD originou volta inteiro, inclusive o que a equipe fez pelo celular nessa ocorrência, no mesmo formato. O que nasceu fora dele (uma ocorrência registrada em campo, ou por outro integrador) ainda não chega: é decisão de produto em aberto, e a referência diz quem recebe cada evento.

Nenhuma rota é escrita à mão (RDT-027). O manifesto de cada plugin e os contratos zod geram a REST, a OpenAPI 3.1, o SDK TypeScript, o webhook e as coleções de comando do . Toda regra mora numa camada única de exposição: porteiro por verbo, autoria imposta pela sessão, , tradução de ids e outbox. Por isso as três camadas desta seção são o mesmo contrato visto de três distâncias: o diz o que, o SDK chama o verbo pelo nome, a REST mostra o que atravessa o fio.

A API de dados do painel não é porta de integração: escrita por ela não passa pelo , não gera evento, e o papel do integrador não a permite.

Há mais de um Geohub, e o contrato é o mesmo em todos: o central, que a central de operações e os integradores acessam, e o local do , que roda na viatura e continua a operar sem conexão. Esta seção fala com "o Geohub" porque o que ela descreve vale para qualquer um deles.

Quem é quem

Ator	Como entra	O que faz
Policial (app)	Login com matrícula e senha; sessão do Geohub, renovada pelo refresh	Apresenta-se, inicia a jornada, assume o comando, declara ; aceita, desloca, chega, registra e encerra o despacho; registra ocorrência em campo; consulta placa
Supervisor	Mesmo login	Constitui a na , substitui integrante, libera jornada
/ Operador de central	Mesmo login, ou o painel pelas coleções de comando (RDT-029)	Registra, atualiza, despacha (só o despachante), cancela, controla, encerra
Integrador (o CAD)	Usuário de serviço com o papel Integração - Sistema de despacho e token estático	Põe policial em serviço, monta a , registra e atualiza ocorrência, despacha, consulta. Nunca aceita, desloca ou chega: isso é da equipe
Sistema	—	Abre ocorrência quando uma leitura de placa validada tem interesse

Onde está a especificação

• A OpenAPI 3.1 fica em /openapi.json e é renderizada em API. É gerada do manifesto (pnpm openapi:gera) e conferida por pnpm check:openapi. O campo info.x-contratos-de-plugin traz a versão e o hash de cada contrato de plugin; é por ele que se descobre que o contrato mudou.
• O guia do integrador continua em Integrar um sistema de atendimento e despacho: é o roteiro completo para um CAD, com todo trecho vindo do pacote testado exemplo-integrador-despacho.
• Os trechos do app do policial vêm do pacote exemplo-app-do-policial, que roda o roteiro do policial contra o Geohub em processo. Nenhum trecho desta seção é colado: um teste reprova se uma página citar região que não existe no fonte.

Os casos de uso

1. Entrar em serviço — o policial se apresenta, inicia a jornada e a guarnição fica disponível.
2. Registrar e despachar — a central ou o CAD registra a ocorrência e empenha viaturas.
3. Atender — a guarnição aceita, desloca, chega e atende.
4. Ocorrência em campo — a equipe se depara com o fato e registra pelo celular.
5. O CAD recebe o que aconteceu — os eventos chegam pelo webhook.
6. Consultar placa e pessoa — as consultas que o policial faz em campo.
7. Leitura validada abre ocorrência — o sistema abre a ocorrência sozinho.

Cada página tem o espaço da cena 3D do caso, embutida da operação 3D quando o roteiro existir; até lá, o diagrama de sequência.