Pular para o conteúdo principal

Documentação de Engenharia Inteligente

A Documentação de Engenharia Inteligente é um recurso poderoso que gera automaticamente documentação técnica abrangente para sua base de código. Ao analisar seu código-fonte, ela cria documentação detalhada incluindo diagramas de arquitetura, referências de API e explicações de lógica de negócios.

Visão Geral​

O menu de Documentação de Engenharia Inteligente fornece um fluxo de trabalho completo para:

  • Criar Projetos - Configure novos projetos de documentação para suas bases de código
  • Gerenciar Organizações - Trabalhe com múltiplas organizações e seus projetos
  • Gerar Documentação - Crie automaticamente documentação técnica completa
  • Gerenciar Tarefas - Acompanhe e regenere tarefas de documentação
  • Baixar Artefatos - Exporte documentação em vários formatos
dica

Acesse a Documentação de Engenharia Inteligente na barra lateral do AI Cockpit para começar a gerar documentação profissional para seus projetos.

Começando​

Seleção de Organização​

Antes de criar ou gerenciar projetos, você deve selecionar uma organização:

  1. Abra o menu de Documentação de Engenharia Inteligente
  2. Use o menu suspenso Seletor de Organização no topo
  3. Selecione sua organização da lista
  4. Todos os projetos serão filtrados pela organização selecionada
info

O seletor de organização mantém sua escolha entre sessões. Os projetos estão sempre associados a uma organização específica.

Criando um Novo Projeto​

Criar Projeto

Passo 1: Informações do Projeto​

Para criar um novo projeto de documentação:

  1. Insira um Nome do Projeto (obrigatório)

    • Use um nome descritivo que identifique sua base de código
    • Exemplo: "API Backend E-commerce"

  2. Adicione uma Descrição do Projeto (opcional)

    • Forneça contexto sobre o projeto
    • Inclua tecnologias ou frameworks principais usados
    • Exemplo: "API REST Node.js para plataforma de e-commerce com MongoDB"

  3. Clique em Criar Projeto para prosseguir

atenção

Certifique-se de ter selecionado a organização correta antes de criar um projeto, pois isso não pode ser alterado posteriormente.

Passo 2: Upload do Código-Fonte​

Upload do Código-Fonte

Após criar o projeto, você precisa fazer upload do seu código-fonte. Existem dois métodos:

Upload de um Arquivo ZIP:

  1. Clique em Escolher Arquivo ou arraste e solte
  2. Selecione um arquivo .zip contendo seu código-fonte
  3. Certifique-se de que o ZIP inclui todos os arquivos de origem relevantes
  4. Clique em Upload para iniciar o processamento
Melhores Práticas
  • Inclua todos os arquivos de código-fonte
  • Exclua diretórios node_modules, vendor ou similares de dependências
  • Mantenha o arquivo ZIP abaixo de 100MB para processamento ideal
  • Inclua arquivos de configuração e documentação

Passo 3: Geração Automática de Documentação​

Progresso da Geração de Documentação

Uma vez que o código-fonte é enviado:

  1. O status do projeto muda para Processando
  2. O sistema analisa a estrutura da sua base de código
  3. Quando pronto, a geração de Documentação Completa inicia automaticamente
  4. Uma página de progresso detalhada abre mostrando as etapas de geração
nota

O tempo de processamento inicial depende do tamanho da sua base de código. Projetos pequenos (< 1000 arquivos) normalmente completam em 2-5 minutos.

Gerenciando Projetos Existentes​

Lista de Projetos​

Lista de Projetos

A seção Projetos Existentes exibe todos os projetos da organização selecionada:

ColunaDescrição
Nome do ProjetoO nome do projeto
StatusEstado atual do projeto (Pronto, Processando, Falhou)
TarefasLista de tarefas de documentação do projeto
AçõesOperações disponíveis para o projeto

Ações do Projeto​

Cada card de projeto fornece várias ações:

Ver Detalhes​

Clique em Ver Detalhes para abrir uma página detalhada mostrando:

  • Informações e metadados do projeto
  • Histórico completo de tarefas
  • Progresso e logs de geração
  • Mensagens de erro (se houver)

Gerar Documentação Completa​

Disponível quando:

  • O status do projeto é Pronto
  • Ainda não existe tarefa de documentação

