Skip to main content

​
Documento de Requisitos de Software: Followw UnB

Versão: 0.2.0 (Escopo da Release 2 / Sprints 1 a 7)
Data: 16 de Outubro de 2026

​
1. Visão Geral do Projeto

O Followw UnB é um cliente alternativo open-source projetado para consolidar os sistemas da Universidade de Brasília (UnB) em uma experiência unificada, ágil e moderna. O projeto atua sobre a fragmentação dos serviços universitários — historicamente dispersos entre o SIGAA, sites estáticos do Restaurante Universitário (RU), calendários acadêmicos em PDF e notícias institucionais desarticuladas. A solução combina uma API pública e independente (FastAPI) e um front-end web progressivo (React, TanStack Router, Vite e Tailwind CSS). Seu grande diferencial é viabilizar o acesso rápido, seguro e stateless à área autenticada do SIGAA, empregando técnicas avançadas de cache (stale-while-revalidate), sincronização concorrente em segundo plano, suporte a funcionamento offline, proteção contra abusos via rate limiting (Redis) e catálogo público estruturado.

​
Pilares Filosóficos e Arquiteturais

  • Código Aberto (Open Source): Todo o repositório é distribuído sob licença permissiva MIT, permitindo auditoria de segurança, manutenção comunitária e transparência no tratamento de dados estudantis.
  • Privacidade por Design e Sessão Stateless: O Followw não cria conta própria nem armazena senhas institucionais em bancos de dados ou logs. A autenticação é delegada ao CAS/SIGAA da UnB e mantida em cookies cifrados no próprio navegador do estudante.
  • Modularidade e Baixo Acoplamento: A arquitetura separa a biblioteca de comunicação com o SIGAA (sigaa-client), os módulos de portais públicos da UnB (unb-browser), a API e o front-end web.
  • Experiência Offline-First e PWA: Dados acadêmicos consultados previamente ficam acessíveis no dispositivo do usuário mesmo sem conexão ativa à internet por até 14 dias.
  • Resiliência e Proteção Institucional: Rate limiting distribuído em memória (Redis) para prevenir abusos de força bruta e sobrecarga no CAS/SIGAA, operando em modelo tolerante a falhas (fail-open).
  • Usabilidade e Acessibilidade: Interface moderna construída sobre componentes reutilizáveis, suporte a tema escuro/claro, comunicação visual clara e tratamento resiliente de indisponibilidades dos sistemas legados da universidade.

​
2. Requisitos Funcionais (RF)

Os requisitos funcionais estão estruturados em 4 Épicos Centrais, englobando suas Histórias de Usuário, requisitos formais e critérios de aceitação testáveis.

​
ÉPICO 1: Autenticação, Perfil e Preferências do Estudante

Conjunto de funcionalidades responsáveis por mediar o acesso autenticado ao SIGAA, gerenciar sessões seguras e efêmeras, apresentar a situação cadastral do aluno e permitir personalizações na interface.

​
1.1: Autenticação de Usuário e Acesso ao SIGAA

Histórias de Usuário:
  • US01: Como estudante, quero realizar login com minha matrícula e senha do SIGAA sem que as credenciais fiquem retidas em servidores ou bancos de dados externos.
  • US02: Como estudante autenticado, quero acessar com rapidez os recursos e dados acadêmicos protegidos do portal do discente.
  • US03: Como estudante, quero poder exibir ou ocultar os caracteres da senha digitada no formulário de login para conferência antes do envio.
  • US04: Como estudante com sessão ativa, quero ser redirecionado automaticamente para a página inicial caso acesse a rota de login.
  • RF01 — Autenticação de Usuário via SIGAA: O sistema deve fornecer endpoint (POST /auth/sigaa) e tela de login dedicada que recebe a matrícula e senha do estudante, valida-as no CAS/SIGAA da UnB e inicializa a sessão emitindo cookies cifrados (access_token e refresh_token), sem persistir a senha em banco de dados ou logs.
Critérios de Aceitação:
  • Credenciais inválidas ou contas bloqueadas no SIGAA devem retornar HTTP 401 acompanhado de mensagem clara na interface.
  • O campo de senha deve dispor de botão para alternar a visibilidade dos caracteres (show/hide password).
  • A sessão do usuário dura enquanto forem válidos os cookies originais da sessão do SIGAA, sendo renovada automaticamente quando oportuno.
  • Usuários já logados que navegam até a página /login devem ser redirecionados imediatamente à tela principal (/).

