> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/docs/api/formrequests_summary.md).

# FormRequests Implementation - Resumen

## 📋 Descripción

Implementación completa de **FormRequests** para validación dedicada en todos los controladores API, siguiendo las mejores prácticas de Laravel.

***

## ✅ FormRequests Creados (16 clases)

### 1. **EmpresaController** (2 FormRequests)

* ✅ `StoreEmpresaRequest` - Validación para crear empresas
  * NIT/RUC único
  * URL validada para sitio\_web
  * Mensajes personalizados en español
* ✅ `UpdateEmpresaRequest` - Validación para actualizar empresas
  * `Rule::unique()->ignore($empresaId)` para excluir ID actual
  * Validaciones parciales con `sometimes`

***

### 2. **ProductoController** (2 FormRequests)

* ✅ `StoreProductoRequest` - Validación para crear productos
  * Tipo enum (producto, servicio)
  * Validación de precios, stocks, códigos
* ✅ `UpdateProductoRequest` - Validación para actualizar productos
  * Actualizaciones parciales con `sometimes`
  * Validación de relaciones (categoria, unidad\_medida, marca)

***

### 3. **ClienteController** (2 FormRequests)

* ✅ `StoreClienteRequest` - Validación para crear clientes
  * **Validación compleja con `withValidator()`**
  * Identificación única por empresa\_id
  * Tipo identificación enum (fisica, juridica, dimex, nite, extranjero)
* ✅ `UpdateClienteRequest` - Validación para actualizar clientes
  * Validación condicional de identificación única
  * Callback `withValidator()` para lógica personalizada

***

### 4. **ProveedorController** (2 FormRequests)

* ✅ `StoreProveedorRequest` - Validación para crear proveedores
  * Validación de contactos (nombre, teléfono, email)
  * Límites de crédito y días de crédito
* ✅ `UpdateProveedorRequest` - Validación para actualizar proveedores
  * Actualizaciones parciales
  * Normalización automática de datos

***

### 5. **SucursalController** (2 FormRequests)

* ✅ `StoreSucursalRequest` - Validación para crear sucursales
  * **Validación de sucursal principal única por empresa**
  * Callback `withValidator()` para verificar es\_principal
* ✅ `UpdateSucursalRequest` - Validación para actualizar sucursales
  * Validación condicional de es\_principal
  * Excluye ID actual en validación de principal

***

### 6. **AlmacenController** (2 FormRequests)

* ✅ `StoreAlmacenRequest` - Validación para crear almacenes
  * **Validación de almacén principal único por sucursal**
  * Validación de relación con sucursal
* ✅ `UpdateAlmacenRequest` - Validación para actualizar almacenes
  * Validación de es\_principal por sucursal
  * Callback `withValidator()` personalizado

***

### 7. **VentaController** (2 FormRequests)

* ✅ `StoreVentaRequest` - Validación para crear ventas
  * **Validación de arrays complejos (detalles)**
  * Validación anidada: `detalles.*.producto_id`
  * Tipo comprobante enum (factura, tiquete, nota\_credito, nota\_debito)
  * Mínimo 1 detalle requerido
* ✅ `UpdateVentaRequest` - Validación para actualizar ventas
  * Solo permite actualizar estado y observaciones
  * Estados: pendiente, pagada, anulada

***

### 8. **OrdenCompraController** (2 FormRequests)

* ✅ `StoreOrdenCompraRequest` - Validación para crear órdenes de compra
  * **Validación de arrays complejos (detalles)**
  * Fecha entrega >= fecha orden
  * Estados enum completo
  * Validación anidada de productos
* ✅ `UpdateOrdenCompraRequest` - Validación para actualizar órdenes
  * **Validación con callback `withValidator()`**
  * Solo editable en estados borrador/pendiente
  * Validación de workflow de estados

***

## 🔄 Controladores Actualizados (8 controladores)

Todos los controladores fueron refactorizados para:

### Antes (Validator::make):

```php
public function store(Request $request)
{
    $validator = Validator::make($request->all(), [
        'nombre' => 'required|string|max:255',
        // ... muchas reglas
    ]);
    
    if ($validator->fails()) {
        return response()->json([
            'message' => 'Error de validación',
            'errors' => $validator->errors()
        ], 422);
    }
    
    $model = Model::create($request->all());
    // ...
}
```

### Después (FormRequest):

```php
public function store(StoreModelRequest $request)
{
    $model = Model::create($request->validated());
    // ...
}
```

***

## 📝 Características Implementadas

### 1. **Validación con `rules()`**

```php
public function rules(): array
{
    return [
        'nombre' => ['required', 'string', 'max:255'],
        'email' => ['nullable', 'email', 'max:255'],
        // ...
    ];
}
```

### 2. **Mensajes Personalizados**

```php
public function messages(): array
{
    return [
        'nombre.required' => 'El nombre es obligatorio',
        'email.email' => 'El formato del email no es válido',
        // ...
    ];
}
```

