Modernizar un registro de pedidos existente con Spec Kit

La modernización cambia la estructura técnica preservando un contrato de negocio declarado. A diferencia del trabajo desde cero, el éxito no consiste en «la nueva aplicación funciona». A diferencia de una función en un proyecto existente, el objetivo aquí no es un nuevo comportamiento de negocio.

Resumen del laboratorio

[!NOTE] Una base de datos creada no prueba una migración completa y compatible.

Conceptos · Primera tarea · Lista de evidencias · Restablecer

Objetivos de aprendizaje

• Fija un contrato público antes de cambiar el almacenamiento.
• Rastrea los requisitos de compatibilidad a través de los artefactos y pruebas de Spec Kit.
• Concilia los recuentos importados, los totales, el orden y la versión del esquema.
• Verifica el rechazo de datos incorrectos y una reversión práctica.

Antes de empezar

Completa la configuración de Spec Kit. Prepara 17-modernization usando la configuración de la unidad de trabajo. Usa la biblioteca estándar de Python y SQLite: no se requiere servidor, dependencia de pip, contenedor, recurso en la nube ni base de datos de producción.

Conceptos y casos de uso

Escenario del ejercicio

Un operador depende de que service.py devuelva un objeto JSON con pedidos ordenados y totales en centavos enteros. Sustituye el almacenamiento sin cambiar las claves, el orden, el filtrado por cliente ni la vía CSV predeterminada.

El fixture local contiene:

Tarea 1 - Caracterizar antes de cambiar nada

1. Lee requirements.md y legacy.py.

2. Ejecuta desde la raíz del fixture preparado:

   python -m unittest test_legacy -v
   python service.py --source data/orders.csv
   python service.py --source data/orders.csv --customer C-01
   

3. Confirma un total de 6249 centavos en conjunto y 3250 centavos para C-01. Son valores deterministas del fixture, no una afirmación de rendimiento.

4. Registra el hash de origen, la estructura de salida, el orden, los códigos de salida y el comportamiento del flujo de errores.

5. Ejecuta python -m unittest test_modernization -v; la implementación incompleta debe fallar. No debilites estas pruebas para obtener una línea base que pase.

Tarea 2 - Especificar por separado la preservación y el cambio

Inicializa únicamente la copia desechable. Después:

/speckit-constitution Preserve the JSON CLI contract in requirements.md.
Do not modify legacy.py or baseline assertions. Keep CSV as default. Use no
network or real data. Require validated migration, non-overwrite, reconciliation,
explicit errors and a tested rollback before selecting SQLite.

/speckit-specify Modernize CSV storage to SQLite without changing business behavior.
Implement migrate.py and order_store.py for MOD-1 through MOD-6. Preserve source
bytes, record order, integer cents, customer filtering and CLI output.

Usa /speckit-clarify para resolver las filas mal formadas, los IDs duplicados, las ejecuciones repetidas, las bases de datos ausentes, los destinos existentes y los fallos a mitad de la importación.

Tarea 3 - Modelar el límite de almacenamiento

---
config:
  theme: base
  look: classic
  themeVariables:
    darkMode: false
    background: "#ffffff"
    primaryColor: "#f5f5f5"
    primaryTextColor: "#111111"
    primaryBorderColor: "#555555"
    secondaryColor: "#e0e0e0"
    secondaryTextColor: "#111111"
    secondaryBorderColor: "#666666"
    tertiaryColor: "#bdbdbd"
    tertiaryTextColor: "#111111"
    tertiaryBorderColor: "#444444"
    lineColor: "#444444"
    textColor: "#111111"
    mainBkg: "#f5f5f5"
    nodeBorder: "#555555"
    clusterBkg: "#ffffff"
    clusterBorder: "#999999"
    edgeLabelBackground: "#ffffff"
    actorBkg: "#e0e0e0"
    actorBorder: "#555555"
    actorTextColor: "#111111"
    actorLineColor: "#777777"
    signalColor: "#333333"
    signalTextColor: "#111111"
    labelBoxBkgColor: "#f5f5f5"
    labelBoxBorderColor: "#777777"
    labelTextColor: "#111111"
    loopTextColor: "#111111"
    activationBkgColor: "#bdbdbd"
    activationBorderColor: "#555555"
    noteBkgColor: "#f5f5f5"
    noteTextColor: "#111111"
    noteBorderColor: "#777777"
    attributeBackgroundColorOdd: "#f5f5f5"
    attributeBackgroundColorEven: "#e0e0e0"
