Jobhero_back/README.md

# 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

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

### 2. Instalar dependencias

```bash
composer install
```

### 3. Configurar variables de entorno

```bash
cp .env.example .env
```

Editar `.env` con tus configuraciones:

```env
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

```bash
php artisan key:generate
```

### 5. Crear base de datos

```sql
CREATE DATABASE jobhero CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 6. Ejecutar migraciones

```bash
php artisan migrate
```

### 7. Ejecutar seeders (datos iniciales)

```bash
php artisan db:seed
```

### 8. Instalar Passport (autenticacion API)

```bash
php artisan passport:install
```

Guardar las claves generadas en `.env`:

```env
PASSPORT_PERSONAL_ACCESS_CLIENT_ID=1
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=xxxxxx
```

### 9. Crear enlace simbolico para storage

```bash
php artisan storage:link
```

### 10. Configurar permisos

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

## Desarrollo

### Ejecutar servidor de desarrollo

```bash
php artisan serve
```

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

### Ejecutar en produccion

Configurar Nginx o Apache. Ejemplo de configuracion Nginx:

```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

```bash
# 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

```bash
# 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

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

### Error de base de datos

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

### Error de permisos storage

```bash
# 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

```bash
# Ejecutar tests
php artisan test

# Con coverage
php artisan test --coverage
```

## Licencia

Proyecto privado - Todos los derechos reservados