Decisões de UX da rodada 2026-05 (v0.9.0-beta4)¶
Diátaxis: explanation. Registra por que decisões de UX foram tomadas, não como executá-las.
Esta nota acompanha a sequência de PRs entregues entre 2026-05-07 e 2026-05-08 (PRs #17 a #21). Documenta opções consideradas, trade-offs e quando reabrir cada decisão.
1. Tema seguindo o sistema operacional por padrão¶
Decisão: AppConfig.theme = "auto" (segue Qt 6.5+
QStyleHints.setColorScheme).
Opções consideradas:
| Opção | Vantagem | Desvantagem |
|---|---|---|
light (status quo) |
Menos surpresa em testes | Quebra hábito do usuário com tema escuro do SO |
dark por padrão |
Combina com o ethos "ferramenta de profissional sério" | Surpreende usuários acostumados ao light |
auto ✅ |
Respeita preferência do usuário no SO | Requer Qt 6.5+ (já temos 6.6+) |
Por que reabrir:
- Se o STYLESHEET custom evoluir e quebrar contraste em um dos
modos, talvez forçar light em modo "alto contraste" temporário.
- Se Qt expor uma API para reaplicar styleSheet sem restart, mudar
da exigência de restart para reload-ao-vivo.
2. Atalhos com letras em vez de números¶
Decisão: Ctrl+M, Ctrl+T, Ctrl+B, Ctrl+J, Ctrl+/ (letras
mnemônicas).
Mnemônicas:
- M = Meu Perfil
- T = Templates
- B = Backups
- J = "números" — N está reservado para Novo (Ctrl+N)
- / = padrão de "search-like" usado em Slack, Linear, etc.
Conflitos evitados:
- Ctrl+N (Novo), Ctrl+S (Salvar), Ctrl+E (Exportar),
Ctrl+P (Pacientes — o usuário associa P a "paciente"),
Ctrl+Q (Sair).
- Atalhos do navegador não conflitam — a janela do app é desktop
Qt, não roda dentro de browser.
Por que reabrir:
- Se acessibilidade WCAG ASA exigir atalhos com modificadores menos
ergonômicos para telas TTS, oferecer alternativa.
- Internacionalização (v4.0): mnemônicos em PT-BR podem precisar
reanálise para PT-PT, ES, FR (B para Backups vira problema?).
3. Tooltips em todos os campos críticos¶
Decisão: 11 dialogs ganharam setToolTip() em todos campos
e botões expostos. Cada tooltip explica:
1. Propósito do campo
2. Se o conteúdo fica em claro ou cifrado em repouso
3. Pré-requisitos (validação, formato, restart)
Por que essa exaustividade: - WCAG 2.1 AA (CLAUDE.md §1.2) exige reforço textual além de rótulos. - Aproveitamos para reforçar privacy-by-design no próprio fluxo — o usuário descobre que CNS/CPF/nome ficam cifrados sem ler doc.
Por que reabrir: - Em revisão de UX profissional (não realizada), tooltips podem ser considerados redundantes em campos óbvios. Trim seletivo após feedback de campo.
4. AboutDialog com 4 abas em vez de QMessageBox.about()¶
Decisão: dialog dedicado com abas Sobre / Licença AGPL-3.0 / Terceiros / Histórico.
Motivos:
- AGPL-3.0 §6 + §10 exigem que o usuário tenha acesso ao texto da
licença e à origem do código. QMessageBox.about() não tinha
espaço para texto integral.
- IEC 62304 §5.3/§8 (transparência de SOUP) — terceiros precisam
estar acessíveis ao operador.
- Compliance forte é decisão de longo prazo: vale o investimento
vs. reescrita futura.
Por que reabrir:
- Quando o app rodar em quiosque de UBS sem internet, links
externos quebram. Considerar empacotar THIRD_PARTY_NOTICES.md e
CHANGELOG.md no --onedir do PyInstaller para abrir local.
5. Dashboard "Meus números" sem gráficos¶
Decisão: apresentar tudo em QTableWidget Top-20.
Trade-offs avaliados:
| Opção | Vantagem | Desvantagem |
|---|---|---|
| Tabelas ✅ | Zero deps; densidade alta; Ctrl+C nativo | Visualmente plano |
| QtCharts (LGPL) | Bonito; nativo Qt | Adiciona deps; problemas LGPL em static binary |
| PyQtGraph (MIT) | Pure Python; rápido | Adiciona deps; UX diferente do resto do app |
| matplotlib | Universal | Pesado; dispara eventos diferentes do Qt |
Por que reabrir: - Se feedback de UBS pedir gráfico de tendência (essencial para reuniões de equipe), avaliar PyQtGraph como dep opt-in (ativada só se instalada). - Um sparkline minimalista cabe em ASCII puro — alternativa intermediária se gráficos virarem requisito sem aceitar dep nova.
6. CLI sem operações que descifram o vault¶
Decisão: anotae backup create/list/verify opera só sobre
arquivos cifrados em repouso e seus hashes; não existe
anotae export, anotae list-encounters etc.
Motivos:
- Senha-mestra não pode aparecer em ps aux, em scripts shell, ou
em logs de cron.
- Operações destrutivas (restore) merecem dupla confirmação visual,
não sair de cron silenciosamente.
- Reduz superfície de ataque: tudo que descifra fica restrito ao
processo Qt do usuário.
Por que reabrir:
- Se um cenário de exportação periódica supervisionada surgir
(exporta XLSX para pasta sincronizada com Drive corporativo),
considerar leitor stdin para senha-mestra com getpass e flag
explícita --unsafe-stdin-password. Default permanece negar.
Como retomar essas decisões¶
Cada decisão foi capturada com: 1. O que foi feito (acima). 2. Por que alternativas foram descartadas. 3. Quando reabrir — gatilhos concretos.
Ao reabrir, edite esta nota com a nova rodada datada (ex.: "2026-08 revisita: …") em vez de apagar o histórico — preserva trilha de auditoria para a equipe que assumir o projeto.