---
erDiagram
    accTitle: Contrato de almacenamiento del registro de pedidos
    accDescr: Un cliente conceptual posee muchos pedidos. SQLite almacena registros de pedidos con un ID principal, identificador de cliente, centavos enteros y un estado permitido.
    CUSTOMER ||--o{ ORDER : identifica
    CUSTOMER {
        string id
    }
    ORDER {
        string id PK
        string customer
        int total_cents
        string status
    }

Leyenda. Los recuadros de entidades enumeran campos. La arista con pata de cuervo significa que un identificador de cliente puede aparecer en muchos pedidos. PK marca el identificador del pedido.

Explicación. CUSTOMER es conceptual, no una tabla nueva ni una clave externa obligatorias. El laboratorio real migra únicamente la tabla orders y establece PRAGMA user_version = 1. Añadir un servicio de clientes ampliaría el alcance y arriesgaría cambiar el comportamiento. total_cents es lógicamente un entero. La referencia almacena texto decimal validado porque el rango de enteros y SUM de SQLite es más estrecho que los valores aceptados por Python; lo convierte de nuevo a enteros de Python para JSON y la conciliación exacta.

Tarea 4 - Planificar una migración reversible

/speckit-plan Use Python sqlite3 and standard-library unittest. Validate every
CSV record before import. Refuse any existing target. Create a constrained orders
schema, insert with parameterized statements in a transaction, reconcile count
and integer total without narrowing Python integer precision, and close resources.
Open query databases read-only and never
create one on a missing-file read. Keep source CSV unchanged for rollback.

Revisa cómo la implementación distingue:

• rechazar un destino existente de limpiar su propio destino nuevo fallido;
• una importación exitosa de una base de datos parcial;
• la validación de los datos fuente de las restricciones de SQLite;
• los valores parametrizados del SQL ejecutable;
• la representación de almacenamiento del contrato público de enteros JSON, incluidos totales que superen el rango de 64 bits con signo;
• una excepción local del proceso de la durabilidad ante caídas o cortes de energía.

El fixture no es un servicio de migración de producción. Documenta las limitaciones de recuperación ante caídas y escritores concurrentes en lugar de afirmar que están cubiertas.

Tarea 5 - Implementar mediante puntos de control de evidencia

1. Ejecuta /speckit-tasks y /speckit-analyze.

2. Relaciona cada requisito MOD con la implementación y su prueba.

3. Implementa un límite a la vez; no cambies el contrato público fijado.

4. Ejecuta:

   python -m unittest test_legacy test_modernization -v
   python migrate.py --source data/orders.csv --target orders.db
   python service.py --backend sqlite --source orders.db --customer C-01
   

5. Compara exactamente el JSON de CSV y SQLite. Inspecciona el recuento y el total, no solo la existencia del archivo.

6. Ejecuta de nuevo la misma migración. Debe fallar sin sobrescribir orders.db.

7. Usa otra vez el comando CSV predeterminado para demostrar la reversión sin eliminar el origen.

8. Ejecuta /speckit-converge para revisar entre artefactos. Limita los intentos de reparación e inspecciona la salida real de las pruebas antes de aceptar la convergencia.

Verifica tu trabajo

• MOD-1: la caracterización original sigue pasando.
• MOD-2: coinciden el recuento 3, el total 6249, el orden y la versión 1 del esquema.
• MOD-3: las entradas mal formadas o duplicadas devuelven un código distinto de cero y no dejan un destino parcial considerado exitoso.
• MOD-4: las ejecuciones repetidas conservan cualquier destino existente byte por byte.
• MOD-5: leer una base de datos ausente no la crea.
• MOD-6: la alternativa CSV y el hash de origen no cambian.
• No se añadió ninguna función de negocio, dato real de clientes ni infraestructura en la nube.

Adaptaciones a otras pilas

Las alternativas son diseños guiados, no afirmaciones de ejecución. Compara las diferencias de API, transacciones, errores y empaquetado antes de implementar. No selecciones un framework nuevo solo porque un asistente pueda generarlo.

Solución de problemas

Si los resultados solo coinciden después de ordenar un lado de otra forma, puede que hayas cambiado el contrato. Si una fila no válida deja una base de datos parcial, inspecciona la validación y la limpieza. Si una lectura de un destino ausente crea un archivo, revisa el modo de conexión. Si las pruebas solo fallan al repetirse, inspecciona el punto de control de no sobrescritura en lugar de eliminar el destino existente.

Práctica independiente

Propón un cambio de esquema v2 que añada una columna que admita null mientras un lector anterior siga activo. Define la negociación de versiones, la compatibilidad hacia delante y hacia atrás, la idempotencia de la migración, la reversión y los criterios de retirada antes de programar.

Restablecimiento

Detén únicamente el proceso de CLI que iniciaste. Guarda los hashes y la salida y después elimina solo el orders.db generado en la copia desechable tras inspeccionar su ruta. Restaura migrate.py y order_store.py desde la línea base local o prepara una copia nueva. Nunca sobrescribas data/orders.csv como técnica de restablecimiento.

Referencias oficiales

• Spec Kit v1.0.4
• Referencia de integración de Spec Kit
• SQLite en .NET
• sqlite3 de Python