10 — Implicações para o Geohub

← Índice · Prefixo de citação: UFE-10

🏛️ Este capítulo não vem da conversa de origem. É a leitura editorial de como o book se encaixa no que já existe no monorepo — tasks, pacotes e decisões tomadas. É a parte que envelhece mais rápido; confira contra o estado atual das tasks antes de agir.

Estado verificado em 2026-09-01; linha de ocorrência atualizada em 2026-09-03.

A tensão que precisa ser entendida antes de tudo

O book inteiro é escrito em vocabulário policial concreto: policial, arma, viatura, guarnição, batalhão. A task-053 decidiu o oposto para o núcleo do Geohub — e a decisão é anterior, deliberada e do dono do produto:

Vocabulário do book	Núcleo do Geohub hoje (task-053)
Policial	usuario / identificador
Escala	agendado, IItemAgenda
Viatura, smartphone híbrido	TipoNo: central | dedicado | hibrido
Batalhão	dado de deployment, não tipo
matricula	identificador

packages/types/src/geohub/plugins/autoriza/Autoriza.types.ts:451 já traz IItemAgenda com essa forma abstrata, e o mirror Python espelha.

Como as duas coisas convivem

Não são contraditórias — são camadas diferentes, e confundi-las produziria um retrabalho equivalente ao que a task-053 acabou de desfazer:

┌─────────────────────────────────────────────────────────┐
│ NÚCLEO ABSTRATO  — tipos, autoriza, agenda, nós          │
│ vocabulário neutro (task-053)                            │
├─────────────────────────────────────────────────────────┤
│ DOMÍNIO OPERACIONAL — ocorrência, despacho, cautela      │
│ é aqui que este book se aplica                           │
├─────────────────────────────────────────────────────────┤
│ VERTICAL / DEPLOYMENT — "policial", "batalhão", "PMxx"   │
│ dados e configuração, nunca tipo                         │
└─────────────────────────────────────────────────────────┘

Regra prática ao usar este book para escrever código: o conceito e as relações vêm daqui; o nome do identificador segue a camada em que ele mora. "Cautela de recurso" é conceito de domínio operacional e pode manter o nome; "policial" é vertical e vira usuario no núcleo. Quando em dúvida, pergunte: este conceito existiria num deployment de bombeiros, de defesa civil ou de uma empresa de segurança privada? Se sim, é domínio. Se não, é vertical.

Onde o book responde perguntas que tasks abertas fazem

task-077 — OcorrenciaHub (pending)

A task declara explicitamente que especificar é parte do trabalho e lista as lacunas. O book cobre boa parte delas:

Lacuna aberta na task-077	Onde o book ajuda
"Definir o que é uma ocorrência: schema do payload"	T-003, T-021–T-030 (classificação), T-031–T-034 (localização), T-011–T-019 (papéis), UC-17 (campos do despacho)
"Definir o vocabulário canônico de status"	T-071–T-080 — com a ressalva de Q-01: o bloco mistura estado de ocorrência e de recurso
"Quem pode fazer cada transição"	UFE-03 (atores) + UFE-06 (ator principal por UC)
"origem — qual ator causou a mudança"	UFE-03 — iniciador vs. ator principal
Distinção solicitacao_id × ocorrencia_id	D-01 (chamado × ocorrência) é exatamente a mesma distinção, um nível acima

O achado mais forte para a task-077: RS-08 — o encerramento do despacho não encerra automaticamente a ocorrência. Se o enum de status da ocorrência incluir em deslocamento e no local, o Geohub estará expondo estado de recurso como se fosse estado de ocorrência, e o ECOPS vai consumir isso. Corrigir depois significa versionar o contrato com um integrador externo.

Segundo achado: D-01/D-02 sugerem que faltam entidades. A task-077 modela ocorrencia + ocorrencia_solicitacao + ocorrencia_evento. Não há incidente (T-004) — o que significa que dois chamados sobre o mesmo fato viram duas ocorrências sem vínculo. Pode ser decisão consciente de escopo; hoje é omissão não registrada. Ver Q-03.

task-179 — API externa para envio de ocorrência ao app (pending)