​
1.2: Logout Seguro

Histórias de Usuário:
  • US05: Como estudante, quero poder encerrar minha sessão a qualquer momento.
  • US06: Como estudante, quero ter a garantia de que ao sair da conta todos os dados privados temporariamente salvos no dispositivo sejam removidos.
  • RF02 — Logout Seguro e Limpeza de Sessão: O sistema deve fornecer encerramento de sessão (POST /auth/logout) que invalida imediatamente os tokens emitidos e expurga os dados pessoais cacheados no navegador do discente.
Critérios de Aceitação:
  • Ao acionar logout, os cookies de autenticação devem ser expirados via cabeçalho Set-Cookie com Max-Age=0.
  • A camada cliente deve limpar chaves de dados confidenciais do discente armazenadas em localStorage e IndexedDB.
  • Requisições subsequentes com cookies antigos devem receber HTTP 401.

​
1.3: Visualização de Perfil Acadêmico e Carga Horária Pendente

Histórias de Usuário:
  • US07: Como estudante autenticado, quero visualizar meus dados acadêmicos básicos (nome, matrícula, curso, unidade e foto).
  • US08: Como estudante autenticado, quero consultar meu Índice de Rendimento Acadêmico (IRA), Média Ponderada (MP) e percentual de integralização curricular.
  • US09: Como estudante autenticado, quero visualizar quantas horas de componentes curriculares ainda faltam para a conclusão do curso, divididas entre obrigatórias, optativas e complementares.
  • RF03 — Perfil Acadêmico e Integralização Curricular (GET /me): O sistema deve disponibilizar endpoint protegido e tela de perfil que retorna name, registration, photo, email, bio, unit, course, integralization, ira, mp, level e o detalhamento das horas pendentes (obrigatórias, optativas e complementares) obtidas do extrato de integralização do SIGAA.
Critérios de Aceitação:
  • A foto do estudante e a dos participantes deve usar formato e proporção padronizada (3:4), exibindo ícone fallback quando não houver imagem cadastrada.
  • Valores numéricos de horas pendentes e percentual de integralização ausentes no SIGAA devem ser omitidos sem quebrar o layout.
  • Os dados devem ser sincronizados em background, exibindo a versão em cache com carregamento instantâneo.

​
1.4: Configurações e Preferências Pessoais

Histórias de Usuário:
  • US10: Como estudante, quero poder escolher como meu nome é exibido no Followw, sem alterar meu registro civil no SIGAA.
  • US11: Como estudante, quero ter meu campus universitário inferido corretamente sem a necessidade de configuração manual.
  • US12: Como estudante, quero que as informações do Restaurante Universitário abram automaticamente no meu campus de preferência.
  • RF04 — Configurações Pessoais do Usuário (GET e PATCH /me/settings): O sistema deve permitir ao estudante consultar e atualizar preferências locais sincronizadas com a API, incluindo display_name e default_campus, mantendo preferências visuais de tema persistidas no cliente.
Critérios de Aceitação:
  • O nome de exibição, quando definido, substitui o nome civil nas saudações e cabeçalhos do Followw, permitindo restauração do nome original a qualquer momento.
  • A alteração de preferências deve ser pontual (suportando atualização parcial de campos via PATCH).

​
1.5: Política de Privacidade e Termos de Serviço

Histórias de Usuário:
  • US45: Como estudante ou visitante, quero consultar como o Followw trata meus dados, como solicitar sua exclusão e quais são as regras de uso do serviço antes de entrar.
  • RF18 — Consulta Pública de Privacidade e Termos (/privacidade): O sistema deve oferecer uma página pública e transparente com política de privacidade e termos de serviço, acessível por link no rodapé do login e navegação, acompanhado do aviso de concordância ao entrar.
Critérios de Aceitação:
  • A política deve informar os dados mantidos em cache no servidor e no dispositivo, sua finalidade, a ausência de descarte automático no servidor e o prazo de até 14 dias do cache de dados offline.
  • O texto deve distinguir cookies e tarefas com credenciais cifradas da ausência de credenciais no banco e nos logs da API, e informar o uso de métricas e gravação de sessões pelo PostHog.
  • A exclusão dos dados existentes deve ser solicitada por removal@followw.app, com aviso de que não altera registros da UnB nem impede novas coletas em sincronizações futuras.
  • Os termos devem permitir automações responsáveis e proibir sobrecarga, acesso indevido, manipulação mal-intencionada de informações, perseguição e assédio.

