Consola da Plataforma (superadmin)

A Consola da Plataforma está acima dos municípios: gere quem usa o SGM, que módulos cada município tem ligados, as contas de todos os municípios, a auditoria global e o estado dos serviços. Não é o painel municipal — aqui um clique desliga um município inteiro. Este capítulo cobre todos os menus da consola:

Secção	Menus
Estado	Visão geral
Municípios	Municípios · Módulos
Contas	Utilizadores
Registo	Auditoria
Definições	Configuração

Acesso restrito

A consola destina-se só à equipa da plataforma. Além do login com 2FA, está protegida por uma credencial de acesso adicional fornecida pela equipa — sem ela a página nem abre. Todos os acessos ficam registados.

Quem é o superadmin

O superadmin é uma conta sem município associado — é isso, e não um perfil especial, que lhe dá acesso à consola. Pode criar, editar, suspender e reactivar municípios; ligar e desligar módulos; criar, editar e bloquear contas em qualquer município; ler a auditoria de toda a plataforma; alterar definições globais; ver o estado dos serviços.

O que não pode fazer: apagar municípios, apagar contas, editar ou apagar registos de auditoria. Bloquear preserva o histórico; apagar destruía-o.

A primeira conta é criada na instalação. O verificador de produção acusa FALHA se pertencer ao fornecedor ou a um domínio de demonstração. Os perfis municipais descrevem-se em /guia/perfis-e-permissoes.

Entrar

1. Abra a consola e introduza a credencial de acesso adicional quando o browser a pedir;
2. Utilizador, email ou telefone e Palavra-passe → Entrar;
3. Com 2FA activo aparece Confirmação em duas etapas: escreva o código recebido → Confirmar (há Reenviar código);
4. Uma conta municipal vê "Esta consola não é para a sua conta" — use o painel do município.

Não existe "manter sessão iniciada": fechar o browser termina a sessão.

Faixa de ambiente

Uma faixa vermelha, fixa no topo de todos os ecrãs diz Consola da Plataforma · PRODUÇÃO · afecta TODOS os municípios e a que API está ligada. Existe para quem tem o painel municipal noutro separador perceber, sem ler nada, onde está. Se disser PRODUÇÃO, cada acção tem efeito real.

Visão geral

Painel de estado, refrescado de 30 em 30 segundos, com a hora da última leitura e um botão Actualizar.

• Cartões — Municípios (total, activos, suspensos), Municípios suspensos (a vermelho quando há algum), Utilizadores (total, activos), Módulos no catálogo;
• Serviços — tabela com Serviço, Estado e Detalhe.

Se a API não responder, aparece um aviso com o motivo e os números antigos ficam esmaecidos. Sem leitura nenhuma, os cartões mostram "—", não zeros.

O que cada serviço significa

A sonda só prova que o processo aceita ligações — não valida funcionalidade.

Serviço	O que é	Se estiver em baixo
API Laravel	O núcleo do SGM; responde a este painel	Nada abre
Base de dados (Postgres)	Onde vivem todos os municípios	Nada funciona
Motor tributário (fiscal-service)	Calcula impostos e taxas	Sem guias nem liquidações
Gestão documental (DMS)	O módulo Arquivo	Sem carregar nem abrir documentos
Armazenamento de objectos (MinIO)	Ficheiros do Arquivo	Arquivo sem ficheiros
Notificações e emails (serviço Node)	Email do portal e notificações na aplicação	Notificações não saem; o email cai no canal de reserva
Consola municipal (admin)	O painel dos funcionários	Funcionários sem acesso
Portal do munícipe	O site público	Munícipes sem acesso

Os três primeiros são essenciais: sem eles o município não trabalha. Estados: operacional (respondeu), degradado (respondeu com erro interno), em_baixo (não respondeu no tempo limite) e nao_configurado (não faz parte desta instalação — não é alarme).

O worker de filas não aparece nesta tabela

Códigos 2FA, OTP e emails saem por uma fila consumida por um processo à parte. Se parar, o painel fica verde e ninguém recebe códigos. Quem o verifica é o sgm:verificar-producao (ver Verificação).

Municípios

As 65 autarquias já estão registadas

O sistema traz as 65 autarquias locais de Moçambique (23 cidades + 42 vilas, do Acórdão 48/CC/2023) já provisionadas: cada uma com o seu tenant, a sua ficha de município, o seu papel de administrador, os 16 perfis municipais, a estrutura do tarifário em rascunho e a ligação ao território que faz o mapa abrir no sítio certo.

O que não trazem — e não podem trazer — é o tarifário deliberado, os utilizadores reais e os parâmetros do município. Um município provisionado é um município pronto a configurar, não um município a funcionar. Ver Nada cobra sem deliberação.

Lista com Município (nome + slug), Estado, Território, Utilizadores, Módulos activos, Criado e Gerir. Pesquisa por nome, slug ou município do catálogo e filtro por estado. Estados: Activo · Suspenso · Inactivo, mais o selo Manutenção (ou Manutenção expirada).

Criar um município (passo a passo)

