Diseñar una migración segura | Curso de desarrollo de videojuegos con IA

1437. Identidad de la lección

Módulo: 3.17 — Migraciones de partidas guardadas
Lección: 2 — Diseñar una migración segura
Tipo académico: Construcción guiada
Tipo de lección: Práctica
Orden: 2 dentro de la secuencia del módulo
Tiempo estimado: 50–70 minutos, incluida la práctica

Esta lección convierte un problema de compatibilidad en un diseño explícito de migración. Crearás una matriz de migración y un plan de validación antes de implementar.

1438. Objetivo de aprendizaje

Después de esta lección, podrás producir una matriz de migración y un plan de validación que definan las rutas de esquema admitidas, el comportamiento de los campos y sus dependencias, los puntos de fallo y una salida transaccional segura.

1439. Por qué importa

Una migración de partidas guardadas no es solamente una función de conversión. Es el límite entre datos escritos bajo un contrato y código que espera otro. Un diseño que solo contempla una partida antigua normal puede borrar progreso silenciosamente, aceptar valores contrarios a las reglas nuevas, intentar un retroceso de versión no admitido o dañar el archivo de origen si se interrumpe la escritura. Definir estas decisiones de antemano proporciona un contrato preciso para implementar y probar.

1440. Conocimientos previos

Debes poder:

explicar por qué un cambio en el formato de guardado crea una obligación de compatibilidad;
distinguir la identidad del esquema de la identidad de la compilación;
distinguir una representación antigua de una nueva;
identificar cuándo un cambio puede interpretarse de forma segura sin código de migración.

Estas capacidades proceden de 3.17 L1 — Un cambio en una partida guardada es una decisión de compatibilidad. También necesitas nociones básicas de validación, valores predeterminados y gestión de errores.

1441. Concepto central

Una migración segura es una tabla explícita de decisiones para cada valor modificado y cada punto de fallo. Comienza con un control de dirección del esquema, antes de transformar ningún campo:

Lee la identidad del esquema de origen sin tratar la partida como si ya tuviera el formato de destino.
Confirma que la ruta entre origen y destino está admitida.
Si el origen es más antiguo, sigue en orden la cadena de migraciones documentada.
Si el origen es más reciente que el cargador, recházalo salvo que exista una ruta de retroceso especificada por separado.
Solo después de aceptar la ruta pueden ejecutarse las transformaciones de campos y las reglas entre campos.

Esta distinción es esencial: un campo desconocido dentro de un esquema de origen admitido puede tener una política documentada de conservación o rechazo. Una partida completa procedente de un esquema posterior no es simplemente un conjunto de campos desconocidos y no debe pasar por una migración ascendente ordinaria.

Para cada entrada admitida, decide si corresponde transformarla, validar el resultado, conservar información, rechazar la partida o recuperar mediante una alternativa definida. Son decisiones independientes. Un valor puede transformarse y aun así fallar la validación, o ser válido por separado pero resultar inseguro junto con otros datos.

Una migración debe responder seis preguntas:

Control de versión: ¿Está admitida esta ruta exacta entre origen y destino?
Transformar: ¿En qué se convierte la representación antigua?
Validar: ¿Qué restricciones debe cumplir después de la transformación?
Conservar: ¿Qué información debe mantenerse o sobrevivir mediante una conversión explícita?
Rechazar: ¿Qué condiciones hacen que la partida no sea segura?
Recuperar: ¿Qué acción limitada y visible existe tras un rechazo o un fallo transaccional?

1442. Modelo mental

Usa filas separadas para las reglas de versión del esquema, los campos modificados, las reglas entre campos y los límites transaccionales.

Alcance de la regla	Decisiones necesarias	Evidencia que debes registrar
Versión del esquema	Ruta admitida, cadena de migración, rechazo de esquemas posteriores y retroceso definido por separado si existe	Versiones de origen y destino, ruta seleccionada y resultado del control
Campo	Transformación, validación, conservación, rechazo y recuperación cuando correspondan	Ejemplos antes/después y casos válidos e inválidos
Regla entre campos	Restricción de relación y propiedad del rechazo o la recuperación	Combinaciones válidas e imposibles
Transacción	Ubicación de salida, validación de lo escrito, confirmación, copia de seguridad o reversión y comportamiento ante interrupciones	Identidad del origen, resultado de la salida temporal, relectura y confirmación

