Verificador de Task (Issue x Documentação)

Sistema web para validar se a documentação entregue por um desenvolvedor está alinhada com uma issue do GitHub, com análise automática de IA, percentual de aderência, resposta sugerida para correção e estimativa de custo por requisição.

Proposta do projeto

Este projeto foi feito para contexto institucional/acadêmico, onde existe necessidade de:

• comparar rapidamente o que foi documentado com o que foi solicitado;
• reduzir subjetividade na avaliação técnica;
• padronizar feedback com um texto de correção copiável;
• acompanhar custo de uso de IA por análise.

Ele funciona com armazenamento local/temporário no navegador para os pontos de atenção, sem banco de dados.

Para que usar

Use este app quando você precisa revisar entregas de documentação técnica baseadas em issues, por exemplo:

• avaliação de atividades em disciplinas de desenvolvimento;
• revisão de entregas em squads acadêmicas;
• validação rápida de conformidade entre escopo e documentação;
• apoio a QA técnico com checklist customizável.

Como funciona (visão geral)

1. O repositório é definido no front/env.js (GITHUB_REPO_URL).
2. O front lista issues desse repo com filtros (abertas/fechadas/todas) e busca.
3. Você seleciona uma issue e envia um arquivo .txt ou .pdf.
4. O backend extrai texto (inclusive de PDF), reduz custo com chunk+sumário quando necessário e chama IA.
5. O app retorna:

• percentual de aderência;
• classificação da documentação;
• análise textual;
• resposta sugerida para copiar e colar;
• tokens usados e custo estimado em reais.

Estrutura de pastas

verificadorDeTask/
  app.js                # Ponto único de execução
  package.json
  .env.example          # Variáveis do backend
  front/
    index.html
    style.css
    script.js
    env.example.js      # Exemplo de config do front
    env.js              # Config real do front (gitignored)
  back/
    server.js           # API + servidor estático

Pré-requisitos

• Node.js 18+ (recomendado 20+)
• chave de API (OpenAI e/ou Gemini)

Configuração

1) Backend (.env)

Copie .env.example para .env e preencha:

• OPENAI_API_KEY (obrigatório para OpenAI)
• OPENAI_MODEL (padrão econômico: gpt-4.1-nano)
• OPENAI_FALLBACK_MODEL (ex.: gpt-4.1-mini)
• USD_TO_BRL (câmbio para estimativa de custo)
• OPENAI_ENABLE_BATCH (true/false para análises não urgentes)

2) Frontend (front/env.js)

Copie front/env.example.js para front/env.js e ajuste:

• GITHUB_REPO_URL (endpoint da API de issues do repo)
• GITHUB_TOKEN (opcional, mas recomendado para evitar limite)
• TRAINED_PROMPT (prompt institucional)
• OPENAI_NON_URGENT (true ativa envio para Batch API)

Execução

npm install
npm start

Abra no navegador:

• http://localhost:3000

Recursos de economia de custo já implementados

• modelo padrão barato (gpt-4.1-nano);
• fallback para gpt-4.1-mini quando resposta incerta;
• extração de texto de PDF no backend (evita mandar base64 bruto para IA);
• redução de tokens por chunk + resumo;
• limite de tamanho de documento processado;
• limite de max_tokens de saída;
• resposta JSON estrita e curta;
• cache de prompts no backend;
• suporte a Batch API para análises não urgentes.

Endpoints do backend

• POST /api/analyze
  • realiza análise e retorna conteúdo + métricas
• GET /api/batch-status?batchId=...
  • consulta status/resultado de batch

Observações importantes

• O custo em reais é estimado, não é faturamento oficial.
• A precisão do preço depende do câmbio (USD_TO_BRL) e da tabela de preços usada.
• Pontos de atenção são temporários (sessionStorage do navegador).
• Não há persistência em banco por design (projeto simples de verificação).