Novo município provisiona o município inteiro numa transacção: papéis, permissões, configuração inicial, séries de numeração, parâmetros fiscais em rascunho, cadastro do Portal do Munícipe, mapa de receita, vereações-padrão e o primeiro administrador.

Campo	Obrigatório	Notas
Nome	Sim	máx. 200; ex.: Conselho Municipal da Cidade da Maxixe
Slug	Sim	gerado do nome; só minúsculas, dígitos e hífens, máx. 60, único na plataforma. É a identidade pública (URLs)
Município do catálogo territorial	Não	unidade territorial oficial (pcode). Os já tomados aparecem mas não se escolhem. Sem isto o mapa abre sobre o país inteiro
Email institucional · Telefone · Morada	Não	sem email, usa-se o do administrador
Administrador — Nome	Sim	a única conta com que o município entra; é ela que cria as restantes
Administrador — Email	Sim	não pode estar em uso; fica por verificar (verifica-o o próprio)

1. Preencha → Criar e provisionar;
2. Aparece o recibo: a senha temporária do administrador (botão Copiar) e os passos manuais pendentes;
3. Entregue a senha por canal seguro — nunca no mesmo email que o endereço de acesso. O primeiro login obriga à troca;
4. Só depois carregue em Já guardei a senha — fechar.

A senha é mostrada uma única vez

Não fica guardada em claro. O recibo não fecha com X nem ao clicar fora — de propósito. Se se perder, resta a recuperação de senha pelo próprio administrador.

Passos manuais típicos: publicar os parâmetros fiscais em Administração › Parâmetros com fundamento legal; nomear os titulares das vereações; carregar a tabela de taxas da postura, o plano de contas, as referências de RH e a tarifa de bancas; abrir o exercício contabilístico; semear os parâmetros do motor tributário; associar o território (se não foi feito); carregar logótipo e papel timbrado. Enquanto estiverem por fazer, o município funciona mas não está completo. Ver /modulos/administracao.

O primeiro município de uma instalação cria-se por comando

Na instalação a consola ainda não existe: o sgm:criar-municipio faz exactamente o mesmo (mesmo código) a partir do terminal, com --dry-run para ensaiar. A consola é o caminho para o segundo e seguintes.

Gerir um município

Gerir abre o painel lateral com três secções.

Identidade — Email, Telefone, Morada, Território (nome e pcode), Exercício fiscal, Utilizadores, Módulos activos, Criado. Editar muda Nome, Slug, Email, Telefone e Morada.

Mudar o slug não é cosmético

O slug é a identidade pública do município. Alterá-lo muda os endereços por onde é conhecido.

Acesso ao sistema:

• Suspender — a API recusa todos os pedidos do município, portal incluído; ninguém entra, nem o administrador municipal. Para decisões administrativas sem fim previsto;
• Marcar inactivo — mesmo efeito, registado como desactivação e não como sanção;
• Reactivar — devolve o município exactamente como estava, sem confirmação.

Suspender e inactivar pedem confirmação por escrita: escreve-se o nome do município (maiúsculas indiferentes, acentos contam) e um Motivo opcional, que fica na auditoria. Nada é apagado.

Janela de manutenção — paragem temporária e anunciada: a API responde "em manutenção" com a mensagem e a hora de regresso. Ligar manutenção pede o nome do município, uma Mensagem para quem tentar entrar (opcional) e Termina em (opcional; tem de ser no futuro — sem data fica até alguém desligar). Terminar manutenção desliga na hora. Manutenção é para trabalho planeado; suspensão é para decisões administrativas.

Território

A associação à unidade territorial oficial faz-se na criação ou, no primeiro município, pelo --pcode do comando de instalação. Um município do catálogo só pode representar um município da plataforma. O painel Gerir mostra o território, mas a versão actual da consola não tem ecrã para o corrigir — a correcção passa pela equipa técnica (a API tem o ponto de associação). Sem território não há polígono, bairros nem mapa: ver /modulos/territorio.

Módulos

Sem município escolhido, mostra o catálogo da plataforma em leitura (essenciais com escudo).

1. Escolha o Município (os suspensos aparecem "sem acesso ao sistema" — as decisões gravam-se e valem quando reactivar);
2. Mexa nos interruptores; cada alteração fica marcada Vai ligar / Vai desligar;
3. Rever e gravar → lista exacta do que vai ser DESLIGADO e LIGADO, com um Motivo opcional que fica ao lado dos módulos desligados;
4. Gravar alterações. Descartar limpa o que estava por gravar.

Desligar faz o menu desaparecer no painel municipal e a API recusar esse módulo. Os dados ficam intactos e voltam assim que o módulo for religado. Nos desligados vê-se Desligado em … por … — motivo. A gravação é em bloco: um acto, uma linha de auditoria.

Módulos essenciais não se desligam

Configurações e Administração aparecem ligados e inertes. Sem eles o município deixava de gerir utilizadores, permissões e parâmetros — e só esta consola o poderia repor.

Utilizadores

Contas de todos os municípios num só sítio. A coluna Município está sempre visível: dois homónimos em municípios diferentes são duas pessoas diferentes. Contas sem município aparecem como Plataforma (administradores desta consola, com escudo âmbar).