Una celda puede indicar «No aplicable — lo gestiona la regla X» cuando la decisión corresponde realmente a una regla de versión, entre campos o transaccional identificada. No inventes una recuperación para un solo campo si la recuperación pertenece a un límite más amplio.

Prueba el diseño con estas clases de entrada:

Datos antiguos esperados: una partida válida de un esquema anterior admitido.
Datos límite: valores mínimos, máximos, vacíos, ausentes y recién introducidos.
Datos malformados: tipos incorrectos, enumeraciones inválidas, combinaciones imposibles o contenido truncado.
Datos desconocidos dentro de un esquema admitido: campos o valores no reconocidos pero cubiertos por la política de compatibilidad.
Dirección de esquema no admitida: en especial, un origen más reciente que el cargador.
Fallo transaccional: interrupción o error al producir, validar o confirmar la salida.

La matriz está completa solo cuando cada celda relevante contiene una decisión o remite a la regla identificada que se hace cargo de ella.

1443. Ejemplo concreto

Supón que la versión 2 guarda credits como entero y que la versión 3 introduce wallet:

v2: { "schemaVersion": 2, "credits": 120, "inventory": ["medkit"] }
v3: { "schemaVersion": 3, "wallet": { "credits": 120 }, "inventory": ["medkit"] }

Un fragmento del plan podría ser:

Caso de entrada	Decisión	Resultado
Origen v2 y destino v3	Aceptar la ruta ascendente documentada	Continuar con la transformación
Origen v4 y cargador compatible hasta v3	Rechazar durante el control de versión	No ejecutar la migración v2–v3 ni sobrescribir el origen
`credits` entero de v2	Transformar	Moverlo a `wallet.credits`
Falta `credits`	Recuperar o rechazar según el contrato	Usar cero solo si conserva el significado y está documentado; si no, rechazar
`credits` negativo	Rechazar	No crear un saldo inválido
`credits` no entero	Rechazar	No redondear silenciosamente
Objeto desconocido en una entrada v2 admitida	Conservar o rechazar según el contrato del inventario	No eliminarlo silenciosamente
Entrada truncada	Rechazar antes de escribir	Mantener intacto el origen e indicar la ruta de recuperación
Escritura temporal interrumpida	Cancelar la transacción	Descartar la salida temporal incompleta y conservar el origen y las copias exigidas
La salida escrita no supera la validación tras releerla	No confirmar	Conservar el origen y registrar el fallo de validación
No se puede confirmar una salida válida	Aplicar la política documentada de copia o reversión	No declarar el éxito si la partida confirmada no es válida e identificable

El ejemplo deja decisiones abiertas. El contrato real debe definir las políticas de valores predeterminados, inventario, copias de seguridad, reversión y comunicación. Lo importante es que mover un campo solo cubre una parte del diseño.

1444. Salida transaccional segura

Transformar y validar en memoria no basta para reemplazar un archivo con seguridad. Define la transacción de salida sin depender de una API de almacenamiento concreta:

Mantén intacta la partida de origen durante la migración.
Escribe la candidata en una ubicación temporal o en un archivo nuevo e independiente.
Vuelve a leer la candidata escrita y valida su identidad de esquema, estructura, restricciones y afirmaciones de conservación.
Confirma o reemplaza únicamente después de que la salida escrita supere la validación.
Indica cuándo se crea una copia de seguridad y cómo funciona la reversión si falla la confirmación o el reemplazo.
Define qué ocurre si hay una interrupción durante la escritura, la validación o la confirmación.
Registra el éxito solo cuando la salida confirmada pueda distinguirse de una candidata meramente analizada o escrita de forma parcial.

La política debe poder probarse: para cada punto de fallo, identifica qué artefacto conserva la autoridad, cuál se descarta o se guarda para diagnóstico y qué se comunica a la persona usuaria.

1445. Errores comunes

Confundir un análisis sintáctico correcto con una migración correcta.
Tratar una partida de un esquema posterior como si solo contuviera campos desconocidos.
Omitir migraciones intermedias obligatorias dentro de una cadena documentada.
Aplicar un valor predeterminado que cambie silenciosamente el significado de la partida.
Obligar a cada fila de campo a inventar su propia recuperación en vez de remitir a la regla entre campos o transaccional correspondiente.
Sobrescribir el origen antes de validar la candidata escrita mediante una relectura.
Declarar el éxito tras validar en memoria aunque falle la confirmación de la salida.