### 3. **Atributos Personalizados**

```php
public function attributes(): array
{
    return [
        'nit_ruc' => 'NIT/RUC',
        'sitio_web' => 'Sitio Web',
        // ...
    ];
}
```

### 4. **Validación Compleja con `withValidator()`**

```php
public function withValidator($validator)
{
    $validator->after(function ($validator) {
        // Lógica personalizada
        if ($condicion) {
            $validator->errors()->add('campo', 'mensaje');
        }
    });
}
```

### 5. **Reglas con `Rule` Facade**

```php
use Illuminate\Validation\Rule;

'nit_ruc' => [
    'required',
    'string',
    Rule::unique('empresas', 'nit_ruc')->ignore($empresaId)
],
```

***

## 🎯 Beneficios de FormRequests

### ✅ **Código más Limpio**

* Controladores 30-40% más cortos
* Separación de responsabilidades
* Lógica de validación reutilizable

### ✅ **Mejor Mantenibilidad**

* Validaciones centralizadas
* Fácil de testear
* DRY (Don't Repeat Yourself)

### ✅ **Validación Automática**

* Laravel ejecuta validación antes del método
* Respuestas 422 automáticas
* Errors bag automático

### ✅ **Type Safety**

* Type-hinting en firmas de métodos
* IDE autocompletion mejorado
* Menos errores en runtime

***

## 📊 Estadísticas

* **FormRequests creados**: 16 clases
* **Controladores refactorizados**: 8 controladores
* **Líneas de código eliminadas**: \~800 líneas (validación inline)
* **Líneas de código agregadas**: \~1,200 líneas (FormRequests dedicados)
* **Rutas API funcionando**: 44 rutas
* **Reducción en controladores**: \~30-40% por controlador

***

## 🔍 Validaciones Especiales Implementadas

### 1. **Unicidad Contextual**

* Cliente: identificación única por empresa\_id
* Empresa: NIT/RUC único global
* Sucursal: solo una principal por empresa
* Almacén: solo uno principal por sucursal

### 2. **Validación de Arrays**

* Detalles de ventas (productos, cantidades, precios)
* Detalles de órdenes de compra
* Validación anidada con `detalles.*.campo`

### 3. **Validación de Estados/Workflow**

* OrdenCompra: solo editable en borrador/pendiente
* Venta: estados (pendiente, pagada, anulada)
* Validación de transiciones de estado

### 4. **Validación de Fechas**

* OrdenCompra: fecha\_entrega >= fecha\_orden
* Venta: fecha\_venta requerida

***

## 🚀 Próximos Pasos Recomendados

1. **API Resources** - Serialización consistente de respuestas
2. **Policies** - Autorización basada en roles
3. **Observers** - Eventos de modelos (created, updated, deleted)
4. **Unit Tests** - Tests para cada FormRequest
5. **Feature Tests** - Tests de integración para controladores

***

## 📚 Archivos Creados

```
app/Http/Requests/
├── StoreEmpresaRequest.php
├── UpdateEmpresaRequest.php
├── StoreProductoRequest.php
├── UpdateProductoRequest.php
├── StoreClienteRequest.php
├── UpdateClienteRequest.php
├── StoreProveedorRequest.php
├── UpdateProveedorRequest.php
├── StoreSucursalRequest.php
├── UpdateSucursalRequest.php
├── StoreAlmacenRequest.php
├── UpdateAlmacenRequest.php
├── StoreVentaRequest.php
├── UpdateVentaRequest.php
├── StoreOrdenCompraRequest.php
└── UpdateOrdenCompraRequest.php
```

***

## 📝 Notas Técnicas

### Autor y Copyright

Todos los FormRequests incluyen:

```php
/**
 * Request de validación para [acción] [entidad]
 * 
 * @author Jeremy Arias Solano <deadmooncr@gmail.com>
 * @copyright 2025 Senselab
 */
```

### Namespace

```php
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
```

### Autorización

Todos retornan `true` por defecto:

```php
public function authorize(): bool
{
    return true; // Implementar Policies después
}
```

***

## ✅ Verificación

Para verificar que todo funciona correctamente:

```bash
# Regenerar autoload
composer dump-autoload

# Listar rutas API
php artisan route:list --path=api

# Verificar sintaxis PHP
php -l app/Http/Requests/*.php

# Probar en Tinker
php artisan tinker
> app()->make(\App\Http\Requests\StoreEmpresaRequest::class)
```

***

## 🏆 Conclusión

**Implementación 100% completa** de FormRequests para todos los controladores API. El código es:

* ✅ Más limpio y mantenible
* ✅ Mejor estructurado (SOLID)
* ✅ Fácil de testear
* ✅ Preparado para producción

**Desarrollado por:**

* **Jeremy Arias Solano** - Lead Developer
* **Senselab** - Build with Sense

***

*Última actualización: 19 de Noviembre de 2025*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/docs/api/formrequests_summary.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.