Setup y getting started

Bienvenido al backend de HUMAE. Esta página te deja corriendo localmente en ≤ 15 minutos asumiendo un macOS o Linux limpio.

Requisitos

Herramienta	Versión	Verificar
PHP	8.3+	php -v
Composer	2.x	composer --version
MySQL	8.0+	mysql --version
Redis	6+ (opcional en dev)	redis-cli --version
Node.js	20+ (para seedear catálogos con scripts)	node -v
Git	cualquiera reciente	git --version

Extensiones PHP obligatorias

php -m | grep -E "(pdo_mysql|mbstring|bcmath|intl|gd|xml|zip|curl|redis|opcache)"

Si alguna falta:

macOS (Homebrew)

brew install php@8.3
# Las extensiones vienen incluidas

Ubuntu/Debian

sudo apt install php8.3-{cli,fpm,mysql,mbstring,bcmath,intl,gd,xml,zip,curl,redis}

Docker

# Usa el docker-compose.yml del monorepo — ya viene todo configurado
docker compose up -d

Clonar

cd ~/CodeWork
git clone git@github.com:tu-org/humae.git
cd humae/humae_backend

Monorepo

HUMAE vive en un monorepo con tres carpetas: humae_backend/, humae_frontend/, humae_docs/. Cada una tiene su propio package manager. Este backend es independiente — no necesitas el frontend para trabajar en él.

Instalación

# Dependencias PHP
composer install

# Configuración
cp .env.example .env
php artisan key:generate

# Crear la DB (asumiendo MySQL local)
mysql -u root -e "CREATE DATABASE humae CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Editar .env con tus credenciales MySQL
#   DB_DATABASE=humae
#   DB_USERNAME=root
#   DB_PASSWORD=<tu password>

# Migraciones + seeds
php artisan migrate --seed

Seeders

Los seeds que corren con php artisan db:seed (orden definido en DatabaseSeeder):

Seeder	Qué carga	Idempotente
RolesAndPermissionsSeeder	45 permisos + 4 roles (admin, recruiter, company_user, candidate)	✅
SalaryCurrencySeeder	MXN, USD, EUR, ...	✅
CountrySeeder	México + 10 países	✅
StateSeeder	32 estados de México	✅
CompanyTaxonomySeeder	Industries, company sizes, ownership types	✅
JobTaxonomySeeder	Career levels, degree levels, functional areas (21 áreas: 15 del PDF + 6 auxiliares), vacancy categories/types/shifts/tags, posiciones	✅ (updateOrCreate por code)
TalentTaxonomySeeder	Skills (~150) + idiomas	✅
MembershipPlanSeeder	Plan candidate_6m 499 MXN / 180 días	✅
PsychometricBigFiveSeeder	Big Five en español (25 preguntas, 5 dimensiones)	✅
AdminUserSeeder	Usuario admin inicial (variables de entorno INITIAL_ADMIN_*)	✅
PdfDemoSeeder (solo dev/staging)	5 candidatos demo con mix empleado/practicante en distintas áreas + 1 empresa + 5 vacantes activas para probar el matching del PDF cosasfaltanteshumae	✅

PdfDemoSeeder hace short-circuit en app()->environment('production') para que sea seguro tener DatabaseSeeder corriéndolo siempre. Crea estos logins (password único Password123):

Email	Categoría	Áreas	Years	Salario expectativa
pablo.intern@demo.humae	Practicante	⭐ Ingeniería + Producción	0	6 000
maria.intern@demo.humae	Practicante	⭐ Sistemas	1	7 000
juan.empleado@demo.humae	Empleado	⭐ Producción + Calidad + Mantenimiento	4	18 000
sofia.empleado@demo.humae	Empleado	⭐ Logística + Almacén	6	25 000
lucia.empleado@demo.humae	Empleado	⭐ Recursos Humanos	8	35 000

Y vacantes (todas en state = activa con code HUM-DEMO-*):

1. Practicante de Ingeniería Industrial · target = intern · área Producción · 0–1 años · ≤ 8 000.
2. Practicante de Sistemas · target = intern · área Sistemas · 0–1 años · ≤ 9 000.
3. Auxiliar de Almacén · target = employee · área Almacén · 1–5 años · ≤ 18 000.
4. Coordinador de Calidad · target = employee · área Calidad · 3–8 años · ≤ 30 000.
5. Generalista de RH · target = any · área RH · 2–10 años · ≤ 32 000.