Clicar neste botão:

  1. Inicia uma nova tarefa de geração de documentação completa
  2. Abre a página de detalhes da tarefa automaticamente
  3. Mostra atualizações de progresso em tempo real

Regenerar Tarefa​

Disponível para tarefas existentes. Esta ação:

  • Cria uma nova tarefa de geração de documentação
  • Usa o mesmo código-fonte
  • Aplica a configuração atual do LLM
  • Abre a página de detalhes da tarefa para monitoramento
Quando Regenerar

Regenere a documentação quando:

  • Você atualizou sua configuração do modelo LLM
  • A geração anterior teve erros
  • Você quer melhorar a qualidade da documentação
  • A análise do código-fonte precisa ser atualizada

Gerar Artefatos​

Disponível quando:

  • O status do projeto é Pronto
  • A tarefa de documentação completa está Concluída

Isso gera artefatos para download incluindo:

  • Documentação Markdown - Documentação completa em formato MD
  • Documentação HTML - Versão HTML interativa
  • Diagramas - Diagramas de arquitetura e fluxo

Baixar Artefatos​

Uma vez que os artefatos são gerados:

  1. Clique no botão Download
  2. Os artefatos abrem automaticamente no VSCode
  3. Os arquivos são salvos no seu disco local
  4. A documentação HTML pode ser visualizada no navegador
info

Os artefatos baixados incluem um arquivo index.html que fornece um site de documentação navegável.

Reenviar Código-Fonte​

Para atualizar o projeto com novo código-fonte:

  1. Clique no botão Reenviar
  2. Selecione um novo arquivo ZIP ou indexe o workspace
  3. O status do projeto muda para Processando
  4. Após o processamento completar, a documentação regenera automaticamente
  5. A página de detalhes da tarefa abre para monitoramento
atenção

Reenviar código-fonte substituirá a base de código existente. As tarefas de documentação anteriores permanecem disponíveis para referência.

Excluir Projeto​

Para remover um projeto:

  1. Clique no botão Excluir
  2. Confirme a exclusão
  3. Todas as tarefas e artefatos associados são removidos
perigo

A exclusão do projeto é permanente e não pode ser desfeita. Baixe quaisquer artefatos importantes antes de excluir.

Gerenciamento de Tarefas​

Lista de Tarefas​

Cada projeto pode ter múltiplas tarefas de documentação:

  • Documentação Completa - Documentação completa da base de código
  • Docs - Apenas documentação de API e código
  • Backlog - Extração de histórias de usuário e requisitos

Status da Tarefa​

As tarefas podem ter os seguintes status:

StatusDescriçãoAções Disponíveis
ExecutandoTarefa está processando atualmenteVer Detalhes
ConcluídaTarefa finalizada com sucessoVer Detalhes, Gerar Artefatos, Download
FalhouTarefa encontrou um erroVer Detalhes, Regenerar
Não EncontradaTarefa expirou ou foi deletadaRegenerar

Ações da Tarefa​

Ver Detalhes da Tarefa​

Abre uma página detalhada mostrando:

  • Porcentagem de progresso atual
  • Log de execução passo a passo
  • Estágios de processamento e subetapas
  • Mensagens de erro (se falhou)
  • Tempo estimado de conclusão

Regenerar Tarefa​

Cria uma nova tarefa com a mesma configuração:

  1. Clique em Regenerar na tarefa
  2. Nova tarefa inicia imediatamente
  3. Página de detalhes da tarefa abre automaticamente
  4. Tarefa anterior permanece no histórico

Excluir Tarefa​

Remover uma tarefa do projeto:

  1. Clique em Excluir na tarefa
  2. Confirme a exclusão
  3. Tarefa e seus artefatos são removidos
nota

Você não pode excluir uma tarefa que está em execução. Aguarde a conclusão ou falha antes de excluir.

Processo de Geração de Documentação​

Estágios de Geração​

