Epycus

Epycus es una plataforma web responsive y PWA para organización académica, hábitos de estudio, bienestar, gamificación y asistencia mediante IA. El sistema actual es un monolito modular construido con Laravel e Inertia; cualquier código ASP.NET anterior se considera legado retirado.

Estado verificado

• Backend: PHP 8.3 y Laravel 12.
• Frontend: Vue 3, Inertia 2, Vite y Tailwind CSS.
• Persistencia: MySQL/MariaDB en producción; SQLite puede usarse en pruebas.
• Producción: Hostinger, https://epycus.es y https://app.epycus.es.
• Escala prevista: cohorte de hasta 80 estudiantes.
• Pruebas al 14-09-2026: 191 pruebas PHP y 831 aserciones correctas.

El repositorio contiene la aplicación Laravel vigente. La documentación operativa detallada y las credenciales se conservan únicamente en el equipo autorizado y están ignoradas por Git:

• DOCUMENTACION-LOCAL.md
• CREDENCIALES-LOCALES.md

Solo este README.md se publica como documentación del repositorio.

Capacidades principales

• cuenta local, Google OAuth, perfil y preferencias;
• cursos, horarios, calendario, planificación diaria, notas, proyectos y calificaciones;
• misiones, subtareas, hábitos y Pomodoro;
• flashcards, simulacros y grafo de conocimiento;
• diario de bienestar, finanzas, actividad física, hidratación, lecturas y habilidades;
• XP, niveles, rachas, logros, ranking, tienda y villanos;
• grupos de estudio;
• asistente IA con proveedores configurables;
• telemetría y panel administrativo de investigación.

Estructura

app/
├── Http/                 autenticación y controladores transversales
├── Console/              comandos operativos
├── Modules/              módulos de negocio
└── Shared/               infraestructura compartida
resources/js/
├── Pages/                páginas Inertia
├── Components/           componentes Vue
├── Layouts/              layouts de invitado y aplicación
├── composables/          comportamiento reutilizable
└── Stores/               estado compartido
database/                 migraciones, factories y seeders
routes/                   rutas web y scheduler
tests/                    pruebas PHP
public/                   punto de entrada y assets compilados

Desarrollo local

Requisitos:

• PHP 8.3 y extensiones requeridas por Laravel;
• Composer;
• Node.js 22 y npm;
• MySQL/MariaDB o SQLite.

Instalación:

composer install
npm ci
copy .env.example .env
php artisan key:generate
php artisan migrate
npm run build

Durante desarrollo se pueden ejecutar backend, cola, logs y Vite mediante:

composer run dev

La aplicación queda disponible normalmente en http://127.0.0.1:8000.

Verificación

php artisan test --compact
npm run build

Los análisis adicionales están configurados, aunque actualmente conservan deuda que debe reducirse antes de convertirlos en una puerta obligatoria:

composer run analyse
npm run lint
composer audit --locked
npm audit --omit=dev

GitHub Actions ejecuta las pruebas PHP y un build frontend limpio sobre Linux. No realiza despliegues automáticos.

Servidor de producción

Elemento	Valor público/no sensible
Proveedor	Hostinger
Dominio público	epycus.es
Aplicación	app.epycus.es
Runtime	PHP 8.3 + Laravel 12
Base de datos	MySQL/MariaDB administrada en Hostinger
Directorio esperado	/home/<usuario-hostinger>/domains/epycus.es/public_html/app
Document root del dominio	redirige al public/ de Laravel
Scheduler requerido	php artisan schedule:run cada minuto

El host, usuario SSH, claves, contraseñas, nombres de base de datos y secretos OAuth/IA no deben añadirse a GitHub. Están en CREDENCIALES-LOCALES.md y en los archivos .env locales/servidor.

Despliegue manual

deploy.bat genera tres paquetes sin documentación ni archivos .env, ejecuta las pruebas, compila Vite y usa OpenSSH con clave privada. Antes de ejecutarlo se deben definir localmente:

set EPYCUS_SSH_HOST=<host>
set EPYCUS_SSH_PORT=<puerto>
set EPYCUS_SSH_USER=<usuario>
set EPYCUS_SSH_KEY=<ruta-absoluta-clave-privada>
set EPYCUS_REMOTE_PATH=<directorio-laravel>
deploy.bat

La clave privada debe vivir fuera del repositorio, idealmente en el directorio .ssh del usuario y protegida por los permisos del sistema. El script no acepta ni contiene contraseñas.

Antes de cada despliegue:

1. crear backup de base de datos y archivos subidos;
2. comprobar espacio libre y ejecución reciente del scheduler;
3. ejecutar pruebas y build;
4. aplicar migraciones con --force;
5. verificar login, dashboard, una escritura y /up;
6. conservar un procedimiento de rollback compatible con la migración.

Seguridad documental

• .env, .env.production, claves SSH, paquetes de despliegue y todos los .md salvo este README están ignorados.
• No usar credenciales reales como valores predeterminados en pruebas o scripts.
• Si un secreto llega a Git, eliminarlo del archivo no es suficiente: debe rotarse y purgarse del historial remoto.
• Los ejemplos públicos deben usar campos vacíos o marcadores evidentemente no válidos.

Mantenimiento

Cada cambio funcional debe incluir pruebas y actualizar DOCUMENTACION-LOCAL.md cuando modifique arquitectura, historias, requisitos, privacidad u operación. No se deben introducir nuevamente árboles tecnológicos alternativos dentro de este repositorio.