🛠 Scripts y comandos del proyecto CORDIA

Este documento recoge los principales scripts disponibles para desarrollar, documentar, probar e implementar CORDIA.

Scripts en raíz: ./run.sh, ./run-service.sh, ./deploy.sh, ./deploy-prod.sh, etc.
Scripts utilitarios en scripts/: ./scripts/migrate.sh, ./scripts/data-imports-run.sh, ./scripts/docs-scribe-generate.sh, ./scripts/tests-run-and-report.sh, ./scripts/generate-reports-index.sh, etc.

📁 Estructura de scripts (principal)

./run.sh                              → Levanta todos los servicios (Docker Compose)
./run-service.sh                      → Levanta/gestiona un servicio concreto
./deploy.sh [entorno]                 → Clona/actualiza repo y levanta entorno (dev/test/pre/prod)
./deploy-prod.sh                      → Despliegue en producción (Alladixital)

./scripts/migrate.sh                  → Migraciones por módulos (opcional fresh/seed)
./scripts/data-imports-run.sh         → Migraciones/seed + importadores de ficheros
./scripts/docs-scribe-generate.sh     → Genera la documentación de API (Scribe)
./scripts/tests-run-and-report.sh     → Ejecuta tests y genera informe HTML
./scripts/generate-reports-index.sh   → Genera índice HTML para reportes JSON

Nota: Algunos utilitarios antiguos (generate-docs.sh, test-report.sh, run-data-imports.sh) han sido reemplazados por los scripts en scripts/.

📚 Tabla rápida de scripts

Script	Descripción	Uso corto
`./run.sh [entorno] [--rebuild]`	Orquesta servicios 'all' con run-service.sh	`./run.sh pre --rebuild`
`./run-service.sh [entorno] [servicio\|all] [--rebuild]`	Levanta servicios con docker compose	`./run-service.sh dev apilaravel`
`./deploy.sh [entorno]`	Clona/actualiza repo y levanta entorno (dev/test/pre/prod)	`./deploy.sh pre`
`./deploy-prod.sh`	Despliegue de rama `prod` en servidor destino	`./deploy-prod.sh`
`./scripts/migrate.sh`	Migraciones por módulos (fresh/seed opcional)	`./scripts/migrate.sh --env=dev --fresh --seed`
`./scripts/data-imports-run.sh`	Migraciones/seed + importadores desde `storage/app/imports/`	`./scripts/data-imports-run.sh --env=test --import=dalla.csv`
`./scripts/docs-scribe-generate.sh [entorno]`	Genera documentación de API (Scribe)	`./scripts/docs-scribe-generate.sh pre`
`./scripts/tests-run-and-report.sh [entorno]`	Ejecuta tests y genera reporte HTML	`./scripts/tests-run-and-report.sh`
`./scripts/generate-reports-index.sh [ruta]`	Índice HTML desde JSON de reportes	`./scripts/generate-reports-index.sh ../public/reports.cordia`

🧭 Convenciones de entorno y contenedores

Contenedor Laravel: cordia-apilaravel (servicio Compose: apilaravel).
Red Docker: cordia_docker_net (externa).
Entornos: dev, test, pre, prod.
Salidas:
MkDocs devdocs: public/devdocs.cordia/
MkDocs docs: public/docs.cordia/
Swagger: public/swagger.cordia/
Reportes: public/reports.cordia/

🆘 Formato de ayuda estándar

Todos los scripts soportan las banderas de ayuda: -h, --help o ?.

Salida típica:

./<script> -h

Uso: ./<script> [opciones]

Opciones:
  ...

Ejemplos:
  ...

🚀 Documentación técnica (MkDocs)

# Eliminar documentación generada previamente
sudo rm -R public/devdocs.cordia/

# Compilar y levantar MkDocs
./run-service.sh local mkdocs

# Forzar reconstrucción de imagen mkdocs
./run-service.sh local mkdocs --rebuild

# Compilar en entorno de test
./run-service.sh test mkdocs

Salida:

public/devdocs.cordia/ (devdocs)
public/docs.cordia/ (docs)

📄 Documentación API (Scribe)

Ayuda (-h):

Uso: ./scripts/docs-scribe-generate.sh [entorno]

Genera la documentación de API (Scribe) dentro del contenedor 'cordia-apilaravel'.

Parámetros:
  entorno    dev | test | pre | prod (por defecto: dev)
  -h, --help, ?    Mostrar esta ayuda y salir

Ejemplos:
  ./scripts/docs-scribe-generate.sh            # usa dev
  ./scripts/docs-scribe-generate.sh pre        # usa pre

Comandos útiles:

# Encender contenedor Laravel si no está levantado
./run-service.sh local apilaravel

# Generar documentación (usa dev por defecto)
./scripts/docs-scribe-generate.sh

# Generar en pre
./scripts/docs-scribe-generate.sh pre

# Alternativa directa dentro del contenedor
docker compose exec apilaravel php artisan scribe:generate

🧩 Documentación base de datos (SchemaSpy)

./run-service.sh local schemaspy

Salida:

public/schema.cordia/

🧪 Tests (PHPUnit)

Ayuda (-h):

Uso: ./scripts/tests-run-and-report.sh [entorno]

Ejecuta los tests de Laravel dentro del contenedor y genera un informe HTML.

Parámetros:
  entorno          dev | test | pre | prod (por defecto: dev)
  -h, --help, ?    Mostrar esta ayuda y salir

Ejemplos:
  ./scripts/tests-run-and-report.sh           # usa dev
  ./scripts/tests-run-and-report.sh test      # usa test

Salida:
  - HTML: public/tests.cordia/index.html
  - XML JUnit dentro del contenedor: /public-tests/results.xml

Comandos útiles:

# Ejecutar todos los tests y generar HTML en dev
./scripts/tests-run-and-report.sh

# Ejecutar en test
./scripts/tests-run-and-report.sh test

# Salida HTML: public/tests.cordia/index.html

🌐 Frontend Vue

Modo desarrollo (recomendado)

cd app/admin-vue
npm install
npm run dev

Nota sobre Docker

El servicio de frontend está actualmente comentado en docker-compose.yml.
Si necesitas build de producción, utiliza:

cd app/admin-vue
npm install
npm run build

🧰 Servicios auxiliares (locales)

./run-service.sh local npm          # Nginx Proxy Manager
./run-service.sh local uptime       # Uptime Kuma
./run-service.sh local mysql        # Base de datos
./run-service.sh local grafana      # Grafana
./run-service.sh local proxy        # Servidor NGINX para documentación
./run-service.sh local proxy --rebuild  # Forzar reconstrucción del proxy

▶️ Orquestación de servicios

run.sh — Uso:

Uso: ./run.sh [dev|test|pre|prod] [--rebuild]

Descripción:
  Orquesta servicios llamando a run-service.sh con 'all'.

Comportamiento:
  - APP_ENV: dev por defecto.
  - --rebuild: propaga a run-service.sh para forzar build y recreación.

Ejemplos:
  ./run.sh                     # dev, servicios 'all'
  ./run.sh pre                 # pre, servicios 'all'
  ./run.sh test --rebuild      # test, build + recreate

run-service.sh — Uso:

Uso: ./run-service.sh [entorno] [servicio|all] [--rebuild]

Descripción:
  Levanta un servicio concreto o todos, copiando .env y usando docker compose.

Detalles:
  - Copia .env.<entorno> a app/api-laravel/.env si existe.
  - Crea la red cordia_docker_net si no existe.
  - Usa docker-compose.yml y, si existe, docker-compose.<entorno>.yml como override.
  - Lanza 'docker compose up -d' con --build --force-recreate si se pasa --rebuild.

Ejemplos:
  ./run-service.sh local all
  ./run-service.sh dev apilaravel
  ./run-service.sh pre proxy --rebuild

⚙️ Despliegue

deploy.sh — Ayuda (-h):

Uso: ./deploy.sh [entorno]

Despliega el backend de CORDIA en el servidor local.

Parámetros:
  entorno   Entorno a usar: dev | test | pre | prod (por defecto: prod)

Ejemplos:
  ./deploy.sh                  # despliega en prod (por defecto)
  ./deploy.sh dev              # despliega en dev
  ./deploy.sh pre              # despliega en pre
  ./deploy.sh test             # despliega en test

Notas:
  - Espera a que Swagger (public/swagger.cordia/index.html) esté disponible.
  - Reinicia el servicio 'proxy' al final con --rebuild.

deploy-prod.sh — Ayuda (-h):

Uso: ./deploy-prod.sh

Despliega la rama 'prod' del repositorio en el directorio configurado.

Parámetros:
  (sin parámetros)

Ejemplos:
  ./deploy-prod.sh           # actualiza y deja desplegada la rama prod

Notas:
  - Usa una clave SSH específica (pull_ed25519) vía GIT_SSH_COMMAND.
  - Ejecuta 'git fetch', 'git checkout prod' y 'git pull origin prod'.

Comandos rápidos:

# Clonar/actualizar y levantar entorno (prod por defecto)
./deploy.sh              # prod
./deploy.sh dev          # dev
./deploy.sh pre          # pre
./deploy.sh test         # test

# Despliegue en producción (Alladixital)
cd ~/cordia.alladixital.org
./deploy-prod.sh

🧱 Migraciones y seeders

Ayuda (-h):

Uso: ./scripts/migrate.sh [--fresh] [--seed] [--env=dev|test|pre|prod]

Ejecuta las migraciones por subcarpetas dentro del contenedor 'cordia-apilaravel'.

