Resolver problemas de aplicações do Fabric

Diagnostice problemas comuns quando desenvolve ou implementa um projeto de Fabric Apps. Este artigo aborda questões relacionadas com início de sessão, serviços locais, alterações de esquema, alojamento estático e a CLI.

Problemas de implementação

A implementação falha com erro 401 ou 403

Sintoma: Executar npx rayfin up devolve um erro de autenticação.

Causa: A tua sessão de autenticação expirou ou não estás logado.

Solution:

Reautentique e tente novamente a implementação:

npx rayfin login
npx rayfin up

A aplicação da base de dados reporta alterações destrutivas

Sintoma: A execução de npx rayfin up db apply é bloqueada com um aviso de perda de dados.

Causa: A CLI detetou alterações no esquema que podiam eliminar dados (eliminar colunas, renomear tabelas).

Solution:

Revise cuidadosamente as operações listadas. Se aceitar a perda de dados, utilize --force:

npx rayfin up db apply --force

A implementação estática excede o limite de tamanho

Sintoma: A implementação de conteúdo estático falha devido a um erro de limite de tamanho.

Causa: O arquivo comprimido ultrapassa os 100 MB.

Solution:

Reduzir o tamanho do resultado da compilação através de:

• Excluindo os mapas de origem das builds de produção
• Otimização ou remoção de imagens e vídeos grandes
• Mover ficheiros binários para armazenamento em vez de os agrupar
• Verifique se a configuração do seu empacotador exclui artefactos de desenvolvimento

Problemas de autenticação

A sessão não é mantida após o início de sessão

Sintoma: Os utilizadores são desconectados imediatamente após a autenticação.

Causa: O cliente não está configurado com a URL base correta nem a chave publicável.

Solution:

Verifica se a RayfinClient configuração corresponde ao teu backend:

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Pop-up do Fabric SSO bloqueado

Sintoma: O navegador bloqueia a janela do portal de Fabric durante o início de sessão.

Causa:ensureSignedInWithFabric() não foi chamado a partir de um processador de gestos do utilizador.

Solution:

Chame a função a partir de um gestor de eventos síncrono:

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

Problemas com modelos de dados

Relações que não aparecem na API

Sintoma: Os campos de entidades relacionadas não estão disponíveis ao fazer consultas.

Causa: O decorador de navegação está em falta ou o esquema não foi aplicado.

Solution:

1. Verifique se os decoradores de relacionamentos estão presentes:

   @one(() => Notebook) notebook?: Notebook;
   

2. Reaplique o esquema.

Política de autorização não funciona

Sintoma: Os utilizadores podem aceder a registos que não deveriam ver.

Causa: A expressão da apólice está incorreta ou os nomes das reclamações não coincidem.

Solution:

1. Verifique se a apólice utiliza nomes de reclamação corretos (sub, email, role):

   policy: (claims, item) => claims.sub.eq(item.user_id)
   

2. Regista o JWT decodificado para verificar se os valores das reclamações correspondem ao teu código.

Respostas obsoletas da API

Sintoma: O frontend devolve formas de dados desatualizadas após alterações no esquema.

Causa: A configuração gerada é armazenada em cache.

Solution:

1. Pare o backend.

2. Apague o .temp/ diretório em rayfin/:

   rm -rf rayfin/.temp/
   

3. Reinicie os serviços e reaplique o esquema.

Problemas da CLI

Comando não encontrado

Sintoma: Executar npx rayfin devolve a mensagem "command not found."

Causa: O CLI não está instalado ou o npm não está no teu PATH.

Solution:

1. Verifique Node.js e npm estão instalados:

   node --version
   npm --version
   

2. Reinstalar dependências:

   npm install
   

Incompatibilidade de versões da CLI

Sintoma: Os comandos CLI falham com erros inesperados após a atualização.

Causa: A versão da CLI em cache está desatualizada.

Solution:

Atualização e reinstalação:

npm update --save
npm install
npx rayfin --version

Incompatibilidade entre a versão global e a versão local da CLI

Sintoma: Os comandos CLI falham com erros inesperados entre projetos.

Causa: Instalação global e local das versões CLI e elas não coincidem.

Solução: Valide a versão local npm list @microsoft/rayfin-cli. Isto mostra a versão no node_modules do seu projeto atual. Verifique a versão global npm list -g @microsoft/rayfin-cli. Isto mostra a versão instalada em todo o sistema. Use npm uninstall -g com o pacote Rayfin CLI para remover a versão global e utilizar as versões locais.

Problemas de montagem e embalagem

O comando de build falha

Sintoma: A implementação de alojamento estático falha porque o comando de compilação não produziu saída.

Causa: Erros de compilação ou comandos de compilação mal configurados.

Solution:

1. Executa manualmente o comando de compilação:

   npm run build
   

2. Corrija quaisquer erros reportados.

3. Verifica se a pasta de saída contém ficheiros.

Pasta estática vazia

Sintoma: A implementação estática falha com o erro de "pasta vazia".

Causa: O caminho configurado folder está incorreto.

Solution:

Verifica se o folder caminho corresponde rayfin.yml ao resultado da tua build:

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

Problemas com bases de dados

Ligação recusada

Sintoma: As operações de dados falham devido a erros de ligação.

Causa: O contentor da base de dados não está a correr ou as verificações de saúde falharam.

Solution:

1. Rever registos de contentores:

   docker compose logs -f
   

2. Reiniciar os serviços.

Perda de dados após o reinício

Sintoma: Os dados desaparecem após a interrupção e início dos serviços.

Causa: Os volumes foram eliminados com --purge.

Solution:

Utilize --down em vez de --purge para preservar os dados.

Limitações conhecidas

Para limitações atuais e soluções recomendadas, veja:

• count() não está disponível no cliente fluent GraphQL — use results.length.
• As relações muitos-para-muitos não são suportadas—use uma entidade de associação explícita.
• Os objetos de sessão são opacos — verifique as propriedades isAuthenticated ou user.
• Depois de ativar ou desativar a autenticação em rayfin.yml, reinicia o backend.

Obter ajuda

Se o problema persistir:

1. Consulte a documentação Fabric Apps.
2. Verifique o repositório GitHub para problemas conhecidos.
3. Faça um relatório de bugs com registos detalhados e passos de reprodução.

Conteúdo relacionado

• Referência da CLI
• Implementar no Fabric
• Configurar a autenticação