From fdb01ecb0cd87f337070406f7c45d1103f52840f Mon Sep 17 00:00:00 2001 From: josedario87 Date: Fri, 21 Nov 2025 19:55:26 -0600 Subject: [PATCH] Documentar funcionalidad de debug en README y PLAN MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Agregar sección de botones de debug (temporales) en README - Documentar endpoints /api/debug/reset-database y /api/debug/seed-database - Incluir advertencias y flujos de uso recomendados - Marcar claramente como TEMPORALES con instrucciones de no eliminar - Actualizar PLAN con endpoints de debug en sección Completado --- PLAN_TRAZABILIDAD.md | 65 +++++++++++++++++++++++++++++++++++++++++++- README.md | 48 +++++++++++++++++++++++++++++--- 2 files changed, 108 insertions(+), 5 deletions(-) diff --git a/PLAN_TRAZABILIDAD.md b/PLAN_TRAZABILIDAD.md index fec0823..51d3de3 100644 --- a/PLAN_TRAZABILIDAD.md +++ b/PLAN_TRAZABILIDAD.md @@ -8,7 +8,7 @@ - [x] Modelo de base de datos (grafo DAG) - [x] Scripts de inicialización y seed con datos de ejemplo -- [x] API REST completa (11 endpoints) +- [x] API REST completa (11 endpoints + 2 debug temporales) - [x] Función recursiva de trazabilidad SQL - [x] Autenticación con Authentik Proxy - [x] CI/CD con Gitea Actions @@ -16,6 +16,11 @@ - [x] Persistencia de datos entre deploys - [x] Configuración automática de autenticación PostgreSQL - [x] Botones de prueba de API en frontend +- [x] **Botones de debug temporales** para gestión de BD (reset y seed) + - ⚠️ Marcados como TEMPORALES - NO ELIMINAR sin consultar + - `POST /api/debug/reset-database` - DROP de todas las tablas + - `POST /api/debug/seed-database` - Carga datos de ejemplo + - UI con advertencias notorias en rojo ### 🎯 Objetivo Actual: Visualización del Grafo @@ -84,6 +89,9 @@ El **Sistema de Trazabilidad de Lotes** rastrea el flujo completo del café desd │ │ │ │ ├── [id].patch.ts │ │ │ │ ├── [id].delete.ts │ │ │ │ └── [id]/ +│ │ │ ├── debug/ # ⚠️ TEMPORALES +│ │ │ │ ├── reset-database.post.ts +│ │ │ │ └── seed-database.post.ts │ │ │ │ └── trazabilidad.get.ts │ │ │ └── operaciones/ │ │ │ ├── index.get.ts @@ -368,6 +376,61 @@ Content-Type: application/json } ``` +### 4. Endpoints de Debug (⚠️ Temporales) + +**⚠️ ADVERTENCIA**: Estos endpoints son temporales y están marcados para no eliminar sin consultar. + +#### Reset Database + +```bash +POST /api/debug/reset-database +``` + +**Descripción**: Elimina completamente todas las tablas (DROP TABLE) para reinicializar la BD. + +**Respuesta:** +```json +{ + "success": true, + "message": "Base de datos reseteada. Tablas eliminadas completamente. El próximo deploy las recreará con datos de ejemplo." +} +``` + +**Flujo recomendado:** +1. Llamar a este endpoint desde el frontend (botón rojo) +2. Hacer push para triggear workflow +3. El workflow detecta que no hay tablas y las recrea con seed + +#### Seed Database + +```bash +POST /api/debug/seed-database +``` + +**Descripción**: Ejecuta el script de seed (`02_seed.sql`) para cargar datos de ejemplo. + +**Respuesta:** +```json +{ + "success": true, + "message": "Datos de ejemplo cargados: 10 lotes, 7 operaciones, 16 relaciones" +} +``` + +**Uso típico:** +- Después de resetear la BD manualmente +- Para pruebas de desarrollo +- Para restaurar datos de ejemplo rápidamente + +**⚠️ Nota importante**: Estos endpoints incluyen comentarios muy visibles en el código fuente: +```typescript +/** + * ⚠️ ⚠️ ⚠️ ENDPOINT DE DEBUG - TEMPORAL ⚠️ ⚠️ ⚠️ + * + * ⚠️ NO ELIMINAR SIN CONSULTAR A DARIO/DRAGANEL/NUCLEO000 ⚠️ + */ +``` + --- ## Componentes Frontend diff --git a/README.md b/README.md index 4580e0d..88f4f08 100644 --- a/README.md +++ b/README.md @@ -112,11 +112,12 @@ UVA-001 (2086kg) │ │ ├── composables/ │ │ │ ├── useLotes.ts # Lógica de negocio │ │ │ └── useAuthentik.ts # Autenticación -│ │ └── app.vue # Aplicación principal +│ │ └── app.vue # Aplicación principal (con botones debug) │ ├── server/ │ │ ├── api/ │ │ │ ├── lotes/ # Endpoints de lotes (6) -│ │ │ └── operaciones/ # Endpoints de operaciones (3) +│ │ │ ├── operaciones/ # Endpoints de operaciones (3) +│ │ │ └── debug/ # ⚠️ Endpoints debug temporales (2) │ │ ├── utils/ │ │ │ ├── db.ts # Pool de PostgreSQL │ │ │ └── queries.ts # Funciones SQL @@ -148,6 +149,13 @@ UVA-001 (2086kg) - `POST /api/operaciones` - Crear operación con lotes - `GET /api/operaciones/:id` - Obtener operación específica +### Debug (⚠️ Temporales) + +- `POST /api/debug/reset-database` - Elimina todas las tablas (DROP) +- `POST /api/debug/seed-database` - Carga datos de ejemplo + +**Nota**: Estos endpoints están marcados como temporales. No eliminar sin consultar. + ### Ejemplo de Respuesta - Trazabilidad ```json @@ -224,13 +232,45 @@ SELECT * FROM get_estadisticas_lote('id-del-lote'); ### Modo Debug -El sistema incluye botones de prueba para verificar la API: +El sistema incluye varios botones de debug para desarrollo: + +#### Botones de Prueba de API (azules) 1. Abre https://lotes.nucleoriofrio.com 2. Abre consola del navegador (F12) -3. Usa los botones "Probar API" +3. Usa los botones "Probar GET /api/lotes", "Probar GET /api/operaciones", "Probar Trazabilidad" 4. Verifica resultados en consola +#### ⚠️ Botones de Gestión de BD (rojos) - TEMPORALES + +**ADVERTENCIA**: Estos botones son para desarrollo/debugging y están marcados como **TEMPORALES**. + +**🗑️ BORRAR TODA LA BD**: +- Elimina completamente todas las tablas (`DROP TABLE`) +- Requiere confirmación antes de ejecutar +- Después de usar, hacer un push para que el workflow recree la BD con datos de ejemplo + +**🌱 CARGAR DATOS DE EJEMPLO**: +- Ejecuta el script de seed (10 lotes, 7 operaciones, 16 relaciones) +- Útil para cargar datos después de un reset + +**Flujo recomendado para resetear completamente**: +```bash +# 1. Click en "🗑️ BORRAR TODA LA BD" en la web +# 2. Trigger redeploy para que se recree automáticamente +git commit --allow-empty -m "Trigger reinit DB" && git push + +# Alternativa rápida (sin redeploy): +# 1. Click en "🗑️ BORRAR TODA LA BD" +# 2. Click en "🌱 CARGAR DATOS DE EJEMPLO" +# 3. Recargar la página +``` + +**⚠️ IMPORTANTE**: Estos botones y endpoints están marcados con advertencias en el código: +- NO ELIMINAR sin consultar a Dario/Draganel/nucleo000 +- Son temporales pero útiles durante desarrollo +- Ver comentarios en el código antes de modificar + ## 🔐 Autenticación Sistema protegido con Authentik Proxy Outpost: