# Guía de migración: 9.11.0 → 9.12.0

Osumi Framework **9.12.0** añade soporte nativo para columnas SQL `DATE`, `DATETIME` y `BIGINT` y redefine el significado de `OField::DATE`.

Esta versión incluye un paso automático de migración para mantener la compatibilidad de los modelos existentes.

## DATE y DATETIME

Hasta Osumi Framework 9.11, `OField::DATE` generaba realmente una columna SQL `DATETIME`.

Desde 9.12 los tipos quedan separados:

```text
OField::DATE     → SQL DATE      → PHP ?string → Y-m-d
OField::DATETIME → SQL DATETIME  → PHP ?string → Y-m-d H:i:s
```

Por ejemplo:

```php
#[OField(
	type: OField::DATE
)]
public ?string $event_date = null;

#[OField(
	type: OField::DATETIME
)]
public ?string $processed_at = null;
```

Los valores temporales se validan estrictamente y se rechazan fechas u horas imposibles.

Los campos `#[OCreatedAt]`, `#[OUpdatedAt]` y `#[ODeletedAt]` continúan representando timestamps completos y utilizan internamente `DATETIME`.

## Migración automática de OField::DATE

Los modelos creados con versiones anteriores a 9.12 utilizaban `OField::DATE` con semántica `DATETIME`.

Al actualizar, la migración `9.12.0` transforma automáticamente:

```php
OField::DATE
```

en:

```php
OField::DATETIME
```

dentro de los modelos existentes en `src/Model/`.

La migración modifica únicamente tokens PHP reales y no cambia apariciones dentro de comentarios o cadenas de texto.

No modifica el esquema de la base de datos: conserva la semántica `DATETIME` que ya tenían esos campos.

Después de completar la migración, los nuevos usos de `OField::DATE` representan verdaderas columnas SQL `DATE`.

## BIGINT

9.12 añade `OField::BIGINT`.

```php
#[OField(
	type: OField::BIGINT
)]
public ?int $external_id = null;
```

También puede utilizarse en `#[OPK]`, incluido autoincremento.

`BIGINT` requiere PHP de 64 bits.

No se admiten `UNSIGNED` ni `ZEROFILL`.

## generateModelFromDB

`generateModelFromDB` reconoce ahora:

```text
DATE     → OField::DATE
DATETIME → OField::DATETIME
BIGINT   → OField::BIGINT
```

Las columnas SQL `TIMESTAMP` siguen rechazándose porque no pueden representarse fielmente mediante la semántica `DATETIME` del ORM.

## Pipes y formato

El pipe `date` admite tanto `DATE` como `DATETIME`.

Sin máscara explícita:

```text
DATE     → d/m/Y
DATETIME → d/m/Y H:i:s
```

El método `OModel::get()` también admite ambos tipos temporales con una máscara explícita.

## Estado de migraciones

9.12 mueve el estado autoritativo de migraciones desde:

```text
ofw/tmp/state.json
```

a:

```text
.ofw-migrations.json
```

en la raíz del proyecto.

Este archivo forma parte del estado versionado de la aplicación y debe incluirse en Git.

Durante la primera actualización a 9.12, si `.ofw-migrations.json` aún no existe, el runner puede leer `ofw/tmp/state.json` para recuperar el último paso ejecutado.

Una vez completada una migración con 9.12, el nuevo archivo pasa a ser la fuente autoritativa.

Este cambio evita que la limpieza de `ofw/tmp/` pueda provocar la repetición accidental de una migración antigua.

## Actualización

Antes de actualizar, asegúrese de que el árbol Git de la aplicación esté limpio.

Actualice normalmente mediante Composer:

```bash
composer update osumionline/framework --with-dependencies
```

La migración `9.12.0` se ejecutará automáticamente cuando corresponda.

Después de la actualización:

1. Revise los modelos modificados.
2. Añada `.ofw-migrations.json` al repositorio.
3. Ejecute la batería de tests de la aplicación.
4. Verifique funcionalmente los campos temporales y BIGINT utilizados por la aplicación.
