JobHero Backend

API REST para la aplicacion JobHero - Plataforma de servicios.

Stack Tecnologico

Tecnologia	Version
Laravel	11.47.0
PHP	8.2+
MySQL	8.0+
Laravel Passport	13.x
Composer	2.x

Requisitos Previos

• PHP 8.2 o superior
• Composer 2.x
• MySQL 8.0 o superior
• Nginx o Apache
• OpenSSL (para Passport)

Extensiones PHP requeridas

php-mbstring
php-xml
php-mysql
php-curl
php-gd
php-zip
php-bcmath
php-json

Instalacion

1. Clonar el repositorio

git clone <url-del-repositorio>
cd jobhero-backend

2. Instalar dependencias

composer install

3. Configurar variables de entorno

cp .env.example .env

Editar .env con tus configuraciones:

APP_NAME=JobHero
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost:8000

# Base de datos
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=jobhero
DB_USERNAME=tu_usuario
DB_PASSWORD=tu_password

# Email
MAIL_MAILER=smtp
MAIL_HOST=smtp.ejemplo.com
MAIL_PORT=587
MAIL_USERNAME=tu_email
MAIL_PASSWORD=tu_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@jobhero.com
MAIL_FROM_NAME="JobHero"

# Openpay (Pagos)
OPENPAY_ID=tu_openpay_id
OPENPAY_APIKEY=tu_openpay_apikey
OPENPAY_PRODUCTION=false

# OneSignal (Notificaciones push)
ONESIGNAL_APP_ID=tu_onesignal_app_id
ONESIGNAL_REST_API_KEY=tu_onesignal_api_key

# Google Cloud Storage
GOOGLE_CLOUD_PROJECT_ID=tu_proyecto
GOOGLE_CLOUD_STORAGE_BUCKET=tu_bucket
GOOGLE_CLOUD_KEY_FILE=storage/credentials.json

# OAuth (Login social)
FACEBOOK_CLIENT_ID=
FACEBOOK_CLIENT_SECRET=
FACEBOOK_CALLBACK_URL=

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CALLBACK_URL=

# reCAPTCHA
RECAPTCHA_SITE_KEY=
RECAPTCHA_SECRET_KEY=

4. Generar clave de aplicacion

php artisan key:generate

5. Crear base de datos

CREATE DATABASE jobhero CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

6. Ejecutar migraciones

php artisan migrate

7. Ejecutar seeders (datos iniciales)

php artisan db:seed

8. Instalar Passport (autenticacion API)

php artisan passport:install

Guardar las claves generadas en .env:

PASSPORT_PERSONAL_ACCESS_CLIENT_ID=1
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=xxxxxx

9. Crear enlace simbolico para storage

php artisan storage:link

10. Configurar permisos

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Desarrollo

Ejecutar servidor de desarrollo

php artisan serve

La API estara disponible en http://localhost:8000

Ejecutar en produccion

Configurar Nginx o Apache. Ejemplo de configuracion Nginx:

