# Nube Backend — DaaS API

Backend FastAPI que actúa como capa de orquestación para servicios de **Database as a Service (DaaS)**. Consume servicios gRPC externos (C#/.NET) para acceso a datos y expone una API REST para los clientes del sistema.

La autenticación de usuarios usa el Bearer token emitido por el sistema padre (vCloud). Las operaciones internas de escritura requieren adicionalmente un `X-Internal-Key`.

> Para convenciones de desarrollo genéricas (routers, servicios, modelos, excepciones) ver [CORE_STRUCTURE.md](CORE_STRUCTURE.md).
> Para patrones específicos de este proyecto (gRPC client, operaciones internas, agregar nuevos DAOs) ver [DEVELOPMENT.md](DEVELOPMENT.md).

---

## Requisitos

- Python 3.11+
- Acceso al servidor gRPC del servicio DaaS
- Certificado TLS del servidor gRPC (`.crt`)
- **Windows:** [Git for Windows](https://git-scm.com/download/win) — incluye Git Bash, necesario para ejecutar `compile_proto.sh`

---

## Instalación

### Linux / macOS

```bash
# 1. Clonar y entrar al proyecto
git clone <repo-url>
cd nube_bcknd

# 2. Crear entorno virtual e instalar dependencias
python -m venv venv
source venv/bin/activate
pip install -r requirements

# 3. Configurar variables de entorno
cp .env.example .env
# Editar .env con los valores del ambiente
```

### Windows

```powershell
# 1. Clonar y entrar al proyecto
git clone <repo-url>
cd nube_bcknd

# 2. Crear entorno virtual e instalar dependencias
python -m venv venv
venv\Scripts\activate
pip install -r requirements

# 3. Configurar variables de entorno
copy .env.example .env
# Editar .env con los valores del ambiente (Notepad, VS Code, etc.)
```

> Para una guía detallada paso a paso en Windows (incluyendo instalación de dependencias y solución de problemas comunes) ver [WINDOWS_SETUP.md](WINDOWS_SETUP.md).

---

## Variables de entorno

Variables requeridas para ejecutar el servicio:

| Sección | Variables |
|---|---|
| App | `APP_TITLE`, `APP_VERSION`, `NAME_APP`, `HOSTING`, `PORT`, `RELOAD`, `ALLOW_ORIGINS` |
| Base de datos | `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` |
| Operaciones internas | `INTERNAL_API_KEY` |
| gRPC DAOs | `GRPC_CLOUD_SERVICES_DAO_HOST`, `GRPC_CLOUD_SERVICES_DAO_CERT` |

> El resto de variables en `.env.example` (autenticación JWT, email, tokens de registro) pertenecen al core base y se activarán conforme se integren esos módulos.

---

## Compilar archivos proto

Los stubs gRPC **no se versionan**. Deben generarse en cada ambiente después de clonar.

```bash
# Instalar herramienta de compilación (solo una vez)
pip install grpcio-tools
```

### Linux / macOS

```bash
bash compile_proto.sh
```

### Windows

Usar **Git Bash** (no PowerShell ni CMD):

```bash
bash compile_proto.sh
```

> Git Bash viene incluido con Git for Windows. Buscar "Git Bash" en el menú de inicio, navegar al directorio del proyecto y ejecutar el comando.

Los `.proto` fuente están en `proto/`. Los archivos generados (`*_pb2.py`, `*_pb2_grpc.py`) se crean en `app/grpc/generated/` y son ignorados por git.

---

## Certificados TLS

Colocar el certificado del servidor gRPC en `certs/` con el nombre configurado en `.env`:

```
certs/
└── ca.crt     ← certificado del servidor gRPC
```

La carpeta `certs/` está en `.gitignore`. Cada ambiente debe tener su propio certificado.

---

## Levantar el servidor

```bash
python main.py
```

O directamente con uvicorn:

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

La documentación interactiva queda disponible en:
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

---

## Autenticación

### Rutas de usuario
Requieren el Bearer token del sistema padre (vCloud):

```http
Authorization: Bearer <token_vcloud>
```

### Rutas de operación interna (inserts, escrituras)
Requieren el Bearer token **más** el header de operación interna:

```http
Authorization: Bearer <token_vcloud>
X-Internal-Key: <valor_de_INTERNAL_API_KEY>
```

Sin el `X-Internal-Key` correcto la respuesta es `403 Forbidden` aunque el token sea válido.

---

## Estructura del proyecto

```
nube_bcknd/
├── main.py                        # Entry point
├── compile_proto.sh               # Compilador de .proto
├── requirements                   # Dependencias Python
├── .env.example                   # Plantilla de variables de entorno
├── proto/                         # Fuentes .proto (versionados)
├── certs/                         # Certificados TLS (NO versionados)
│
└── app/
    ├── api/v1/                    # Routers (autocarga dinámica)
    ├── core/                      # Config, DB, CRUD, logger, utilidades
    ├── dependencies/              # auth.py (get_current_user, require_internal)
    ├── exceptions/                # Jerarquía de errores de dominio
    ├── grpc/
    │   ├── generated/             # Stubs generados por protoc (NO versionados)
    │   └── clients/               # Clientes gRPC listos para usar en servicios
    ├── models/                    # Modelos SQLAlchemy
    └── services/                  # Lógica de negocio
```

---

## Tests

```bash
pytest
```

---

## Flujo de una request

```
Cliente HTTP
    ↓  Authorization: Bearer <token>  [+ X-Internal-Key en rutas admin]
Router  (app/api/v1/)
    ↓  Depends(get_current_user)  [+ Depends(require_internal)]
Service (app/services/)
    ↓
gRPC Client (app/grpc/clients/)
    ↓  TLS
Servidor gRPC externo (DaaS / C#)
```