fix(Readme): Ajustado o readme para orientar sobre a instalação do projeto
This commit is contained in:
parent
1946f3dc53
commit
ee0585fc3f
1 changed files with 102 additions and 110 deletions
212
README.md
212
README.md
|
|
@ -1,150 +1,142 @@
|
||||||
# 🧩 Projeto [SAAS]
|
# Configuração do Projeto Python
|
||||||
|
|
||||||
Este projeto é uma **API monolítica modular**, onde cada módulo representa um **domínio específico** da aplicação. Internamente, cada módulo é construído sobre a **Arquitetura Hexagonal**, promovendo separação de responsabilidades, testabilidade e independência da infraestrutura.
|
Este guia descreve o passo a passo para configurar o ambiente de desenvolvimento de um projeto Python, incluindo a preparação do ambiente virtual, instalação de dependências e configuração do banco de dados.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ⚙️ Visão Geral da Arquitetura
|
## 1. Clonar o Projeto
|
||||||
|
|
||||||
### 🏗️ Estrutura Monolítica Modular
|
Primeiro, clone o repositório do projeto a partir do Git:
|
||||||
|
|
||||||
- Modelo **monolítico**, modularizado por **domínios**
|
```bash
|
||||||
- Cada domínio organizado dentro do diretório `packages/`
|
git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git
|
||||||
- Componentes por domínio:
|
|
||||||
- **Controllers** (entrada)
|
|
||||||
- **Endpoints** (rotas)
|
|
||||||
- **Schemas** (validação e transformação)
|
|
||||||
- **Actions** (orquestração de lógica)
|
|
||||||
- **Services** (casos de uso)
|
|
||||||
- **Repositories** (acesso a dados)
|
|
||||||
|
|
||||||
### 🧭 Arquitetura Hexagonal por Módulo
|
|
||||||
|
|
||||||
```text
|
|
||||||
/<domínio>
|
|
||||||
/actions # Orquestra lógica entre services, schemas e repositories
|
|
||||||
/controllers # Interface entre endpoints e actions
|
|
||||||
/endpoints # Define as rotas da API
|
|
||||||
/repositories # Acesso ao Firebird via SQLAlchemy
|
|
||||||
/schemas # Entrada e saída de dados
|
|
||||||
/services # Casos de uso
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🛠️ Tecnologias Utilizadas
|
## 2. Criar o Ambiente Virtual
|
||||||
|
|
||||||
- **Linguagem:** Python 3.11+
|
O uso de um **ambiente virtual** garante que as bibliotecas instaladas para este projeto não afetem o Python global da sua máquina.
|
||||||
- **ORM:** SQLAlchemy
|
|
||||||
- **Banco de Dados:** Firebird
|
```bash
|
||||||
- **Driver:** fdb
|
python -m venv venv
|
||||||
- **Arquitetura:** Hexagonal por módulo
|
```
|
||||||
- **Organização:** Modular por domínio
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🗄️ Banco de Dados
|
## 3. Ativar o Ambiente Virtual
|
||||||
|
|
||||||
O projeto utiliza **Firebird** como banco principal.
|
Ative o ambiente virtual antes de instalar as dependências ou executar a aplicação.
|
||||||
|
|
||||||
**Arquivo de configuração:**
|
```bash
|
||||||
|
venv\Scripts\activate
|
||||||
```text
|
|
||||||
Api/config/database/firebird.json
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Exemplo:**
|
> **Observação:**
|
||||||
|
> Em sistemas Unix (Linux/Mac), o comando pode ser:
|
||||||
|
>
|
||||||
|
> ```bash
|
||||||
|
> source venv/bin/activate
|
||||||
|
> ```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Instalar Dependências do Sistema
|
||||||
|
|
||||||
|
A biblioteca de criptografia utilizada no projeto requer uma extensão da Microsoft para ser instalada.
|
||||||
|
Baixe e instale o **Microsoft C++ Build Tools** através do link abaixo:
|
||||||
|
|
||||||
|
[https://visualstudio.microsoft.com/pt-br/visual-cpp-build-tools/](https://visualstudio.microsoft.com/pt-br/visual-cpp-build-tools/)
|
||||||
|
|
||||||
|
Durante a instalação, selecione o pacote:
|
||||||
|
|
||||||
|
```
|
||||||
|
Desktop Development With C++
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Instalar as Bibliotecas do Projeto
|
||||||
|
|
||||||
|
Com o ambiente virtual **ativado**, instale as dependências listadas no arquivo `requirements.txt`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Configurar o Banco de Dados
|
||||||
|
|
||||||
|
O projeto utiliza um banco **Firebird**.
|
||||||
|
Edite o arquivo de configuração localizado em:
|
||||||
|
|
||||||
|
```
|
||||||
|
api/config/database/firebird.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Exemplo do conteúdo padrão:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"host": "localhost",
|
"host": "localhost",
|
||||||
|
"name": "D:/Orius/Base/CAIAPONIA.FDB",
|
||||||
"port": 3050,
|
"port": 3050,
|
||||||
"database": "/caminho/para/database.fdb",
|
|
||||||
"user": "SYSDBA",
|
"user": "SYSDBA",
|
||||||
"password": "masterkey"
|
"password": "",
|
||||||
|
"charset": "UTF8",
|
||||||
|
"pool": {
|
||||||
|
"pre_ping": true,
|
||||||
|
"size": 5,
|
||||||
|
"max_overflow": 10
|
||||||
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Classe de conexão:**
|
### Ajustes Necessários:
|
||||||
|
|
||||||
```text
|
* **host**: Endereço do servidor do banco de dados.
|
||||||
Api/core/connections/firebird.py
|
* **name**: Caminho completo do arquivo `.FDB`.
|
||||||
```
|
* **port**: Porta do Firebird (padrão: `3050`).
|
||||||
|
* **user**: Usuário do banco de dados.
|
||||||
|
* **password**: Senha do usuário configurado.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🧠 SQLAlchemy com Queries Manuais
|
## 7. Iniciar a Aplicação
|
||||||
|
|
||||||
Utilizamos SQLAlchemy para:
|
Com o ambiente virtual **ativado**, execute o comando abaixo para iniciar a aplicação:
|
||||||
|
|
||||||
- Gerenciar conexões
|
|
||||||
- Preencher parâmetros em queries nativas
|
|
||||||
|
|
||||||
**Exemplo:**
|
|
||||||
|
|
||||||
```python
|
|
||||||
sql = "SELECT * FROM CLIENTES WHERE ID = :id"
|
|
||||||
params = {"id": 123}
|
|
||||||
result = session.execute(text(sql), params).fetchall()
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🗂️ Estrutura de Diretórios
|
|
||||||
|
|
||||||
```text
|
|
||||||
Api/
|
|
||||||
├── api/
|
|
||||||
│ └── v1/
|
|
||||||
│ ├── packages/
|
|
||||||
│ │ └── administrative/
|
|
||||||
│ │ ├── actions/
|
|
||||||
│ │ ├── controllers/
|
|
||||||
│ │ ├── endpoints/
|
|
||||||
│ │ ├── repositories/
|
|
||||||
│ │ ├── schemas/
|
|
||||||
│ │ └── services/
|
|
||||||
│ └── api.py
|
|
||||||
├── config/
|
|
||||||
│ └── database/firebird.json
|
|
||||||
├── core/
|
|
||||||
│ ├── base/
|
|
||||||
│ ├── connections/
|
|
||||||
│ ├── system/
|
|
||||||
│ ├── utils/
|
|
||||||
│ └── auth.py
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ▶️ Executando a API
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Criar ambiente virtual
|
uvicorn main:app --reload
|
||||||
python -m venv .venv
|
|
||||||
|
|
||||||
# Ativar ambiente virtual
|
|
||||||
source .venv/bin/activate # Linux/macOS
|
|
||||||
.venv\Scripts\activate # Windows
|
|
||||||
|
|
||||||
# Instalar dependências
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
# Executar a API
|
|
||||||
uvicorn api.v1.api:app --reload
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
> **Dica:**
|
||||||
|
> O parâmetro `--reload` reinicia automaticamente a aplicação sempre que houver alterações no código.
|
||||||
## 📌 Observações
|
|
||||||
|
|
||||||
- Novos domínios devem seguir a estrutura modular.
|
|
||||||
- A arquitetura hexagonal facilita manutenção e futura extração para microsserviços.
|
|
||||||
- A separação entre actions, services e repositories melhora a organização e testabilidade.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 👨💻 Autor
|
## 8. Testando a Aplicação
|
||||||
|
|
||||||
Desenvolvido por **Orius Tecnologia**
|
Após iniciar a aplicação, abra o navegador e acesse o seguinte endereço:
|
||||||
GitHub / LinkedIn: [seu-link](#)
|
|
||||||
|
```http
|
||||||
|
http://localhost:8000/docs
|
||||||
|
```
|
||||||
|
|
||||||
|
Você deverá visualizar a interface do **Swagger**, onde estarão listados todos os endpoints disponíveis da API.
|
||||||
|
|
||||||
|
> **Observação:**
|
||||||
|
> O Swagger permite testar os endpoints diretamente pelo navegador, sem necessidade de ferramentas externas como Postman ou Insomnia.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resumo dos Comandos
|
||||||
|
|
||||||
|
| Etapa | Comando |
|
||||||
|
| ----------------------- | ------------------------------------------------------------------------------- |
|
||||||
|
| Clonar o projeto | `git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git` |
|
||||||
|
| Criar ambiente virtual | `python -m venv venv` |
|
||||||
|
| Ativar ambiente virtual | `venv\Scripts\activate` *(Windows)*<br>`source venv/bin/activate` *(Linux/Mac)* |
|
||||||
|
| Instalar dependências | `pip install -r requirements.txt` |
|
||||||
|
| Iniciar a aplicação | `uvicorn main:app --reload` |
|
||||||
Loading…
Add table
Reference in a new issue