​
ÉPICO 2: Gestão de Turmas, Frequência e Rotina Acadêmica

Compreende a sincronização, organização e acompanhamento das disciplinas em que o aluno está inscrito, histórico letivo, controle de frequência, avisos dos professores e agenda do dia.

​
2.1: Listagem de Turmas e Histórico de Semestres com Menções

Histórias de Usuário:
  • US13: Como estudante matriculado, quero listar rapidamente minhas turmas do semestre atual com horário, sala, número de turma e código da disciplina.
  • US14: Como estudante, quero consultar as turmas cursadas em semestres anteriores com o histórico das menções finais obtidas (SS, MS, MM, MI, II, SR).
  • RF05 — Listagem de Turmas e Histórico Letivo (GET /classrooms): O sistema deve fornecer endpoint protegido para listar turmas atuais e anteriores (?semester=all ou ?semester=AAAA.P), informando código, nome da disciplina, turma, horários, local, carga horária e a menção final quando consolidada.
Critérios de Aceitação:
  • As turmas de semestres anteriores devem exibir com destaque visual a menção recebida (colorida conforme a escala de rendimento).
  • Turmas sem sala informada pelo SIGAA devem exibir "Local não informado", sem omitir a matéria.
  • Turmas com matrícula em processamento devem exibir a badge amarela "Em processamento".

​
2.2: Detalhes da Turma e Participantes

Histórias de Usuário:
  • US15: Como estudante, quero abrir uma turma específica e navegar em abas dedicadas para Aulas/Frequência, Postagens e Participantes.
  • US16: Como estudante, quero consultar a lista de docentes e colegas de classe matriculados na mesma turma para contato e trabalhos em grupo.
  • RF06 — Detalhes da Turma e Participantes (GET /classrooms/{id}/members): O sistema deve disponibilizar página de detalhes da disciplina com abas dedicadas e listar discentes e docentes da turma (name, role, registration, photo, email, course, unit).
Critérios de Aceitação:
  • Docentes devem aparecer destacados antes da lista de discentes, que deve vir em ordem alfabética.
  • Caso a turma não exista ou o discente não esteja matriculado nela, deve retornar HTTP 404.

​
2.3: Controle e Estimativa de Frequência

Histórias de Usuário:
  • US17: Como estudante, quero poder marcar manualmente presença, falta ou aula cancelada nas datas que já ocorreram e ainda não receberam chamada oficial no SIGAA.
  • US18: Como estudante, quero acompanhar o percentual consolidado e estimado de frequência para não correr risco de reprovação por falta (< 75%).
  • US19: Como estudante, quero que as chamadas oficiais lançadas posteriormente pelo docente no SIGAA tenham precedência sobre as marcações manuais realizadas.
  • RF07 — Gestão e Estimativa de Frequência (GET e PUT /classrooms/{id}/frequency): O sistema deve permitir ao aluno registrar marcações locais de frequência em aulas sem chamada oficial, calculando o percentual projetado e sinalizando em cores de alerta o risco de reprovação.
Critérios de Aceitação:
  • As chamadas oficiais registradas pelo docente não podem ser sobrescritas por marcações manuais do aluno.
  • O sistema deve sinalizar visualmente com a tag "Estimada" quando o cálculo de frequência incluir anotações manuais do estudante.
  • A barra e texto de frequência devem tingir em verde (> 80%), amarelo (75%–80%) e vermelho (< 75%).

​
2.4: Notícias da Disciplina em Markdown

Histórias de Usuário:
  • US20: Como estudante, quero ler os comunicados postados pelo docente com formatação completa (Markdown), incluindo tabelas, listas e links.
  • US21: Como estudante, quero acessar os comunicados da matéria mesmo se estiver sem internet ou se a publicação for apagada do portal legado.
  • RF08 — Notícias da Disciplina com Suporte a Markdown (GET /classrooms/{id}/news): O sistema deve extrair e exibir comunicados das turmas convertendo a marcação para Markdown higienizado, salvando-os em cache com validade de 60 minutos e retenção persistente.
