Proyecto-SaaS/django-core-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: README completo con despliegue, BD y mantenimiento
All checks were successful
DEPLOY_MULTI_BRACH/pipeline/head This commit looks good
Details

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
juanjo
2026-04-16 23:59:54 +02:00
parent 04c37f669c
commit 47f23a73e1
1 changed files with 284 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

329
README.md
View File

@@ -1,73 +1,312 @@
# django-core-base # django-core-base · API Hub Orquestador
// V-Encore Lab: Sistema Automatizado v1.0.4 > V-Encore Lab — Microservicio principal. Actúa como orquestador y punto de entrada central del ecosistema SaaS.
> Puerto por defecto: **8000**
## 🚀 Inicio Rápido (Desarrollo Local) ---
## 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
### 1. Clonar y Configurar
```bash ```bash
# 1. Clonar
git clone https://git.v-encore-lab.com/Proyecto-SaaS/django-core-base.git git clone https://git.v-encore-lab.com/Proyecto-SaaS/django-core-base.git
cd django-core-base cd django-core-base
cp .env.example .env
```
### 2. Instalar Dependencias # 2. Entorno virtual
```bash python -m venv .venv
source .venv/bin/activate # Linux/Mac
.venv\Scripts\activate # Windows
# 3. Dependencias
pip install -r deployments/requirements.txt pip install -r deployments/requirements.txt
```
### 3. Migraciones de Base de Datos # 4. Variables de entorno
```bash cp .env.example .env
# Crear y aplicar migraciones para todos los modelos # Editar .env según el entorno (ver sección Variables de entorno)
python manage.py makemigrations
# 5. Migraciones (SQLite en local)
cd app
python manage.py migrate python manage.py migrate
# Opcional: Crear superusuario # 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 python manage.py createsuperuser
``` ```
### 4. Correr el Servidor La carpeta `app/data/` está en `.gitignore` (solo se versiona `.gitkeep`).
```bash
python manage.py runserver ### 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
``` ```
Abrir http://localhost:8000
## 🐳 Docker (Producción/Desarrollo)
```bash ```bash
docker-compose up --build cd app
python manage.py migrate
``` ```
Acceder a: ### Comandos útiles de migración
- App: http://localhost:8000
- Admin: http://localhost:8000/admin/
- DB: localhost:5432 (Postgres)
## 📋 Comandos Django Comunes
```bash ```bash
# Verificar configuración cd app
python manage.py check
# Recopilar static files # Ver migraciones pendientes
python manage.py collectstatic --noinput python manage.py showmigrations
# Test # Crear migraciones de una app
python manage.py test 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
``` ```
## 🔧 Estructura del Proyecto ---
``` ## Docker — Producción
├── apps/ # Aplicaciones Django
│ ├── backend_admin/ ```bash
│ ├── common/ # Construir e iniciar
│ └── promociones/ docker-compose up --build -d
├── core/ # Configuración principal
├── deployments/ # Docker, requirements prod # Ver logs
└── manage.py docker-compose logs -f
# Parar
docker-compose down
# Parar y eliminar volúmenes (¡cuidado en producción!)
docker-compose down -v
``` ```
## .env Variables El contenedor expone el puerto **8000**.
Ver `.env.example` para configuración.
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`