✨ feat(api, docs): Melhora busca e documentação da API #10
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Este commit introduz duas melhorias principais:
LAMP-LUCAS
added a commit
that referenced
this pull request
Sep 17, 2025
* Feature/estrutura inicial | Estrutura inicial completa da AutoSINAPI API com FastAPI, Docker e Kong (#3) * chore: adiciona configuração inicial do projeto * chore(infra): configura ambiente de desenvolvimento com Docker e Kong * feat(api): implementa estrutura inicial da API com FastAPI * feat(worker): adiciona configuração do Celery para tarefas em background * docs: adiciona documentação inicial e padrões de nomenclatura * chore: adiciona arquivo de exemplo para variáveis de ambiente * fixup! chore(infra): configura ambiente de desenvolvimento com Docker e Kong * Feature/correção docker e api | 🚀 Correções e Expansões na Arquitetura da API AutoSINAPI (#4) * chore: adiciona configuração inicial do projeto * chore(infra): configura ambiente de desenvolvimento com Docker e Kong * feat(api): implementa estrutura inicial da API com FastAPI * feat(worker): adiciona configuração do Celery para tarefas em background * docs: adiciona documentação inicial e padrões de nomenclatura * chore: adiciona arquivo de exemplo para variáveis de ambiente * fixup! chore(infra): configura ambiente de desenvolvimento com Docker e Kong * fix(docker): Adiciona permissão de execução ao script de inicialização do DB * feat(project): Refatora arquitetura e adiciona módulos de BI Esta refatoração completa moderniza a arquitetura do projeto, introduzindo modularidade e novas funcionalidades de Business Intelligence. Principais alterações: - Centralização de configurações com Pydantic-Settings em 'api/config.py'. - Atualização de dependências e adição do módulo 'autosinapi' via Git. - Melhoria na orquestração do Docker com 'depends_on' e 'healthcheck' robustos. - Refatoração completa dos módulos da API ('crud', 'main', 'schemas') para usar a nova configuração e desacoplar a lógica. - Adição de três novos endpoints de BI: - Análise de Estrutura (Bill of Materials) - Cálculo de Hora-Homem - Curva ABC de Insumos * feat(bi): Adiciona endpoint de otimização de custo Cria o endpoint /bi/composicao/{codigo}/otimizar que retorna os N insumos de maior impacto financeiro em uma composição, reutilizando a lógica do BOM. * feat(bi): Adiciona endpoint de análise de custo histórico Cria o endpoint /bi/item/{tipo_item}/{codigo}/historico para visualizar a variação de preço/custo de um item ao longo do tempo. Adiciona a dependência python-dateutil para manipulação de datas. * docs(project): Atualiza documentação e adiciona guia de contribuição - Renomeia nomenclaturas.md para CONTRIBUTING.md e expande o conteúdo. - Atualiza o README.md com as novas funcionalidades de BI. - Adiciona o WorkPlan.md com o plano para as próximas funcionalidades. * fix(infra): Corrige inicialização e configuração do ambiente Docker' -m 'Este commit corrige uma série de problemas que impediam a inicialização completa e estável do ambiente Docker, especialmente relacionados à configuração do Kong e suas dependências. (#5) - **`docker-compose.yml`**: - **Uso de Imagem Customizada:** Os serviços `kong` e `kong-migrations` passam a usar uma imagem construída localmente (`build: ./kong/`) em vez da imagem pública, permitindo a customização necessária. - **Correção de Healthcheck:** O `healthcheck` do serviço `sinapi_db` foi ajustado para verificar o usuário e banco de dados corretos (`kong`), garantindo que o status de saúde do banco de dados seja verificado corretamente. - **Correção de Script de Migração:** A sintaxe do laço `until` no comando do `kong-migrations` foi corrigida com a adição da cláusula `do`, resolvendo um erro de shell que bloqueava a inicialização. - **Melhora no Logging:** O comando de bootstrap das migrações foi alterado para `kong migrations bootstrap --vv`, ativando o modo verbose para facilitar a depuração de problemas de inicialização. - **`kong/Dockerfile` (Novo):** - **Criação de Imagem Customizada:** Um novo `Dockerfile` para o Kong foi criado para adicionar dependências que não existem na imagem oficial. - **Instalação do `postgresql-client`:** Adiciona o cliente do PostgreSQL, essencial para que o script de migração possa usar o comando `pg_isready` para verificar o status do banco de dados. - **Gerenciamento de Permissões:** Utiliza `USER root` para instalar as dependências e retorna para `USER kong` ao final, seguindo as boas práticas de segurança para evitar a execução do container com privilégios de root. - **`Dockerfile` (API):** - **Adição do Git:** O `git` foi adicionado à imagem da API para permitir a instalação de dependências diretamente de repositórios Git, se necessário. - **`docker/db/multiple-databases.sh`**: - **Formatação:** Adicionada uma nova linha ao final do arquivo para seguir as convenções de formatação de arquivos de texto. * feat(project): adiciona Makefile e melhora a documentacao de setup (#7) * Fix/db init script execution | 🧩 fix(infra): corrige execução do script de inicialização do banco de dados (#8) * fix(infra): Resolve o erro 'não é possível executar: arquivo necessário não encontrado' na configuração do banco de dados Docker * fix(infra): corrige execucao do script de inicializacao do banco de dados * fix(infra): ajusta chamada da tarefa populate_sinapi_task no Makefile para incluir configuracoes de db e sinapi * docs(project): adiciona documentacao para administracao e uso da API * Fix/db init script execution | 🛠️ Correções na infraestrutura e melhorias no processo de carga de dados do SINAPI (#9) * fix(infra): Resolve o erro 'não é possível executar: arquivo necessário não encontrado' na configuração do banco de dados Docker * fix(infra): corrige execucao do script de inicializacao do banco de dados * fix(infra): ajusta chamada da tarefa populate_sinapi_task no Makefile para incluir configuracoes de db e sinapi * docs(project): adiciona documentacao para administracao e uso da API * feat(etl): implementa bypass de arquivo local para ETL do SINAPI Este commit introduz a capacidade de popular o banco de dados SINAPI usando arquivos .zip locais, ignorando a etapa de download. - Configurado o mapeamento de volume `autosinapi_downloads` no `docker-compose.yml` para os serviços `api` e `celery_worker`. - Atualizado o `README.md` com instruções detalhadas sobre como usar arquivos SINAPI locais, incluindo a estrutura de subdiretórios `AAAA_MM`. fix(infra): resolve problemas de ambiente Docker e acesso à API Este commit corrige vários problemas críticos de infraestrutura e acesso à API: - Corrigido o comando `kong-migrations` no `docker-compose.yml` para importar corretamente a configuração declarativa do Kong a partir de `kong.yml`. Isso resolve os erros de "no Route matched". - Revertido o `kong/kong.yml` para usar a rota genérica `/`. - Depurado e confirmado a resolução do erro `TooManyRedirects` durante o download do ETL (pelo uso de arquivos locais). - Depurado e confirmado a resolução do `psycopg2.OperationalError` na API (garantindo reinícios limpos do Docker). Isso garante que a aplicação esteja totalmente funcional, com a população de dados e o acesso à API funcionando de ponta a ponta. * feat(api, docs): Melhora busca e documentação da API (#10) Este commit introduz duas melhorias principais: 1. Refatoração da Busca de Composições (crud.py): * A lógica de busca agora divide a string de consulta em palavras-chave independentes. * Para cada palavra-chave é aplicado um ILIKE, garantindo resultados mais precisos e flexíveis. * A query SQL é montada dinamicamente para otimizar a performance. 2. Atualização da Documentação (user.md, README.md): * Foram adicionados exemplos de curl para todos os endpoints na documentação do usuário. * O cabeçalhe de autenticação foi corrigido para X-API-KEY nos exemplos. * A documentação agora está mais clara e fácil de usar para novos desenvolvedores.
LAMP-LUCAS
added a commit
that referenced
this pull request
Sep 17, 2025
* Feature/estrutura inicial | Estrutura inicial completa da AutoSINAPI API com FastAPI, Docker e Kong (#3) * chore: adiciona configuração inicial do projeto * chore(infra): configura ambiente de desenvolvimento com Docker e Kong * feat(api): implementa estrutura inicial da API com FastAPI * feat(worker): adiciona configuração do Celery para tarefas em background * docs: adiciona documentação inicial e padrões de nomenclatura * chore: adiciona arquivo de exemplo para variáveis de ambiente * fixup! chore(infra): configura ambiente de desenvolvimento com Docker e Kong * Feature/correção docker e api | 🚀 Correções e Expansões na Arquitetura da API AutoSINAPI (#4) * chore: adiciona configuração inicial do projeto * chore(infra): configura ambiente de desenvolvimento com Docker e Kong * feat(api): implementa estrutura inicial da API com FastAPI * feat(worker): adiciona configuração do Celery para tarefas em background * docs: adiciona documentação inicial e padrões de nomenclatura * chore: adiciona arquivo de exemplo para variáveis de ambiente * fixup! chore(infra): configura ambiente de desenvolvimento com Docker e Kong * fix(docker): Adiciona permissão de execução ao script de inicialização do DB * feat(project): Refatora arquitetura e adiciona módulos de BI Esta refatoração completa moderniza a arquitetura do projeto, introduzindo modularidade e novas funcionalidades de Business Intelligence. Principais alterações: - Centralização de configurações com Pydantic-Settings em 'api/config.py'. - Atualização de dependências e adição do módulo 'autosinapi' via Git. - Melhoria na orquestração do Docker com 'depends_on' e 'healthcheck' robustos. - Refatoração completa dos módulos da API ('crud', 'main', 'schemas') para usar a nova configuração e desacoplar a lógica. - Adição de três novos endpoints de BI: - Análise de Estrutura (Bill of Materials) - Cálculo de Hora-Homem - Curva ABC de Insumos * feat(bi): Adiciona endpoint de otimização de custo Cria o endpoint /bi/composicao/{codigo}/otimizar que retorna os N insumos de maior impacto financeiro em uma composição, reutilizando a lógica do BOM. * feat(bi): Adiciona endpoint de análise de custo histórico Cria o endpoint /bi/item/{tipo_item}/{codigo}/historico para visualizar a variação de preço/custo de um item ao longo do tempo. Adiciona a dependência python-dateutil para manipulação de datas. * docs(project): Atualiza documentação e adiciona guia de contribuição - Renomeia nomenclaturas.md para CONTRIBUTING.md e expande o conteúdo. - Atualiza o README.md com as novas funcionalidades de BI. - Adiciona o WorkPlan.md com o plano para as próximas funcionalidades. * fix(infra): Corrige inicialização e configuração do ambiente Docker' -m 'Este commit corrige uma série de problemas que impediam a inicialização completa e estável do ambiente Docker, especialmente relacionados à configuração do Kong e suas dependências. (#5) - **`docker-compose.yml`**: - **Uso de Imagem Customizada:** Os serviços `kong` e `kong-migrations` passam a usar uma imagem construída localmente (`build: ./kong/`) em vez da imagem pública, permitindo a customização necessária. - **Correção de Healthcheck:** O `healthcheck` do serviço `sinapi_db` foi ajustado para verificar o usuário e banco de dados corretos (`kong`), garantindo que o status de saúde do banco de dados seja verificado corretamente. - **Correção de Script de Migração:** A sintaxe do laço `until` no comando do `kong-migrations` foi corrigida com a adição da cláusula `do`, resolvendo um erro de shell que bloqueava a inicialização. - **Melhora no Logging:** O comando de bootstrap das migrações foi alterado para `kong migrations bootstrap --vv`, ativando o modo verbose para facilitar a depuração de problemas de inicialização. - **`kong/Dockerfile` (Novo):** - **Criação de Imagem Customizada:** Um novo `Dockerfile` para o Kong foi criado para adicionar dependências que não existem na imagem oficial. - **Instalação do `postgresql-client`:** Adiciona o cliente do PostgreSQL, essencial para que o script de migração possa usar o comando `pg_isready` para verificar o status do banco de dados. - **Gerenciamento de Permissões:** Utiliza `USER root` para instalar as dependências e retorna para `USER kong` ao final, seguindo as boas práticas de segurança para evitar a execução do container com privilégios de root. - **`Dockerfile` (API):** - **Adição do Git:** O `git` foi adicionado à imagem da API para permitir a instalação de dependências diretamente de repositórios Git, se necessário. - **`docker/db/multiple-databases.sh`**: - **Formatação:** Adicionada uma nova linha ao final do arquivo para seguir as convenções de formatação de arquivos de texto. * feat(project): adiciona Makefile e melhora a documentacao de setup (#7) * Fix/db init script execution | 🧩 fix(infra): corrige execução do script de inicialização do banco de dados (#8) * fix(infra): Resolve o erro 'não é possível executar: arquivo necessário não encontrado' na configuração do banco de dados Docker * fix(infra): corrige execucao do script de inicializacao do banco de dados * fix(infra): ajusta chamada da tarefa populate_sinapi_task no Makefile para incluir configuracoes de db e sinapi * docs(project): adiciona documentacao para administracao e uso da API * Fix/db init script execution | 🛠️ Correções na infraestrutura e melhorias no processo de carga de dados do SINAPI (#9) * fix(infra): Resolve o erro 'não é possível executar: arquivo necessário não encontrado' na configuração do banco de dados Docker * fix(infra): corrige execucao do script de inicializacao do banco de dados * fix(infra): ajusta chamada da tarefa populate_sinapi_task no Makefile para incluir configuracoes de db e sinapi * docs(project): adiciona documentacao para administracao e uso da API * feat(etl): implementa bypass de arquivo local para ETL do SINAPI Este commit introduz a capacidade de popular o banco de dados SINAPI usando arquivos .zip locais, ignorando a etapa de download. - Configurado o mapeamento de volume `autosinapi_downloads` no `docker-compose.yml` para os serviços `api` e `celery_worker`. - Atualizado o `README.md` com instruções detalhadas sobre como usar arquivos SINAPI locais, incluindo a estrutura de subdiretórios `AAAA_MM`. fix(infra): resolve problemas de ambiente Docker e acesso à API Este commit corrige vários problemas críticos de infraestrutura e acesso à API: - Corrigido o comando `kong-migrations` no `docker-compose.yml` para importar corretamente a configuração declarativa do Kong a partir de `kong.yml`. Isso resolve os erros de "no Route matched". - Revertido o `kong/kong.yml` para usar a rota genérica `/`. - Depurado e confirmado a resolução do erro `TooManyRedirects` durante o download do ETL (pelo uso de arquivos locais). - Depurado e confirmado a resolução do `psycopg2.OperationalError` na API (garantindo reinícios limpos do Docker). Isso garante que a aplicação esteja totalmente funcional, com a população de dados e o acesso à API funcionando de ponta a ponta. * feat(api, docs): Melhora busca e documentação da API (#10) Este commit introduz duas melhorias principais: 1. Refatoração da Busca de Composições (crud.py): * A lógica de busca agora divide a string de consulta em palavras-chave independentes. * Para cada palavra-chave é aplicado um ILIKE, garantindo resultados mais precisos e flexíveis. * A query SQL é montada dinamicamente para otimizar a performance. 2. Atualização da Documentação (user.md, README.md): * Foram adicionados exemplos de curl para todos os endpoints na documentação do usuário. * O cabeçalhe de autenticação foi corrigido para X-API-KEY nos exemplos. * A documentação agora está mais clara e fácil de usar para novos desenvolvedores. * docs(release): Prepara documentação para o release v0.1.0-beta.0 * chore(license): Altera a licença para GPLv3 e atualiza dependência
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
📌 Descrição
Este PR introduz duas melhorias significativas:
🔍 Busca por composições aprimorada
A função
search_composicoes_by_descricaofoi reescrita para permitir buscas mais flexíveis e precisas. Agora, a string de busca é quebrada em palavras-chave individuais, e cada uma é usada em cláusulasILIKEcombinadas comAND, permitindo resultados mais relevantes.Exemplo: uma busca por
"CONCRETO BOMBEADO"agora retorna composições que contenham ambas as palavras, em qualquer ordem.📚 Expansão da documentação do usuário
O arquivo
docs/user.mdfoi enriquecido com exemplos de uso viacurl, parâmetros esperados e retornos para diversos endpoints:/insumos//composicoes//bi/composicao/{codigo}/hora-homem/bi/curva-abc/bi/composicao/{codigo}/otimizar/bi/item/{tipo_item}/{codigo}/historico/admin/populate-databaseIsso facilita o onboarding de novos usuários e melhora a experiência de desenvolvedores que consomem a API.
📂 Arquivos Modificados
api/crud.py: Refatorada a lógica de busca por composições.README.md: Corrigido exemplo de chamada à API.docs/user.md: Documentação expandida com exemplos e explicações detalhadas.✅ Benefícios