# Arquitetura e roadmap — v8.1

## Auditoria da base

Base identificada: MyCity-Site-v8, pacote Cloudflare v8.0. Site estático (`index.html`, `site.js`, `site.css`), aplicativo com telas em um HTML e navegação hash (`demo/index.html`, `app-core.js`), painel independente (`demo/painel.html`, `painel.js`). Leaflet é a única biblioteca visual relevante; carregada localmente. Mapas usam OpenStreetMap e busca de endereço por GPS usa Photon. Vídeo H.264, 404×848, cerca de 44s. Sem servidor de aplicação ou banco remoto.

A atualização adiciona `demo/operations.js`, módulo compartilhado com funções de normalização, transições, SLA, métricas, proximidade e repositório local. Não muda a hospedagem nem o manifesto de instalação `/demo/`. A leitura legada é compatível e não destrutiva.

## Modelo operacional

Chamado: `code`, `category`, `description`, `location`, `point`, `photo`, `status`, `department`, `team`, `assignee`, `priority`, `createdAt`, `triagedAt`, `startedAt`, `dueAt`, `completedAt`, `history`, `evidence`, `feedback`, `reviewRequested`, `rating`.

OS: `workOrder.id`, `reportCode`, `department`, `team`, `assignee`, `priority`, `createdAt`, `dueAt`, `status`, `notes`, `startedAt`, `completedAt`. Uma OS por chamado nesta demonstração; não é ERP. Transferir preserva a OS e seu histórico, altera secretaria e limpa equipe/pessoa até nova atribuição.

Evidência: `id`, `photo` opcional, `note`, `at`, `author`, `team`, `point` opcional (local da demanda, não GPS da equipe), `share`. Imagens JPG/PNG/WebP até 8MB na seleção; redução para até 1000px em JPEG. Falha de quota preserva o registro anterior e mostra erro.

Status canônicos: Novo, Aguardando triagem, Atribuído, Em execução, Transferido, Em espera, Concluído, Cancelado. Validação do cidadão é um sinal separado: confirmação ou revisão solicitada; a conclusão técnica permanece no histórico.

## Tempo real implementado

Eventos `storage` atualizam abas do mesmo navegador/perfil/origem. Após uma ação local, o painel relê a base. O app relê o protocolo por código estável quando a base muda. O painel compara a string do armazenamento a cada 5s e não renderiza novamente se não mudou; prazos/intervalos locais são reavaliados a cada minuto. Não existe consulta à API, WebSocket, SSE ou notificações externas. A última atualização vem do maior timestamp dos eventos do chamado, nunca do refresh da tela.

As datas novas usam timestamp em milissegundos. Exibição operacional usa Brasília; o campo de entrada de prazo informa o horário do dispositivo. Registros antigos mantêm a data textual original e podem não permitir reconstrução de todos os tempos com precisão; quando o campo não existe, não entra na média.

## Eventos e evolução futura

| Evento | Situação nesta edição |
|---|---|
| CHAMADO_CRIADO | Registro local do cidadão |
| CHAMADO_TRIADO | Triagem local |
| SECRETARIA_ALTERADA | Transferência ou definição de área |
| RESPONSAVEL_ATRIBUIDO | Pessoa/equipe/prazo definidos |
| OS_CRIADA | OS local vinculada |
| ATENDIMENTO_INICIADO | Início registrado |
| STATUS_ALTERADO | Espera/cancelamento |
| EVIDENCIA_ADICIONADA | Texto/foto local |
| ATENDIMENTO_CONCLUIDO | Conclusão validada pelas regras locais |
| CIDADAO_CONFIRMOU | Confirmação local |
| CIDADAO_SOLICITOU_REVISAO | Alerta para análise administrativa |
| CIDADAO_NOTIFICADO | **Planejado, não emitido** |

Em produção: eventos precisam de ID único, tenant, versão do agregado, ator autenticado, timestamp do servidor, escopo público/interno, idempotência, outbox e garantia de entrega. O histórico atual não é imutável nem protegido contra adulteração pelo usuário.

## Proposta de API — nenhuma rota ativa

| Contrato proposto | Finalidade |
|---|---|
| POST /api/v1/requests | Receber demanda com categoria, localização e origem |
| GET /api/v1/requests/{id} | Consultar com autorização por município e papel |
| PATCH /api/v1/requests/{id}/status | Transição validada e versionada |
| GET /api/v1/requests/{id}/timeline | Filtrar eventos públicos e internos |
| POST /api/v1/requests/{id}/work-orders | Criar execução vinculada |
| POST /api/v1/work-orders/{id}/evidence | Upload controlado e política de publicação |
| POST /api/v1/requests/{id}/feedback | Confirmar solução ou pedir revisão |
| POST /api/v1/webhooks/subscriptions | Assinatura administrativa de eventos |

Exigir autenticação, autorização no servidor, validação, rate limiting, idempotência, concorrência otimista, validação de arquivos, URLs de curta duração e monitoramento antes de ativar. Webhooks futuros: assinatura, retentativa, deduplicação e controle de destinos. Nenhum segredo deve entrar no JavaScript público.

## Interoperabilidade

Estudo futuro de Open311 GeoReport v2, sem compatibilidade atual. Avaliar correspondência de categorias/códigos de serviço, identificadores, localização, atributos, atualizações e mídia; os status internos precisarão de um mapeamento documentado. Referência oficial consultada em 29/09/2026: https://wiki.open311.org/GeoReport_v2/

Atende.Net/IPM, 1Doc, Fala.BR, ERP e WhatsApp são referências de ecossistema para validação com fornecedores/município. Não há conexão, parceria ou certificação anunciada.

## Limites e próximo piloto

- Base no localStorage: sem segurança multiusuário, sincronização entre aparelhos, criptografia própria, transações entre abas ou backup remoto. Edições simultâneas podem competir; usar um operador por vez na apresentação.
- Filtro de secretaria e ocultação de evidências são regras de interface, não autorização.
- Prazo em horas corridas; próximo de vencer até 6h; espera prolongada acima de 24h. Não inclui calendário de expediente ou pausa de SLA.
- Relação territorial: mesma categoria normalizada, até 250m e diferença de criação até 90 dias; só coordenadas geográficas, sem converter posições gráficas antigas para inferir reincidência.
- “Região” usa texto do registro, não geofencing oficial.
- Revisão do cidadão gera alerta; reabertura formal, nova OS/ciclo e moderação são próximos passos.
- Homologar persistência, acessibilidade, dispositivos, exclusão/retenção, base legal, responsabilidades, canal de suporte, segurança e operação antes de receber demandas reais.

Piloto sugerido: 90 dias, 1–2 secretarias, critérios acordados, operação real somente após infraestrutura e governança. Medir início, triagem, conclusão, cumprimento de prazo, revisões e satisfação; entregar relatório de resultados sem prometer ganhos percentuais prévios.