# Si ya tenías la DB, solo correr el demo:
php artisan db:seed --class=PdfDemoSeeder

# Si quieres reset completo + todos los catálogos + demo:
php artisan migrate:fresh --seed

No usar PdfDemoSeeder en producción

El seeder se auto-bloquea con app()->environment('production'), pero igual: nunca uses --seed con DatabaseSeeder en producción. Para datos reales, corre solo los seeders necesarios (php artisan db:seed --class=NombreEspecifico).

Arrancar el servidor

# Opción 1: individual
php artisan serve
# → http://localhost:8000

# Opción 2: con queue + logs en paralelo (recomendado)
composer dev

composer dev lanza 4 procesos con concurrently:

• php artisan serve en 8000
• php artisan queue:listen
• php artisan pail (tail de logs)
• vite (si aplica)

Verificación

# Health
curl http://localhost:8000/api/v1/health

# Esperado:
# {"success":true,"message":"OK","data":{"app":"ok","database":"ok","cache":"ok","queue":"ok"}}

Si devuelve 200, estás listo.

Crear un admin de desarrollo

php artisan tinker

>>> $u = \App\Models\User::factory()->create([
...     'name' => 'Andrés Admin',
...     'email' => 'andres@humae.local',
...     'password' => bcrypt('Password123'),
... ]);
>>> $u->assignRole('admin');
>>> $u->markEmailAsVerified();

Login desde el frontend (o directamente con Postman contra POST /api/v1/auth/login).

Dev loop diario

Después del setup inicial, el día a día es:

# Bajar cambios
git pull --rebase

# Aplicar nuevas migraciones (si hay)
php artisan migrate

# Si hay nuevos seeds, correr individualmente:
php artisan db:seed --class=NewSeederClass

# Instalar nuevas deps (si composer.lock cambió)
composer install

# Correr
composer dev

Comandos frecuentes

Comando	Uso
composer dev	Dev server + queue + logs
composer test	Toda la suite Pest
composer test:coverage	Tests con cobertura (requiere Xdebug/pcov)
composer lint	Corre Pint (formato)
composer lint:check	Pint en modo check sin modificar
composer analyse	PHPStan nivel 8
composer check	Lint + analyse + test (pre-commit)
composer docs	Genera Scribe API docs → public/docs
php artisan migrate:fresh --seed	Resetear DB y cargar seeds (incluye PdfDemoSeeder en dev)
php artisan db:seed --class=PdfDemoSeeder	Solo recargar usuarios demo del PDF (idempotente)
php artisan db:seed --class=JobTaxonomySeeder	Refrescar catálogo de áreas funcionales tras cambios
php artisan route:list	Todas las rutas
php artisan tinker	REPL interactivo

Estructura del repo

humae_backend/
├── app/
│   ├── Console/          Comandos artisan custom
│   ├── Enums/            Estados de dominio
│   ├── Helpers/          StripeClient, LocalFileStorage
│   ├── Http/
│   │   ├── Controllers/
│   │   ├── Middleware/
│   │   ├── Requests/     FormRequests (validación)
│   │   └── Resources/    API Resources (respuesta JSON)
│   ├── Jobs/             Queueable jobs
│   ├── Models/           Eloquent models
│   ├── Notifications/    Laravel Notifications
│   ├── Policies/         Autorización por recurso
│   ├── Providers/        Service providers
│   ├── Services/         Lógica de negocio transaccional
│   └── Support/          ApiResponse, ApiExceptionHandler
├── bootstrap/
├── config/
├── database/
│   ├── factories/        Factories para tests
│   ├── migrations/       55+ migraciones
│   └── seeders/          10+ seeders
├── public/
├── resources/
│   └── views/
│       ├── emails/       Plantillas Blade para correos
│       └── pdf/          Template del CV PDF
├── routes/
│   ├── api.php           Todas las rutas /api/v1/*
│   ├── channels.php
│   └── console.php
├── storage/
│   ├── app/
│   ├── framework/
│   └── logs/
├── tests/
│   ├── Feature/          Tests de endpoints + services
│   ├── Unit/             Tests puros (FSMs)
│   ├── Pest.php
│   └── TestCase.php
├── composer.json
├── phpstan.neon
├── phpunit.xml
└── pint.json

Siguiente

Entender la arquitectura de capas y los patrones: Arquitectura →