feat(admin): implementar backoffice administrativo (issue #4)

[vinimartinsufrr]

O que muda

Leva apps/admin/ de esqueleto (só pubspec.yaml) a um backoffice Flutter navegável, no mesmo padrão visual/código de apps/acs/ e apps/patient/:

• Login (local, ambiente de desenvolvimento — ver divergência 2 abaixo)
• Painel de indicadores: contadores por RiskLevel, alertas vermelhos abertos/reconhecidos, TMRAV
• Microáreas: listagem somente leitura de microárea + ACS vinculado
• Alertas: consulta filtrável por microárea/status, sem reclassificação de risco
• Logs de auditoria: somente leitura, com o próprio acesso do admin também registrado (AdminDataSource.recordAccess)

Camada de dados isolada atrás de AdminDataSource (interface) + MockAdminDataSource (implementação mock, dados fictícios espelhando os campos reais dos .spy.yaml do backend), no espírito do AlertPublisher/AlertStore do servidor. Tema em admin_theme.dart, seguindo a estrutura de acs_theme.dart/patient_theme.dart (accent índigo #4F46E5). Navegação responsiva: NavigationRail em telas ≥640px, NavigationBar abaixo disso.

Suporte a Flutter Web adicionado (flutter create --platforms=web .) — alvo de plataforma decidido como Web (backoffice é desktop-first), conforme a issue sugeria confirmar antes do scaffolding.

Por quê

Fecha a issue #4: o apps/admin/ era o único dos três clientes (P-APP, ACS-APP, ADMIN) ainda não implementado, apesar de já reservado na arquitetura (spec/PRD_system.md §2.1) e na matriz RBAC (§4.2.2).

Como testar

cd apps/admin
flutter pub get
flutter analyze      # 0 erros/warnings
flutter test         # 12 arquivos de teste, 1+ por tela
flutter run -d web-server --web-port=8765   # depois abrir http://localhost:8765 manualmente
                                              # (flutter run -d chrome/edge falhou nesta máquina — problema
                                              #  de lançamento do CDP, não relacionado a este código)

Divergências em relação ao texto da issue (documentadas para não deixar o revisor descobrir sozinho)

1. Versão do Flutter: a issue citava 3.24.0 para o job de CI; o ci.yml real já fixava 3.44.8 nos jobs patient-app/acs-app no momento em que criei a branch (confirmado lendo o arquivo). Usei 3.44.8.

2. Login não chama auth.developmentLogin: a issue pede explicitamente esse endpoint. Investiguei implementar de verdade, seguindo o padrão que apps/patient/apps/acs já usam (sinalacs_client + BackendClient, que passaram a existir depois que este branch foi criado). Descobri que backend/sinalacs_server/lib/src/endpoints/auth_endpoint.dart só aceita role: 'patient' ou role: 'acs' — não há usuário fixo de desenvolvimento para admin; a chamada real falha com AlertValidationException. Ligar isso de verdade exige uma mudança no backend (endpoint compartilhado, fora do escopo desta issue de app). Mantive login local, documentado no código (LoginScreen) e em docs/telas-admin.md. Abro uma issue separada para estender auth.developmentLogin com o papel admin, se fizer sentido para o grupo.

Fora do escopo (por decisão explícita da issue)

• Escrita/edição de vínculo ACS↔microárea (fica para uma próxima issue)
• Autenticação institucional real (SSO/gov.br), mTLS no broker, deploy de produção
• Qualquer reclassificação manual de risco

Screenshots

Capturadas rodando flutter run -d web-server e abrindo localhost manualmente no navegador (dados fictícios). Documentação completa por tela em docs/telas-admin.md.

Login	Indicadores	Microáreas

Alertas	Auditoria

Closes #4

🤖 Generated with Claude Code

https://claude.ai/code/session_01WyMMKXSksyUUNXPieFpSfX

[Copilot]

🟡 Changes recommended

Unresolved critical authentication and moderate data-loading and audit error-handling issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a Flutter Web administrative backoffice with responsive navigation, mock data, dashboards, alerts, microareas, and audit logs.

Changes:

• Adds admin screens, theme, and local development login.
• Adds data-source contracts, mock implementation, tests, and documentation.
• Adds Web scaffolding and an admin CI job.

File summaries

File	Description
docs/telas-admin.md	Admin screen documentation.
apps/admin/web/manifest.json	PWA metadata.
apps/admin/web/index.html	Flutter Web shell.
apps/admin/test/mock_admin_data_source_test.dart	Mock data-source tests.
apps/admin/test/micro_areas_screen_test.dart	Microareas screen tests.
apps/admin/test/login_flow_test.dart	Login flow tests.
apps/admin/test/audit_log_screen_test.dart	Audit log tests.
apps/admin/test/alerts_screen_test.dart	Alerts screen tests.
apps/admin/test/admin_home_shell_test.dart	Admin shell tests.
apps/admin/README.md	Admin app documentation.
apps/admin/pubspec.lock	Locked dependencies.
apps/admin/lib/main.dart	Application entry point.
apps/admin/lib/core/data/mock_admin_data_source.dart	Mock administrative data source.
apps/admin/lib/core/data/admin_data_source.dart	Data-source interface and models.
apps/admin/lib/app/app.dart	Login, navigation, and administrative screens.
apps/admin/lib/app/admin_theme.dart	Admin theme.
apps/admin/analysis_options.yaml	Analyzer configuration.
apps/admin/.metadata	Flutter project metadata.
apps/admin/.gitignore	Project exclusions.
.github/workflows/ci.yml	Admin CI job.

Review details

Suppressed comments (9)

apps/admin/lib/app/app.dart:244

• Se fetchDashboardIndicators() falhar, snapshot.hasData permanece falso mesmo quando o Future termina com erro, então a tela fica em um spinner indefinidamente e oculta falhas de rede/backend. Trate snapshot.hasError antes desse ramo e mostre um estado de erro, idealmente com retry.

          if (!snapshot.hasData) return const Center(child: CircularProgressIndicator());

apps/admin/lib/app/app.dart:325

• O mesmo FutureBuilder deixa qualquer erro de fetchMicroAreas() preso no spinner: com erro, snapshot.hasData nunca fica verdadeiro. Isso faz uma falha do backend parecer uma tela carregando para sempre; trate snapshot.hasError explicitamente antes de renderizar o loading.

          final areas = snapshot.data ?? const [];
          if (!snapshot.hasData) return const Center(child: CircularProgressIndicator());

apps/admin/lib/app/app.dart:431

• Quando fetchAlerts falha, snapshot.data fica nulo e este ramo exibe “Nenhum alerta...” como se a consulta tivesse retornado vazia. Uma indisponibilidade pode assim ocultar alertas vermelhos; trate snapshot.hasError antes do estado vazio e mostre uma falha (idealmente com retry).

              else if (alerts.isEmpty)
                const Padding(padding: EdgeInsets.only(top: 24), child: Text('Nenhum alerta para o filtro selecionado.'))

apps/admin/lib/app/app.dart:487

• Se fetchAuditLogs() falhar, entries também vira vazio e a tela afirma “Nenhum acesso registrado ainda”, ocultando a falha de leitura dos logs. Diferencie snapshot.hasError do resultado vazio e mostre um erro/retry.

              final entries = snapshot.data ?? const [];

apps/admin/lib/app/app.dart:369

• Aqui o Future de recordAccess() também é descartado. Uma falha na fonte real deixa a consulta de alertas disponível sem registrar o acesso e gera uma exceção assíncrona não tratada; aguarde o registro e trate falha antes de mostrar a lista.

    widget.dataSource.recordAccess(actionType: 'view', resourceType: 'alerts');

apps/admin/lib/app/app.dart:38

• O repositório removeu a senha pré-preenchida do app ACS (apps/acs/lib/app/app.dart:98-100), e este 123456 volta a embutir uma credencial no bundle. Mesmo sendo mock, isso pode ser confundido com uma senha válida ou reutilizado por engano; mantenha o campo vazio e documente o modo de desenvolvimento separadamente.

  final _senha = TextEditingController(text: '123456');

apps/admin/lib/app/app.dart:393

• DropdownButton trata value == null como ausência de seleção, portanto este item nulo não mantém o rótulo “Todas” visível: o campo começa ou volta do filtro com aparência vazia. Use um valor sentinela não nulo (mapeado para filtro nulo) ou um hint para deixar o estado sem filtro claro.

                        DropdownMenuItem(value: null, child: Text('Todas')),

apps/admin/lib/app/app.dart:418

• O filtro de status tem o mesmo problema do filtro de microárea: com value nulo, “Todos” não é exibido como seleção atual e o campo fica visualmente vazio após limpar o filtro. Use um sentinela não nulo ou um hint explícito.

                        const DropdownMenuItem(value: null, child: Text('Todos')),

apps/admin/web/manifest.json:9

• O manifesto ainda declara portrait-primary e os metadados padrão do Flutter. Como este backoffice é desktop-first e tem layout responsivo, uma instalação PWA pode ficar restrita a retrato e exibir splash/chrome azul genérico, divergindo do tema índigo/escuro do app. Ajuste esses metadados para o backoffice, usando orientação any e as cores/descrição do produto.

    "background_color": "#0175C2",
    "theme_color": "#0175C2",
    "description": "A new Flutter project.",
    "orientation": "portrait-primary",

• Files reviewed: 19/30 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[hbgit]

Olá @vinimartinsufrr , obrigado pelas suas contribuições.

Visando atender certos critérios de qualidade, segue aqui nesta ISSUE uma revisão que necessita de alguns ajustes no seu PR: #5 (review)

Verifique as alterações necessárias e faça uma atualização nesta PR.

[vinimartinsufrr]

Bom dia Professor @hbgit, obrigado pela revisão. Tratei os 13 pontos da review do Copilot (pull/5#pullrequestreview-5199741445, sendo 9 no resumo + 4 comentários inline, sendo 2 destes últimos duplicados dos 9):

Tratamento de erro (indicadores, microáreas, alertas, auditoria): os FutureBuilder só checavam hasData, então um erro real ficava em spinner infinito ou era mostrado como se a lista estivesse vazia. O que podia esconder, por exemplo, uma falha ao carregar alertas vermelhos. Agora as 4 telas tratam snapshot.hasError com um estado de erro próprio e botão de retry.

Auditoria de acesso não esperada: recordAccess() era chamado sem await em Microáreas e Alertas, então uma falha no registro não impedia a tela de mostrar dado sensível. Agora o acesso é registrado antes dos dados serem exibidos.

Login sem nenhum controle de acesso: o botão Entrar ignorava matrícula/senha e não tinha gate nenhum, ou seja, qualquer pessoa clicava e via alertas/auditoria, em qualquer build. Adicionei um gate por kDebugMode (desabilitado de verdade fora de modo debug). Não resolve a falta de auth institucional real (documentado como fora de escopo desta issue), mas fecha esse buraco específico.

Filtro de microárea fixo no código: os itens do dropdown eram três strings fixas do seed mock. Agora vêm de fetchMicroAreas().

Dropdown "em branco" ao selecionar Todas/Todos* DropdownButton mostra o hint, não o child do item, quando o valor é null. Adicionei hint explícito nos dois filtros.

Senha pré-preenchida no login: removida, seguindo o padrão atual do ACS.

Metadados padrão do Flutter Web (manifest.json, index.html): ainda tinham a cor azul/descrição genérica do template. Atualizados para o tema do backoffice.

Durante a correção, os próprios testes novos pegaram mais um bug (setState(() => future = fetch()) retorna a Future da atribuição, o que o Flutter rejeita), foi corrigido também.

Adicionei 8 testes novos cobrindo especificamente esses achados (erro/retry por tela, gate de login, filtro dinâmico), além dos 11 que já existiam. flutter analyze limpo e flutter test com 19/19 passando.

Sem force-push em nenhum momento. Apenas commits novos em cima do que já estava no PR, como pede o guia de contribuição.