150 lines
3.3 KiB
Markdown
150 lines
3.3 KiB
Markdown
# 🧩 Projeto [SAAS]
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## ⚙️ Visão Geral da Arquitetura
|
|
|
|
### 🏗️ Estrutura Monolítica Modular
|
|
|
|
- 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
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ Tecnologias Utilizadas
|
|
|
|
- **Linguagem:** Python 3.11+
|
|
- **ORM:** SQLAlchemy
|
|
- **Banco de Dados:** Firebird
|
|
- **Driver:** fdb
|
|
- **Arquitetura:** Hexagonal por módulo
|
|
- **Organização:** Modular por domínio
|
|
|
|
---
|
|
|
|
## 🗄️ Banco de Dados
|
|
|
|
O projeto utiliza **Firebird** como banco principal.
|
|
|
|
**Arquivo de configuração:**
|
|
|
|
```text
|
|
Api/config/database/firebird.json
|
|
```
|
|
|
|
**Exemplo:**
|
|
|
|
```json
|
|
{
|
|
"host": "localhost",
|
|
"port": 3050,
|
|
"database": "/caminho/para/database.fdb",
|
|
"user": "SYSDBA",
|
|
"password": "masterkey"
|
|
}
|
|
```
|
|
|
|
**Classe de conexão:**
|
|
|
|
```text
|
|
Api/core/connections/firebird.py
|
|
```
|
|
|
|
---
|
|
|
|
## 🧠 SQLAlchemy com Queries Manuais
|
|
|
|
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
|
|
|
|
```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
|
|
```
|
|
|
|
---
|
|
|
|
## 📌 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
|
|
|
|
Desenvolvido por **Orius Tecnologia**
|
|
GitHub / LinkedIn: [seu-link](#)
|