Arquitetura - CAKeysama/ReTool GitHub Wiki

Arquitetura

Visão geral

O ReTool é uma aplicação de página única (SPA) em React que roda no navegador e conversa diretamente com o Firebase pelo SDK web. Não existe um servidor de aplicação próprio:

  • Firebase Authentication — login com e-mail e senha.
  • Cloud Firestore — todos os dados (usuários, dispositivos, reutilizações, notificações, auditoria).
  • Cloud Storage — imagens e PDFs dos dispositivos.
  • Regras de segurança (firestore.rules e storage.rules) — fazem o papel de backend de autorização: cada leitura e escrita é validada no servidor contra o perfil gravado em users.
  • Cloud Functions — uma única função, redefinirSenhaTemporaria, para a operação que o SDK do navegador não permite: alterar a senha de outra pessoa.
flowchart LR
  subgraph Navegador
    UI[Páginas e componentes React] --> CTX[AuthContext e ReToolContext]
    CTX --> UC[Casos de uso]
    UC --> REPO[Repositórios e serviços]
    CTX --> REPO
  end
  REPO -->|SDK web| AUTH[Firebase Authentication]
  REPO -->|SDK web| FS[(Cloud Firestore)]
  REPO -->|SDK web| ST[(Cloud Storage)]
  REPO -->|httpsCallable| FN[Cloud Function redefinirSenhaTemporaria]
  FN -->|Admin SDK| AUTH
  FN -->|Admin SDK| FS
  RULES[firestore.rules e storage.rules](/CAKeysama/ReTool/wiki/firestore.rules-e-storage.rules) -. validam cada requisição .- FS
  RULES -. validam cada requisição .- ST

Tecnologias

Versões conforme retool/package.json e retool/functions/package.json.

Tecnologia Versão Uso
React ^19.2 Interface
React Router DOM ^7.14 Rotas da SPA
TypeScript 6.x, instalado como dependência transitiva (não declarado no package.json) Código-fonte .ts/.tsx; tsconfig.json com strict: false
Vite ^8.0 Servidor de desenvolvimento e build
Firebase (SDK web) ^12.12 Auth, Firestore, Storage e Functions no cliente
lucide-react ^1.8 Ícones
xlsx ^0.18 Leitura de planilhas na importação
uuid ^13 Identificadores de documentos
Jest + ts-jest ^30 / ^29 Testes
@firebase/rules-unit-testing ^5.0 Testes das regras no emulador
firebase-tools ^15.32 Emuladores e deploy (npx firebase-tools)
ESLint ^9 Lint (configurado apenas para .js/.jsx)
Cloud Functions: firebase-functions / firebase-admin ^7.4 / ^14.5 Função administrativa (Node.js 22)

A estilização usa CSS puro (src/index.css) com variáveis no :root (paleta vermelho/cinza da Baldan) e estilos inline; não há framework de CSS.

Estrutura do repositório

ReTool/
├── README.md
└── retool/                      # aplicação
    ├── src/
    │   ├── domain/              # entidades, regras puras e contratos
    │   │   ├── entities/        # user, auditLog, notificacao, solicitacaoCargo, dispositivo, reutilizacao...
    │   │   ├── repositories/    # interfaces (IDispositivosRepository, IAcessosRepositories...)
    │   │   └── services/        # senhaTemporaria, IStorageService
    │   ├── data/
    │   │   ├── datasources/     # firebase.ts: inicialização do SDK (e emuladores)
    │   │   ├── repositories/    # Firestore*Repository (acesso ao Firestore)
    │   │   └── services/        # FirebaseStorageService, FirebaseContasService (Cloud Function)
    │   ├── application/usecases # ImportarLote e os fluxos de acesso (cadastro, cargo, senha)
    │   ├── context/             # AuthContext e ReToolContext (estado global)
    │   ├── presentation/hooks/  # controladores de tela (dispositivos, categorias, histórico)
    │   ├── pages/               # telas roteadas
    │   ├── components/          # componentes compartilhados; components/admin/ = painéis da Administração
    │   ├── hooks/               # usePermissions, useHotkeys, useKeyboardNavigation, useBulkProgress
    │   ├── utils/               # fileValidators
    │   └── tests/               # testes (Jest), mocks, regras e funções
    ├── functions/               # Cloud Functions (TypeScript, Node.js 22)
    ├── scripts/                 # emuladores, semeadura e scripts auxiliares
    ├── docs/                    # documentação resumida e imagens
    ├── firebase.json            # Firestore, Functions, Hosting, Storage e emuladores
    ├── .firebaserc              # aliases de projeto: default e fallback
    ├── firestore.rules
    ├── firestore.indexes.json
    └── storage.rules

Camadas

A organização segue a separação usada desde a refatoração para Clean Architecture:

Camada Pasta Responsabilidade Depende de
Domínio src/domain Tipos, regras puras e testáveis (permissões, situação da conta, máquina de estados de reutilização, sanitização de logs, geração de senha) nada
Dados src/data Acesso ao Firebase (repositórios e serviços) domínio, SDK Firebase
Aplicação src/application/usecases Orquestra fluxos com várias etapas (gravar, notificar, auditar) contratos do domínio
Estado global src/context Sessão, assinaturas em tempo real e operações expostas à interface todas as anteriores
Apresentação src/pages, src/components, src/presentation/hooks, src/hooks Telas, componentes e controladores contextos

Contextos

  • AuthContext (src/context/AuthContext.tsx) — sessão do Firebase Auth, perfil em tempo real, permissões, lista de usuários, notificações, solicitações de cargo e as operações de acesso (login, cadastro, aprovação, cargos, senhas, bloqueio, exclusão). Detalhes em Fluxos de Acesso.
  • ReToolContext (src/context/ReToolContext.tsx) — dados industriais em tempo real (dispositivos, categorias, tipos, famílias, produtos, reutilizações), CRUD com auditoria, fluxo de reutilização, importação em lote, avisos (toasts) e o formulário global de dispositivo.

As assinaturas em tempo real (onSnapshot) só são abertas para contas operacionais. Convidados, contas com troca de senha pendente e sessões encerradas não leem dados.

Rotas

Definidas em src/App.tsx. Toda rota, exceto /login, passa pelo ProtectedLayout, que decide a tela pela situação da conta (telaDaSessao):

Rota Tela Acesso
/login Login e cadastro público Visitantes; usuários logados são redirecionados
/ Home (busca rápida) Contas operacionais
/sobre Sobre o projeto Contas operacionais
/dispositivos Lista de dispositivos Contas operacionais
/dispositivos/:id Detalhes do dispositivo Contas operacionais
/reutilizacoes Filas e histórico de reutilizações Contas operacionais
/categorias Classificações Administração e Projetista
/administracao/:aba? Administração (cadastros, cargos, usuarios, logs) Administração
qualquer outra Redireciona para /dispositivos —

Antes de qualquer rota do sistema:

  • conta Convidado aguardando aprovação → só vê a tela Cadastro em análise;
  • conta com senha temporária → só vê a tela Defina sua nova senha.

As telas / e /sobre usam o layout sem barra lateral (menu de perfil no canto superior). As demais usam a barra lateral e, no celular, a navegação inferior.

Fluxo de dados

  1. A tela chama uma função do contexto (ex.: addDispositivo, decidirCadastro).
  2. O contexto confere a permissão na interface e chama o repositório ou o caso de uso.
  3. O repositório grava no Firestore. As regras validam a operação no servidor.
  4. Em caso de sucesso, a operação registra a auditoria (ver Logs e Auditoria) e, quando o fluxo prevê, notificações (ver Notificações).
  5. Os onSnapshot atualizam o estado de todas as telas abertas em tempo real.

Princípios de design do domínio

  • Dados incompletos não bloqueiam o fluxo (Open World Assumption): quase todos os campos de dispositivo são opcionais, e a interface mostra "Não info." quando falta um dado.
  • Acessibilidade e teclado: atalhos globais, navegação por setas nas listas (FocusableList) e avisos duplos (announce), com região aria-live para leitores de tela e toast visual de 3,5 s. Ver Módulos do Sistema.