Visão Geral da Aplicação

v1.0

Sistema de Processamento de Documentos com IA

O TransferLog PHP é uma aplicação inteligente de processamento de documentos que utiliza inteligência artificial para extrair automaticamente dados estruturados de documentos educacionais (PDFs e arquivos Excel) e gerar recibos profissionais.

Principais Funcionalidades

Processamento com IA

Integração com OpenAI GPT para extração inteligente de dados

Suporte Multi-Formato

Processa documentos PDF e Excel perfeitamente

Processamento Automatizado

Processamento em segundo plano com atualizações de status em tempo real

Pipeline de Processamento

1. Upload de Documentos

Upload seguro de arquivos com validação

2. Extração de Texto

Extrai conteúdo de texto de PDFs/Excel

3. Análise com IA

OpenAI GPT processa pedaços para dados estruturados

4. Fusão de Dados

Combina resultados em conjunto de dados final

5. Geração de Recibos

Cria recibos profissionais em Excel

Requisitos do Sistema

  • PHP: 8.1 ou superior
  • Banco de dados: MySQL 5.7+
  • Armazenamento: 500MB+ de espaço livre
  • API OpenAI: Chave de API válida obrigatória

Instalação e Configuração

Instalação Automatizada

A maneira mais fácil de instalar o TransferLog PHP é usando o instalador automatizado:

# Baixe e extraia a aplicação cd /caminho/para/raiz/web/ unzip transferlog-php.zip # Execute o instalador automatizado php install.php

O instalador irá:

Instalação Manual

Se preferir configuração manual:

Passo 1: Configuração do Banco de Dados
# Criar banco de dados mysql -u root -p CREATE DATABASE transferlog_db; GRANT ALL PRIVILEGES ON transferlog_db.* TO 'transferlog_user'@'localhost' IDENTIFIED BY 'sua_senha'; FLUSH PRIVILEGES; EXIT; # Importar esquema mysql -u transferlog_user -p transferlog_db < database/database.sql
Passo 2: Configuração

Edite config/database.php com suas credenciais do banco:

return [ 'host' => 'localhost', 'dbname' => 'transferlog_db', 'username' => 'transferlog_user', 'password' => 'sua_senha' ];
Passo 3: Configuração OpenAI

Adicione sua chave da API OpenAI em config/config.php:

'openai' => [ 'api_key' => 'sua-chave-openai-aqui' ]
Passo 4: Permissões
chmod 755 uploads/ receipts_generated/ logs/ temp/
Passo 5: Executar Migrações
php migrate.php run

Instalação Concluída!

Acesse sua aplicação em: https://seudominio.com/transferlog-php/

Primeiros Passos

Fazendo Login

Acesse a página de login da aplicação e use suas credenciais:

Conta Admin Padrão:
  • Usuário: admin
  • Senha: admin123

Altere a senha padrão após o primeiro login!

Navegação

Após o login, você verá o painel principal com:

  • Upload: Enviar novos documentos
  • Jobs: Monitorar status de processamento
  • Resultados: Visualizar dados extraídos
  • Recibos: Baixar recibos gerados

Enviando Documentos

Tipos de Arquivo Suportados

Arquivos PDF
  • Documentos digitalizados
  • PDFs baseados em texto
  • Até 50MB por arquivo
  • Suporte a OCR para conteúdo digitalizado
Arquivos Excel (.xlsx, .xls)
  • Planilhas estruturadas
  • Tabelas de dados educacionais
  • Até 50MB por arquivo
  • Suporte a múltiplas planilhas

Processo de Upload

1. Navegar para Página de Upload

Clique em "Upload" na navegação principal ou vá para /upload

2. Selecionar Arquivo

Escolha seu arquivo PDF ou Excel usando o seletor de arquivos

3. Adicionar Descrição (Opcional)

Forneça uma descrição para ajudar a identificar o documento

4. Clicar em Upload

O sistema irá validar e enfileirar seu arquivo para processamento

5. Monitorar Progresso

Verifique a página Jobs para ver o status de processamento

Diretrizes de Upload

  • Tamanho do Arquivo: Máximo 50MB por arquivo
  • Conteúdo: Documentos educacionais com dados de escolas/distribuição
  • Formato: Documentos claros e legíveis funcionam melhor
  • Idioma: Conteúdo em português otimizado

Pipeline de Processamento

O TransferLog PHP utiliza um sofisticado pipeline de processamento em múltiplas etapas:

Etapa 1: Extração de Texto

Extrai texto legível de arquivos PDF/Excel

Etapa 2: Divisão em Pedaços

Divide texto em pedaços gerenciáveis para processamento de IA

Etapa 3: Análise com IA

OpenAI GPT extrai dados educacionais estruturados

Etapa 4: Fusão de Resultados

Combina todos os resultados de pedaços em conjunto de dados final

Etapa 5: Geração de Recibos

Cria recibos profissionais em Excel automaticamente

Tempo de Processamento

Tempos típicos de processamento:

Processamento em Segundo Plano

Todo processamento acontece automaticamente em segundo plano. Você pode enviar múltiplos arquivos e verificar seu status a qualquer momento na página Jobs.

Visualizando Resultados

Acessando Resultados

