Saltar a contenido

❓ Preguntas frecuentes (FAQ)

Este apartado responde a algunas de las dudas más comunes relacionadas con el uso y desarrollo del sistema CORDIA.

🚀 Inicio y Configuración

🔧 ¿Cómo accedo a los servicios en local?

Asegúrate de tener configurado tu archivo /etc/hosts con las rutas locales:

127.0.0.1 api.cordia.local
127.0.0.1 admin.cordia.local
127.0.0.1 docs.cordia.local
...

Y luego ejecuta:

./run.sh dev

🐳 ¿Cómo enciendo solo un servicio concreto con Docker?

./run-service.sh local nombre_servicio

Ejemplo:

./run-service.sh local grafana

🔄 ¿Cómo reinicio todos los servicios?

# Parar todos los servicios
docker-compose down

# Iniciar de nuevo
./run.sh dev

🏗️ ¿Cómo reconstruyo los contenedores tras cambios en Docker?

./run.sh dev --rebuild

🔐 Autenticación y Acceso

🔐 ¿Cómo accedo a la documentación protegida por contraseña?

Se solicitará usuario/contraseña HTTP al acceder a dominios como docs.cordia.local o swagger.cordia.local. Consulta al equipo técnico para obtener las credenciales.

🔐 ¿Por qué me da error 403 al acceder a ciertos subdominios?

Porque están protegidos con .htpasswd o no has iniciado sesión con JWT. Verifica si necesitas credenciales o token.

🔑 ¿Cómo genero un token JWT para la API?

# Acceder al contenedor Laravel
docker exec -it cordia-apilaravel bash

# Generar token para un usuario
php artisan tinker
>>> $user = App\Models\User::first();
>>> $token = auth()->login($user);
>>> echo $token;

📚 Documentación y Desarrollo

📥 ¿Cómo actualizo la documentación de la API?

# Generar documentación Scribe
docker exec cordia-apilaravel php artisan scribe:generate

# O usar el script
./scripts/docs-scribe-generate.sh

📝 ¿Cómo actualizo la documentación técnica?

La documentación se actualiza automáticamente con MkDocs live server. Solo edita los archivos .md en docker/mkdocs/devdocs/docs/.

📋 ¿Cómo añado entradas al changelog?

Edita el archivo CHANGELOG.md en la raíz del proyecto. Los cambios se sincronizan automáticamente con la documentación.

🧪 Testing y Calidad

🧪 ¿Cómo lanzo los tests del sistema?

# Ejecutar todos los tests
docker exec cordia-apilaravel php artisan test

# Generar reporte HTML
./scripts/tests-run-and-report.sh

Esto genera un resumen accesible en http://tests.cordia.local

🔍 ¿Cómo verifico la calidad del código?

# Laravel Pint (code style)
docker exec cordia-apilaravel ./vendor/bin/pint

# PHPStan (análisis estático)
docker exec cordia-apilaravel ./vendor/bin/phpstan analyse

🗄️ Base de Datos

🧬 ¿Dónde consulto el esquema de base de datos?

Accede a http://schema.cordia.local

🔄 ¿Cómo ejecuto migraciones?

# Ejecutar migraciones pendientes
docker exec cordia-apilaravel php artisan migrate

# Rollback última migración
docker exec cordia-apilaravel php artisan migrate:rollback

🌱 ¿Cómo cargo datos de prueba?

# Ejecutar seeders
docker exec cordia-apilaravel php artisan db:seed

# Seeder específico
docker exec cordia-apilaravel php artisan db:seed --class=UserSeeder

🔧 ¿Cómo accedo a la base de datos directamente?

Usa Adminer en http://adminer.cordia.local o:

# MySQL CLI
docker exec -it cordia-mysql mysql -u root -p

📊 Procesamiento de Datos

📥 ¿Cómo importo datos y genero reportes?

Opción principal (recomendada): 

# Ejecutar proceso completo: importaciones + reportes + documentación
./scripts/full.sh

Este script internamente ejecuta: 1. Importaciones de datos: DALLA, ETYMOS y otros diccionarios 2. Generación de reportes: Calidad de datos, estadísticas, análisis 3. Actualización de documentación: API docs, esquemas, índices 4. Limpieza y optimización: Cache, índices de búsqueda

Opciones específicas: 

# Solo importaciones de datos
./scripts/data-imports-run.sh

# Solo generar reportes
./scripts/reports-generate.sh

# Procesar archivo CSV DALLA específico
docker exec cordia-apilaravel php artisan cordia:parse-dalla3-csv --path=/ruta/al/archivo.csv

Los reportes estarán disponibles en http://reports.cordia.local

🚨 Resolución de Problemas

🧯 ¿Qué hago si un servicio Docker no responde?

  1. Verificar estado de contenedores: 

    docker ps -a

  2. Ver logs del servicio: 

    docker logs cordia-nombre-servicio

  3. Reiniciar servicio específico: 

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

💾 ¿Cómo libero espacio en disco de Docker?

# Limpiar contenedores parados
docker container prune

# Limpiar imágenes no utilizadas
docker image prune

# Limpieza completa (¡cuidado!)
docker system prune -a

🔧 ¿Cómo soluciono problemas de permisos?

# Cambiar propietario de archivos
sudo chown -R $USER:$USER ./

# Permisos de ejecución para scripts
chmod +x ./run.sh ./run-service.sh

📱 ¿Cómo accedo desde dispositivos móviles en la red local?

  1. Encuentra tu IP local: 

    ip addr show | grep inet

  2. Configura el proxy para aceptar conexiones externas

  3. Accede desde el móvil usando http://TU_IP:PUERTO

🔄 Actualizaciones y Mantenimiento

🆙 ¿Cómo actualizo CORDIA a la última versión?

# Actualizar código
git pull origin main

# Reconstruir contenedores
./run.sh dev --rebuild

# Ejecutar migraciones
docker exec cordia-apilaravel php artisan migrate

🗂️ ¿Cómo hago backup de los datos?

# Backup automático (si está configurado)
./scripts/backup.sh

# Backup manual de MySQL
docker exec cordia-mysql mysqldump -u root -p cordia > backup.sql

¿Tu duda no está aquí? Crea un issue y la añadiremos.