47f23a73e1
All checks were successful
DEPLOY_MULTI_BRACH/pipeline/head This commit looks good
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
313 lines
8.6 KiB
Markdown
313 lines
8.6 KiB
Markdown
# django-core-base · API Hub Orquestador
|
|
|
|
> V-Encore Lab — Microservicio principal. Actúa como orquestador y punto de entrada central del ecosistema SaaS.
|
|
> Puerto por defecto: **8000**
|
|
|
|
---
|
|
|
|
## Tabla de contenidos
|
|
|
|
1. [Requisitos previos](#requisitos-previos)
|
|
2. [Inicio rápido — Desarrollo local](#inicio-rápido--desarrollo-local)
|
|
3. [Variables de entorno](#variables-de-entorno)
|
|
4. [Base de datos](#base-de-datos)
|
|
5. [Docker — Producción](#docker--producción)
|
|
6. [Estructura del proyecto](#estructura-del-proyecto)
|
|
7. [Endpoints principales](#endpoints-principales)
|
|
8. [Patrón LogService](#patrón-logservice)
|
|
9. [Flujo de ramas](#flujo-de-ramas)
|
|
10. [Mantenimiento](#mantenimiento)
|
|
|
|
---
|
|
|
|
## Requisitos previos
|
|
|
|
| Herramienta | Versión mínima |
|
|
|-------------|---------------|
|
|
| Python | 3.11 |
|
|
| pip | 23+ |
|
|
| Docker | 24+ |
|
|
| Docker Compose | v2 |
|
|
| Git | 2.40+ |
|
|
|
|
---
|
|
|
|
## Inicio rápido — Desarrollo local
|
|
|
|
```bash
|
|
# 1. Clonar
|
|
git clone https://git.v-encore-lab.com/Proyecto-SaaS/django-core-base.git
|
|
cd django-core-base
|
|
|
|
# 2. Entorno virtual
|
|
python -m venv .venv
|
|
source .venv/bin/activate # Linux/Mac
|
|
.venv\Scripts\activate # Windows
|
|
|
|
# 3. Dependencias
|
|
pip install -r deployments/requirements.txt
|
|
|
|
# 4. Variables de entorno
|
|
cp .env.example .env
|
|
# Editar .env según el entorno (ver sección Variables de entorno)
|
|
|
|
# 5. Migraciones (SQLite en local)
|
|
cd app
|
|
python manage.py migrate
|
|
|
|
# 6. Superusuario (primera vez)
|
|
python manage.py createsuperuser
|
|
|
|
# 7. Servidor de desarrollo
|
|
python manage.py runserver 0.0.0.0:8000
|
|
```
|
|
|
|
Accesos:
|
|
- API: http://localhost:8000/api/
|
|
- Admin: http://localhost:8000/admin/
|
|
|
|
---
|
|
|
|
## Variables de entorno
|
|
|
|
Copia `.env.example` a `.env` y ajusta los valores:
|
|
|
|
| Variable | Descripción | Ejemplo / Default |
|
|
|----------------|--------------------------------------------------|----------------------------|
|
|
| `SECRET_KEY` | Clave secreta Django | `django-insecure-...` |
|
|
| `DEBUG` | Modo debug | `True` (dev) / `False` (prod) |
|
|
| `ALLOWED_HOSTS`| Hosts permitidos (separados por coma) | `localhost,127.0.0.1` |
|
|
| `DB_HOST` | Host PostgreSQL. **Si no se define → SQLite** | `localhost` / vacío |
|
|
| `DB_PORT` | Puerto PostgreSQL | `5432` |
|
|
| `DB_NAME` | Nombre de la base de datos | `vencorelab` |
|
|
| `DB_USER` | Usuario PostgreSQL | `postgres` |
|
|
| `DB_PASSWORD` | Contraseña PostgreSQL | `postgres` |
|
|
|
|
---
|
|
|
|
## Base de datos
|
|
|
|
### Desarrollo local — SQLite
|
|
|
|
Si `DB_HOST` **no** está definido en `.env`, Django usa automáticamente SQLite:
|
|
|
|
```
|
|
app/data/db.sqlite3
|
|
```
|
|
|
|
```bash
|
|
cd app
|
|
python manage.py migrate # crea app/data/db.sqlite3
|
|
python manage.py createsuperuser
|
|
```
|
|
|
|
La carpeta `app/data/` está en `.gitignore` (solo se versiona `.gitkeep`).
|
|
|
|
### Producción — PostgreSQL
|
|
|
|
Define `DB_HOST` en `.env` para activar el driver PostgreSQL:
|
|
|
|
```env
|
|
DB_HOST=localhost
|
|
DB_PORT=5432
|
|
DB_NAME=vencorelab
|
|
DB_USER=postgres
|
|
DB_PASSWORD=supersecret
|
|
```
|
|
|
|
```bash
|
|
cd app
|
|
python manage.py migrate
|
|
```
|
|
|
|
### Comandos útiles de migración
|
|
|
|
```bash
|
|
cd app
|
|
|
|
# Ver migraciones pendientes
|
|
python manage.py showmigrations
|
|
|
|
# Crear migraciones de una app
|
|
python manage.py makemigrations <app_name>
|
|
|
|
# Aplicar todas las migraciones
|
|
python manage.py migrate
|
|
|
|
# Revertir migraciones de una app al estado inicial
|
|
python manage.py migrate <app_name> zero
|
|
```
|
|
|
|
---
|
|
|
|
## Docker — Producción
|
|
|
|
```bash
|
|
# Construir e iniciar
|
|
docker-compose up --build -d
|
|
|
|
# Ver logs
|
|
docker-compose logs -f
|
|
|
|
# Parar
|
|
docker-compose down
|
|
|
|
# Parar y eliminar volúmenes (¡cuidado en producción!)
|
|
docker-compose down -v
|
|
```
|
|
|
|
El contenedor expone el puerto **8000**.
|
|
|
|
Para producción con PostgreSQL, asegúrate de que `.env` tenga `DB_HOST` apuntando al host correcto (puede ser el nombre del servicio en la red Docker).
|
|
|
|
---
|
|
|
|
## Estructura del proyecto
|
|
|
|
```
|
|
django-core-base/
|
|
├── app/
|
|
│ ├── api_config/ # Configuración Django (settings, urls, wsgi)
|
|
│ ├── general/ # App transversal
|
|
│ │ └── utilidades/
|
|
│ │ ├── acciones.py # LogService — auditoría centralizada
|
|
│ │ └── utils.py # Utilidades HTTP (get_client_ip, etc.)
|
|
│ ├── backend_admin/ # App admin: modelo Log, endpoints de gestión
|
|
│ ├── common/ # Modelos y utilidades compartidas
|
|
│ ├── promociones/ # App de ejemplo
|
|
│ ├── automatizados/ # Endpoints para Jenkins/automatizaciones
|
|
│ ├── data/ # Directorio de la BD SQLite (gitignored)
|
|
│ │ └── .gitkeep
|
|
│ └── manage.py
|
|
├── deployments/
|
|
│ ├── requirements.txt
|
|
│ └── Dockerfile
|
|
├── docker-compose.yml
|
|
├── .env.example
|
|
└── README.md
|
|
```
|
|
|
|
---
|
|
|
|
## Endpoints principales
|
|
|
|
| Método | Ruta | Descripción | Auth |
|
|
|--------|-------------------------------|-----------------------------------|--------------|
|
|
| POST | `/api/token/` | Obtener JWT (login) | No |
|
|
| POST | `/api/token/refresh/` | Renovar access token | No |
|
|
| GET | `/admin/` | Panel de administración Django | Session |
|
|
| POST | `/api/promociones/obtener/` | Consultar promociones | JWT Bearer |
|
|
| GET | `/api/general/health/` | Health check | No |
|
|
|
|
Autenticación: `Authorization: Bearer <access_token>`
|
|
|
|
---
|
|
|
|
## Patrón LogService
|
|
|
|
Todas las vistas deben usar `LogService` para auditoría:
|
|
|
|
```python
|
|
from general.utilidades.acciones import LogService
|
|
|
|
class MiVista(APIView):
|
|
authentication_classes = [JWTAuthentication]
|
|
permission_classes = [IsAuthenticated]
|
|
|
|
def post(self, request):
|
|
path = '/mi-app/mi-endpoint/'
|
|
|
|
# Bloque 1 — Inicio log
|
|
log_id = LogService.gestionar_log(self, request, path=path)
|
|
|
|
try:
|
|
# Bloque 2 — Limpieza de datos
|
|
data = request.data
|
|
LogService.gestionar_log(self, request, log_id=log_id,
|
|
path=path, body_request=data, status_code=100)
|
|
params = {'campo': data.get('campo')}
|
|
except Exception as error:
|
|
response = {'error': str(error)}
|
|
LogService.gestionar_log(self, request, log_id=log_id,
|
|
path=path, body_response=response, status_code=400)
|
|
return JsonResponse(response, status=400)
|
|
|
|
try:
|
|
# Bloque 3 — Acción
|
|
resultado = mi_accion(params)
|
|
LogService.gestionar_log(self, request, log_id=log_id,
|
|
path=path, body_response=resultado, status_code=200)
|
|
return JsonResponse(resultado, status=200)
|
|
except Exception as error:
|
|
response = {'error': str(error)}
|
|
LogService.gestionar_log(self, request, log_id=log_id,
|
|
path=path, body_response=response, status_code=500)
|
|
return JsonResponse(response, status=500)
|
|
```
|
|
|
|
`LogService` registra automáticamente en la tabla `audit_logs` el usuario, IP, path, request/response y status code.
|
|
|
|
---
|
|
|
|
## Flujo de ramas
|
|
|
|
```
|
|
pre-dev → dev → master
|
|
```
|
|
|
|
- `pre-dev`: desarrollo activo, integración de features
|
|
- `dev`: validación previa a producción
|
|
- `master`: rama de producción estable
|
|
|
|
```bash
|
|
# Crear feature
|
|
git checkout pre-dev
|
|
git checkout -b feature/mi-feature
|
|
|
|
# Mergear a pre-dev
|
|
git checkout pre-dev
|
|
git merge feature/mi-feature --no-ff
|
|
|
|
# Promover a dev
|
|
git checkout dev
|
|
git merge pre-dev --no-ff
|
|
|
|
# Promover a master
|
|
git checkout master
|
|
git merge dev --no-ff
|
|
```
|
|
|
|
---
|
|
|
|
## Mantenimiento
|
|
|
|
```bash
|
|
# Limpiar sesiones expiradas
|
|
cd app && python manage.py clearsessions
|
|
|
|
# Ver estado de la BD
|
|
cd app && python manage.py dbshell
|
|
|
|
# Backup SQLite (desarrollo)
|
|
cp app/data/db.sqlite3 app/data/db.sqlite3.bak
|
|
|
|
# Backup PostgreSQL (producción)
|
|
pg_dump -U postgres vencorelab > backup_$(date +%Y%m%d).sql
|
|
|
|
# Actualizar dependencias
|
|
pip list --outdated
|
|
pip install -U <paquete>
|
|
pip freeze > deployments/requirements.txt
|
|
|
|
# Reiniciar contenedor Docker
|
|
docker-compose restart web
|
|
|
|
# Ver logs del contenedor
|
|
docker-compose logs -f web --tail=100
|
|
```
|
|
|
|
---
|
|
|
|
> **V-Encore Lab** — Sistema Automatizado v1.0
|
|
> Repositorio: `Proyecto-SaaS/django-core-base`
|