O processo de geração de documentação inclui vários estágios:

  1. Análise de Código

    • Análise de arquivos de origem
    • Identificação da estrutura do código
    • Extração de dependências

  2. Extração de Símbolos

    • Classes e interfaces
    • Funções e métodos
    • Variáveis e constantes

  3. Geração de Documentação

    • Documentação de API
    • Descrições de arquitetura
    • Explicações de lógica de negócios

  4. Criação de Diagramas

    • Diagramas de arquitetura
    • Fluxogramas
    • Grafos de dependências

  5. Compilação de Artefatos

    • Arquivos Markdown
    • Geração HTML
    • Empacotamento de assets

Monitoramento de Progresso​

Enquanto a documentação é gerada:

  • Porcentagem de progresso em tempo real
  • Estágio e subetapa atual
  • Tempo restante estimado
  • Logs de execução detalhados
dica

Mantenha a página de detalhes da tarefa aberta para monitorar o progresso. A página atualiza automaticamente a cada 15 segundos.

Melhores Práticas​

Organização de Projetos​

  • ✅ Use nomes de projeto descritivos
  • ✅ Inclua descrições abrangentes
  • ✅ Agrupe projetos relacionados por organização
  • ✅ Mantenha um projeto por base de código
  • ✅ Atualize regularmente o código-fonte

Preparação do Código-Fonte​

  • ✅ Inclua todos os arquivos de origem relevantes
  • ✅ Exclua diretórios de dependências
  • ✅ Mantenha arquivos ZIP abaixo de 100MB
  • ✅ Inclua README e arquivos de configuração
  • ✅ Certifique-se de que o código está bem estruturado

Gerenciamento de Documentação​

  • ✅ Regenere após mudanças significativas no código
  • ✅ Baixe artefatos para acesso offline
  • ✅ Revise a documentação gerada quanto à precisão
  • ✅ Use os modelos LLM mais recentes para melhores resultados
  • ✅ Mantenha histórico de tarefas para referência

Otimização de Desempenho​

  • ✅ Remova arquivos desnecessários antes do upload
  • ✅ Use indexação de workspace para projetos ativos
  • ✅ Gere artefatos apenas quando necessário
  • ✅ Exclua projetos antigos para economizar espaço
  • ✅ Monitore o progresso das tarefas regularmente

Solução de Problemas​

Falha no Processamento do Projeto​

Se o processamento do projeto falhar:

  1. Verifique os detalhes do projeto para mensagens de erro
  2. Verifique se o arquivo ZIP contém código-fonte válido
  3. Certifique-se de que o ZIP não está corrompido
  4. Tente reenviar com um subconjunto menor da base de código
  5. Entre em contato com o suporte se o problema persistir

Falha na Geração de Documentação​

Se a geração de documentação falhar:

  1. Abra os detalhes da tarefa para ver logs de erro
  2. Verifique se a estrutura da base de código é suportada
  3. Verifique se a configuração do LLM está correta
  4. Tente regenerar a tarefa
  5. Considere usar um modelo LLM diferente

Artefatos Não Disponíveis​

Se os artefatos não puderem ser gerados:

  1. Certifique-se de que a tarefa de documentação foi concluída com sucesso
  2. Verifique se o status do projeto é Pronto
  3. Verifique se você tem permissões suficientes
  4. Tente regenerar a documentação
  5. Verifique mensagens de erro nos detalhes da tarefa

Problemas de Download​

Se o download do artefato falhar:

  1. Verifique sua conexão com a internet
  2. Verifique se a URL de download ainda é válida
  3. Tente baixar novamente após alguns minutos
  4. Verifique o painel de saída do VSCode para erros
  5. Certifique-se de ter permissões de gravação no local de download

Recursos Avançados​

Múltiplas Organizações​

Trabalhe com múltiplas organizações:

  • Alterne entre organizações usando o seletor
  • Cada organização tem sua própria lista de projetos
  • Projetos são isolados por organização
  • Permissões são específicas da organização

Histórico de Tarefas​

Acesse o histórico completo de tarefas:

  • Visualize todas as gerações de documentação anteriores
  • Compare diferentes resultados de tarefas
  • Acompanhe a evolução da documentação
  • Audite tentativas de geração

Configuração Personalizada do LLM​

Configure as definições do LLM para documentação:

  • Escolha diferentes modelos de IA
  • Ajuste o idioma de saída
  • Personalize parâmetros de geração
  • Otimize para casos de uso específicos

Próximos Passos​

Agora que você entende a Documentação de Engenharia Inteligente, explore: