# Modelo de datos y plan de migración Produce el modelo que el sistema debería contener y el camino reversible desde el almacenamiento que existe hoy hasta ese modelo. ## Entregable Un documento Markdown, `data-model-and-migration.md`, con la estructura fijada en **Salida** más abajo. Lleva dos artefactos unidos — el modelo objetivo y el manual que llega hasta él — porque un modelo sin camino hacia él no se puede planificar. ## Entradas obligatorias - **Las entidades que el sistema debe contener** — qué se guarda y qué significa cada cosa para quienes lo usan. Las secciones 3 y 5 de `architecture-specification.md` son la forma esperada. - **El almacenamiento tal como está hoy** — las estructuras que existen ahora, leídas del sistema o descritas por alguien que lo opera. Si falta el estado actual, detente y repórtalo. Una migración planificada contra un punto de partida supuesto es un plan para otro sistema, y se detiene en el primer paso que toca datos reales. ## Entradas opcionales - Acceso directo a las estructuras vivas, con sus claves, restricciones e índices - Volúmenes de datos y crecimiento, tal como los declare el dueño del sistema - Las obligaciones de retención, residencia y borrado asociadas a cada entidad - Los patrones de acceso que el modelo debe servir: qué se lee, qué se escribe y qué se lee junto - El proceso de publicación dentro del que deben caber los pasos de migración - La ventana en la que el sistema puede estar no disponible, si la hay, tal como la declare su dueño Un volumen ausente nunca se convierte en una duración. Cuando no se aportaron volúmenes, cada paso declara su coste en términos de qué toca — qué estructuras, qué filas, qué lectores — y no de cuánto tarda. ## Ejecución **1 — Registrar el estado actual con exactitud.** Cada estructura del camino que se va a cambiar, con sus campos, claves, restricciones e índices. Marca cada una como `observada` si se leyó del sistema o `reportada` si la describió una persona. Un paso planificado contra una estructura reportada lleva ese riesgo a producción, y el paso lo dice. **2 — Modelar el objetivo.** Entidades, atributos con sus tipos, claves, relaciones con su cardinalidad, las restricciones que deben cumplirse y la retención que lleva cada entidad. Cada atributo se traza hasta algo que el sistema debe hacer; el que no se trace a nada se marca en lugar de arrastrarse porque ya existía. **3 — Indexar para los patrones de acceso declarados.** Un índice existe para servir una lectura que alguien describió. Cuando no se aportaron patrones de acceso, registra solo las claves y las restricciones de unicidad y marca el conjunto de índices como `pendiente de patrones de acceso`. Nunca añadas un índice para una consulta que nadie nombró. **4 — Comparar el actual con el objetivo.** Por cada diferencia: qué cambia, si es aditiva, destructiva o un renombrado disfrazado, y si los datos que existen pueden satisfacer la nueva restricción. Una restricción que los datos actuales violarían es un relleno con una decisión detrás, no un cambio de esquema. **5 — Ordenar los pasos para que cada uno sea reversible.** Primero las estructuras aditivas, junto a las antiguas. Luego el relleno, luego el cambio de lectores, luego el cambio de escritores, luego la retirada de lo que ya no se usa — cada cosa como su propio paso. Un paso que no se pueda revertir lo declara dentro del propio paso, nombra qué lo hace irreversible y nombra quién lo acepta. **6 — Escribir la verificación y la reversión de cada paso.** Por paso: la comprobación que demuestra que hizo lo que dice, expresada como una comparación sobre los datos y no como una cifra, y la acción exacta que lo deshace. Un paso sin verificación no es un paso; es una esperanza con un número al lado. **7 — Declarar la estrategia de conmutación.** Escritura doble, lectura en sombra o una ventana acotada de indisponibilidad — la que permitan las restricciones declaradas — con lo que exige y lo que cuesta mientras dura. Si el dueño no declaró ninguna ventana, el plan asume que no hay y lo dice en las preguntas abiertas. ## Salida `data-model-and-migration.md`, en este orden: - **1. Entrada y fecha** — de qué entidades y de qué estado actual parte este plan, quién los aportó y cuándo - **2. Estado actual** — por estructura: campos, claves, restricciones, índices y `observada` o `reportada` - **3. Modelo objetivo** — por entidad: atributos y tipos, claves, relaciones, restricciones, retención y con qué se traza - **4. Índices** — por índice: la entidad, los campos y el patrón de acceso al que sirve - **5. Diferencia** — por cambio: aditivo, destructivo o renombrado, y si los datos existentes lo satisfacen - **6. Pasos de migración** — en orden; por paso: qué hace, si es reversible y quién lo acepta cuando no lo es - **7. Relleno** — por relleno: qué se rellena, desde qué fuente y qué se hace con las filas que esa fuente no puede rellenar - **8. Verificación y reversión** — por paso: la comprobación que lo demuestra y la acción que lo deshace - **9. Conmutación** — la estrategia, lo que exige y la indisponibilidad que necesita, si la necesita - **10. Preguntas abiertas** — la pregunta, qué bloquea, quién puede responderla ## Validación El plan está listo cuando se cumple todo esto: - Cada entidad de la entrada aparece en la sección 3, o allí se registra como deliberadamente fuera del modelo - Cada atributo de la sección 3 se traza hasta algo que el sistema debe hacer, o se marca como que no se traza a nada - Cada paso de la sección 6 tiene verificación y reversión en la sección 8 - Cada paso irreversible declara su irreversibilidad dentro del paso y nombra quién lo acepta - Cada índice de la sección 4 nombra el patrón de acceso al que sirve, o el conjunto entero está marcado como `pendiente de patrones de acceso` - No aparece ningún volumen, duración ni recuento de filas que el dueño del sistema no haya aportado Falla la ejecución si un paso es irreversible sin decirlo, o si algún paso llega a la sección 6 sin verificación. ## Gestión de fallos - **No hay estado actual** — detente. Entrega solo el modelo objetivo si era lo pedido, e informa de que no se puede planificar ningún camino hacia él desde un punto de partida desconocido. - **Estado actual reportado pero no observado** — produce el plan completo, marca la sección 2 como `reportada` y declara en la sección 10 que cada paso debe volver a comprobarse contra las estructuras reales antes de ejecutarse. - **Sin patrones de acceso** — produce las secciones 1 a 3 y 5 a 10, marca la sección 4 como `pendiente de patrones de acceso` y declara que la indexación queda sin resolver, no cerrada. - **Un paso no se puede hacer reversible** — mantenlo, declara qué lo hace irreversible, nombra los datos que no se podrían recuperar y márcalo como que exige una aceptación con nombre antes de ejecutarse. No lo entierres dentro de un paso mayor. - **Material parcial** — planifica los pasos que el material sostenga, marca el resto como `INCOMPLETO — pendiente de ` y entrega.