UC-17 (receber despacho) é literalmente o payload que essa API entrega, e UC-18 (aceitar despacho) é o passo 4 do cenário canônico da task-077 — a mudança que nasce fora do ECOPS e precisa chegar nele. UC-19–UC-25 descrevem o resto do que o app precisa oferecer ao policial na ocorrência.

task-053 — autorização e autenticação (in-progress)

Dois pontos de contato diretos:

• Login agendado é, no vocabulário do book, UC-06 (registrar apresentação) validado contra T-102 (item de escala). O conceito operacional que já está implementado de forma abstrata tem nome no domínio.
• Os quatro modos de login (agendado, emergência autônoma, remota, avalizada) não têm equivalente no book — a conversa de origem presume rede e central disponíveis. O Geohub resolve um problema que o modelo teórico não enxerga: operação degradada. Isso é vantagem, não lacuna.

Onde o Geohub já tem peça pronta

Leitura de UFE-03, consolidada por capacidade do book:

Capacidade do book	Situação
T-039 localização do recurso	✅ @geocontrol/avl-mensageria + @geocontrol/azimutehub
T-040 geocodificação	✅ packages/geocode-client (+ task-236, sidecar Rust)
T-099 auditoria	✅ directus-extension-access-report, RDT-006
T-016/T-019 suspeito, desaparecido	✅ packages/pessoa-interesse, task-056
UC-06 apresentação por biometria	✅ geobox-biometria, fingerprint-converter
UC-12/UC-35 imagens de vistoria	✅ missao-fotografica-hub resolve captura estruturada com metadados
T-091 comunicação operacional	🟡 packages/notifica + app do smartphone; não é rádio
T-003 ocorrência	🟡 tipada (task-077, parte 1: packages/types/src/geohub/plugins/ocorrencia/ + mock em ocorrenciahub); coleção e extensão são a parte 2
T-101–T-110 escala	🟡 só IItemAgenda, abstrato; sem elaboração, publicação, conflitos ou versão
T-132 cautela de recurso	❌ inexistente
AS-04 armamento	❌ inexistente
AS-05 frota (como cautela)	❌ inexistente — há telemetria, não há patrimônio

O padrão que salta da tabela: o Geohub é forte no eixo "onde está e quem é" e vazio no eixo "quem é responsável por qual bem". A espinha dorsal de UFE-02 atravessa exatamente o vazio.

Convenções do monorepo que se aplicam a qualquer task derivada daqui

Nada aqui é novo; é a lembrança do que o CLAUDE.md já exige e que este domínio vai tocar:

1. TDD. Teste primeiro, começando vermelho. Máquina de estado é o caso ideal: as transições proibidas de UFE-07 viram testes antes de existir implementação.
2. TypeScript é a fonte canônica. Modele e valide em TS; só depois porte para o mirror Python. Não desenhe contrato no Python.
3. Vocabulário em português, com nome técnico seguindo a camada (ver a tensão no topo deste capítulo).
4. Decisão arquitetural vira RDT, em docs/RDT/ — não seção de task e não este book. Quando uma 🔶 de UFE-11 for decidida, é para lá que ela vai.
5. Coleção nova criada por hook, no padrão setup-collection já usado por furto-roubo-veiculo e directus-extension-access-report — como a task-077 já determina.

Ordem sugerida de ataque

Não é plano de execução; é a ordem que as dependências do próprio book impõem:

1. Fechar Q-01 (separar estado de ocorrência de estado de recurso) — é pré-requisito da task-077 e o mais caro de corrigir depois, porque vaza para contrato externo.
2. Ocorrência + despacho (task-077, task-179) — é onde já há demanda real e integrador esperando.
3. Jornada e prontidão — é o que o CAD precisa saber para despachar, e o que conecta a agenda já existente ao ciclo operacional.
4. Cautela de recurso — maior valor incremental, nenhuma peça pronta, nenhuma dependência externa. Pode andar em paralelo.
5. Escala completa (elaboração, publicação, conflitos) — o mais caro, e o único que compete de frente com sistemas já instalados nas corporações.

---

← 09 — Panorama de sistemas · Índice · Próximo: 11 — Questões em aberto →