# Documentación de Campos de Fecha en la Tabla Alumnos

## Campos Timestamp

La tabla `alumnos` cuenta con tres campos de timestamp para rastrear diferentes momentos en el ciclo de vida de un registro:

### 1. **created_at** (Fecha de Creación del Borrador)
- **Propósito**: Registra la fecha y hora cuando se crea el registro por primera vez COMO BORRADOR.
- **Se guarda cuando**: 
  - Se crea un nuevo capacitando como BORRADOR (status = 'B')
- **Permanece NULL cuando**:
  - Se crea un capacitando directamente como COMPLETO (sin pasar por borrador)
- **Nunca cambia**: Una vez establecido, este campo permanece constante.

### 2. **updated_at** (Última Actualización)
- **Propósito**: Registra la fecha y hora de la última modificación del registro.
- **Se actualiza cuando**:
  - Se crea un registro (borrador o completo)
  - Se modifica cualquier dato del capacitando
  - Se guarda un borrador con cambios
  - Se completa un borrador
  - Se actualiza un registro completo
  - Se cambia el estatus del capacitando
- **Siempre se actualiza**: Cada modificación actualiza este campo.

### 3. **saved_at** (Fecha de Completado)
- **Propósito**: Registra la fecha y hora cuando el formulario se completa por primera vez.
- **Se guarda cuando**:
  - Se crea un nuevo capacitando COMPLETO directamente (btnGuardar en insert)
  - Se completa un borrador existente por primera vez (btnGuardar en update desde status 'B')
- **Permanece NULL cuando**:
  - El registro es un borrador que nunca se ha completado
- **Nunca cambia después**: Una vez establecido, no se modifica en actualizaciones posteriores.

## Flujos de Trabajo

### Flujo 1: Crear como Borrador → Completar → Actualizar
```
1. Crear borrador:
   created_at  = 2024-12-02 10:00:00  (se establece)
   updated_at  = 2024-12-02 10:00:00  (se establece)
   saved_at    = NULL
   status      = 'B'

2. Completar borrador (primera vez):
   created_at  = 2024-12-02 10:00:00  (sin cambios - mantiene fecha de creación del borrador)
   updated_at  = 2024-12-02 11:30:00  (actualizado)
   saved_at    = 2024-12-02 11:30:00  (establecido por primera vez)
   status      = 'I'

3. Actualizar datos:
   created_at  = 2024-12-02 10:00:00  (sin cambios - mantiene fecha de creación del borrador)
   updated_at  = 2024-12-02 14:15:00  (actualizado)
   saved_at    = 2024-12-02 11:30:00  (sin cambios - mantiene fecha de completado)
   status      = 'I'
```

### Flujo 2: Crear Completo Directamente (sin borrador previo)
```
1. Crear completo:
   created_at  = NULL                 (no se establece - nunca fue borrador)
   updated_at  = 2024-12-02 10:00:00  (se establece)
   saved_at    = 2024-12-02 10:00:00  (se establece - completado inmediato)
   status      = 'I'

2. Actualizar datos:
   created_at  = NULL                 (sin cambios - nunca fue borrador)
   updated_at  = 2024-12-02 12:45:00  (actualizado)
   saved_at    = 2024-12-02 10:00:00  (sin cambios - mantiene fecha de completado)
   status      = 'I'
```

### Flujo 3: Crear como Borrador → Guardar Borrador Múltiples Veces
```
1. Crear borrador:
   created_at  = 2024-12-02 10:00:00  (se establece)
   updated_at  = 2024-12-02 10:00:00  (se establece)
   saved_at    = NULL
   status      = 'B'

2. Actualizar borrador (1ra vez):
   created_at  = 2024-12-02 10:00:00  (sin cambios)
   updated_at  = 2024-12-02 10:30:00  (actualizado)
   saved_at    = NULL                 (sin cambios)
   status      = 'B'

3. Actualizar borrador (2da vez):
   created_at  = 2024-12-02 10:00:00  (sin cambios)
   updated_at  = 2024-12-02 11:00:00  (actualizado)
   saved_at    = NULL                 (sin cambios)
   status      = 'B'
```

## Implementación Técnica

### Migración
```php
// database/migrations/2024_12_02_000002_add_saved_at_to_alumnos_table.php
Schema::table('alumnos', function (Blueprint $table) {
    $table->timestamp('saved_at')->nullable()->after('updated_at')
        ->comment('Fecha y hora cuando se guardó por primera vez como completo');
});
```

### Controlador - Insert
```php
'created_at' => isset($request->btnBorrador) ? now() : null, // Solo si es borrador
'updated_at' => now(),
'saved_at'   => isset($request->btnGuardar) ? now() : null,  // Solo si se guarda completo
```

### Controlador - Update
```php
// Verificar si es la primera vez que se completa (de borrador a completo)
$esPrimeraVezCompleto = (
    $capacitandoAnterior->alu_status === 'B' && 
    isset($request->btnGuardar) && 
    !$capacitandoAnterior->saved_at
);

// Agregar saved_at solo si es primera vez completo
if ($esPrimeraVezCompleto) {
    $updateData['saved_at'] = now();
}

// updated_at siempre se actualiza
$updateData['updated_at'] = now();
```

## Casos de Uso

### Reportes
- **Nuevos borradores hoy**: WHERE DATE(created_at) = CURDATE()
- **Completados hoy**: WHERE DATE(saved_at) = CURDATE()
- **Modificados hoy**: WHERE DATE(updated_at) = CURDATE()
- **Borradores pendientes**: WHERE saved_at IS NULL AND alu_status = 'B'
- **Creados directamente como completos**: WHERE created_at IS NULL AND saved_at IS NOT NULL
- **Tiempo de borrador a completado**: TIMESTAMPDIFF(HOUR, created_at, saved_at) WHERE created_at IS NOT NULL

### Auditoría
- **Inicio como borrador**: created_at (NULL si nunca fue borrador)
- **Última modificación**: updated_at
- **Fecha de completado**: saved_at
- **Tiempo total de edición (solo para borradores)**: updated_at - created_at WHERE created_at IS NOT NULL
- **Tiempo para completar (desde borrador)**: saved_at - created_at WHERE created_at IS NOT NULL
- **Tipo de creación**: IF(created_at IS NULL, 'Creado completo', 'Inició como borrador')

## Bitácora

El sistema registra en la bitácora cuando:
- Se crea un registro (borrador o completo)
- Se actualiza un registro
- Se completa un borrador por primera vez (marcado especialmente)

Ejemplo de entrada en bitácora cuando se completa por primera vez:
```
Capacitando actualizado (ACTUALIZACIÓN COMPLETA)
ID: 123
No. Control: 24219990001234
Nombre: JUAN PÉREZ GARCÍA
CURP: PEGJ900101HDFRXN01
Estatus: I
*** PRIMERA VEZ COMPLETADO: Cambió de BORRADOR a COMPLETO ***
Fecha de completado (saved_at): 2024-12-02 11:30:00
```

## Notas Importantes

1. **created_at** se establece SOLO cuando se crea como BORRADOR. Si se crea directamente como completo, será NULL.
2. **updated_at** se actualiza en cada modificación, sin importar el tipo (creación, edición, cambio de status).
3. **saved_at** solo se establece UNA VEZ cuando se completa el formulario por primera vez.
4. Si un registro se crea directamente como completo: created_at = NULL, saved_at y updated_at tendrán el mismo valor.
5. Los borradores que nunca se completan tendrán **saved_at = NULL**.
6. **Diferencia clave**: created_at rastrea cuando inició como borrador, saved_at rastrea cuando se completó.