🛠️ Comandos comunes en CORDIA - Revisión 3

Este documento recopila los comandos más frecuentes para el entorno local de desarrollo, organizados por contexto y servicio. Muchos de estos comandos están automatizados mediante scripts como run.sh, run-service.sh, ./scripts/docs-scribe-generate.sh, ./scripts/tests-run-and-report.sh.

🐳 Docker: iniciar servicios

./run-service.sh dev apilaravel        # API principal (Laravel)
./run-service.sh dev mkdocs            # Documentación técnica (MkDocs)
./run-service.sh dev schemaspy         # Esquema de BD
./run-service.sh dev grafana           # Paneles estadísticos
./run-service.sh dev npm               # Nginx Proxy Manager
./run-service.sh dev adminer           # Admin de base de datos
./run-service.sh dev uptime            # Monitorización
./run-service.sh dev proxy             # Proxy web para recursos estáticos

Para reiniciar un servicio con reconstrucción:

./run-service.sh dev nombre --rebuild

📚 Documentación

./run-service.sh dev mkdocs              # Genera documentación estática (DevDocs/Docs)
./run-service.sh test mkdocs             # Genera en modo test
./scripts/docs-scribe-generate.sh        # Genera docs de la API con Scribe (HTML)

📥 Importación datos

🆕 NUEVO: Script mejorado con soporte multi-entorno

Vacía completamente la base de datos, ejecuta los seeders según el entorno especificado, y opcionalmente importa datos desde archivos CSV/TXT.

# Solo seeders básicos (entorno pre-producción)
./scripts/data-imports-run.sh --env=pre

# Solo seeders completos (entorno desarrollo)
./scripts/data-imports-run.sh --env=dev

# Seeders + importación de archivos específicos
./scripts/data-imports-run.sh --env=dev --import=dalla.csv,etymos_della.2025.txt

# Múltiples archivos del mismo tipo
./scripts/data-imports-run.sh --env=test --import=dalla.csv,dalla.sample.csv

Entornos disponibles: - dev: Datos completos de desarrollo (44 archivos de seeding) - pre: Datos básicos de preproducción (24 archivos de seeding) - test: Datos básicos para testing (24 archivos de seeding) - prod: Datos básicos para producción (24 archivos de seeding)

Archivos de importación soportados: - dalla.csv, dalla.sample.csv → cordia:parse-dalla-csv - etymos_della.2025.txt → cordia:parse-etymos_della-txt

🧪 Tests

./scripts/tests-run-and-report.sh       # Ejecuta PHPUnit + genera informe

🔁 Despliegue

./deploy-prod.sh                         # Despliega en producción (manual)
./deploy.sh                              # Script de despliegue genérico

GitHub Actions también lo ejecuta automáticamente al hacer push a main.

💾 Backups

# ⚠️ NOTA: Los scripts de backup están deshabilitados (prefijo NO-)
./scripts/NO-backup.sh                   # Backup deshabilitado
./scripts/NO-restore.sh                  # Restore deshabilitado

⚙️ Comandos útiles Laravel (API)

Comandos básicos de Laravel

# Migración completa con seeders (usando variable SEED_ENV)
docker compose exec -e SEED_ENV=dev apilaravel php artisan migrate:fresh --seed
docker compose exec -e SEED_ENV=pre apilaravel php artisan migrate:fresh --seed

# Limpiar configuración
docker compose exec apilaravel php artisan config:clear

# Generar documentación API
./scripts/docs-scribe-generate.sh

🆕 Comandos CORDIA actualizados

# Importación DALLA (CSV)
docker compose exec apilaravel php artisan cordia:parse-dalla-csv

# Procesamiento DELLA (DOCX → CSV)
docker compose exec apilaravel php artisan cordia:parse-della-word

# Importación etimologías
docker compose exec apilaravel php artisan cordia:parse-etymos_della-txt

# Sincronización y comparación DALLA
docker compose exec apilaravel php artisan cordia:sync-dalla

# Comandos de testing y desarrollo
docker compose exec apilaravel php artisan cordia:test-csv-scientific
docker compose exec apilaravel php artisan cordia:test-dalla-refactoring
docker compose exec apilaravel php artisan cordia:test-scientific-forms
docker compose exec apilaravel php artisan cordia:test-scientific-processing

📊 Reportes y utilidades

# Generar índice de reportes
./scripts/generate-reports-index.sh

# Comparar comandos DALLA
./scripts/compare-dalla-commands.sh

🔍 CAMBIOS EN ESTA REVISIÓN:

✅ Actualizaciones realizadas:

