Merge pre-dev: docs flujo ramas

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,110 @@
+# Convenciones del Ecosistema V-Encore Lab
+
+## Ecosistema de microservicios
+
+| Repo | Rol | Puerto |
+|------|-----|--------|
+| `django-core-base` | Hub orquestador principal | 8000 |
+| `api_backoffice` | Consulta y gestión de BD | 8001 |
+| `api_comunicaciones` | Emails, notificaciones, webhooks | 8002 |
+| `api_documentacion` | Generación y gestión de documentos | 8003 |
+| `web_interno` | Panel de gestión (React + Ant Design) | 3000 |
+
+## Stack Django
+
+- Django 5.0 + DRF + SimpleJWT
+- Apps bajo `app/`. Prefijo `/api/` en todas las URLs salvo `admin/`.
+- Patrón 3 capas: **URL → View → Action**
+- SQL con `connection.cursor()` y placeholders (`%s`). Nunca concatenar strings.
+
+## Patrón de vistas — 4 bloques obligatorios
+
+```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 — Data Cleaning
+            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 — Action Call
+            resultado = mi_accion(params)
+            # Bloque 4 — Cierre Log
+            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 — reglas
+
+- Siempre llamar como `LogService.gestionar_log(self, request, ...)` — pasar `self` de la vista.
+- Primera llamada (sin `log_id`): crea el registro, devuelve el `log_id`.
+- Llamadas siguientes: actualizar con `log_id=log_id`.
+- `body_request` y `body_response` se serializan con `DjangoJSONEncoder` — soporta `datetime.date`, `Decimal`, etc.
+- `status_code` como entero. Usar `is not None` para comprobar (0 es válido).
+
+## Base de datos
+
+- `DB_HOST` definido → PostgreSQL
+- `DB_HOST` no definido → SQLite en `app/data/db.sqlite3`
+- Migraciones siempre desde `app/`: `cd app && python manage.py migrate`
+- SQL INSERT con psycopg2: usar `INSERT ... RETURNING id` + `cursor.fetchone()`. **Nunca `cursor.lastrowid`**.
+- Booleans en psycopg2: pasar `True`/`False`, no `1`/`0`.
+
+## Flujo de ramas
+
+```
+pre-dev  →  dev  →  master
+```
+
+- `pre-dev`: desarrollo activo — aquí entran todos los cambios
+- `dev`: validación previa a producción
+- `master`: producción estable
+- Merges siempre con `--no-ff`
+- **NUNCA** propagar en sentido inverso (master → dev o dev → pre-dev)
+- Secuencia correcta:
+  ```bash
+  git checkout pre-dev && git merge <mi-cambio> --no-ff
+  git checkout dev     && git merge pre-dev --no-ff && git push origin dev
+  git checkout master  && git merge dev --no-ff     && git push origin master
+  ```
+
+## Estructura de app Django
+
+```
+app/
+├── api_config/       # settings.py, urls.py, wsgi.py
+├── general/          # LogService, utils — NO tiene modelos propios
+├── backend_admin/    # Modelo Log (audit_logs), admin panel
+├── common/           # Modelos y utilidades compartidas entre apps
+├── <feature_app>/    # Una app por dominio de negocio
+├── data/             # SQLite (gitignored, solo .gitkeep versionado)
+└── manage.py
+```
+
+## Fixtures
+
+- `loaddata` ignora `auto_now_add=True` — incluir fechas explícitas en el JSON o falla con NOT NULL en PostgreSQL.

app/api_config/asgi.py

@@ -1,4 +1,4 @@
 import os
 from django.core.asgi import get_asgi_application
-os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'api_hub_dispatcher.settings')
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'api_config.settings')
 application = get_asgi_application()

app/api_config/settings.py

@@ -74,7 +74,7 @@ MIDDLEWARE = [
     'django.middleware.clickjacking.XFrameOptionsMiddleware',
 ]
 
-ROOT_URLCONF = 'api_hub_dispatcher.urls'
+ROOT_URLCONF = 'api_config.urls'
 
 TEMPLATES = [
     {
@@ -92,7 +92,7 @@ TEMPLATES = [
     },
 ]
 
-WSGI_APPLICATION = 'api_hub_dispatcher.wsgi.application'
+WSGI_APPLICATION = 'api_config.wsgi.application'
 
 # 3. DATABASE
 # En producción (cuando DB_HOST está definido) usa PostgreSQL.

app/api_config/wsgi.py

@@ -2,6 +2,6 @@ import os
 from django.core.wsgi import get_wsgi_application
 
 # Este es el enlace con tus configuraciones
-os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'api_hub_dispatcher.settings')
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'api_config.settings')
 
 application = get_wsgi_application()

deployments/docker-compose.yml

@@ -1,44 +1,40 @@
 version: '3.8'
 
 services:
-  gitea-db:
-    image: postgres:15
-    # Usará el nombre de tu .env (django_db_local)
-    container_name: ${DB_CONTAINER_NAME:-django_db_dev}
-    restart: always
+  db:
+    image: postgres:15-alpine
+    container_name: ${DB_CONTAINER_NAME:-django_core_db}
+    restart: unless-stopped
     environment:
-      POSTGRES_DB: ${DB_NAME:-gitea}
-      POSTGRES_USER: ${DB_USER:-gitea}
-      POSTGRES_PASSWORD: ${DB_PASSWORD:-gitea}
+      POSTGRES_DB: ${DB_NAME:-django_core_db}
+      POSTGRES_USER: ${DB_USER:-postgres}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-postgres}
     volumes:
       - postgres_data:/var/lib/postgresql/data
-    # --- ESTO ES LO QUE FALTA ---
     ports:
       - "${DATABASE_EXPOSE_PORT:-5432}:5432"
-    # ----------------------------
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-gitea} -d ${DB_NAME:-gitea}"]
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-postgres} -d ${DB_NAME:-django_core_db}"]
       interval: 5s
       timeout: 5s
-      retries: 5
+      retries: 10
+      start_period: 10s
 
   web:
     build:
       context: ..
       dockerfile: deployments/Dockerfile
-    container_name: ${APP_CONTAINER_NAME:-django_app_dev}
-    restart: always
+    container_name: ${APP_CONTAINER_NAME:-django_core_app}
+    restart: unless-stopped
     env_file:
       - .env
     environment:
-      - DEBUG=${DEBUG_MODE:-1}
-      # IMPORTANTE: Este nombre debe coincidir con el nombre del servicio arriba (gitea-db)
-      - DB_HOST=gitea-db  
+      - DB_HOST=db
       - DB_PORT=5432
     ports:
       - "${PORT:-8000}:8000"
     depends_on:
-      gitea-db:
+      db:
         condition: service_healthy
 
 volumes:

deployments/entrypoint.sh

@@ -3,16 +3,39 @@
 # Salir inmediatamente si un comando falla
 set -e
 
+# --- Esperar a PostgreSQL si estamos en modo BD remota ---
+if [ -n "$DB_HOST" ]; then
+    echo "--> Esperando a PostgreSQL en $DB_HOST:${DB_PORT:-5432}..."
+    until python -c "
+import sys, psycopg2, os
+try:
+    psycopg2.connect(
+        host=os.environ['DB_HOST'],
+        port=os.environ.get('DB_PORT', 5432),
+        user=os.environ['DB_USER'],
+        password=os.environ['DB_PASSWORD'],
+        dbname=os.environ['DB_NAME']
+    )
+    sys.exit(0)
+except Exception:
+    sys.exit(1)
+" 2>/dev/null; do
+        echo "   PostgreSQL no disponible, reintentando en 2s..."
+        sleep 2
+    done
+    echo "--> PostgreSQL listo."
+fi
+
 echo "--> Ejecutando migraciones..."
-# Esto asegura que si hay cambios en models.py, se generen y apliquen las tablas
-python manage.py makemigrations --noinput
 python manage.py migrate --noinput
 
-echo "--> Cargando datos de prueba..."
-# Este comando busca archivos JSON en las carpetas 'fixtures' de tus apps
-# Usamos || true para que si el archivo no existe o ya están cargados, el contenedor no se detenga
-python manage.py loaddata semillas || echo "Aviso: No se pudieron cargar las semillas (fichero no encontrado o error de formato)."
+echo "--> Cargando semillas (si existen)..."
+python manage.py loaddata semillas 2>/dev/null || echo "   Sin semillas, continuando."
 
-echo "--> Arrancando el servidor Django..."
-# Usamos exec para que Django sea el proceso principal (PID 1) y reciba señales de Docker
-exec python manage.py runserver 0.0.0.0:8000
+echo "--> Arrancando servidor con Gunicorn..."
+exec gunicorn api_config.wsgi:application \
+    --bind 0.0.0.0:8000 \
+    --workers 2 \
+    --timeout 120 \
+    --access-logfile - \
+    --error-logfile -