poc-mvc-ocr/README.md

Claro! Aqui está um exemplo de **README** para o seu projeto, cobrindo a criação do **virtual environment (venv)**, instalação de dependências, execução do **Flasgger** para documentação e execução de **testes**:

---

# Projeto de Testes com SQLAlchemy, Factory Boy e Flask

Este é um projeto simples de teste utilizando **SQLAlchemy**, **Factory Boy** para a criação de dados e **Flasgger** para a documentação de APIs. O projeto inclui exemplos de como configurar o ambiente de desenvolvimento, realizar testes e gerar documentação interativa para suas APIs.

## Índice

- [Pré-requisitos](#pré-requisitos)
- [Instalação](#instalação)
- [Uso](#uso)
  - [Rodar Flasgger (Documentação da API)](#rodar-flasgger-documentação-da-api)
  - [Rodar Testes Unitários](#rodar-testes-unitários)
- [Estrutura de Diretórios](#estrutura-de-diretórios)

## Pré-requisitos

Antes de começar, você precisa ter o **Python** instalado na sua máquina. Você pode verificar se o Python está instalado executando o seguinte comando:

```sh
python --version
```

Se você não tiver o Python instalado, pode obter a versão mais recente [aqui](https://www.python.org/downloads/).

Além disso, é necessário ter o **pip** (gerenciador de pacotes do Python) instalado. Você pode verificar isso com:

```sh
pip --version
```

## Instalação

1. **Crie um ambiente virtual (virtualenv):**

   Para isolar as dependências do seu projeto, é recomendável criar um **ambiente virtual**. Navegue até o diretório do projeto e execute:

   ```sh
   python -m venv venv
   ```

2. **Ative o ambiente virtual:**

   - **No Windows:**

     ```sh
     venv\Scripts\activate
     ```

   - **No macOS/Linux:**

     ```sh
     source venv/bin/activate
     ```

3. **Instale as dependências:**

   Após ativar o ambiente virtual, instale as dependências necessárias listadas no `requirements.txt`:

   ```sh
   pip install -r requirements.txt
   ```

4. **Requisitos (requirements.txt)**:

   Certifique-se de que o arquivo `requirements.txt` contenha as bibliotecas necessárias:

   ```txt
   Flask
   Flask-SQLAlchemy
   Flask-Flasgger
   factory_boy
   pytest
   ```

## Uso

### Rodar Flasgger (Documentação da API)

Este projeto utiliza o **Flasgger** para gerar uma interface de documentação interativa para as APIs Flask. Para visualizar a documentação da sua API:

1. **Inicie o servidor Flask:**

   Certifique-se de que o ambiente virtual está ativado e execute o seguinte comando:

   ```sh
   flask run
   ```

2. **Abra a documentação no navegador:**

   Depois que o servidor estiver em execução, você pode acessar a documentação da API através do seguinte endereço:

   ```
   http://127.0.0.1:5000/apidocs/
   ```

   A interface do **Flasgger** permitirá que você veja as rotas, envie requisições e veja as respostas de forma interativa.

### Rodar Testes Unitários

Este projeto usa o **pytest** para rodar testes unitários. Os testes estão localizados na pasta `tests/`.

Para rodar os testes, execute:

```sh
pytest -v
```

Isso irá rodar todos os testes dentro da pasta `tests/`. Você verá a saída com os resultados dos testes diretamente no terminal.

#### Exemplo de execução de teste unitário:

```sh
tests/test_invoices.py::test_get_invoices
```

### Rodar Testes Rápidos (Sem Flask)

Se você quiser rodar testes rápidos sem o Flask (usando apenas SQLAlchemy e Factory Boy), pode executar o seguinte código diretamente, sem iniciar o servidor Flask. Apenas instancie o banco em memória e rode a fábrica.

```python
# Executar a criação de usuários sem o Flask (em memória)
from app.database import db
from tests.factories import UserFactory

# Configurar banco de dados em memória
engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)

# Criar um usuário usando a factory
user = UserFactory.create(name="João", email="joao@example.com")
print(user.name, user.email)
```

Este código irá criar um banco de dados SQLite temporário em memória e usar o **Factory Boy** para gerar dados de teste rapidamente.

## Estrutura de Diretórios

A estrutura do projeto segue a seguinte organização:

```
/project-root
  ├── /app
  │    ├── /__init__.py
  │    ├── /models.py
  │    ├── /routes.py
  │    └── /database.py
  ├── /tests
  │    ├── /__init__.py
  │    ├── /test_invoices.py
  │    └── /factories.py
  ├── requirements.txt
  ├── run.py
  ├── /venv
  └── README.md
```

- **/app**: Contém a lógica da aplicação Flask (modelos, rotas, configuração do banco de dados).
- **/tests**: Contém os testes unitários, como `test_invoices.py`.
- **requirements.txt**: Arquivo que contém todas as dependências do projeto.
- **run.py**: Script para iniciar o servidor Flask.
- **venv/**: Diretório do ambiente virtual.