Navegue para a página "Resultados" para visualizar documentos processados:

Lista de Resultados
  • ID do Job: Identificador único para cada job de processamento
  • Nome Original: Nome do arquivo enviado
  • Status: Status de processamento (pendente, processando, concluído)
  • Data de Criação: Quando o job foi enviado
  • Ações: Ver detalhes, baixar dados
Detalhes do Resultado

Clique em "Ver" para ver dados extraídos:

  • Escolas: Lista de instituições educacionais encontradas
  • Modalidades: Programas de ensino e contagem de alunos
  • Dados de Distribuição: Quantidades semanais de distribuição de alimentos
  • Informações do Fornecedor: Nome do fornecedor e CNPJ
  • Metadados: Informações adicionais do documento

Exportando Dados

Na página de resultados, você pode:

Qualidade dos Dados

O processamento com IA inclui pontuações de confiança e validação para garantir precisão dos dados. Revise os resultados antes de usar em produção.

Gerenciando Recibos

Visão Geral dos Recibos

O TransferLog PHP gera automaticamente recibos profissionais em Excel para cada escola encontrada em seus documentos.

Funcionalidades dos Recibos
  • Formato Profissional: Template Excel pré-projetado
  • Por Escola: Recibo individual para cada escola
  • Dados Completos: Todas as informações de distribuição incluídas
  • Formatação em Português: Datas e formatação localizadas
Conteúdo dos Recibos
  • Informações da Escola: Nome, endereço, regional
  • Detalhes da Distribuição: Produtos, quantidades, modalidades
  • Dados do Fornecedor: Nome do fornecedor e CNPJ
  • Detalhamento Semanal: Distribuição por semana
  • Formatação Oficial: Pronto para uso oficial

Encontrando Recibos

Use a página Recibos para:

Geração Automática

Os recibos são gerados automaticamente:

Armazenamento de Recibos

Os recibos gerados são armazenados no diretório receipts_generated/ e ficam permanentemente disponíveis para download.

Solução de Problemas

Problemas de Upload

Problema Solução
Erro "Arquivo muito grande" Verifique limites de upload do PHP em php.ini (máx 50MB)
Erro "Tipo de arquivo inválido" Apenas arquivos PDF e Excel (.pdf, .xlsx, .xls) são suportados
Upload trava ou falha Verifique configurações de timeout do servidor e conexão de rede

Problemas de Processamento

Problema Solução
Job parado em "processando" Verifique se workers em segundo plano estão rodando (cron jobs)
Erros da API OpenAI Verifique se chave da API é válida e tem créditos suficientes
Processamento demora muito Documentos grandes podem levar 30+ minutos para processar
Nenhum resultado gerado Verifique se conteúdo do documento é legível e contém dados educacionais

Problemas de Banco de Dados

Problema Solução
Falha na conexão com banco Verifique credenciais em config/database.php
Erros de migração Execute php migrate.php status para verificar estado das migrações
Permissão negada Certifique-se de que servidor web pode escrever nos diretórios necessários

Problemas com Recibos

Problema Solução
Nenhum recibo gerado Certifique-se de que job foi concluído com sucesso e worker de recibos está rodando
Download de recibo falha Verifique permissões no diretório receipts_generated/
Recibo tem dados errados Revise documento fonte e resultados de extração da IA

Obtendo Ajuda

Se você encontrar problemas não cobertos aqui:

  • Verifique o diretório logs/ para mensagens de erro
  • Revise logs da aplicação para informações detalhadas de erro
  • Contate administrador do sistema com mensagens específicas de erro

Detalhes Técnicos

Arquitetura do Sistema

O TransferLog PHP utiliza uma arquitetura moderna de aplicação PHP:

Componentes Backend
  • PHP 8.1+: Lógica core da aplicação
  • MySQL 5.7+: Persistência de dados
  • API OpenAI: Engine de processamento de IA
  • PhpSpreadsheet: Manipulação de arquivos Excel
  • Monolog: Sistema de logging
Workers de Processamento
  • worker.php: Processamento de arquivos e chunking
  • chunk_worker.php: Análise de IA de pedaços de texto
  • merger.php: Agregação de resultados
  • generate_receipts_new.php: Criação de recibos

Esquema do Banco de Dados

A aplicação utiliza 9 tabelas core:

Tabela Propósito
users Autenticação de usuários e sessões
files Metadados de documentos enviados
jobs Rastreamento de jobs de processamento
chunks Pedaços de texto de documentos para processamento de IA
chunk_results Resultados de processamento de IA por pedaço
results Resultados finais de processamento mesclado
migrations Rastreamento de mudanças no esquema do banco
system_config Configurações da aplicação

Detalhes do Processamento com IA

O sistema utiliza modelos OpenAI GPT para extração inteligente de dados:

Funcionalidades de Segurança

Processamento em Segundo Plano

A aplicação utiliza cron jobs para processamento automatizado:

# Configuração recomendada de cron * * * * * /usr/bin/php /caminho/para/auto_run_workers.php # A cada minuto */5 * * * * /usr/bin/php /caminho/para/generate_receipts_new.php # A cada 5 minutos

Isto garante processamento contínuo sem intervenção manual.