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**
|
||||
- Cada domínio organizado dentro do diretório `packages/`
|
||||
- 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
|
||||
```bash
|
||||
git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Tecnologias Utilizadas
|
||||
## 2. Criar o Ambiente Virtual
|
||||
|
||||
- **Linguagem:** Python 3.11+
|
||||
- **ORM:** SQLAlchemy
|
||||
- **Banco de Dados:** Firebird
|
||||
- **Driver:** fdb
|
||||
- **Arquitetura:** Hexagonal por módulo
|
||||
- **Organização:** Modular por domínio
|
||||
O uso de um **ambiente virtual** garante que as bibliotecas instaladas para este projeto não afetem o Python global da sua máquina.
|
||||
|
||||
```bash
|
||||
python -m venv venv
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ 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:**
|
||||
|
||||
```text
|
||||
Api/config/database/firebird.json
|
||||
```bash
|
||||
venv\Scripts\activate
|
||||
```
|
||||
|
||||
**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
|
||||
{
|
||||
"host": "localhost",
|
||||
"name": "D:/Orius/Base/CAIAPONIA.FDB",
|
||||
"port": 3050,
|
||||
"database": "/caminho/para/database.fdb",
|
||||
"user": "SYSDBA",
|
||||
"password": "masterkey"
|
||||
"password": "",
|
||||
"charset": "UTF8",
|
||||
"pool": {
|
||||
"pre_ping": true,
|
||||
"size": 5,
|
||||
"max_overflow": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Classe de conexão:**
|
||||
### Ajustes Necessários:
|
||||
|
||||
```text
|
||||
Api/core/connections/firebird.py
|
||||
```
|
||||
* **host**: Endereço do servidor do banco de dados.
|
||||
* **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:
|
||||
|
||||
- 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
|
||||
Com o ambiente virtual **ativado**, execute o comando abaixo para iniciar a aplicação:
|
||||
|
||||
```bash
|
||||
# Criar ambiente virtual
|
||||
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
|
||||
uvicorn main:app --reload
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📌 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.
|
||||
> **Dica:**
|
||||
> O parâmetro `--reload` reinicia automaticamente a aplicação sempre que houver alterações no código.
|
||||
|
||||
---
|
||||
|
||||
## 👨💻 Autor
|
||||
## 8. Testando a Aplicação
|
||||
|
||||
Desenvolvido por **Orius Tecnologia**
|
||||
GitHub / LinkedIn: [seu-link](#)
|
||||
Após iniciar a aplicação, abra o navegador e acesse o seguinte endereço:
|
||||
|
||||
```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