Problemas já encontrados no projeto e como resolver. Os comandos rodam dentro de retool/.

• Causa: as dependências não foram instaladas.
• Correção: npm install em retool/. Para as Cloud Functions, npm --prefix functions install; os scripts de emulador fazem isso sozinhos.

• Causa: retool/.env ausente ou incompleto.
• Correção: cp .env.example .env e preencha os valores do projeto. Ver Configuração do Ambiente.

• Causa: o .env escolhe o projeto (VITE_USE_FALLBACK_DB), mas o deploy vai para o default quando não há --project.
• Como identificar: a mensagem de índice ausente no Histórico de Ações mostra o projeto consultado. Compare com o .env.
• Correção: publique no mesmo projeto, por exemplo --project fallback. Ver Build e Deploy.

• Causa: a conta logada no Firebase CLI não tem acesso a esse projeto.
• Como identificar: npx firebase-tools login:list mostra a conta ativa.
• Correção: entre com a conta certa (npx firebase-tools login:add) e ative-a com npx firebase-tools login:use [email protected], ou use --account [email protected] no comando.

• Causa: o comando foi digitado com --account <email>, com os sinais < >.
• Correção: escreva o e-mail sem os sinais: --account [email protected].

• Causa: Cloud Functions exigem o plano pago do Firebase.
• Correção: faça o upgrade do projeto ou publique sem functions. Só a geração de nova senha temporária fica indisponível: a tela mostra "Serviço de redefinição de senha indisponível".

• Causa: o índice composto exigido pelo filtro não existe nesse projeto.
• Correção: npx firebase-tools deploy --only firestore:indexes --project <alias do projeto X>. Detalhes em Logs e Auditoria.

• Causa: os índices foram publicados há pouco.
• Correção: aguarde alguns minutos. O andamento aparece no Firebase Console → Firestore → Índices.

• Causa: a contagem no servidor falhou. Em geral é o mesmo motivo dos índices, ou uma falta de permissão.
• Correção: a mesma dos itens anteriores.

• Causas possíveis:
  • as regras novas não foram publicadas no projeto em uso;
  • a conta não é operacional (bloqueada, pendente ou com troca de senha pendente);
  • o cargo não permite a ação.
• Como identificar: confira o documento users/{uid} no Console (perfil, ativo, statusAprovacao, trocaSenhaObrigatoria).
• Correção: publique as regras ou ajuste a conta pela Administração. Ver Usuários, Cargos e Permissões.

• Causa: a conta é um Convidado aguardando aprovação.
• Correção: uma conta da Administração aprova em Administração → Cadastros pendentes. Se ainda não existe nenhum administrador, siga Primeira conta de Administração.

• Causa: a conta está bloqueada ou o cadastro foi rejeitado.
• Correção: a Administração desbloqueia a conta na aba Usuários. Um cadastro rejeitado só é reavaliado se a Administração excluir o perfil: no próximo login, a pessoa volta como Convidado pendente.

• O sistema não tem recuperação de senha por e-mail.
• A Administração gera uma nova senha temporária pelo botão 🔑 em Administração → Usuários. Isso exige as Cloud Functions publicadas.

• Causa: a porta 8181 está ocupada. A porta padrão, 8080, costuma estar em uso por outros programas, por isso o projeto usa 8181. Outra causa é um processo Java órfão de uma execução anterior.
• Como identificar:
  • Windows: netstat -ano | findstr :8181;
  • Linux/macOS: lsof -i :8181.
• Correção: os scripts npm run test:rules, test:funcoes e emuladores já encerram o Java que eles mesmos iniciaram. Se o processo for de outra origem, feche-o ou troque a porta em firebase.json e em src/data/datasources/firebase.ts.

• Causa: Java não instalado.
• Correção: instale um JDK 11 ou superior e verifique com java -version.

• Causa: a descoberta das funções demora mais que 10 s enquanto os outros emuladores sobem, principalmente em pastas sincronizadas como OneDrive.
• Correção: use npm run emuladores ou npm run test:funcoes, que definem FUNCTIONS_DISCOVERY_TIMEOUT=60. Rodando o firebase diretamente, defina essa variável antes.

• Causa: o Jest foi executado sem os emuladores, por exemplo npx jest src/tests/rules.
• Correção: use npm run test:rules ou npm run test:funcoes, que sobem os emuladores antes.

• Causa: erros antigos em arquivos fora do app:
  • coverage/lcov-report/, relatório gerado;
  • scripts/criarFormularioBugReTool.js, script do Google Apps Script com os globais FormApp e Logger;
  • scripts/criarIssuesGitHub.js, que usa process.
• Observação: a configuração do ESLint cobre apenas .js/.jsx, então os arquivos .ts/.tsx do app não são analisados. Esses erros não afetam o build.

"Some chunks are larger than 500 kB" e INEFFECTIVE_DYNAMIC_IMPORT são avisos conhecidos e não impedem o build.

Posso escolher meu cargo ao me cadastrar? Não. Toda conta nova entra como Convidado, e o cargo é definido pela Administração na aprovação. Depois, dá para pedir outro cargo pelo menu do perfil.

Como descubro quem alterou um registro? Em Administração → Histórico de ações, filtrando por recurso, usuário ou período. Clique na linha para ver os valores anteriores.

Excluir um usuário apaga a conta dele no Firebase? Apaga só o perfil. A conta de autenticação só pode ser removida no Firebase Console.

Os dados dos emuladores ficam salvos? Não. Eles se perdem quando os emuladores param. Rode node scripts/semearEmulador.mjs de novo para recriar as contas de demonstração.