Colunas: Utilizador, Município, Papel, Estado (Activo · Inactivo · Bloqueado, mais Senha por trocar), Último acesso, e Editar / Bloquear / Desbloquear. Pesquisa por nome, email ou telefone; filtros por município (incluindo Plataforma (sem município)) e estado.

Criar uma conta em qualquer município

Nova conta:

Campo	Obrigatório	Notas
Nome	Sim	máx. 200
Email	Sim	é por aqui que entra; único dentro do município (pode repetir-se noutro)
Telefone	Não	máx. 40
Município	Sim	define que dados a conta vê. Depois de criada não se muda

A senha inicial é gerada pela plataforma e mostrada no recibo uma única vez (Copiar); a conta troca-a no primeiro acesso e o email fica por verificar. Saia com Já guardei a senha. O papel dentro do município atribui-se no painel municipal.

Criar um administrador da plataforma

A última opção do campo Município é Plataforma — administrador desta consola. Uma conta sem município é um superadmin: gere todos os municípios, suspende qualquer um e cria outros administradores. A opção aparece a vermelho e o botão passa a Criar administrador da plataforma; o servidor recusa criar uma conta sem município sem esta confirmação explícita.

Editar e bloquear

Editar corrige Nome, Email e Telefone. O município não se muda: todo o trabalho da conta o referencia. Quem muda de município recebe uma conta nova — e a antiga bloqueia-se.

Bloquear pede confirmação com nome, email e município da conta, e um Motivo opcional. A conta deixa de entrar e as sessões abertas caem de imediato. Nada é apagado; Desbloquear devolve a conta como estava. O servidor recusa bloquear a própria conta e o último superadmin activo.

Auditoria

O que foi feito, por quem, quando e onde — em toda a plataforma. Junta duas trilhas num fluxo cronológico:

• Alteração — quem mudou o quê, com valor anterior e novo;
• Acesso — entradas, saídas e tentativas falhadas, com resultado (Sucesso / Falhou) e IP.

Colunas: Quando, Tipo, Acção (rótulo e código gravado), Quem (e IP), Município, Sobre (entidade e n.º). Filtros: quem praticou o acto, município (incluindo Plataforma (sem município)), tipo e intervalo De … até. Nas alterações, Ver alterações abre o antes → depois campo a campo — só o que mudou, com botão para ver o resto. Nunca JSON cru.

A trilha é só de leitura

Não há forma de editar nem apagar um registo — nem na consola, nem na API, nem para o superadmin. É isso que a torna utilizável como prova. Os actos desta consola entram aqui com o motivo escrito.

Configuração

Definições que valem para toda a plataforma, por grupos. Cada uma mostra rótulo, chave, ajuda, unidade e a origem: Definido aqui ou Valor de fábrica. Um município pode ter uma sobreposição própria, que prevalece.

1. Altere os campos (interruptor, número, texto ou JSON); os limites validam-se ao lado;
2. Repor devolve ao valor de fábrica;
3. Rever e guardar → lista antes → depois → Guardar definições.

Só se envia o que mudou. Valores secretos chegam mascarados: campo em branco não altera, escrever substitui; nunca aparecem no resumo nem na auditoria.

Verificação e cópias de segurança

sgm:verificar-producao é a checklist executável da instalação: imprime [OK] / [AVISO] / [FALHA] por item e sai com erro se algo bloquear. Usa a mesma sonda da Visão geral e verifica ainda o worker de filas, trabalhos falhados, migrações, município configurado, cópias de segurança, se o superadmin pertence ao município e vestígios de demonstração (removem-se com sgm:limpar-demonstracao, que se recusa a apagar um município com dados reais).

A consola da plataforma não tem painel de cópias. O estado vive no painel de segurança da consola municipal (última cópia, último teste de restauro, retenção), alimentado por sgm:registar-backup, que a rotina de cópia chama no fim de cada execução. Sem rotina, o cartão diz "Sem informação" a vermelho. O verificador acusa FALHA sem cópia registada ou com a última há mais de 2 dias, e AVISO se o restauro nunca foi testado ou há mais de 90 dias — uma cópia nunca restaurada é um ficheiro, não uma cópia.

Boas práticas de segurança

• 2FA ligado em todas as contas da plataforma — sem ele, uma senha comprometida é a plataforma inteira;
• Sessões de 120 minutos, só em memória do separador: fechar o browser termina a sessão. Não deixe a consola aberta num posto partilhado;
• Bloquear um superadmin fecha-lhe a sessão no acto — também nesta consola. Quando alguém sai da equipa: bloqueie (não há apagar);
• Mantenha mais do que um superadmin activo; o sistema recusa bloquear o último;
• A conta de superadmin pertence ao município ou à entidade responsável, nunca ao fornecedor;
• Escreva sempre o motivo ao suspender, desligar módulos ou bloquear contas;
• Confirme a faixa de ambiente antes de uma acção destrutiva, e o município antes de bloquear uma conta;
• Senhas temporárias entregam-se por canal seguro.