1446. Práctica guiada

Crea una matriz de migración y un plan de validación para este cambio hipotético:

Versión 4
- `credits`: entero, debe ser 0 o mayor
- `rank`: uno de "runner", "broker", "fixer"
- `inventory`: lista de identificadores de objetos
- `lastSafehouse`: identificador que puede faltar en partidas antiguas

Versión 5
- `wallet.balance`: entero, debe ser 0 o mayor
- `rank`: uno de "runner", "broker", "fixer", "handler"
- `inventory`: lista de registros con identificador y cantidad >= 1
- `safehouse.id`: obligatorio al cargar una partida
- `safehouse.visited`: booleano

Sigue estos pasos:

Añade una fila de versión antes de todas las filas de campos. Define el comportamiento para origen v4 y destino v5, cualquier cadena documentada desde versiones anteriores, un origen v5 y un origen posterior a v5. No definas un retroceso si el contrato no lo proporciona expresamente.
Enumera cada campo cuya ubicación, tipo, valores permitidos, obligatoriedad o significado cambie.
Añade al menos una fila por cada campo modificado y cada dependencia entre campos.
Añade una fila transaccional que cubra salida temporal o en archivo nuevo, relectura y validación, confirmación o reemplazo, política de copia o reversión e interrupción durante la escritura.
Para cada fila, registra las decisiones aplicables de transformación, validación, conservación, rechazo y recuperación. Si alguna no corresponde, escribe «No aplicable — lo gestiona la regla X» e identifica la regla responsable.
Incluye casos para lastSafehouse ausente, rank desconocido, inventario vacío, cantidad cero, saldo negativo, identificador de objeto desconocido, entrada truncada, un esquema de origen posterior no admitido y una escritura interrumpida.
Marca las decisiones que requieren una política elegida por la persona responsable del producto o del sistema, en lugar de una inferencia silenciosa.
Escribe un plan con al menos un caso antiguo esperado, dos casos límite, dos casos malformados, un caso de versión no admitida, un caso de recuperación y dos casos transaccionales: interrupción durante la escritura y fallo al confirmar o reemplazar.
Añade un punto de control de compatibilidad versionado por esquema. Registra las versiones de origen y destino, el resultado del control, la cadena seleccionada, los resultados de validación y conservación, el estado transaccional, el resultado de rechazo o recuperación y si el original conservó la autoridad.

Tu plan debe distinguir entre una candidata validada en memoria, una candidata escrita y validada, y una partida confirmada correctamente.

1447. Validación y evidencia

Tu trabajo está completo cuando incluye:

un control de versión que permita únicamente rutas documentadas entre origen y destino;
el rechazo explícito de un esquema de origen posterior salvo que exista un retroceso definido por separado;
una matriz que cubra los campos modificados y las dependencias entre campos;
una regla responsable identificada para cada decisión marcada como no aplicable;
una política para campos e identificadores desconocidos dentro de entradas admitidas;
casos normales, límite, malformados, truncados, de versión no admitida, de recuperación y de fallo transaccional;
una regla transaccional que cubra salida separada, relectura y validación, confirmación, copia o reversión e interrupciones;
un punto de control que muestre qué artefacto conserva la autoridad tras cada fallo;
al menos una decisión que requiera una política humana en lugar de una inferencia silenciosa.

Otra persona o un agente de implementación debería poder derivar el comportamiento sin inventar reglas de versión, de campos o de transacción.

1448. Ideas clave

Comprueba la dirección del esquema antes de transformar campos.
Los datos desconocidos dentro de un esquema admitido no son lo mismo que un esquema posterior no admitido.
Transformar y validar son obligaciones distintas.
Las reglas entre campos y las reglas transaccionales pueden ser responsables del rechazo o la recuperación.
Una candidata no está migrada de forma segura hasta validar su representación escrita y confirmarla bajo una política de reversión definida.
El origen debe conservar la autoridad si falla la migración, la validación de lo escrito o la confirmación.

1449. Próxima lección

Continúa con 3.18 — Arquitectura de localización.