server {
    listen 80;
    server_name api.jobhero.com;
    root /var/www/jobhero-backend/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Estructura del Proyecto

app/
├── Http/
│   ├── Controllers/
│   │   ├── Auth/              # Autenticacion
│   │   ├── ContractController.php
│   │   ├── PostulationController.php
│   │   ├── SupplierController.php
│   │   ├── UserController.php
│   │   └── ...
│   └── Middleware/
│       ├── RoleCheck.php      # Verificacion de roles
│       └── SuperAdmin.php     # Solo superadmin
├── Models/                    # Modelos Eloquent
│   ├── User.php
│   ├── Suppliers.php
│   ├── Postulations.php
│   ├── CurrentContracts.php
│   ├── FinishedContracts.php
│   └── ...
├── Services/                  # Servicios
│   └── SocialAccountsService.php
└── Notifications/            # Notificaciones email
    └── PasswordReset.php

config/                       # Configuracion
database/
├── migrations/              # Migraciones de BD
├── seeders/                 # Datos iniciales
└── factories/               # Factories para tests

routes/
├── api.php                  # Rutas de la API
└── web.php                  # Rutas web (admin)

resources/views/             # Vistas Blade (admin panel)

Endpoints API Principales

Autenticacion

POST   /api/auth/register     # Registro
POST   /api/auth/login        # Login
POST   /api/auth/logout       # Logout
POST   /api/auth/fb           # Login Facebook
POST   /api/auth/google       # Login Google
GET    /api/auth/user         # Usuario actual
POST   /api/auth/verify       # Verificar telefono

Contratos

POST   /api/contracts/create  # Crear contrato
GET    /api/contracts/current # Contratos activos
GET    /api/contracts/pending # Contratos pendientes
GET    /api/contracts/finished # Contratos terminados
POST   /api/contracts/start   # Iniciar contrato
POST   /api/contracts/cancel  # Cancelar contrato
POST   /api/contracts/review  # Calificar contrato

Proveedores

POST   /api/add-hero          # Registrar como proveedor
GET    /api/check-category    # Verificar categoria
GET    /api/get-contracted-postulations # Postulaciones contratadas

Pagos

POST   /api/cards/add         # Agregar tarjeta
GET    /api/cards/get         # Listar tarjetas
POST   /api/cards/delete      # Eliminar tarjeta

Roles de Usuario

ID	Rol	Permisos
1	Usuario	Crear postulaciones, contratar
2	Proveedor	Postularse a trabajos
3	Analisis	Ver estadisticas
4	Facturacion	Gestionar pagos
5	Moderador	Panel admin basico
6	Administrador	Panel admin completo
7	SuperAdmin	Eliminar registros

Comandos Utiles

# Cache
php artisan cache:clear      # Limpiar cache
php artisan config:clear     # Limpiar config cache
php artisan route:clear      # Limpiar rutas cache
php artisan view:clear       # Limpiar vistas cache
php artisan optimize         # Optimizar para produccion

# Base de datos
php artisan migrate          # Ejecutar migraciones
php artisan migrate:fresh    # Recrear BD (BORRA TODO)
php artisan db:seed          # Ejecutar seeders

# Passport
php artisan passport:install # Instalar claves
php artisan passport:keys    # Regenerar claves

# Mantenimiento
php artisan down             # Modo mantenimiento
php artisan up               # Salir de mantenimiento

# Logs
tail -f storage/logs/laravel.log  # Ver logs en tiempo real

Solucion de Problemas

Error 500 en produccion

# Verificar permisos
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# Limpiar cache
php artisan cache:clear
php artisan config:clear

Error de Passport

# Regenerar claves
php artisan passport:keys
php artisan passport:client --personal

Error de base de datos

# Verificar conexion
php artisan tinker
>>> DB::connection()->getPdo();

Error de permisos storage

# Linux
chmod -R 775 storage
chown -R www-data:www-data storage

# Si persiste
chmod -R 777 storage/logs

Integraciones Externas

Openpay (Pagos)

• Crear cuenta en openpay.mx
• Obtener credenciales de sandbox/produccion
• Configurar webhooks

OneSignal (Push Notifications)

• Crear app en onesignal.com
• Configurar plataformas (Android/iOS)
• Obtener App ID y REST API Key

Google Cloud Storage

• Crear proyecto en Google Cloud
• Crear bucket de storage
• Descargar credenciales JSON

Seguridad

• Todas las rutas API requieren autenticacion Bearer Token
• Passport maneja tokens OAuth 2.0
• CORS configurado en config/cors.php
• Rate limiting en rutas sensibles
• Validacion de entrada en todos los endpoints

Testing

# Ejecutar tests
php artisan test

# Con coverage
php artisan test --coverage

Licencia

Proyecto privado - Todos los derechos reservados