Critérios de Aceitação:
  • Links externos presentes nas notícias devem abrir obrigatoriamente em nova aba (target="_blank" rel="noopener noreferrer").
  • Notícias consultadas anteriormente devem permanecer legíveis em modo offline.

​
2.5: Agenda Diária e Calendário Acadêmico

Histórias de Usuário:
  • US22: Como estudante, quero consultar na tela inicial minhas aulas do dia atual ordenadas por horário, sabendo qual está em andamento e qual será a próxima.
  • US23: Como estudante, quero poder verificar se vai haver aula em um determinado dia em virtude de feriado, ponto facultativo, Semana Universitária ou período de férias.
  • RF09 — Agenda Diária e Sincronização com o Calendário Acadêmico: O sistema deve integrar o horário das turmas ao calendário oficial da UnB, exibindo a sequência de aulas do dia selecionado, destacando status "Em andamento" / "Próxima" e unificando horários contínuos entre turnos (ex.: 12:00–13:50 e 18:00–19:50).
Critérios de Aceitação:
  • Em dias sem aula previstos no calendário acadêmico, o card de aulas deve ser substituído por informativo com o motivo oficial do evento.
  • Horários contínuos com transição entre turnos (como M5T1 e T6N1) devem ser fundidos em um único cartão de horário.

​
2.6: Sincronização Concorrente e Atualização de Cache

Histórias de Usuário:
  • US24: Como estudante, quero que as páginas carreguem de imediato com os últimos dados salvos, enquanto atualizações ocorrem em segundo plano.
  • US25: Como estudante, quero poder forçar uma revalidação imediata das turmas com o SIGAA puxando a tela para atualizar.
  • RF10 — Sincronização Paralela e Invalidação de Cache: A API deve suportar requisições concorrentes com sessões independentes do SIGAA, servindo respostas imediatas via cache e aceitando o parâmetro ?refresh=true ou cabeçalho Cache-Control: no-cache para atualização manual.
Critérios de Aceitação:
  • Turmas já consolidadas ou de semestres findados não devem disparar novas requisições de raspagem ao SIGAA.
  • Caso o SIGAA apresente erro temporário durante uma revalidação, a versão em cache deve ser preservada e entregue ao discente.

​
ÉPICO 3: Busca, Catálogo e Descoberta de Turmas e Docentes

Funcionalidades de pesquisa e descoberta, permitindo consultar todo o catálogo geral da UnB, analisar concorrência de vagas, pré-requisitos, quadro de professores e recomendações de matrícula.

​
3.1: Catálogo Geral e Consulta Pública de Turmas da UnB

Histórias de Usuário:
  • US26: Como qualquer estudante ou visitante, quero pesquisar as turmas ofertadas na UnB sem precisar de login, filtrando por departamento, código, nome ou professor.
  • US27: Como estudante, quero consultar uma matéria diretamente pelo código da disciplina (ex.: MAT0031 ou FGA0312) sem saber previamente o departamento ofertante.
  • US28: Como estudante em fase de matrícula, quero visualizar o total de vagas e a ocupação em tempo real de cada turma, identificando turmas lotadas.
  • US29: Como estudante autenticado, quero que o catálogo me informe se já atendi aos pré-requisitos ou equivalências da turma com base no meu histórico acadêmico.
  • RF11 — Catálogo Geral e Pesquisa Pública de Turmas (GET /public/classrooms): O sistema deve oferecer busca pública aberta no catálogo geral da UnB, suportando filtros por unidade, código completo ou prefixo, nome da matéria e docente, integrando dataset estruturado para respostas em milissegundos.
Critérios de Aceitação:
  • A busca pública não deve exigir autenticação e deve tolerar variações de acentuação e caixa alta/baixa.
  • A visualização da turma deve exibir barra de progresso com vagas ocupadas sobre o total (ex.: 64 de 80 vagas ocupadas).
  • Para estudantes autenticados, o sistema deve avaliar o histórico escolar e indicar se a turma está liberada ou impedida por pré-requisitos não atendidos.

​
3.2: Estatísticas Históricas de Aprovação

Histórias de Usuário:
  • US30: Como estudante planejando minha matrícula, quero consultar a taxa histórica consolidada de aprovação e reprovação de cada professor na matéria.
  • US31: Como estudante, quero compartilhar um link direto com as estatísticas de aprovação da disciplina com meus colegas.
  • RF12 — Estatísticas Consolidadas de Rendimento (GET /classrooms/{id}/statistics): O sistema deve prover métricas históricas de aprovação e reprovação agrupadas por disciplina e docente, permitindo compartilhamento via URL pública.
