API de Localização de Lojas Físicas by FR-macedo

Esta API permite aos usuários encontrar a loja física mais próxima com base no seu CEP, utilizando a API ViaCEP para obter as informações de localização.

Funcionalidades

• Consulta de lojas físicas mais próximas com base no CEP do usuário
• Validação de CEP
• Filtro de lojas por proximidade (raio de 100km)
• Ordenação por distância ou nome da loja
• Logs detalhados das operações

Tecnologias Utilizadas

• TypeScript
• Express.js
• MongoDB (Mongoose)
• Axios
• Winston (para logs)
• Jest (para testes)
• dotenv (para variaveis de ambiente)

Estrutura do Projeto

O projeto segue uma arquitetura em camadas:

• Controllers: Gerenciam as requisições HTTP e respostas
• Services: Contêm a lógica de negócio
• Models: Definem os esquemas do MongoDB
• Routes: Definem as rotas da API
• Middlewares: Processam requisições antes de chegarem aos controllers
• Utils: Funções utilitárias como cálculo de distância
• Config: Configuração do banco de dados e logger

Instalação

1. Clone o repositório

git clone https://github.com/FR-macedo/Physical-Stores-Finder.git
cd Physical-Stores-Finder

2. Instale as dependências

npm install

3. Configure o MongoDB

• Certifique-se de ter o MongoDB instalado e rodando na porta 27017
• Ou atualize a URL de conexão nas variaveis de ambiente

4. Popule o banco de dados com lojas de teste

npm run seed

5. Inicie o servidor de desenvolvimento

npm run dev

Uso da API

Encontrar a loja mais próxima

GET /api/stores/nearest/:cep

Exemplo:

GET /api/stores/nearest/01310100

Listar lojas próximas com paginação e ordenação

GET /api/stores/nearby/:cep?page=1&limit=10&sortBy=distance&sortOrder=asc

Parâmetros de query:

• page: Número da página (padrão: 1)
• limit: Itens por página (padrão: 10)
• sortBy: Campo para ordenação - 'distance' ou 'name' (padrão: 'distance')
• sortOrder: Ordem - 'asc' ou 'desc' (padrão: 'asc')

Testes

Para executar os testes:

npm test

Estratégia de Versionamento (GitFlow)

O projeto utiliza o modelo GitFlow para controle de versão:

• main: Branch principal que contém código de produção
• develop: Branch de desenvolvimento
• feature/*: Branches para novas funcionalidades
• bugfix/*: Branches para correção de bugs
• release/*: Branches para preparação de releases
• hotfix/*: Branches para correções urgentes em produção

Fluxo de trabalho:

1. Crie uma branch de feature a partir de develop

git checkout -b feature/nome-da-feature develop

2. Trabalhe na feature e faça commits

git add .
git commit -m "Implementação da feature X"

3. Finalize a feature mesclando com develop

git checkout develop
git merge --no-ff feature/nome-da-feature

4. Para criar uma release

git checkout -b release/1.0.0 develop
# Faça ajustes finais se necessário
git checkout main
git merge --no-ff release/1.0.0
git tag -a v1.0.0 -m "Versão 1.0.0"

Licença

Este projeto está licenciado sob a licença MIT.