Especificação de Requisitos de Software
Neemias
1. Introdução
Este documento define os requisitos funcionais e não-funcionais do Neemias. O sistema é uma aplicação de chamada e presença baseada em navegador com backend primário, resiliência offline, controle de acesso baseado em papéis e requisitos de LGPD e WCAG nível AA.
2. Visão Geral do Sistema
O sistema deve suportar um pequeno número de usuários simultâneos em ambiente de navegador móvel e de desktop. Ele deve ser concebido como um progressive web app modular com sincronização em nuvem.
3. Definições
| Termo | Significado |
|---|---|
| Aluno | Pessoa cuja presença é registrada. |
| Ação de presença | Uma marcação de presente, ausente ou outro estado futuro de presença. |
| Ação de admin | Qualquer ação executada por um usuário admin que sobrepõe ações conflitantes de menor privilégio. |
| Backend primário | O app opera contra o backend Cloudflare Worker; recorre ao IndexedDB local (via Dexie) quando offline. |
| Sincronização | O processo de reconciliar as alterações locais com o servidor quando a conectividade retorna. |
4. Papéis de Usuário e Controle de Acesso
| ID do Requisito | Requisito |
|---|---|
| FR-001 | O sistema deve suportar os papéis ADMIN, CHAMADOR, RELATORIOS, CADASTRO, RESPONSAVEL, VOLUNTARIO, COORDENACAO_KIDS e ADMINISTRATIVO_KIDS (8+ papéis). |
| FR-001-A | O sistema deve suportar atribuição de múltiplos papéis — os usuários podem acumular vários papéis simultaneamente por meio de uma tabela de junção user_roles. (v0.56.0+) |
| FR-001-B | O sistema deve resolver AuthPrincipal.roles[] com um primaryRole para exibição, usando uma hierarquia explícita de papéis. (v0.56.0+) |
| FR-001-C | requireRole() deve usar correspondência any() — o usuário passa se ao menos um papel corresponder à lista de permitidos. (v0.56.0+) |
| FR-001-D | A resolução de escopo para usuários com múltiplos papéis deve produzir uma união composta (a mais permissiva entre os papéis). A sanitização deve aplicar a mais restritiva entre os papéis. (v0.56.0+) |
| FR-002 | O sistema deve aplicar o princípio do menor privilégio a todas as ações por papel. |
| FR-003 | O sistema deve permitir que usuários chamadores busquem alunos e marquem presença. |
| FR-004 | O sistema deve permitir que contas de usuário de relatórios vejam apenas relatórios. |
| FR-005 | O sistema deve permitir que usuários de cadastro adicionem alunos. |
| FR-006 | O sistema deve permitir que usuários admin acessem relatórios, marquem presença, adicionem alunos, editem alunos e removam alunos. |
| FR-007 | O sistema deve exigir um campo de texto com justificativa antes de aceitar qualquer remoção de aluno. |
| FR-008 | O sistema deve rejeitar ações não autorizadas com um estado de falha claro e um registro auditável. |
| FR-NEW-01 | O sistema deve permitir que ADMIN_USER veja todos os usuários com nome, nome de usuário, papel e status. |
| FR-NEW-02 | O sistema deve permitir que ADMIN_USER crie usuários com nome de usuário único (3 a 50 caracteres, /[1]+$/), displayName (1 a 100 caracteres), papel e senha (mínimo de 8 caracteres). |
| FR-NEW-03 | O sistema deve permitir que ADMIN_USER edite o displayName e o papel de qualquer usuário. |
| FR-NEW-04 | O sistema deve permitir que ADMIN_USER redefina a senha de qualquer usuário. |
| FR-NEW-05 | O sistema deve permitir que ADMIN_USER desative usuários; usuários desativados não conseguem fazer login. |
| FR-NEW-06 | O sistema deve bloquear a autodesativação. |
| FR-NEW-07 | O sistema deve bloquear a desativação do último ADMIN_USER ativo. |
| FR-NEW-09 | O sistema deve implementar hashing de senha PBKDF2-600k para autenticação local. (v0.53.0+) |
| FR-NEW-10 | O sistema deve aplicar bloqueio de login com backoff exponencial (5s→30s) após falhas consecutivas, e bloqueio definitivo após 10 falhas (15min). (v0.53.0+) |
| FR-NEW-11 | O sistema deve implementar Content Security Policy por meio de uma CSP estática baseada em hash, gerada em app/public/_headers no momento do build. (v0.55.0+) |
| FR-NEW-12 | O sistema deve usar o padrão EntityRepository (D1EntityRepo + MemoryEntityRepo) para acesso a dados na camada Worker. (v0.54.0+) |
| FR-NEW-13 | O sistema deve suportar troca de tema em tempo de execução via atributo data-theme com 4 temas embutidos (light, warm, dark, ijcp). (v0.54.0+) |
| FR-NEW-14 | O sistema deve fornecer um adaptador de armazenamento OnlineProxy que delega leituras/escritas pela API do Worker quando o backend está acessível. (v0.53.0+) |
| FR-NEW-15 | O sistema deve gravar registros imutáveis de UserEvent para todas as ações de gestão de usuários. |
5. Requisitos Funcionais
| ID do Requisito | Requisito |
|---|---|
| FR-010 | O sistema deve permitir que os usuários busquem alunos por nome e outros identificadores configurados. |
| FR-011 | O sistema deve exibir a foto do aluno imediatamente quando um resultado correspondente é mostrado. |
| FR-012 | O sistema deve suportar o registro de presença de um aluno em um pequeno número de passos. |
| FR-013 | O sistema deve preservar um histórico das ações relacionadas a alunos e das ações de presença. |
| FR-014 | O sistema deve suportar a criação offline de ações e postergar a sincronização até que a conectividade retorne. |
| FR-015 | O sistema deve reconciliar ações conflitantes conforme a precedência de admin, em que ações de admin sobrepõem ações de menor privilégio. |
| FR-016 | O sistema deve reter ações offline não sincronizadas caso a sessão do usuário expire enquanto estiver offline. |
| FR-017 | O sistema deve exigir reautenticação antes de enviar ações após o vencimento da sessão. |
| FR-018 | O sistema deve suportar módulos de funcionalidades futuras, como novos relatórios, sem exigir um grande redesenho. |
| FR-019 | O sistema deve definir o português do Brasil como padrão para todo o texto voltado ao usuário. |
| FR-020 | O sistema deve fornecer uma arquitetura que permita adicionar idiomas adicionais depois. |
| FR-021 | O sistema deve fornecer feedback visual e sonoro para ações bem-sucedidas e malsucedidas. |
| FR-022 | O sistema deve fornecer uma etapa de conferência dupla ou verificação equivalente antes de efetivar alterações visíveis ao usuário. |
| FR-023 | O sistema deve apresentar as listas de alunos em ordem alfabética pelo nome de exibição localizado. |
| FR-024 | O sistema deve fornecer uma visão de perfil/detalhes do aluno que exponha a identidade, a foto e o estado de presença recente do aluno. |
6. Requisitos Não-Funcionais
| ID do Requisito | Requisito |
|---|---|
| NFR-001 | O sistema deve ser acessível em conformidade com o nível AA das WCAG. |
| NFR-002 | O sistema deve operar como progressive web app em navegadores móveis e de desktop. |
| NFR-003 | O sistema deve ser otimizado para interação rápida e baixa latência percebida. |
| NFR-004 | O sistema deve usar cache agressivo para ativos estáticos e recursos da aplicação reutilizados com frequência. |
| NFR-005 | O sistema deve suportar operação offline para todos os fluxos essenciais de chamada. |
| NFR-006 | O sistema deve sincronizar as alterações enfileiradas quando a conectividade com a internet retornar. |
| NFR-007 | O sistema deve proteger os dados pessoais armazenados usando criptografia adequada ao armazenamento do navegador (tanto no trânsito até o backend quanto no fallback local). |
| NFR-008 | O sistema deve usar controles de segurança que suportem as obrigações da LGPD onde aplicável. |
| NFR-009 | O sistema deve limitar o acesso aos dados por papel e por necessidade de conhecimento. |
| NFR-010 | O sistema deve permanecer sustentável por meio de fronteiras modulares que suportem o crescimento futuro de funcionalidades. |
| NFR-011 | O sistema deve suportar o uso simultâneo por aproximadamente 3 a 5 usuários ativos. |
| NFR-012 | O sistema deve persistir as ações do usuário localmente até que sejam confirmadas como sincronizadas ou explicitamente rejeitadas. |
7. Requisitos de Dados
| ID do Requisito | Requisito |
|---|---|
| DR-001 | Os registros de aluno devem incluir, no mínimo, um identificador único, o nome de exibição e uma referência de foto. |
| DR-002 | Os registros de presença devem incluir referência ao aluno, status, autor, timestamp e estado de sincronização. |
| DR-003 | Os registros de exclusão devem incluir o usuário que excluiu, o timestamp e o texto de justificativa. |
| DR-004 | O sistema deve manter uma trilha de auditoria de eventos de criação, atualização, exclusão e presença. |
| DR-005 | O sistema deve manter registros históricos suficientes para revisão de conformidade e revisão operacional. |
| DR-NEW-01 | Os registros de usuário devem incluir identidade do usuário, papel, status, passwordHash e timestamps de ciclo de vida. |
| DR-NEW-02 | Os eventos de auditoria de usuário devem ser somente de acréscimo e não devem incluir passwordHash no payload de alteração. |
8. Requisitos de Sincronização e Conflito
| ID do Requisito | Requisito |
|---|---|
| SR-001 | O sistema deve enfileirar as alterações offline localmente até que possam ser sincronizadas. |
| SR-002 | O sistema deve aplicar regras de resolução de conflitos no lado do servidor durante a sincronização. |
| SR-003 | O sistema deve tratar ações de admin como autoritativas sobre ações conflitantes de menor privilégio. |
| SR-004 | O sistema deve preservar todos os eventos conflitantes no histórico mesmo quando um evento é sobreposto. |
| SR-005 | O sistema deve expor claramente ao usuário os estados de sucesso e de falha da sincronização. |
9. Requisitos de Segurança e Conformidade
| ID do Requisito | Requisito |
|---|---|
| SCR-001 | O sistema deve exigir autenticação antes que um usuário possa enviar ações protegidas. |
| SCR-002 | O sistema deve exigir reautenticação após o vencimento do TTL da sessão. |
| SCR-003 | O sistema deve suportar tratamento de sessão ciente do modo offline por até o período de sessão configurado. |
| SCR-004 | O sistema deve minimizar a retenção de dados sensíveis no dispositivo quando a sessão não for mais válida para o envio de ações. |
| SCR-005 | O sistema deve estar em conformidade com os requisitos da LGPD onde aplicável. |
| SCR-006 | O sistema deve implementar logging de acesso suficiente para responsabilização e auditoria. |
| SCR-007 | O sistema deve tratar a remoção de aluno como uma ação administrativa sensível. |
| SCR-NEW-01 | O sistema deve gerar hash de senhas usando SHA-256 via window.crypto.subtle e nunca persistir senhas em texto puro. |
10. Notas de Aceitação
A implementação é considerada alinhada a esta SRS apenas se todas as condições a seguir permanecerem verdadeiras:
- O português do Brasil é o idioma padrão.
- Ações de admin vencem conflitos.
- O trabalho offline é preservado e sincronizado depois.
- A remoção de aluno exige justificativa.
- As fotos são exibidas imediatamente nos resultados de busca.
- Acessibilidade e LGPD são tratadas como requisitos de primeira classe, não como melhorias opcionais.
11. Decisões Arquiteturais em Aberto
| Tópico | Requisito |
|---|---|
| Hospedagem | Deve permanecer implantável em nuvem sem pressupostos de aprisionamento a fornecedor. |
| Autenticação | Deve suportar sessões de curta duração com reautenticação após o vencimento. |
| Armazenamento | Deve suportar fallback local em IndexedDB, adequado à operação offline quando o backend estiver inacessível. |
| Criptografia | Deve depender, quando possível, de criptografia compatível com o navegador e baseada em padrões. |
| Expansão de idiomas | Deve suportar locales adicionais por meio de arquivos de recursos modulares. |
a-z0-9- ↩︎