Saltar a contenido

Solo puente entre código y modelo

Este archivo traduce enums del código a los nombres canónicos. La UI nunca debe mostrar nombres en MAYUSCULAS_CON_GUIONES_BAJOS ni en español en CamelCase: siempre pasa por la capa PackageStatusPresentation con etiqueta humana y siguiente acción.

Equivalencias de estados (legacy → oficial)

Documento de normalización — 2026-06-07 (revisado)

Este documento lista los nombres de estado que aparecen en código, diagramas, tablas o copias viejas de la documentación, y los mapea al nombre oficial definido en estados.md.

Regla: el nombre oficial es la única verdad. Los nombres listados aquí son legacy y deben migrarse a los oficiales en próximas iteraciones.

Verificación 2026-06-07: el código Kotlin usa MAYÚSCULAS_CON_GUIONES_BAJOS; la doc oficial usa snake_case en español. La migración a nombres oficiales es T-405 (abierta).

Por qué existe este documento

Durante la auditoría del 2026-06-07 se detectaron estados con nombres no oficiales dispersos por:

  • Códigos Kotlin (enums) en la APK.
  • Diagramas UML de estado.
  • Tablas Markdown de varios documentos.
  • Diagramas de secuencia.
  • Capturas de texto en srs.md, integraciones.md, reglas-negocio.md.

Estos nombres rompen la trazabilidad entre la doc funcional, el código y los diagramas.

Estados de prealerta (compra reportada)

Estado oficial Estados legacy encontrados Notas
borrador DRAFT Disponible en PurchaseReportStatus.
reportada REPORTADA Disponible en PurchaseReportStatus.
reportada_sin_tracking REPORTADA_SIN_TRACKING Disponible y usado por la prealerta demo.
tracking_actualizado TRACKING_ACTUALIZADO Disponible en PurchaseReportStatus.
vinculada_a_paquete VINCULADA_A_PAQUETE Disponible en PurchaseReportStatus.
requiere_correccion REQUIERE_CORRECCION Disponible en PurchaseReportStatus.
cancelada_por_usuario CANCELADA_POR_USUARIO Disponible en PurchaseReportStatus.
cancelada_por_operador CANCELADA_POR_OPERADOR Disponible en PurchaseReportStatus.

Estados del paquete físico

Estado oficial Estados legacy encontrados Notas
prealertado PREALERTADO, PENDIENTE_RECEPCION La capa de presentación traduce ambos; retirar el alias legacy en una iteración posterior.
recibido_sin_identificar RECIBIDO_SIN_IDENTIFICAR Disponible.
recibido_identificado RECIBIDO_IDENTIFICADO Disponible.
en_servicio_adicional EN_SERVICIO_ADICIONAL Disponible.
listo_para_consolidar LISTO_PARA_CONSOLIDAR, LISTO_PARA_ENVIAR LISTO_PARA_ENVIAR es alias legacy presentado como listo para agrupar.
consolidado CONSOLIDADO Disponible.
en_almacen EN_ALMACEN Disponible.
esperando_instrucciones ESPERANDO_INSTRUCCIONES Disponible.
pendiente_conciliacion PENDIENTE_CONCILIACION Disponible.
reservado_para_consolidacion RESERVADO_PARA_CONSOLIDACION Disponible.
en_camino_al_almacen — Aún falta como enum explícito.
en_transito DESPACHADO Alias legacy mostrado como "En camino a Cuba"; debe separarse de envío.
entregado — Aún falta como estado físico explícito.
retenido_por_incidencia INCIDENCIA Alias legacy mostrado con texto canónico.
devuelto_a_tienda DEVUELTO_A_TIENDA Disponible.
descartado_o_cerrado DESCARTADO_O_CERRADO Disponible.

Nota: el estado DESPACHADO en código Kotlin se usa para "el paquete ya salió del almacén", que es despachado_desde_almacen en el modelo de envío (shipment), no del paquete físico. Hay que distinguir las dos entidades.

Estados del envío (shipment)

Estado oficial Estados legacy encontrados Notas
borrador — Coincide ✅
pendiente_kyc — Coincide ✅
pendiente_destinatario — Coincide ✅
pendiente_cotizacion — Coincide ✅
cotizado — Coincide ✅
pendiente_pago — Coincide ✅
pagado procesando (en srs.md:622, seq-pago.md) Renombrar en docs
en_preparacion — Coincide ✅
despachado_desde_almacen despachado (en narrativa) Usar nombre oficial
en_transito_a_cuba — Coincide ✅
en_aduana — Coincide ✅
liberado_de_aduana — Coincide ✅
en_reparto — Coincide ✅
entregado — Coincide ✅
incidencia — Coincide ✅
cancelado — Coincide ✅

Estados del pago

Estado oficial Estados legacy encontrados Notas
pendiente pending, processing, procesando Renombrar en código y docs
pago_reportado REPORTED, PAYMENT_REPORTED Comprobante manual informado y pendiente de validación.
completado completed Renombrar en código
fallido failed Renombrar en código
reembolsado refunded Renombrar en código
parcial — Solo composición vía payment_method_mix

Acción concreta: la entidad payments en modelo-datos.md línea 397 define el enum como pending/processing/completed/failed/refunded. Debe cambiarse a los nombres oficiales en español.

Estados del KYC

Estado oficial Estados legacy encontrados Notas
sin_iniciar — Coincide ✅
borrador — Coincide ✅
enviado — Coincide ✅
en_revision — Coincide ✅
aprobado — Coincide ✅
rechazado — Coincide ✅
requiere_mas_informacion — Coincide ✅
vencido — Coincide ✅
bloqueado_manual — Coincide ✅

Estados de incidencias

Estado oficial Estados legacy encontrados Notas
abierta open Renombrar en incidents.status
en_revision in_review Renombrar
esperando_usuario waiting_user Renombrar
esperando_operador waiting_operator Renombrar
resuelta resolved Renombrar
cerrada closed Renombrar

Cómo aplicar estas equivalencias

  1. En código Kotlin: usar el rename de IntelliJ para cada enum (PENDIENTE_TRACKING → REPORTADA_SIN_TRACKING, etc.). Actualizar todos los when y los FakeDataSource mockeados.
  2. En diagramas: regenerar los .puml con los nombres oficiales.
  3. En docs: aplicar búsqueda y reemplazo con la tabla de arriba.
  4. En integraciones.md: la fila returned | en_devolucion debe renombrarse a returned | devuelto_a_tienda o el estado equivalente que aplique al transportista.

Trazabilidad: la tarea T-405 (en tareas.md) cubre la mayoría de estas migraciones. Esta tabla es la especificación detallada de qué cambiar.