Critérios de Aceitação:
  • Nenhuma informação ou menção individual de alunos pode ser exposta nas estatísticas públicas.
  • Turmas sem registros históricos de rendimento devem exibir mensagem informativa orientando o usuário.

​
3.3: Recomendações de Disciplinas

Histórias de Usuário:
  • US42: Como estudante autenticado, quero recomendações que excluam disciplinas já cursadas ou em andamento, inclusive equivalentes, permitindo repetição somente com reprovação confirmada.
  • RF16 — Exclusão de Disciplinas Cursadas e Equivalências (GET /public/subjects): O sistema deve excluir aprovações, matrículas atuais e tentativas sem resultado, considerando as expressões de equivalência do catálogo.
Critérios de Aceitação:
  • A falta de menção após a consolidação não deve ser interpretada como reprovação.
  • Vínculos trancados ou indeferidos não contam como tentativa sem resultado.
  • MI, II ou SR permitem repetir somente sem aprovação, matrícula atual ou outra tentativa incerta.
  • Equivalências devem respeitar grupos E/OU e sua direção, sem inferir reciprocidade ou transitividade.
  • Tentativas sem menção devem presumir aprovação no ranking, liberar pré/correquisitos diretos e por equivalência e contar como concluídas no fluxo, sem alterar a menção armazenada.

​
3.4: Catálogo Público de Docentes da UnB

Histórias de Usuário:
  • US43: Como qualquer estudante ou visitante, quero pesquisar os docentes cadastrados na UnB sem necessidade de login, filtrando por nome ou departamento.
  • US44: Como estudante, quero visualizar o e-mail institucional e o link para a página pública do docente no SIGAA para contato e consulta de orientações e publicações.
  • RF17 — Catálogo Geral e Pesquisa Pública de Docentes (GET /public/professors): O sistema deve oferecer busca pública aberta no quadro docente da UnB, suportando filtros por unidade acadêmica e nome parcial do professor, retornando nome completo, departamento, e-mail institucional e URL do portal público no SIGAA.
Critérios de Aceitação:
  • A busca não deve exigir autenticação e deve tolerar variações de acentuação e caixa alta/baixa.
  • A listagem deve vir ordenada alfabeticamente pelo nome do docente.
  • Docentes com dados parciais (sem e-mail ou página pública) devem ser exibidos sem quebra de leiaute.

​
ÉPICO 4: Restaurante Universitário (RU) e Serviços Estudantis

Módulo dedicado aos serviços do RU e facilidades da vida universitária, agregando cardápio multi-campus, controle financeiro de refeições, carteirinha digital e emissão de declarações acadêmicas.

​
4.1: Cardápio Multi-Campus

Histórias de Usuário:
  • US32: Como estudante da UnB, quero consultar o cardápio do RU por dia e campus (Darcy Ribeiro, Gama, Ceilândia, Planaltina e Fazenda Água Limpa) sem necessidade de login.
  • US33: Como estudante com restrição alimentar, quero identificar claramente os pratos principais e complementos nas opções padrão, ovolactovegetariana e vegetariana estrita (vegana).
  • US34: Como estudante residente ou frequentador do RU aos fins de semana, quero poder consultar o cardápio aos domingos e ser informado em datas sem expediente ou sem cardápio publicado.
  • US41: Como estudante, quero compartilhar o cardápio de um dia, refeição e campus específicos com uma prévia visual que identifique o Followw.
  • RF13 — Consulta Pública do Cardápio do RU (GET /public/restaurant): O sistema deve extrair, estruturar e disponibilizar o cardápio semanal das refeições (café da manhã, almoço e jantar) para todos os campi da universidade, cobrindo o ciclo completo de Segunda a Domingo e sinalizando feriados e dias sem refeição.
Critérios de Aceitação:
  • O seletor de dias deve exibir 7 dias (SEG a DOM), mantendo a semana correta mesmo quando consultado no domingo.
  • Cada refeição deve listar o prato principal, guarnições, saladas, sobremesas e bebidas, marcando opções vegetarianas e veganas com ícones dedicados.
  • Dias sem cardápio disponível devem apresentar mensagem explicativa com o motivo (ex.: "Cardápio não publicado para esta data").
  • O compartilhamento deve preservar dia, refeição e campus nos parâmetros da URL e apresentar uma imagem dinâmica do cardápio com a identidade visual do Followw, acessível sem login. As seções devem manter a ordem exibida no site, com os rótulos dos acompanhamentos em negrito. As alternativas ovolactovegetarianas e vegetarianas estritas devem usar os ícones de ovo e folha. A imagem usa um tema fixo, definido no gerador, sem parâmetro de tema na URL.

