Skip to content

feat(apps): aviso educativo na primeira abertura e em Sobre (C-02, #125) - #155

Merged
hbgit merged 2 commits into
developfrom
feat/c-02-aviso-educativo
Nov 13, 2026
Merged

hbgit merged 2 commits into
developfrom
feat/c-02-aviso-educativo

Conversation

@Rosialdo

@Rosialdo Rosialdo commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator

[C-02] Aviso educativo na primeira abertura e em "Sobre"

Closes #125 · Requisito RF21 · Texto canônico: spec/escopo_projeto.md#aviso-educativo

O que muda para quem usa

Nos apps do paciente e do agente (ACS):

  • Primeira abertura: antes do login, aparece a tela "Antes de começar", com a versão curta do aviso:

    Conteúdo educativo. Não substitui atendimento profissional. Emergência: ligue 192.

    O app só segue depois de tocar em "Entendi". O botão "Ler o aviso completo" abre a tela "Sobre".

  • Aberturas seguintes: o aviso não aparece mais e o app abre direto no login. Se o texto canônico mudar, o aviso volta uma vez para quem confirmou a versão antiga.

  • Tela "Sobre": mostra a versão longa do aviso, copiada literalmente do escopo.

    • Paciente: abre pelo menu "Mais › Sobre" e também pelo link "Sobre o SinalACS" na tela de login, sem precisar entrar (pilar A). Reaproveita o widget LocalProtectionNotice da [RNF03] Cifra local dos dados do app do paciente com PIN #136, como pedido no comentário da issue, em vez de repetir o texto.
    • ACS: abre pelo menu "Mais › Sobre" do painel. O aviso da cifra local é só do paciente e não entra.

Como foi feito

Peça Onde O que faz
Texto canônico apps/{patient,acs}/lib/core/legal/educational_notice.dart Guarda as versões longa e curta e a versão do texto (educationalNoticeVersion). Os apps não têm pacote em comum, então são duas cópias, travadas por teste.
Confirmação persistida mesmo arquivo (EducationalNoticeStore) Grava em shared_preferences, na chave aviso_educativo_confirmado, junto com a versão do texto. Se a leitura falhar, o aviso aparece. Se a gravação falhar, a pessoa não fica presa: o aviso só volta na próxima abertura.
Portão da primeira abertura apps/{patient,acs}/lib/app/educational_notice_screens.dart (EducationalNoticeGate) Fica no home do MaterialApp, antes do login. No ACS, fica antes também da retomada da sessão por biometria; a checagem da limpeza remota (#81) continua na raiz e não espera o aviso.
Tela "Sobre" mesmo arquivo (AboutScreen) Mostra o texto longo; no paciente, também o LocalProtectionNotice.
Entradas no app apps/{patient,acs}/lib/app/app.dart Item more_about no menu "Mais" dos dois apps e login_about_link no login do paciente. A folha "Mais" do paciente passou a rolar, para caber o novo item com fonte grande.
Testes existentes test/flutter_test_config.dart e integration_test/flutter_test_config.dart nos dois apps Os outros testes sobem o app como um aparelho que já confirmou o aviso, para não pararem nessa tela. geofence_gps_e2e.dart roda por flutter drive, que ignora esse arquivo, então recebe a confirmação diretamente.
Teste do backup Android apps/patient/test/android_backup_manifest_test.dart Passa a permitir educational_notice.dart como mais um arquivo que importa shared_preferences.

Critérios de aceite da #125

  • A primeira abertura exibe o aviso curto e só segue após confirmação. Coberto por widget test nos dois apps e conferido no emulador.
  • A tela "Sobre" exibe o aviso longo, copiado literalmente. O teste lê spec/escopo_projeto.md e reprova qualquer diferença. No ACS, outro teste compara a cópia do ACS com a do paciente.
  • Teste de widget para as duas telas nos dois apps. Está em apps/{patient,acs}/test/educational_notice_test.dart, que cobre:
    • o aviso aparece antes do login e "Entendi" segue e grava;
    • se o aviso já foi confirmado, o app abre direto no login;
    • se a leitura falha, o aviso aparece;
    • dá para ir e voltar entre o aviso e "Sobre", e "Sobre" abre pelo login (paciente) e pelo menu "Mais";
    • a 200% de fonte, nada estoura e o botão continua alcançável;
    • a confirmação de outra versão do texto não vale;
    • em produção a loja é a persistente, e nada em lib/ a troca.

Como foi verificado

  • flutter analyze: sem avisos nos dois apps.
  • Testes do paciente: 347 de 347 passaram.
  • Testes do ACS: 824 passaram e 2 falharam, ambos em test/mqtt_tls_refused_test.dart. A falha é do ambiente Windows: lá, a recusa TLS do servidor de teste chega ao cliente como NoConnectionException, não como erro de socket. Esta mudança não toca no MQTT, e a CI roda em Linux.
  • Emulador Android (API 37) com a stack local via Docker Compose:
    • o aviso aparece antes do login nos dois apps;
    • "Ler o aviso completo" abre "Sobre";
    • "Entendi" segue, e ao reabrir o app ele vai direto ao login;
    • o link "Sobre o SinalACS" aparece no login do paciente;
    • "Mais › Sobre" abre nos dois apps depois de um login real: paciente sintético com OTP, ACS com matrícula e senha.

Fora deste PR

  • Aviso em "toda tela inicial dos apps": a regra do escopo vai além da C-02, porque hoje a versão curta só aparece na primeira abertura, não no login a cada vez. Fica registrado no PROGRESS.md.
  • Texto legal: é a C-01.
  • Outros itens de "Sobre": as licenças (MIT e CC BY 4.0) são da C-03, e "Apagar meus dados" é da C-10.
  • App do backoffice (apps/admin): não entra, porque a C-02 cobre só os apps do paciente e do agente.

Mostra o aviso curto canônico antes do login nos apps do paciente e do agente, e só segue depois de Entendi. A confirmação fica gravada com a versão do texto. A tela Sobre mostra o aviso longo; no paciente ela reaproveita o LocalProtectionNotice da #136. Testes de widget para as duas telas nos dois apps, com o texto comparado ao de spec/escopo_projeto.md.

Closes #125
Comment thread PROGRESS.md
- **Testes.** Widget tests das duas telas nos dois apps: aviso antes do login, "Entendi" segue e grava, já confirmado abre direto no login, leitura que falha mostra o aviso, ida e volta para "Sobre", 200% de fonte sem estouro, loja de `shared_preferences` (versão diferente não vale). Os outros testes sobem o app como aparelho que já confirmou: `test/flutter_test_config.dart` e `integration_test/flutter_test_config.dart` trocam `educationalNoticeStoreFactory`; um teste confere na fonte que o padrão de produção é a loja persistente e que nada em `lib/` o troca. `integration_test/geofence_gps_e2e.dart` roda por `flutter drive`, que não aplica o `flutter_test_config.dart`, e injeta a loja confirmada.

**Abertos e limites.**
- Rodado em 2026-11-08 no Windows (Flutter 3.44.8): `flutter analyze` limpo nos dois apps; paciente 347/347; ACS 824 passam e 2 falham em `test/mqtt_tls_refused_test.dart` (a recusa TLS do servidor de teste chega ao cliente como `NoConnectionException` no Windows, não como erro de socket; a C-02 não toca no MQTT, e a CI roda em Linux).

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

O CONTRIBUTING.md pede para não gravar contagens de testes nos documentos ("elas envelhecem a cada PR"). Sugiro deixar esta linha assim, e manter as contagens só no corpo da PR:

  • flutter analyze limpo e suítes verdes nos dois apps em Windows e em Linux (a diferença do Windows em test/mqtt_tls_refused_test.dart é do ambiente: a recusa TLS chega como NoConnectionException; a C-02 não toca no MQTT).

Rodei a suíte do ACS em Linux e mqtt_tls_refused_test.dart passa (7/7).

/// Trocar o texto canônico exige trocar esta versão: quem confirmou o texto
/// antigo vê o novo na próxima abertura, em vez de seguir com uma confirmação
/// de um texto que nunca leu.
const educationalNoticeVersion = '2026-11-01';

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

educationalNoticeVersion é mantida à mão. O teste do escopo pega um texto divergente, mas não um bump esquecido: quem trocar o texto e não a versão deixa quem já confirmou sem ver o texto novo. Uma forma barata de prender as duas, sem mudar a API, é um teste em cada app que falhe quando o texto mudar sem a versão:

// `package:crypto` já é dependência dos dois apps.
test('trocar o texto exige trocar a versão', () {
  // Atualize os dois valores juntos quando o escopo mudar.
  expect(educationalNoticeVersion, '2026-11-01');
  final digest = sha256.convert(utf8.encode(educationalNoticeLong + educationalNoticeShort)).toString();
  expect(digest.substring(0, 12), '<valor atual>');
});

Alternativa: derivar a versão de um hash curto do texto em tempo de compilação. Opcional; pode ficar para depois.

import 'package:sinalacs_patient/app/local_protection_notice.dart';
import 'package:sinalacs_patient/core/legal/educational_notice.dart';

/// Primeira abertura (RF21, C-02): o aviso educativo curto, e o app só segue

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Só para deixar escrito: a aceitação dos termos foi feita como prompt, não portão, para o alerta de emergência nunca esperar. Aqui o portão vem antes de tudo, inclusive da aba de urgência, e acho que está certo: a #125 pede "só segue após confirmação", é um toque, e o texto curto já traz "Emergência: ligue 192". Vale uma frase no bloco do PROGRESS.md registrando essa decisão, para quem ler a #153/#137 não a tomar por descuido.

Comment thread apps/acs/lib/app/app.dart
builder: (context, ready, _) => ready ? _loginScreen() : const _WipeHold(),
// Aviso educativo da primeira abertura (RF21) antes do login.
builder: (context, ready, _) => ready
? EducationalNoticeGate(store: _educationalNotice, child: _loginScreen())

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Conferi a ordem: _WipeHold → EducationalNoticeGate → _loginScreen(), com o AppLockGate no builder, acima do Navigator. A recriação do gate por ValueKey(_gateGeneration) não toca no home, então o State do portão (e a confirmação em memória) sobrevive a "Entrar com senha". Nada a mudar.

@hbgit hbgit left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revisei a PR contra a issue #125, o escopo (spec/escopo_projeto.md#aviso-educativo) e o pedido de reaproveitar o LocalProtectionNotice. Os três critérios de aceite estão atendidos e provados por teste:

Critério da #125 Evidência
Primeira abertura exibe o aviso curto e só segue após confirmação test/educational_notice_test.dart nos dois apps: "mostra o aviso curto e só segue para o login depois de Entendi" afirma que o login não está montado antes do toque e está depois, e que a loja gravou uma vez.
"Sobre" exibe o aviso longo, copiado literalmente Os testes "as duas versões são cópia literal de spec/escopo_projeto.md" leem o escopo e comparam; no ACS, "o texto é o mesmo do app do paciente" compara as duas cópias.
Teste de widget para as duas telas nos dois apps 9 testWidgets no paciente e 8 no ACS: primeira abertura, já confirmado, leitura que falha, ida e volta para "Sobre", "Sobre" pelo login (paciente) e pelo menu "Mais", 200 % de fonte nas duas telas.

O LocalProtectionNotice entra em "Sobre" do paciente pelo mesmo widget de "Lembretes" e "Meus dados", como pedido na issue; no ACS fica de fora por desenho, e concordo.

O que rodei em Linux (Flutter estável, worktree limpo da branch):

  • flutter test completo: paciente 347 passam; ACS 826 passam. test/mqtt_tls_refused_test.dart passa aqui (7/7), o que confirma que a falha descrita na PR é só do ambiente Windows.
  • flutter analyze nos dois apps: só o aviso asset_directory_does_not_exist de assets/certs/, que é o diretório gitignorado que scripts/dev/sync_dev_ca.sh cria; não é desta PR.
  • bash scripts/qa/check_documentation_links.sh: nada novo (o único "ausente" é graphify-out, gitignorado, em AGENTS.md, já assim em develop).
  • CI: 9 de 9 verdes, inclusive android-e2e.

Pontos que conferi no código e aprovo:

  • Portão no home do MaterialApp: no ACS, depois de _WipeHold (a limpeza remota da #81 não espera o aviso) e antes de _loginScreen(); o AppLockGate fica no builder, acima, e a recriação do gate por _gateGeneration não desmonta o EducationalNoticeGate, então a confirmação em memória sobrevive.
  • Semântica de falha: leitura que falha mostra o aviso; gravação que falha não prende a pessoa (o estado muda antes do await). As duas metades têm teste (_FailingStore).
  • O seam educationalNoticeStoreFactory só é atribuído na declaração e nos quatro flutter_test_config.dart; o teste "nada em lib/ a troca" prende o lado de produção. geofence_gps_e2e.dart é mesmo o único que roda por flutter drive.
  • Backup Android: sharedpref continua excluído de cloud-backup e device-transfer; a confirmação some num aparelho novo, coerente com a #136.
  • Acessibilidade: alvos 48×52/48×48, Semantics(header: true) nos títulos, só onSurface/onSurfaceVariant como cor de texto (nenhum fill clínico como texto).
  • Duas cópias de educational_notice.dart sem pacote comum, travadas por teste: aceito, como totp.dart.

Pedidos (pequenos, nesta PR): ver os comentários inline em PROGRESS.md e o comentário sobre a mensagem do commit.

Sugestões (opcionais): prender educationalNoticeVersion ao texto; link "Sobre" no login do ACS.

Registros (só documentam): o portão de um toque antes da aba de urgência é decisão consciente que vale registrar; a regra do escopo "toda tela inicial" fica para a issue de continuação que abro ao aprovar.

@hbgit

hbgit commented Nov 13, 2026

Copy link
Copy Markdown
Owner

Pedido: mensagem do commit. O corpo do commit eb78c64 está truncado ("A confir..."). Antes do merge, um git commit --amend com o texto completo (pode ser o resumo da PR) e push --force-with-lease; ou, se preferir, faço o merge por squash com o corpo da PR como mensagem.

Sugestão (opcional): "Sobre" no login do ACS. O paciente tem o link no login (pilar A, sem sessão); no ACS, "Sobre" só aparece depois do login. A C-02 não exige, mas um TextButton igual ao do paciente deixaria o aviso longo alcançável antes de entrar.

Registro (UX, sem pedido): no paciente, a primeira abertura encadeia o diálogo de permissão de notificação (#153) e depois o aviso. Nada quebra; fica como nota para a #137.

Continuação: a regra do escopo "toda tela inicial dos apps" fica na #164, bloqueada pelo merge desta PR.

Mantém as três seções novas do PROGRESS.md (#125, #153 e #151).
@hbgit
hbgit merged commit 8ade3c9 into develop Nov 13, 2026
10 checks passed
@hbgit
hbgit deleted the feat/c-02-aviso-educativo branch November 13, 2026 13:59
hbgit added a commit that referenced this pull request Nov 14, 2026
hbgit added a commit that referenced this pull request Nov 14, 2026
docs(plano): distribuição das issues do Pilot e revisões das PRs #155–#163
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants