US-041 — Carga inicial de datos

Detalle de la historia¶

Historia¶

Como administrador de FleteChat al arrancar el sistema, quiero cargar los datos iniciales del negocio (unidades de medida, factores de conversión, parámetros de servicio, lista de precios base) ejecutando scripts que leen los formatos Excel de levantamiento L1–L6, para dejar el sistema operativo para salir a producción sin depender de una interfaz de gestión que queda fuera del alcance del MVP.

Persona de usuario¶

Aplica al administrador técnico de FleteChat (rol admin con acceso a ejecución de scripts). No aplica al operador ni al price_manager: en v1.0 la carga inicial es una operación técnica puntual que se ejecuta antes del go-live o ante re-levantamientos de datos.

Contexto de negocio¶

El sistema necesita datos maestros para funcionar: qué unidades de medida acepta, cómo convierte kg a lb, qué parámetros tiene cada servicio, cuál es la lista de precios base. El SOW §2.6 excluye explícitamente una UI de gestión para estos catálogos en el MVP: se prevé para una fase posterior. La alternativa práctica en v1.0 es cargar los datos desde los formatos Excel L1–L6 que el equipo comercial ya utiliza para levantar información; scripts idempotentes leen los archivos, validan y persisten.

El enfoque resuelve un trade-off: construir UI de gestión para cada catálogo en v1.0 duplicaría el esfuerzo (UI + validaciones + audit log) sin valor operativo hasta después del go-live. Cargar por script deja el sistema listo para operar; si el negocio necesita ajustar un dato maestro en v1.0, se re-ejecuta el script con un Excel actualizado. La UI de gestión llega en una fase posterior.

Criterios de aceptación¶

Alcance de los scripts¶

1. FleteChat entrega un script por cada archivo de levantamiento (L1 a L6), cada uno responsable de un dominio específico (unidades de medida, factores de conversión, parámetros de servicio, lista de precios base, y los demás levantamientos según documentación del proyecto).
2. Cada script acepta el archivo Excel de entrada como parámetro y una opción --dry-run que muestra el resumen de cambios (altas, modificaciones, filas con error) sin tocar la base de datos.
3. Sin --dry-run, el script aplica los cambios en la base y deja un reporte con las filas procesadas, las ignoradas y los errores encontrados.

Validación e integridad¶

1. Antes de persistir, cada script valida la integridad referencial del archivo: claves foráneas existentes, formatos numéricos válidos, referencias entre hojas dentro del Excel.
2. Filas con errores se reportan fila por fila y no abortan el resto: el script procesa lo válido y deja un log de lo inválido para que el admin corrija el Excel y re-ejecute.
3. Los scripts son idempotentes (ver PR-168): re-ejecutar con el mismo archivo no duplica registros. Se identifica cada fila por una clave natural del negocio (nombre de servicio, código de unidad, combinación de ruta, etc.), documentada en el script.

No hay UI de gestión en MVP¶

1. La historia no incluye UI en el backoffice para gestionar estos datos. Cualquier ajuste posterior al go-live requiere editar el Excel correspondiente y re-ejecutar el script (ver PR-167). Esto está alineado con el SOW §2.6 y se prevé UI en una fase posterior.

Audit log¶

1. Cada ejecución del script queda registrada en el audit log con actor, script, archivo procesado, timestamp, resumen (filas leídas, insertadas, actualizadas, rechazadas) y ruta al log detallado generado.

Edge cases¶

• Excel con layout distinto al esperado (columnas renombradas, hojas en otro orden). El script detecta el desajuste al cargar, reporta el problema y aborta sin tocar la base (ver PR-169 sobre layout estable).
• Excel con datos inconsistentes entre hojas (una ruta referencia un origen que no existe en la hoja de orígenes). Las filas inválidas se rechazan con mensaje descriptivo; las válidas se procesan.
• Re-ejecución con un Excel al que se le agregaron filas nuevas y se corrigieron existentes. Las filas nuevas se insertan, las existentes se actualizan según clave natural, las no presentes en el archivo no se eliminan (el script no borra): si el admin quiere eliminar, lo hace explícitamente (script dedicado o intervención técnica).
• Script falla a mitad de ejecución (caída del proceso, timeout de DB). El script deja un log del punto de corte; re-ejecutar retoma procesamiento desde ese punto gracias a la idempotencia.
• Cambios post-go-live de parámetros maestros (por ejemplo, un factor de conversión ajustado). El admin actualiza el Excel correspondiente y re-ejecuta el script. No hay UI para "edición en caliente" en v1.0.

Tamaño, prioridad y tipo¶

• Tamaño: S
• Prioridad: P0 — sin carga inicial el sistema no tiene catálogos para operar.
• Tipo: chore

Premisas¶

La historia está redactada bajo las siguientes premisas. Si alguna cambia, la historia debe revisarse y ajustarse en consecuencia. Todas deben ser confirmadas por el cliente antes de cerrar la historia.

• PR-167 — Sin UI de gestión en v1.0. La carga y posterior mantenimiento de datos maestros (L1–L6) se hace exclusivamente por scripts. El SOW §2.6 excluye la UI de gestión del alcance del MVP; se prevé para una fase posterior al go-live.
• PR-168 — Idempotencia de la carga. Los scripts son idempotentes: re-ejecutar con el mismo Excel no genera duplicados. Cada fila se identifica por una clave natural del negocio documentada en el script.
• PR-169 — Layout estable de los archivos L1–L6. Los archivos L1–L6 mantienen el layout documentado (nombres de hojas, columnas, tipos). Cambios de layout no son transparentes: requieren adaptar el script correspondiente antes de re-ejecutar.

Refinamiento y Definition of Ready¶

Notas¶

Checklist¶

• ✅ Historia escrita en formato Como / Quiero / Para
• ✅ Persona de usuario identificada
• ✅ Contexto de negocio documentado
• ✅ Criterios de aceptación observables y pass/fail
• ✅ Edge cases relevantes listados
• ✅ Tamaño y prioridad asignados
• ⬜ Premisas PR-167 a PR-169 confirmadas por el cliente
• ⬜ Reglas de negocio aplicables aprobadas
• ⬜ Requerimientos funcionales aplicables aprobados
• ⬜ Historia aprobada formalmente por el cliente