Initial commit: Horux Backend API

- API REST para gestion de facturas electronicas mexicanas (CFDI) - Laravel 9 con autenticacion OAuth 2.0 (Passport) - Integracion con Syntage, Clerk y Facturama - 30 modelos Eloquent, 39 controladores - Documentacion completa en /docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-18 07:44:29 +00:00
commit 61320b44d8
191 changed files with 22895 additions and 0 deletions
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -0,0 +1,383 @@
+# Guia de Instalacion - Horux Backend
+
+Guia completa para instalar y configurar el proyecto Horux Backend.
+
+## Requisitos Previos
+
+### Software Requerido
+
+| Software | Version Minima | Comando de verificacion |
+|----------|---------------|------------------------|
+| PHP | 8.0.2 | `php -v` |
+| Composer | 2.0 | `composer -V` |
+| MySQL/MariaDB | 5.7 / 10.3 | `mysql --version` |
+| Node.js | 16.0 | `node -v` |
+| NPM | 8.0 | `npm -v` |
+| Git | 2.0 | `git --version` |
+
+### Extensiones PHP Requeridas
+
+```
+- BCMath
+- Ctype
+- cURL
+- DOM
+- Fileinfo
+- JSON
+- Mbstring
+- OpenSSL
+- PDO
+- PDO_MySQL
+- Tokenizer
+- XML
+```
+
+Verificar extensiones instaladas:
+```bash
+php -m
+```
+
+---
+
+## Instalacion Paso a Paso
+
+### 1. Clonar Repositorio
+
+```bash
+git clone https://git.consultoria-as.com/tu-usuario/Horux_back.git
+cd Horux_back
+```
+
+### 2. Instalar Dependencias PHP
+
+```bash
+composer install
+```
+
+Si hay problemas de memoria:
+```bash
+COMPOSER_MEMORY_LIMIT=-1 composer install
+```
+
+### 3. Instalar Dependencias NPM
+
+```bash
+npm install
+```
+
+### 4. Configurar Archivo de Entorno
+
+```bash
+# Copiar archivo de ejemplo
+cp .env.example .env
+
+# Generar clave de aplicacion
+php artisan key:generate
+```
+
+### 5. Editar Configuracion
+
+Editar el archivo `.env` con los valores apropiados:
+
+```env
+# Aplicacion
+APP_NAME=Horux
+APP_ENV=local
+APP_KEY=base64:GENERADA_AUTOMATICAMENTE
+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=horux360bd
+DB_USERNAME=tu_usuario
+DB_PASSWORD=tu_password
+
+# Logging
+LOG_CHANNEL=stack
+LOG_LEVEL=debug
+```
+
+### 6. Crear Base de Datos
+
+```bash
+# Conectar a MySQL
+mysql -u root -p
+
+# Crear base de datos
+CREATE DATABASE horux360bd CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+# Crear usuario (opcional)
+CREATE USER 'horux_user'@'localhost' IDENTIFIED BY 'password_seguro';
+GRANT ALL PRIVILEGES ON horux360bd.* TO 'horux_user'@'localhost';
+FLUSH PRIVILEGES;
+
+# Salir
+exit
+```
+
+### 7. Ejecutar Migraciones
+
+```bash
+php artisan migrate
+```
+
+O importar el dump existente:
+```bash
+mysql -u usuario -p horux360bd < horux360bd.sql
+```
+
+### 8. Configurar Laravel Passport
+
+```bash
+# Instalar Passport
+php artisan passport:install
+
+# Esto generara Client ID y Client Secret
+# Copiar estos valores al archivo .env o config/app.php
+```
+
+Agregar al `.env`:
+```env
+PASSPORT_CLIENT_ID=1
+PASSPORT_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXX
+```
+
+### 9. Configurar Permisos de Directorios
+
+```bash
+# Linux/Mac
+chmod -R 775 storage
+chmod -R 775 bootstrap/cache
+
+# Si hay problemas de permisos
+sudo chown -R www-data:www-data storage bootstrap/cache
+```
+
+### 10. Compilar Assets (Opcional)
+
+```bash
+# Desarrollo
+npm run dev
+
+# Produccion
+npm run build
+```
+
+### 11. Iniciar Servidor de Desarrollo
+
+```bash
+php artisan serve
+```
+
+La aplicacion estara disponible en: `http://localhost:8000`
+
+---
+
+## Configuracion Avanzada
+
+### Configurar Clerk (Autenticacion)
+
+1. Crear cuenta en [Clerk](https://clerk.com)
+2. Crear aplicacion y obtener credenciales
+3. Configurar redirect URIs:
+   - Desarrollo: `http://localhost:3000/callback`
+   - Produccion: `https://tu-dominio.com/callback`
+
+### Configurar Syntage API
+
+La API key de Syntage se configura en `routes/api.php`. Para produccion, mover a variables de entorno:
+
+```env
+SYNTAGE_API_KEY=tu_api_key
+```
+
+### Configurar Facturama
+
+```env
+FACTURAMA_USER=tu_usuario
+FACTURAMA_PASSWORD=tu_password
+FACTURAMA_SANDBOX=true  # false para produccion
+```
+
+---
+
+## Configuracion para Produccion
+
+### 1. Optimizar Autoloader
+
+```bash
+composer install --optimize-autoloader --no-dev
+```
+
+### 2. Cachear Configuracion
+
+```bash
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+```
+
+### 3. Configurar Variables de Produccion
+
+```env
+APP_ENV=production
+APP_DEBUG=false
+APP_URL=https://tu-dominio.com
+
+LOG_LEVEL=error
+```
+
+### 4. Configurar HTTPS
+
+Asegurarse de que el servidor web (Nginx/Apache) tenga SSL configurado.
+
+### 5. Configurar Cola de Trabajos (Opcional)
+
+```bash
+# En .env
+QUEUE_CONNECTION=database
+
+# Ejecutar migraciones de cola
+php artisan queue:table
+php artisan migrate
+
+# Iniciar worker
+php artisan queue:work
+```
+
+---
+
+## Configuracion de Servidor Web
+
+### Nginx
+
+```nginx
+server {
+    listen 80;
+    server_name tu-dominio.com;
+    root /var/www/Horux_back/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.0-fpm.sock;
+        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
+        include fastcgi_params;
+    }
+
+    location ~ /\.(?!well-known).* {
+        deny all;
+    }
+}
+```
+
+### Apache
+
+Crear archivo `.htaccess` en `/public`:
+
+```apache
+<IfModule mod_rewrite.c>
+    <IfModule mod_negotiation.c>
+        Options -MultiViews -Indexes
+    </IfModule>
+
+    RewriteEngine On
+
+    # Handle Authorization Header
+    RewriteCond %{HTTP:Authorization} .
+    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
+
+    # Redirect Trailing Slashes If Not A Folder...
+    RewriteCond %{REQUEST_FILENAME} !-d
+    RewriteCond %{REQUEST_URI} (.+)/$
+    RewriteRule ^ %1 [L,R=301]
+
+    # Send Requests To Front Controller...
+    RewriteCond %{REQUEST_FILENAME} !-d
+    RewriteCond %{REQUEST_FILENAME} !-f
+    RewriteRule ^ index.php [L]
+</IfModule>
+```
+
+---
+
+## Solucion de Problemas
+
+### Error: SQLSTATE[HY000] [2002]
+
+No se puede conectar a MySQL. Verificar:
+- MySQL esta corriendo: `sudo systemctl status mysql`
+- Credenciales en `.env` son correctas
+- Host y puerto son correctos
+
+### Error: Permission denied
+
+```bash
+sudo chown -R $USER:www-data storage bootstrap/cache
+sudo chmod -R 775 storage bootstrap/cache
+```
+
+### Error: Class not found
+
+```bash
+composer dump-autoload
+php artisan clear-compiled
+```
+
+### Error: The Mix manifest does not exist
+
+```bash
+npm run dev
+# o
+npm run build
+```
+
+### Limpiar Cache
+
+```bash
+php artisan cache:clear
+php artisan config:clear
+php artisan route:clear
+php artisan view:clear
+```
+
+---
+
+## Comandos Utiles
+
+```bash
+# Ver rutas disponibles
+php artisan route:list
+
+# Ejecutar tests
+php artisan test
+
+# Ejecutar tinker (REPL)
+php artisan tinker
+
+# Crear nuevo controlador
+php artisan make:controller NombreController
+
+# Crear nuevo modelo
+php artisan make:model Nombre -m
+
+# Ver logs
+tail -f storage/logs/laravel.log
+```