​
4.2: Gestão de Saldo e Extrato do RU

Histórias de Usuário:
  • US35: Como estudante cadastrado no RU, quero consultar o meu grupo tarifário e horário atual.
  • US36: Como estudante, quero visualizar meu extrato com créditos (recargas) e débitos (refeições) consumidos recentemente.
  • US37: Como estudante, quero receber um aviso preventivo quando meu saldo for menor que o custo da refeição correspondente ao horário atual.
  • RF14 — Saldo, Extrato e Alertas Financeiros do RU (GET /me/ru-statement): O sistema deve consultar a conta do estudante no sistema do RU e fornecer saldo, grupo de gratuidade/tarifa e histórico recente de transações, calculando o saldo faltante para a refeição iminente.
Critérios de Aceitação:
  • Caso o estudante pertença a grupo com isenção total (refeição gratuita) ou tenha saldo suficiente, o alerta de saldo faltante não deve ser exibido.
  • O extrato deve conter data, tipo de operação (crédito/débito), valor e descrição da transação.

​
4.3: Carteirinha Digital e Emissão de Documentos

Histórias de Usuário:
  • US38: Como estudante, quero apresentar a carteirinha estudantil digital com QR Code no meu celular para ingressar no Restaurante Universitário.
  • US39: Como estudante, quero ser informado caso minha carteirinha estudantil esteja com a validade mensal expirada, recebendo instruções para emissão de nova via.
  • US40: Como estudante, quero realizar o download direto do PDF da minha carteirinha estudantil e da declaração de vínculo do SIGAA pelo Followw.
  • RF15 — Carteirinha Digital e Emissão de Documentos Estudantis (GET /me/ru-token e /me/documents): O sistema deve extrair o código de barras/QR Code da carteirinha estudantil do SIGAA, gerar o SVG local com verificação de vigência mensal e disponibilizar o download de comprovantes acadêmicos em formato PDF.
Critérios de Aceitação:
  • O QR Code deve ser gerado e renderizado localmente no cliente no momento da exibição, abrindo em gaveta/gaveta modal (drawer) sem expor dados desnecessários na tela.
  • Carteirinhas vencidas devem exibir alerta destacado indicando que o estudante deve emitir novo documento no portal institucional.
  • O sistema deve oferecer botões diretos de download para o PDF da Carteirinha e para a Declaração de Vínculo Oficial.

​
3. Requisitos Não Funcionais (RNF)

Os requisitos não funcionais definem os critérios técnicos de qualidade, confiabilidade, desempenho, conformidade de arquitetura e segurança da informação.
  • RNF01 — Documentação Interativa de Endpoints (Mintlify / OpenAPI):
    • Todos os endpoints da API devem ser documentados com modelos rigorosos de entrada, códigos de retorno HTTP (200, 401, 404, 422, 502) e exemplos claros via OpenAPI, renderizados pela interface Mintlify integrada.
  • RNF02 — Cobertura Abrangente de Testes Automatizados:
    • Toda funcionalidade e correção deve conter testes automatizados. O back-end utiliza Pytest com clientes assíncronos e mocks de requisições externas; o front-end web utiliza a suíte de testes ultrarrápida do Bun (bun test).
  • RNF03 — Segurança, Privacidade e Sessão Efêmera:
    • O sistema não deve, sob qualquer condição, persistir senhas de usuários em bancos de dados relacionais, discos ou logs.
    • O transporte de dados na web deve ocorrer exclusivamente por HTTPS/TLS com atributos de cookies HttpOnly, SameSite e Secure.
    • Os dados pessoais salvos no dispositivo devem ser descartados no momento do logout ou ao expirar a sessão.
  • RNF04 — Desempenho e Sincronização Concorrente da API:
    • A API deve utilizar chamadas paralelas não bloqueantes (asyncio) para a extração do SIGAA, reduzindo o tempo de sincronização inicial.
    • Consultas a recursos previamente armazenados no cache relacional ou local devem responder com latência média inferior a 300 ms.
  • RNF05 — Modularidade e Extensibilidade Arquitetural:
    • O código deve seguir separação rigorosa de pacotes: scrapers e clientes do SIGAA isolados em bibliotecas próprias (sigaa-client, unb-browser), permitindo a evolução independente do front-end e da API.
  • RNF06 — Licenciamento e Governança de Código Aberto:
    • O código-fonte integral deve permanecer sob licença permissiva MIT, em repositório público com rastreabilidade de commits, diretrizes de contribuição e convenções de código limpo.
  • RNF07 — Suporte Offline e Instalação (Progressive Web App - PWA):
    • O front-end deve funcionar como uma aplicação web progressiva instalável na tela inicial de celulares (Android e iOS) e desktops, com manifesto de aplicativo válido (manifest.json) e Service Worker.
    • O aplicativo deve permitir navegação completa pelas páginas já visitadas mesmo sem acesso à internet, mantendo os dados locais por até 14 dias em armazenamento seguro (IndexedDB e localStorage), exibindo banner indicativo de modo offline.
  • RNF08 — Padronização Visual e Acessibilidade (Design System):
    • A interface deve adotar componentes reutilizáveis padronizados construídos com shadcn/ui, Base UI e Tailwind CSS.
    • A paleta de cores deve garantir contraste adequado para legibilidade e oferecer suporte dinâmico a temas claro (light) e escuro (dark) com persistência automática no navegador.
  • RNF09 — Otimização para Mecanismos de Busca (SEO) em Rotas Públicas:
    • As páginas de acesso público (Início, Cardápio do RU e Busca de Turmas) devem conter títulos semânticos, meta tags OpenGraph, dados estruturados Schema.org, canonical tags, sitemap.xml e robots.txt.
    • Rotas que exigem login e tratam dados privados (perfil, turmas do discente) devem incluir obrigatoriamente a diretiva noindex.
  • RNF10 — Resiliência e Tolerância a Falhas do SIGAA:
    • Em caso de indisponibilidade, lentidão extrema ou instabilidade dos servidores do SIGAA/UnB, o sistema deve exibir tela de erro temática em português, explicando ao estudante que o problema tem origem na plataforma institucional e oferecendo botão para tentar novamente.
  • RNF11 — Observabilidade e Monitoramento de Produção:
    • A API deve emitir logs estruturados padronizados contendo identificadores de requisição e tempos de execução, e o front-end deve integrar telemetria analítica e de erros (PostHog) preservando o anonimato de dados sensíveis.
  • RNF12 — Controle de Taxa de Requisições e Proteção contra Abuso (Rate Limiting via Redis):
    • A API deve implementar limitação de taxa em memória por janela fixa de 60 segundos com persistência volátil no Redis (Upstash Redis em produção e redis:8 local), aplicando cotas globais de 600 requisições por IP a cada 60 s e cota estrita de 30 requisições por IP a cada 60 s para o endpoint de autenticação (POST /auth/sigaa).
    • Requisições que excederem o limite da janela devem receber HTTP 429 Too Many Requests com cabeçalho Retry-After indicando os segundos restantes para a renovação da cota e Cache-Control: no-store.
    • O middleware deve operar em modo tolerante a falhas (fail-open), liberando a requisição caso o serviço de Redis fique indisponível ou sofra timeout (> 1 s).
    • Os endereços IP devem ser anonimizados por HMAC derivado de JWT_SECRET_KEY antes de serem indexados, agrupando blocos IPv6 pelo prefixo /64.
    • Chamadas originadas pelo servidor SSR devem encaminhar o IP real do cliente assinado criptograficamente com HMAC-SHA256 e expiração de 60 s (RATE_LIMIT_SECRET_KEY), prevenindo falsificações.

​
4. Aprimoramentos de Engenharia e Infraestrutura