Opciones:
  --fresh             Ejecuta migrate:fresh antes de migrar
  --seed              Ejecuta los seeders después de migrar
  --env=<entorno>     dev | test | pre | prod
  -h, --help, ?       Mostrar esta ayuda y salir

Ejemplos:
  ./scripts/migrate.sh --env=dev --fresh --seed
  ./scripts/migrate.sh --env=test --seed

Comandos útiles:

# Fresh + seed en dev
./scripts/migrate.sh --env=dev --fresh --seed

# Solo migraciones + seed en test
./scripts/migrate.sh --env=test --seed

📥 Importación de datos y ejecución de importadores

Ayuda (-h):

Uso: ./scripts/data-imports-run.sh [--env=dev|test|pre|prod] [--import=f1.csv,f2.json,...] [--nofresh]

Ejecuta migraciones y seeders, y opcionalmente importaciones específicas dentro del contenedor 'cordia-apilaravel'.

Opciones:
  --env=<entorno>      dev | test | pre | prod (por defecto: dev)
  --import=<lista>     Lista separada por comas de archivos dentro de storage/app/imports/
  --nofresh            No ejecutar migrate:fresh; solo migraciones incrementales + seed
  -h, --help, ?        Mostrar esta ayuda y salir

Ejemplos:
  ./scripts/data-imports-run.sh --env=dev                         # fresh + seed en dev
  ./scripts/data-imports-run.sh --env=dev --nofresh               # sin fresh
  ./scripts/data-imports-run.sh --env=test --import=dalla.csv     # ejecuta cordia:parse-dalla-csv
  ./scripts/data-imports-run.sh --import=dalla.csv,otros.json     # múltiples imports

Notas:
  - Los archivos se buscan en storage/app/imports/ dentro del contenedor.
  - El nombre del comando se construye como cordia:parse-<nombre>-<ext>.
  - Requiere contenedor en ejecución: 'cordia-apilaravel'.

Comandos útiles:

# Migrar en dev (fresh) + seed
./scripts/data-imports-run.sh --env=dev

# Sin fresh (solo migraciones incrementales + seed)
./scripts/data-imports-run.sh --env=dev --nofresh

# Ejecutar importadores para ficheros concretos (dentro de storage/app/imports)
./scripts/data-imports-run.sh --env=test --import=dalla.csv
./scripts/data-imports-run.sh --import=dalla.csv,otros.json

Notas:

Los archivos se buscan dentro del contenedor en /var/www/html/storage/app/imports/.
Los comandos de importación se construyen como cordia:parse-<nombre>-<ext> (ver integración más abajo).

🗂 Índice de reportes HTML desde JSON

Ayuda (-h):

Uso: ./scripts/generate-reports-index.sh [ruta_relativa_al_script]

Genera un índice HTML (y actualiza resumen.json) a partir de los JSON de reportes.

Parámetros:
  ruta_relativa_al_script   Carpeta con reportes; por defecto usa /reports
  -h, --help, ?             Mostrar esta ayuda y salir

Ejemplos:
  ./scripts/generate-reports-index.sh                   # usa /reports
  ./scripts/generate-reports-index.sh ../public/reports.cordia

Notas:
  - Si defines WWWUSER, ajusta propietario y permisos de los .html generados.

Comandos útiles:

# Genera índice usando /reports (por defecto)
./scripts/generate-reports-index.sh

# Especificando carpeta relativa al script
./scripts/generate-reports-index.sh ../public/reports.cordia

🔄 Comandos Laravel útiles (dentro del contenedor)

# Asegurar contenedor levantado
./run-service.sh local apilaravel

# Artisan (recomendado)
docker compose exec apilaravel php artisan migrate

# Alternativa equivalente
docker exec cordia-apilaravel php artisan migrate

Los scripts que aceptan entorno usan dev, test, pre y prod.

📄 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.

🛠 Scripts y comandos del proyecto CORDIA

📁 Estructura de scripts (principal)

📚 Tabla rápida de scripts

🧭 Convenciones de entorno y contenedores

🆘 Formato de ayuda estándar

🚀 Documentación técnica (MkDocs)

📄 Documentación API (Scribe)

🧩 Documentación base de datos (SchemaSpy)

🧪 Tests (PHPUnit)

🌐 Frontend Vue

Modo desarrollo (recomendado)

Nota sobre Docker

🧰 Servicios auxiliares (locales)

▶️ Orquestación de servicios

⚙️ Despliegue

🧱 Migraciones y seeders

📥 Importación de datos y ejecución de importadores

🗂 Índice de reportes HTML desde JSON

🔄 Comandos Laravel útiles (dentro del contenedor)

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

Uso

Dónde colocar el archivo en el host

Qué hace

Estadísticas y reporte

Notas y convenciones

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

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