Cidelo
Manual de Uso e Operação do Sistema
Guia completo e ilustrado por perfil de acesso para a plataforma integrada de gestão de serviços municipais, zeladoria urbana com SLA, atendimento multicanal e transparência ativa.
Sumário dos Módulos:
Plataforma Cidelo: Gestão Municipal Integrada
O Cidelo (domínio oficial cidelo.app.br) é uma plataforma completa de gestão de serviços públicos, zeladoria urbana com SLA, atendimento multicanal, transparência ativa e inteligência de dados, desenvolvida especificamente para prefeituras de pequeno e médio porte, com projeto piloto de homologação no município de Dois Vizinhos (PR).
Multi-tenant em Banco Único
Cada município é isolado por código IBGE (tenant) via Row Level Security (RLS) nativo do PostgreSQL e trait BelongsToTenant. Cidadão e malha são globais.
Motor de SLA & Feriados
Cálculo de prazos em horas corridas ou dias úteis considerando calendário municipal de feriados, expedientes e travas de transição de estado da máquina.
Privacidade & LGPD Rígida
Desfoque assistido de rostos e placas por IA, fotos públicas sem EXIF/GPS, CPFs mascarados e supressão de dados pessoais em relatórios da Câmara e MCP.
Ambientes e Links de Acesso
Produção & HomologaçãoO ambiente de homologação online está implantado na infraestrutura Contabo com deploy via Coolify. Todos os domínios utilizam HTTPS seguro e isolamento por subdomínio:
| Destino / Interface | Endereço Online (Homologação) | Público-Alvo |
|---|---|---|
| Portal da Prefeitura (Transparência) | dvz.cidelo.app.br | Público geral, munícipes e órgãos de controle |
| Backoffice Administrativo | dvz.cidelo.app.br/entrar | Servidores, secretarias, atendentes e vereadores |
| App do Cidadão (Mobile PWA) | cidelo.app.br/app | Cidadãos de qualquer município (geolocalizado) |
| App de Campo das Equipes | cidelo.app.br/campo | Equipes operacionais próprias e terceirizadas |
| Painel da Plataforma (Superadmin) | plataforma.cidelo.app.br | Equipe Cidelo (superadmin, suporte, financeiro) |
| Documentação da API v1 | cidelo.app.br/docs/api | Desenvolvedores e integrações externas |
Catálogo de Perfis de Homologação
Perfis de servidores municipais, contas globais de plataforma e munícipes para validação de fluxos. As credenciais de teste são entregues pela equipe do projeto e não ficam publicadas nesta wiki.
Peça as credenciais de teste à equipe do projeto. Em homologação os servidores informam apenas e-mail e senha, sem código de confirmação, e o cidadão usa um código de teste informado pela equipe. Nada disso existe em produção.
| Usuário / Perfil | Escopo / Secretaria | O que testar nesta conta |
|---|---|---|
| Atendente da Central Atendente |
Central de Atendimento | Fila de triagem, reclassificar, recusar, abrir protocolo por telefone e WhatsApp. |
| Gestor de Viação e Obras Gestor de Secretaria |
Viação e Obras | Quadro da secretaria (B2), atribuir equipe terceirizada, custos operacionais e rondas. |
| Gestor de Serviços Urbanos Gestor de Secretaria |
Serviços Urbanos | Iluminação pública, troca de lâmpadas, bueiros e arborização. |
| Gestor de Meio Ambiente Gestor de Secretaria |
Meio Ambiente | Fiscalização de lotes sujos (B13), autos de notificação de proprietários e limpeza pública. |
| Gestor da Agricultura Gestor de Secretaria |
Agricultura | Fila da patrulha mecânica, deferimento de horas, agendamento e malha de estradas rurais. |
| Equipe 1 · Centro/Norte Equipe de Campo |
Operacional / Campo | App de campo (/campo): iniciar ordens, registrar fotos antes/depois e concluir. |
| Equipe 2 · Sul Equipe de Campo |
Operacional / Campo | Rondas preventivas (F5) de bueiros e vistoria de hidrantes com checklists. |
| Pavimenta Sul Terceirizada |
Empresa Contratada | Ordens de tapa-buracos com apropriação automática de custos por ordem e medição. |
| Operador de Máquinas Equipe de Campo |
Patrulha Mecânica | App de campo F7: validação de raio GPS (< 100m), horímetro inicial/final e fotos. |
| Gestão Geral Gestão Geral |
Prefeitura Global | Painel analítico BI (B3), SLA global, mapa de calor territorial e conexões MCP de IA. |
| Defesa Civil Defesa Civil |
Segurança / Emergência | Modo Emergência (B10): traçado de área no mapa, priorização crítica e avisos públicos. |
| Administrador Municipal Administrador |
TI / Governança | Configurações (B4), secretarias, equipes, categorias, SLA, feriados e usuários. |
| Secretaria Escola Esperança Servidor |
Educação / Escola | Abrir chamado interno (S1): suporte de TI e manutenção predial da unidade. |
| Gestor de TI Gestor de Área |
Departamento de TI | Fila de chamados internos de TI (B8), atribuição a técnicos e controle de prazos. |
| Técnico de TI Técnico |
Suporte de TI | Execução de chamados: Iniciar, Pausar com motivo justificado e Concluir atendimento. |
| Editor da Prefeitura Editor |
Comunicação Social | Publicações (B6), notícias, licitações, modo eleitoral e boletim semanal da rádio (B20). |
| Vereadora Joana Vereador |
Câmara de Vereadores | Pedidos formais de informação (B5), consulta a protocolos sem dados pessoais (LGPD). |
| Super Admin (Plataforma) Superadmin |
Plataforma Global | Gestão geral de prefeituras, adesão de novos municípios, planos, módulos e impersonate. |
Aplicativo do Cidadão (Mobile PWA)
O aplicativo do munícipe é uma Progressive Web App (PWA) instalável diretamente pelo navegador em smartphones Android ou iOS (Safari › Adicionar à Tela de Início), acessível no endereço cidelo.app.br/app.
1 Entrada Rápida e Sem Senha pelo Celular
O cidadão nunca precisa memorizar senhas. A autenticação é realizada via OTP (One-Time Password) de 6 dígitos enviado por SMS ou WhatsApp.
- Acesse https://cidelo.app.br/app no celular ou computador.
- Informe o seu CPF ou telefone celular.
- Em homologação o código de confirmação é um código de teste, informado pela equipe do projeto.
- No primeiro acesso, confirme o nome e aceite os termos da LGPD (exigência de 18+ anos).
Proteção de Privacidade (LGPD)
O CPF e o celular do cidadão são armazenados com hash cifrado e exibidos sempre mascarados na interface (***.000.000-**). O nome completo nunca é revelado publicamente em mapas, dados abertos ou para a Câmara Municipal.
2 Abertura de Ocorrência com Câmera ao Vivo e GPS
Para combater fraudes, denúncias anônimas inverídicas e desvios de atendimento, o Cidelo adota a captura fotográfica obrigatória e georreferenciada.
A imagem deve ser capturada no momento da solicitação. Não é permitido upload de imagens da galeria externa, garantindo a veracidade do evento.
O pino de localização no mapa é preenchido com a coordenada GPS do celular. O munícipe pode ajustar o pino em até 50 metros para refinar o local exato.
O sistema gera o número oficial (ex.: DV-2026-00015), apresenta o prazo legal de resolução (SLA) e inicia o acompanhamento.
3 Inteligência Anti-Duplicidade e Apoio Coletivo
Quando múltiplos munícipes identificam o mesmo problema urbano (ex.: o mesmo buraco na via ou poste sem luz no mesmo raio de proximidade), o sistema detecta a duplicidade:
O munícipe apoia a ocorrência já existente. O número de pessoas afetadas sobe, fortalecendo a prioridade do atendimento sem poluir a fila da prefeitura com chamados duplicados. O cidadão passa a receber notificações automáticas do andamento.
Permite ao cidadão gerar um protocolo separado caso discorde que se trata da mesma ocorrência ou se for um ponto diferente no mesmo perímetro.
4 Resiliência e Operação Offline (IndexedDB)
Em bairros rurais ou momentos de instabilidade no sinal 4G/5G, o munícipe não perde o atendimento:
O aplicativo guarda a foto, as coordenadas do GPS e as respostas no banco local seguro do navegador (IndexedDB). Na tela inicial, exibe o aviso Aguardando sinal com botão de reenvio automático assim que a conexão for restabelecida.
5 Pedido de Patrulha Mecânica e Linhas Rurais
Para produtores agrícolas e famílias do interior, o aplicativo dispõe de módulos exclusivos dedicados ao campo:
Patrulha Mecânica (C19)
O produtor solicita serviços de cascalhamento, abertura de açude ou destoca. O sistema controla a cota legal anual (até 20 horas/ano por produtor) e informa a posição transparente na fila da máquina (ex.: Patrola 01, posição 4º da fila).
Estradas Rurais & Transporte Escolar (C20)
O munícipe consulta o mapa com as linhas rurais (São Roque, Barra Bonita, Jacutinga) e seu estado (Transitável, Atenção ou Intransitável). Mães e motoristas de van escolar clicam em "Seguir esta linha" para receber avisos push imediatos quando chover forte ou houver interdição.
6 Portal Público de Transparência e Dados Abertos
Acesso livre e universal em dvz.cidelo.app.br sem necessidade de cadastro ou senha:
Fila Pública de Máquinas da Agricultura (Transparência Ativa)
O cidadão e os produtores rurais podem acompanhar a fila pública das motoniveladoras e retroescavadeiras da prefeitura, garantindo isonomia sem privilégios políticos:
Central de Atendimento & Triagem (Atendente)
O perfil Atendente (conta de teste "atendente") é a linha de frente do município no backoffice (dvz.cidelo.app.br/central). Ele atua no saneamento dos protocolos que exigem triagem humana antes do envio às secretarias e no atendimento multicanal via WhatsApp e telefone.
1 Operação da Fila de Triagem Central
Ao acessar a tela Central, o atendente visualiza a lista ordenada de protocolos pendentes de despacho:
Identifica se outro cidadão abriu chamado similar a menos de 50 metros.
Indica que o mesmo local já teve chamado aberto e concluído recentemente.
Protocolos abertos via telefone ou balcão que não possuem evidência visual anexada.
Chamado devolvido por um secretário por falta de competência da pasta.
2 Ações do Atendente: Encaminhar, Reclassificar e Recusar
Ao selecionar um protocolo na lista lateral, o painel central exibe a foto original sem desfoque (exclusiva para a equipe interna), os dados georreferenciados e as opções de ação:
1. Encaminhar
Confirma que a categoria está correta e envia diretamente para o quadro de trabalho da secretaria responsável (Viação, Meio Ambiente, Serviços Urbanos, etc.). O status do chamado muda para "Encaminhado".
2. Reclassificar
Se o munícipe escolheu "Buraco na rua", mas a foto revela que se trata de uma "Tampa de bueiro quebrada", o atendente reclassifica a categoria e a urgência. O novo SLA é recalculado automaticamente e registrado na linha do tempo.
3. Recusar
Utilizado quando a demanda não é da competência municipal (ex.: rodovia federal/estadual, conflito entre vizinhos ou foto inválida). É obrigatório informar a justificativa detalhada, que é enviada ao munícipe.
3 Abertura Assistida Presencial e Telefônica (156)
Quando um cidadão liga para o 156 da Prefeitura ou comparece pessoalmente sem smartphone, o atendente abre o chamado pelo menu "Novo":
- Digite o CPF ou telefone do munícipe para buscar o cadastro existente.
- Selecione a categoria do problema e preencha o endereço aproximado ou clique no mapa.
- Clique em "Abrir Protocolo": o cidadão recebe imediatamente um SMS com o número do protocolo e link de acompanhamento.
4 Atendimento Multicanal: WhatsApp & Agente de IA
O módulo oficial de WhatsApp integrado à plataforma permite que a IA faça a triagem primária e escale para o atendente quando necessário:
Identifica a queixa do munícipe ("buraco na frente da escola"), solicita foto e localização atual e registra o protocolo automaticamente.
O atendente pode usar o botão "Anotar" para inserir comentários com fundo amarelo na conversa que o cidadão não vê no WhatsApp.
Após 24h sem mensagem do cidadão, a caixa de digitação vira uma seleção de templates oficiais aprovados pela Meta para reengajamento.
Gestão de Secretarias (Obras, Meio Ambiente e Agricultura)
Os secretários municipais (obras@, ambiente@ e agricultura@) gerenciam a execução dos serviços públicos recebidos da Central de Triagem, controlam seus quadros de trabalho, despacham ordens para equipes de campo e monitoram custos de insumos e maquinários.
1 Quadro de Ordens de Serviço da Secretaria
Visualização ágil no formato Kanban, separando os chamados por estágio de execução operacional:
Chamados encaminhados pela triagem com SLA correndo. O secretário define prioridade e equipe.
Ordem despachada para a equipe de campo ou empresa terceirizada com materiais alocados.
Serviço finalizado com foto comprobatória do 'depois' e encerramento do protocolo.
Retorno fundamentado para a Central caso a ocorrência pertença a outra pasta municipal.
2 Mapa de Ativos Urbanos & Inventário Municipal
Georreferenciamento do patrimônio público em vias urbanas: postes de iluminação com plaquetas, bueiros/bocas de lobo, lixeiras comunitárias e abrigos de ônibus.
3 Rondas Programadas & Rotinas Preventivas
A prefeitura não espera apenas a queixa do munícipe. O sistema gera automaticamente rotinas periódicas de inspeção para os fiscais e equipes:
4 Apontamento e Controle de Custos Operacionais
Cada ordem de serviço concluída registra os insumos consumidos (toneladas de massa asfáltica CBUQ, metros cúbicos de brita, lâmpadas LED, tubos de concreto) e horas de trabalho:
5 Fiscalização de Lotes Particulares (Meio Ambiente)
Módulo exclusivo da Secretaria de Meio Ambiente para combate à dengue e mato alto em terrenos particulares sem manutenção:
6 Patrulha Mecânica Rural & Linhas de Estradas (Agricultura)
A Secretaria de Agricultura dispõe de controle especializado para atender as comunidades do interior do município:
Gestão da Patrulha Mecânica
Controle de maquinário público (motoniveladoras, pás-carregadeiras, tratores de esteira), cota de até 20 horas anuais por produtor e posicionamento na fila de atendimento.
Monitoramento de Estradas Rurais
Gestão dos trechos rurais, pontes de madeira/concreto e bueiros. Sinalização imediata de linhas intransitáveis com disparo de alertas aos motoristas escolares.
App de Campo das Equipes & Terceirizadas
Desenvolvido sob medida para uso em celulares e tablets robustos pelas equipes da prefeitura e empreiteiras terceirizadas em cidelo.app.br/campo. Possui interface de alto contraste, botões grandes e suporte a sincronização offline para áreas sem sinal 4G.
1 Ordens de Serviço do Dia no Celular
Ao iniciar o expediente, o encarregado da equipe visualiza a lista ordenada das tarefas atribuídas pelo secretário:
Para concluir qualquer ordem de serviço no campo, a equipe deve tirar a foto do reparo finalizado ao vivo pela câmera do aplicativo. O sistema aplica desfoque automático em rostos de pedestres e placas de veículos antes de qualquer publicação.
Fluxo de Conclusão da Ordem:
- A equipe chega ao endereço e clica em "Iniciar Deslocamento / Trabalho".
- Registra o consumo de materiais reais utilizados na manutenção.
- Aciona o botão "Tirar Foto do Depois" com a câmera ao vivo.
- Clica em "Concluir Ordem": o status muda para Concluído e o munícipe é notificado na mesma hora.
2 Rondas Preventivas e Apontamento de Horímetro
O aplicativo de campo também atende tarefas dinâmicas de ronda preventiva e apontamento de maquinário pesado:
Execução de Rondas de Campo
Inspeção georreferenciada de postes apagados ou praças danificadas diretamente pelo trajeto do veículo.
Apontamento de Horímetro da Máquina
O operador da motoniveladora ou escavadeira registra o horímetro inicial, final e colhe a assinatura digital do produtor rural.
Atendimento Interno, TI e Manutenção Predial
Além do atendimento ao cidadão externo, o Cidelo possui um canal estruturado para servidores públicos municipais solicitarem reparos de infraestrutura, suporte de informática e melhorias prediais em escolas, creches e postos de saúde.
1 Abertura de Chamado pelo Servidor Municipal
Diretores escolares, médicos de UBS e agentes administrativos abrem chamados sem intermediários:
2 Fila de Chamados do Gestor de TI & Manutenção
O encarregado de TI ou predial prioriza os chamados por urgência e atribui ao técnico responsável:
3 Quadros de Tarefas Ágeis (Kanban Interno)
Organização interna de projetos e rotinas das equipes municipais sem misturar com chamados de zeladoria:
Comunicação Social, Defesa Civil e Câmara Municipal
Módulos que conectam o poder executivo à população através de notícias e boletins semanais para rádios locais, oferecem canal de emergência para a Defesa Civil e garantem acompanhamento qualificado e transparente para o poder legislativo (vereadores).
1 Notícias Oficiais & Publicações no Portal
Gerenciamento da comunicação oficial da prefeitura com agendamento de postagens e trava legal de conformidade com o Modo Eleitoral (suspensão automática nos 90 dias que antecedem a eleição):
2 Boletim Semanal Automatizado para Emissoras de Rádio
Gerado automaticamente todas as sextas-feiras pelo sistema, consolidando os números de zeladoria com texto em linguagem coloquial pronto para locução de rádio e envio para jornais da região:
3 Ativação do Modo de Emergência (Defesa Civil)
Em caso de vendaval, inundação, granizo ou deslizamentos, a Defesa Civil aciona o Modo de Emergência:
- Uma tarja vermelha de alerta é afixada no topo de todo o portal e aplicativo móvel.
- Categorias de risco (desabamento, abrigo, remoção de árvores caídas) passam a ter prioridade absoluta sobre serviços rotineiros.
- Cidadãos recebem avisos imediatos com telefones de apoio e pontos de abrigo no município.
4 Painel do Poder Legislativo (Vereadores)
Acesso exclusivo para os gabinetes dos vereadores acompanharem pedidos de indicação e providências com transparência e respeito à LGPD:
Garantias Legais e Governança Legislativa:
O vereador visualiza o andamento oficial de todos os pedidos do município com indicação de prazos e respostas técnicas das secretarias. O sistema emite alerta automático ao gestor quando um pedido atinge 80% do prazo legal. Dados pessoais de terceiros (nomes completos, CPFs e telefones de munícipes) permanecem anonimizados em total conformidade com a LGPD.
Alta Gestão, BI Executivo, MCP e Configurações
O Prefeito, o Secretário de Governo e os Administradores Municipais dispõem de ferramentas de Business Intelligence (BI), servidores MCP para integração segura com agentes de inteligência artificial e controle completo das regras de negócio do município.
1 Painel de Inteligência de Dados & BI Executivo
Métricas consolidadas em tempo real sobre cumprimento de SLA, bairros mais demandados, taxa de reincidência e índices de satisfação popular:
2 Assistentes de Inteligência Artificial & Servidor MCP
O Cidelo disponibiliza um servidor MCP (Model Context Protocol) oficial no endpoint POST /v1/mcp/{ibge}:
3 Parâmetros Gerais e Configurações Municipais
Painel do Administrador Municipal para parametrização do catálogo de serviços, bairros oficiais, feriados locais e regras de transição de status:
Área da Plataforma Global (Superadministrador)
Acesso exclusivo da equipe mantenedora do Cidelo em plataforma.cidelo.app.br (conta de teste "super"). Gerencia a operação nacional, a adesão de novos municípios, a cobrança e o monitoramento técnico da infraestrutura em nuvem.
1 Dashboard da Plataforma Nacional
Visão macro de todos os municípios do país, volume de protocolos transacionados e métricas de desempenho:
2 Catálogo IBGE dos 5.570 Municípios & Adesões
Todos os municípios brasileiros já nascem pré-cadastrados com sua malha geográfica do IBGE:
Possuem contrato ativo, subdomínio próprio ativado ({ibge}.cidelo.app.br), portal de transparência liberado e backoffice para servidores.
Cidadãos podem registrar demandas pelo app, que ficam salvas com contagem de apoio. Os dados geram inteligência agregada e prospecção comercial sem revelar informações pessoais.
3 Faturamento e Cobrança de Licenças
Gestão de contratos municipais, empenhos, faturas e controle de limites contratados de mensagens e armazenamento:
4 Operação Técnica, Filas de Mensagens e Auditoria Global
Monitoramento das filas de mensageria (WhatsApp oficial, Meta API, SMS, Workers Horizon) e logs de auditoria de segurança da informação:
Tickets Cidelo e Solicitações Internas
Dois quadros no mesmo estilo: um leva o pedido do município à equipe da plataforma; o outro organiza os pedidos entre os servidores do próprio município, inclusive de quem não tem login.
1 Ticket Cidelo: do município para a equipe da plataforma
Quando o administrador do município encontra um erro, tem uma dúvida ou quer uma melhoria, ele abre um Ticket Cidelo para a equipe de desenvolvimento. Só o perfil Administrador vê o menu Ticket Cidelo.
- Em Abrir um ticket, informe o resumo, a parte do sistema (ou "Não sei / geral") e o que aconteceu. Dá para anexar até 5 capturas de tela, PDF ou texto (10 MB cada).
- O ticket nasce em Backlog, sem prioridade. A equipe define prioridade e módulo na triagem.
- Acompanhe o andamento no quadro: Backlog, Em análise, Em desenvolvimento, Em testes e Concluído.
- Cada resposta pública da equipe e cada mudança de coluna chega por e-mail. As notas internas da equipe nunca aparecem para o município.
2 Painel da plataforma: kanban, triagem e TI interno
A equipe da plataforma (papéis super e suporte) trata todos os tickets de todos os municípios em Plataforma › Tickets.
- Quadro: arraste o cartão para mudar a coluna. Dentro da coluna a ordem é prioridade e depois número.
- Triagem: no detalhe, defina prioridade, módulo, etiquetas, responsável e coluna.
- Comentário público x nota interna: só o público aparece para o município e gera e-mail.
- Checklists: "Desenvolvimento" e "Testes" por ticket, só para a equipe.
- Filtros e arquivados: por município e responsável; ticket arquivado sai do quadro.
- Cadastros: colunas, prioridades, módulos e etiquetas.
- TI interno: o botão "Novo ticket do TI interno" cria um ticket do próprio backlog da equipe, sem município, sob "Cidelo (TI interno)".
3 Solicitações internas: o mesmo quadro, entre servidores
Para pedidos entre os servidores da própria prefeitura (TI, manutenção, compras, o que precisar) existe o menu Solicitações internas. Ele convive com os Chamados internos (atendimento formal com prazo) e os Quadros de tarefas: use as solicitações para pedidos do dia a dia que não precisam de SLA.
| Perfil | O que vê | O que faz |
|---|---|---|
| Gestor de secretaria, gestão geral, administrador, gestor de área | O quadro inteiro | Abre, define prioridade, encaminha para um servidor e move de coluna |
| Servidor, equipe, técnico, atendente | Só o que abriu ou recebeu | Abre, comenta; o responsável move a coluna |
- A solicitação nasce em Backlog e sem prioridade; quem gerencia faz a triagem.
- Em Encaminhar para escolha o servidor responsável. Ele passa a ver a solicitação.
- A conversa registra quem escreveu; comentários de assistente de IA aparecem como "via assistente de IA".
- Solicitações internas nunca aparecem no Ticket Cidelo nem para a equipe da plataforma.
4 Formulário público: servidor sem login também pede ajuda
Quem não tem login na plataforma abre a solicitação pelo formulário público do município, sem entrar: https://SUBDOMINIO.cidelo.app.br/solicitar (há um link "Solicitação interna" no cabeçalho do portal público).
- Preencha nome, secretaria ou setor, ramal/telefone/e-mail para retorno, resumo e detalhes.
- Ao enviar, aparece a página de acompanhamento com a situação e o responsável. Guarde o endereço: ele funciona como o código da solicitação e não mostra a conversa.
- Quem gerencia o quadro vê a solicitação marcada como aberta por formulário, com o nome e o contato do solicitante.
- Proteções: até 8 envios por hora por IP e um campo-isca contra robôs. O município pode desligar o formulário (parametros.solicitacoes_publicas).
Assistentes de IA, MCP e Agente de Triagem
Conecte o assistente que a sua equipe já usa (Claude e outros clientes MCP) e deixe que ele consulte, triague e proponha. A regra é simples: quem decide é sempre uma pessoa.
1 Os quatro servidores MCP e o que cada um faz
MCP é o jeito padrão de ligar um assistente de IA ao sistema. O assistente age como o dono do token e herda as permissões dele; nunca vê dados pessoais de cidadãos.
| Servidor | Endereço | Faz | Escopo do token |
|---|---|---|---|
| Gestão municipal | /v1/mcp/{ibge} | Só lê: protocolos, prazos, equipes, custos, ativos, chamados, emergência, interdições, patrulha, estradas | mcp (padrão) |
| Solicitações internas | /v1/mcp/{ibge}/tickets | Lista, abre, classifica, encaminha e comenta | tickets:gerir |
| Agente de triagem | /v1/mcp/{ibge}/agente | Propõe agrupamentos, equipe, prioridade e rotas; uma pessoa aprova | agente:propor |
| Tickets da plataforma | /v1/plataforma/mcp/tickets | Triagem, comentários, checklists e kanban (equipe da plataforma) | mcp:tickets |
2 Criar a conexão e ligar o assistente
- Entre no backoffice e abra Assistentes de IA (MCP) (gestor de secretaria, gestão geral, administrador, vereador e gestor de área).
- Em Nova conexão, dê um nome (ex.: "Triagem do TI"), marque o que o assistente pode consultar e, se precisar, os escopos de escrita (solicitações internas e/ou agente de triagem).
- Clique em Criar conexão. O token aparece uma única vez: guarde num gerenciador de senhas. Se perder, revogue e crie outro.
- No assistente, informe o endereço do servidor e o cabeçalho Authorization: Bearer SEU_TOKEN. Exemplo no Claude Code: claude mcp add --transport http cidelo-triagem https://dvz.cidelo.app.br/v1/mcp/4107207/agente --header "Authorization: Bearer SEU_TOKEN".
- Para revogar, use Revogar na lista: o acesso acaba na hora.
O passo a passo completo, com configuração para outros clientes e um teste com curl, está no doc 13 do repositório (docs/13-guia-dos-assistentes-de-ia.md).
3 O que pedir: receitas prontas
- Gestão (leitura): "Quais protocolos estão com prazo vencido esta semana e em que secretaria?"; "Compare o tempo médio de solução de buracos e lâmpadas nos últimos 30 dias."
- Solicitações internas: "Liste as solicitações sem responsável e sugira a quem encaminhar."; "Abra uma solicitação de TI: impressora da Saúde parada desde ontem."; "Encaminhe a solicitação 12 para o técnico de manutenção e comente o motivo."
- Agente de triagem: "Veja as pendências em triagem e proponha o agrupamento dos buracos próximos para a equipe de pavimentação."; "Monte a rota de amanhã com os protocolos já encaminhados para a Equipe 2."; "Proponha a rota da motoniveladora para os pedidos da fila da patrulha, por comunidade."
O assistente primeiro consulta (listar_pendencias, listar_recursos, listar_taxonomia) e só então escreve. Cite sempre o número do protocolo ou da solicitação no pedido.
4 Agente de triagem: o assistente propõe, a pessoa aprova
O agente não executa nada. Ele cria propostas de quatro tipos: agrupamento (protocolos da mesma categoria a até 500 m entre si, para uma equipe), equipe e prioridade, rota de manutenção (protocolos já encaminhados, na ordem de visita) e rota de máquina (pedidos da fila da patrulha). Elas aparecem em Propostas do agente.
- Aprovar executa tudo de uma vez, pelo mesmo motor da tela; se algum protocolo mudou de situação, nada é feito e a mensagem diz qual. O histórico do protocolo registra o canal "agente" e o seu nome.
- Recusar pede um motivo.
- Você só aprova o que o seu perfil permite: triar, atribuir equipe ou gerir a patrulha.
- O token do agente nunca aprova ou recusa.
- A rota de máquina não fura a fila: as regras de agrupamento por comunidade, critério e justificativa da patrulha continuam valendo.
5 MCP dos tickets da plataforma (equipe de desenvolvimento)
Em Plataforma › Tickets › Assistentes de IA (MCP) a equipe cria um token pessoal com a habilidade mcp:tickets. O assistente faz a triagem (prioridade, módulo, etiquetas), comenta (nota interna por padrão), move cartões e mantém os checklists. O responsável, o arquivamento e a exclusão continuam só no painel.
Ambiente de Homologação e Próximos Passos
O que está no ar, como as mudanças chegam e o que falta para o piloto com dados reais (detalhes técnicos de infraestrutura ficam na documentação interna do projeto).
1 Endereços e como o ambiente funciona
| Endereço | Para quê |
|---|---|
| https://cidelo.app.br | Raiz: leva ao app do cidadão (/app) |
| https://dvz.cidelo.app.br | Portal público de Dois Vizinhos; /entrar é o backoffice; /painel é o painel do servidor; /solicitar é o formulário público |
| https://plataforma.cidelo.app.br | Painel da plataforma (superadmin e equipe) |
| https://coolify.cidelo.app.br | Painel de deploy (Coolify) |
- É um ambiente de homologação. Os dados de Dois Vizinhos são fictícios: seis meses de histórico, cerca de 70% dos protocolos resolvidos e 30% abertos, com todos os perfis. As contas de teste e as senhas estão no artefato "Cidelo Homologação" e não fazem parte desta wiki.
- Deploy automático: cada alteração publicada na branch main do GitLab dispara um deploy no Coolify, com as migrações do banco. Os dados persistem entre deploys.
- Sem e-mail e SMS por enquanto: o login dos servidores entra sem código (apenas e-mail e senha) e o cidadão usa o código fixo de teste. Isso só existe em homologação.
- O mapa depende do provedor de tiles configurado; sem ele o mapa pode aparecer em branco.
2 O que ainda falta antes de usar dados reais
- Backups: snapshot da hospedagem e rotina do Postgres para armazenamento externo.
- Registro de acesso (auditoria): todo log deve mostrar data e hora, local, IP, usuário e equipamento de quem acessou ou fez a atividade. Ainda não implementado; precisa de revisão da LGPD (base legal, prazo de guarda, acesso restrito).
- Configurar e-mail (SMTP), SMS e as chaves da Meta (WhatsApp) e do Asaas (cobrança).
- Colunas, prioridades e etiquetas próprias de cada município nos tickets (hoje são globais).
Quem assumir a operação deve ler primeiro o docs/12-ambiente-homologacao.md, que é o diário do ambiente.