Melhorias técnicas internas que sustentam as capacidades funcionais do produto, sem constituir telas ou regras de negócio isoladas para o usuário final:
  1. Automação de Diagramas C4 via Script Local: Script em Python (scripts/generate_diagrams.py) para geração autônoma de diagramas arquiteturais em SVG (C4 Context, Container, Componentes), reduzindo a dependência de esteiras externas de CI.
  2. Repositório Centralizado de Armazenamento no Navegador: Engine unificada de persistência para tratar leituras e escritas em localStorage e IndexedDB, gerenciando cotas, tratamento de erros de gravação e namespaces isolados (followw:).
  3. Dataset Local Estruturado de Ofertas: Compilação e indexação de turmas abertas da universidade para permitir pesquisas com tempo de resposta sub-milissegundo no catálogo público.
  4. Otimização de Índices no Banco de Dados: Criação de índices estratégicos em tabelas de menções, turmas e docentes para garantir alto desempenho durante sincronizações em lote.
  5. Camada de Rate Limiting e Proteção de Borda via Redis: Implementação de controle de taxa em memória compatível com arquitetura Serverless (Upstash Redis), protegendo os servidores do SIGAA/CAS da UnB contra ataques de negação de serviço e força bruta sem comprometer a latência da API.

​
5. Escopo das Releases e Evolução do Projeto

O desenvolvimento do Followw UnB é conduzido de forma incremental através de sprints ágeis:

​
Funcionalidades Entregues na Release 1 (MVP — 15/09/2026)

  • Autenticação via SIGAA sem retenção de senhas e Logout seguro.
  • Consulta básica do perfil do discente (nome, matrícula, IRA, MP).
  • Listagem simples de turmas matriculadas no semestre corrente.
  • Sincronização inicial de turmas com o SIGAA.
  • Documentação dos endpoints em OpenAPI.

​
Funcionalidades Entregues na Release 2 (Escopo Atual — Sprints 4 a 7 — 16/10/2026)

  • Módulo do RU Completo: Cardápio de 5 campi, suporte a domingos e dias sem cardápio, extrato, saldo, avisos de saldo insuficiente e compartilhamento com prévia OpenGraph.
  • Carteirinha Digital e Documentos: Emissão de QR Code com checagem de validade e download direto de comprovantes em PDF.
  • Gestão de Frequência: Marcação manual de presenças/faltas e cálculo em tempo real de frequência estimada com alertas de infrequência.
  • Histórico Completo de Turmas: Visualização de menções finais (SS a SR) no semestre atual e em semestres anteriores.
  • Notícias das Turmas: Renderização em Markdown higienizado e retenção persistente em cache.
  • Agenda Diária e Calendário Acadêmico: Identificação de feriados, recessos e junção de horários de aulas contínuas.
  • Perfil Avançado e Preferências: Detalhamento de horas pendentes (obrigatórias, optativas, complementares) e definição de nome social/exibição.
  • Catálogo Público de Turmas e Docentes: Pesquisa por código/nome/docente/local com dataset local, visualização de vagas, análise de pré-requisitos e busca aberta de professores.
  • Recomendação de Disciplinas: Algoritmo ponderado para sugestão de matrícula excluindo matérias cursadas e avaliando equivalências.
  • Proteção contra Abuso e Rate Limiting: Limitação de taxa distribuída com Redis para mitigar ataques de força bruta no login e scraping excessivo.
  • Transparência e LGPD: Página pública de termos de uso e política de privacidade (/privacidade).
  • PWA e Suporte Offline Total: Instalação na tela inicial do celular/desktop e navegação completa por até 14 dias sem conexão.
  • Design System e Resiliência: Padronização com shadcn/ui, suporte a temas e tela dedicada para indisponibilidades do SIGAA.

​
Backlog Evolutivo (Próximas Releases)

  • Ações Ativas de Matrícula: Solicitação interativa de trancamento de matrícula e ajuste de inscrição direto pelo Followw.
  • Realização de Matrícula e visualização de resultados: Realização de matrícula, rematrícula e matrícula extraordinária no período oficial permitido e exposição dos resultados obtidos nas tentativas diretamente no Followw.

​
6. Restrições e Premissas do Projeto

  • Independência Operacional: O Followw UnB é um projeto acadêmico de código aberto mantido por estudantes da UnB, sem vínculo institucional com a reitoria ou com os fornecedores oficiais do SIGAA.
  • Resiliência a Mudanças de Layout: Por realizar scraping em portais web legados da UnB, a arquitetura deve isolar os seletores em adaptadores específicos, cobertos por testes frequentes de regressão.
  • Responsabilidade pelo Uso: O fornecimento de credenciais institucionais é uma escolha voluntária do estudante, pautada na transparência do código aberto e na garantia de arquitetura estritamente sem retenção de senhas.

​
7. Artefatos e Documentos Relacionados