doc: anotacoes de estudo e visao geral do projeto

Author: wellington1993

doc/arquivos.txt

@@ -0,0 +1,271 @@
+Anotacoes sobre os arquivos do projeto
+Wellington - Desafio Flugo
+---
+
+Vou descrevendo cada arquivo conforme fui entendendo o que cada um faz.
+Escrevi isso pra me ajudar a explicar na entrevista sem travar.
+
+
+RAIZ DO PROJETO
+---------------
+
+package.json
+  Define todas as dependencias do projeto. As principais sao:
+  React 19 (interface), Material UI 7 (componentes visuais prontos),
+  Firebase 12 (banco de dados na nuvem), TanStack Query 5 (gerenciar
+  requisicoes e cache), React Hook Form (formularios), Zod (validacao).
+  Tambem tem os scripts de desenvolvimento, build e testes.
+
+vite.config.ts
+  Configuracao do Vite, que e o bundler que compila e serve o projeto.
+  Defini um alias "@" apontando pra src/ pra nao ficar com caminho relativo
+  feio no import. Tambem configurei o build pra separar os pacotes grandes
+  (React, MUI, Firebase) em arquivos diferentes, o que ajuda o browser
+  a fazer cache melhor.
+
+vitest.config.ts
+  Configuracao do Vitest, que roda os testes unitarios. Usei jsdom como
+  ambiente pra simular o browser. Tambem aponta pro arquivo de setup que
+  mocka o localStorage.
+
+playwright.config.ts
+  Configuracao do Playwright, que roda os testes E2E (de ponta a ponta).
+  Timeout de 60 segundos porque as operacoes com Firebase podem demorar.
+  Em desenvolvimento sobe o servidor local automaticamente.
+
+firestore.rules
+  Regras de seguranca do Firestore. Por enquanto ta aberto (allow all)
+  porque o desafio nao pediu autenticacao. Em producao real teria que
+  restringir por usuario autenticado.
+
+Dockerfile
+  Build em dois estagios: primeiro compila o app com Node 22, depois
+  copia o resultado pra uma imagem enxuta do nginx. Isso reduz o tamanho
+  final da imagem.
+
+docker-compose.yml
+  Sobe o app com Docker sem precisar instalar nada. Aponta as variaveis
+  de ambiente e mapeia a porta 8080 do host pra porta 80 do container.
+
+nginx.conf
+  Configuracao do nginx dentro do container. Habilita gzip pra comprimir
+  os arquivos antes de mandar pro browser, e tem o fallback de HTML5
+  history (index.html pra qualquer rota) que e necessario em SPA.
+  Assets estaticos ficam em cache por 1 ano.
+
+.github/workflows/ci.yml
+  Pipeline de CI no GitHub Actions. Roda em todo push e PR na main.
+  Faz build, roda os testes unitarios, e roda os smoke tests contra
+  a URL de producao no Vercel pra garantir que o deploy funcionou.
+
+
+SRC/MAIN.TSX E SRC/APP.TSX
+---------------------------
+
+main.tsx
+  Ponto de entrada do app. Aqui e onde tudo e inicializado junto:
+  o React Query (cache de dados), o tema do MUI, o error boundary
+  (captura erros), o analytics da Vercel, e o router. Qualquer
+  provider que precise envolver o app inteiro fica aqui.
+
+App.tsx
+  Layout principal da aplicacao. Define a estrutura visual que aparece
+  em todas as paginas: sidebar esquerda, header no topo, breadcrumb
+  de navegacao, e o "Outlet" que e onde o React Router renderiza
+  a pagina atual.
+
+
+SRC/ROUTES
+----------
+
+routes/app-router.tsx
+  Define as rotas da aplicacao usando React Router v7. Cada pagina
+  e carregada de forma lazy (so quando o usuario navega ate ela),
+  o que melhora o tempo de carregamento inicial. Rotas:
+  / -> lista de colaboradores
+  /colaboradores/novo -> formulario de criacao
+  /colaboradores/:id/editar -> formulario de edicao
+  /debug -> painel de diagnostico (oculto)
+  * -> pagina 404
+
+
+SRC/LIBS
+--------
+
+libs/firebase.ts
+  Inicializa a conexao com o Firebase. Le as variaveis de ambiente
+  (VITE_FIREBASE_*) e cria a instancia do Firestore com persistencia
+  local habilitada, o que significa que o app funciona mesmo offline
+  e sincroniza quando a conexao volta. Exporta o db e um booleano
+  isConfigured pra checar se as variaveis estao preenchidas.
+
+libs/mui-theme.ts
+  Tema visual do Material UI. Defini o verde como cor primaria pra
+  combinar com a identidade da Flugo. Tambem ajustei tipografia e
+  alguns detalhes de componentes.
+
+libs/tanstack-query.ts
+  Configuracao do React Query. Defini que dados ficam "frescos" por
+  5 minutos antes de buscar de novo, nao refaz requisicao quando a
+  janela ganha foco (pra nao spammar o Firebase), e tenta de novo
+  1 vez em caso de erro.
+
+
+SRC/FEATURES/STAFF
+------------------
+
+features/staff/types.ts
+  Define os tipos TypeScript do projeto. O tipo Staff tem: id, name,
+  email, department, status (Ativo/Inativo), createdAt, e dois campos
+  de controle interno: _pendingSync (true quando ainda nao foi pro
+  Firebase) e _localId (identificador temporario no localStorage).
+
+features/staff/validation.ts
+  Schema de validacao com Zod. Define as regras de cada campo:
+  nome obrigatorio e maximo 80 caracteres, email valido, departamento
+  tem que ser um dos valores validos, status tem que ser Ativo ou Inativo.
+  Todos os erros sao em portugues.
+
+features/staff/hooks.ts
+  Hooks do React Query que conectam os componentes com o servico.
+  useStaffs: busca a lista completa com cache
+  useCreateStaff: cria colaborador com update otimista (aparece na lista
+    antes de confirmar no servidor, e remove automaticamente se der erro)
+  useUpdateStaff: atualiza colaborador
+  useDeleteStaff: exclui colaborador
+  useSyncPending: tenta sincronizar com Firebase os itens que ficaram
+    salvos so no localStorage
+
+features/staff/validation.test.ts
+  Testes da validacao. Cobre casos como nome vazio, email invalido,
+  departamento que nao existe na lista, status errado.
+
+
+SRC/SERVICES
+------------
+
+services/staffs.ts
+  Camada que faz de fato as operacoes no Firebase. Todo acesso ao
+  Firestore passa por aqui. Funcoes principais:
+  listStaffs: busca todos os colaboradores e mescla com os pendentes
+    do localStorage
+  createStaff: salva no Firebase; se der erro, salva no localStorage
+    pra tentar depois (fallback silencioso)
+  updateStaff e deleteStaff: operacoes diretas no Firebase
+  syncPendingStaffs: percorre o localStorage e tenta salvar cada
+    pendente no Firebase
+  logRemoteError: salva erros na colecao app_logs do Firestore
+    pra diagnostico remoto
+  withTimeout: wrapper que cancela a operacao se demorar mais de 30s
+
+services/local-storage.ts
+  Gerencia a chave "flugo_pending_staffs" no localStorage. Funcoes:
+  getPendingStaffs: retorna a lista atual
+  addPendingStaff: adiciona um item com _pendingSync:true e _localId unico
+  removePendingStaffById: remove pelo _localId
+  removePendingStaffByEmail: remove pelo email (usado na sincronizacao)
+  A deduplicacao por email evita salvar o mesmo colaborador duas vezes.
+
+services/local-storage.test.ts
+  Testes do servico de localStorage. Cobre adicionar, remover, deduplicar.
+
+
+SRC/COMPONENTS
+--------------
+
+components/staff-list.tsx
+  Tabela principal que mostra todos os colaboradores. Tem paginacao,
+  ordenacao por coluna, e indicador "Pendente" quando o item ainda
+  nao foi sincronizado com o Firebase. Filtros e botoes de editar/excluir
+  estao no codigo mas ocultos da interface por ora (nao faziam parte
+  do escopo original do desafio).
+
+components/staff-form.tsx
+  Formulario em dois passos para criar colaborador:
+  Passo 1: nome e email (com validacao de email duplicado em tempo real)
+  Passo 2: departamento e status
+  Salva rascunho no localStorage enquanto o usuario preenche, e limpa
+  o rascunho depois que salva com sucesso. O botao de avancar so
+  aparece quando o passo atual esta valido.
+
+components/staff-edit-page.tsx
+  Pagina de edicao. Carrega o colaborador pelo ID da URL e passa os
+  dados para o StaffForm no modo de edicao.
+
+components/breadcrumb.tsx
+  Barra de navegacao no topo mostrando onde o usuario esta. Exemplo:
+  Colaboradores > Novo Colaborador. Gera os links automaticamente
+  baseado na URL atual.
+
+components/sidebar.tsx
+  Menu lateral fixo com o logo da Flugo e o link para Colaboradores.
+
+components/header.tsx
+  Barra de topo com um avatar no canto direito.
+
+components/not-found.tsx
+  Pagina 404 com mensagem simples e link pra voltar pra lista.
+
+components/error-boundary.tsx
+  Componente de classe que captura erros do React e mostra uma mensagem
+  amigavel ao inves de travar a tela. Tem um botao pra recarregar.
+
+components/delete-confirm-dialog.tsx
+  Dialog de confirmacao antes de excluir um colaborador. Mostra o
+  nome da pessoa e tem botao cancelar/confirmar.
+
+components/debug-sync.tsx
+  Painel de diagnostico oculto na rota /debug. Mostra a config do
+  Firebase, lista os pendentes no localStorage, e tem botao pra
+  forcar a sincronizacao manualmente.
+
+components/theme-provider.tsx
+  Envolve o app com o tema do MUI e o CssBaseline (que aplica um
+  reset CSS consistente em todos os browsers).
+
+
+SRC/HOOKS E SRC/HELPERS
+-----------------------
+
+hooks/use-sort-table.ts
+  Hook que gerencia o estado de ordenacao da tabela: qual coluna e
+  em qual direcao (asc ou desc). Retorna o estado atual e uma funcao
+  pra criar handlers de clique por coluna.
+
+hooks/use-sort-table.test.ts
+  Testes do hook de ordenacao.
+
+helpers/table-sorting.ts
+  Funcao utilitaria que compara dois objetos por um campo especificado,
+  usada para ordenar os dados da tabela.
+
+helpers/table-sorting.test.ts
+  Testes da funcao de comparacao.
+
+
+SRC/TEST
+--------
+
+test/setup.ts
+  Arquivo que roda antes de cada suite de testes. Cria um mock do
+  localStorage do browser, porque o jsdom nao implementa tudo que
+  o localStorage real tem.
+
+
+TESTS/ (E2E)
+------------
+
+tests/e2e/smoke.spec.ts
+  Teste que roda em CI. Acessa a URL de producao, confere se a pagina
+  carrega, se a tabela aparece, e se o formulario abre. Nao salva
+  nada, so verifica que o deploy nao quebrou nada visivel.
+
+tests/e2e/staff.spec.ts (nao roda no CI)
+  Testes completos de criacao de colaborador via Playwright. Esses
+  nao rodam no CI porque gravam dados reais no Firebase de producao.
+
+tests/e2e/sync-validation.spec.ts (nao roda no CI)
+  Testa o fluxo de validacao e sincronizacao offline/online.
+
+tests/e2e/forge-prod-save.spec.ts (nao roda no CI)
+  Teste rapido para forcar um salvamento em producao durante o debug.