Script de importación mejorado: ./scripts/data-imports-run.sh
✅ Soporte multi-entorno (--env=dev|test|pre|prod)
✅ Importación selectiva de archivos (--import=file1,file2)
✅ Validación automática de archivos y comandos
✅ Seeders específicos por entorno
Comandos Laravel actualizados:
✅ Todos los comandos cordia:* verificados y documentados
✅ Comando correcto para etimologías: cordia:parse-etymos_della-txt
✅ Nuevos comandos de testing añadidos
Scripts verificados:
✅ ./scripts/docs-scribe-generate.sh (antes generate-docs.sh)
✅ ./scripts/tests-run-and-report.sh (antes test-report.sh)
✅ Scripts de backup marcados como deshabilitados

❌ Comandos obsoletos removidos:

~~./scripts/run-data-imports.sh~~ → ./scripts/data-imports-run.sh
~~./generate-docs.sh~~ → ./scripts/docs-scribe-generate.sh
~~./test-report.sh~~ → ./scripts/tests-run-and-report.sh

🆕 Nuevas funcionalidades:

Entornos de seeding: dev (completo), pre/test/prod (básico)
Importación flexible: múltiples archivos, detección automática de comandos
Validación robusta: verificación de archivos y comandos antes de ejecutar

Para detalles adicionales, revisa los scripts en scripts.md o ejecuta ./run.sh sin argumentos para ver las opciones disponibles.

📄 Detalle: cordia:parse-etymos_della-txt (revisión 1)

Este comando importa etimologías desde un fichero de texto plano etymos.txt, haciendo matching con entradas existentes y generando un reporte JSON.

Ruta del comando: app/api-laravel/app/Console/Commands/ParseEtymosDellaTxt.php

Uso

Dentro del contenedor Laravel (apilaravel):

# Usando la ruta por defecto
docker compose exec apilaravel php artisan cordia:parse-etymos_della-txt

# Indicando una ruta distinta
docker compose exec apilaravel php artisan cordia:parse-etymos_della-txt --path=storage/app/imports/etymos.txt

Opción: --path (por defecto storage/app/imports/etymos.txt).
Formato esperado por línea: ETYMON: texto donde texto contiene el lemma y posibles alternativas/comentarios.

Dónde colocar el archivo en el host

El contenedor monta ./app/api-laravel en /var/www/html. Por tanto, coloca el fichero en:

Host: app/api-laravel/storage/app/imports/etymos.txt
Contenedor: /var/www/html/storage/app/imports/etymos.txt

Ejemplo para crearlo en el host:

mkdir -p app/api-laravel/storage/app/imports
cat > app/api-laravel/storage/app/imports/etymos.txt << 'EOF'
*LATINUS: abruñar, comentario
GOTICUS: andar || andarín
PROTO: l' á 2
EOF

Qué hace

Lee etymos.txt línea a línea.
Normaliza y extrae lemma (primera alternativa antes de ||, ignora comentarios tras ,, recorta símbolos y normaliza espacios y numeraciones finales).
Busca matches en entries por lemma_form o lemma_form_display (case-insensitive).
Inserta nuevas filas en entry_etymologies si no existe la misma PK (entry_etymology_id).
Genera un reporte JSON: app/api-laravel/reports/etymos_import.json con estadísticas, ambiguos, sin match y errores de parseo.

Estadísticas y reporte

El reporte incluye:

lines_total, lines_parsed, matched_entries, unmatched, ambiguous, parse_errors, inserted.
Tablas con lemmas ambiguos, sin match, líneas con errores y conteo de símbolos recortados.

Ver archivo: app/api-laravel/reports/etymos_import.json.

Notas y convenciones

El comando usa SOURCE_ID = 'DALLA'. Si procede, puede cambiarse a 'DELLA' para mayor consistencia.
Idempotencia: se evita duplicados comprobando la clave primaria generada (ETYM_<hash>).
Si no hay entradas en BD, la mayoría de líneas quedarán como "sin match". Ejecuta migrate:fresh --seed si quieres poblar datos de referencia en entorno de desarrollo.

docker compose exec -e SEED_ENV=dev apilaravel php artisan migrate:fresh --seed

Integración con `scripts/data-imports-run.sh`

El script construye nombres de comando tipo cordia:parse-<name>-<ext>. Para un archivo etymos.txt buscaría cordia:parse-etymos-txt. Nuestro comando se llama cordia:parse-etymos_della-txt; por tanto, al usar el script, especifica el archivo exacto y valida que el comando exista o ajusta el script si deseas un mapeo específico.