feat: [TESIS-141] open the shipment of an order from its detail

[TomasMartin2004]

Descripción

Una orden que no entró por el asistente de alta manual no tenía forma de llegar al circuito logístico desde la app.

El envío lo abría un solo lugar: el paso 3 del alta manual, donde useConfirmDraftOrder encadena createOrder → createOrderShipment → dispatchShipment. Su propio comentario lo decía: «sin envío, este paso sigue siendo el único lugar que lo abre». Toda orden que entra por webhook nace sin envío, y el detalle mostraba «La orden todavía no tiene un envío creado.» sin ninguna acción al lado.

Son todas las ventas de canal, que es justamente lo que el OMS existe para resolver. Contra la base de desarrollo:

#6  manual   paid       envio=ready_to_ship
#7  webhook  pending    envio=pending      ← se lo pone db/seeds.rb, no la app
#8  webhook  cancelled  envio=NINGUNO
#11 webhook  paid       envio=NINGUNO      ← la venta real de Shopify

La orden #11 entró por el webhook de Shopify (TESIS-138), está pagada, con el stock descontado, y no se puede despachar desde ninguna pantalla.

Qué hace

El detalle de la orden ofrece «Crear envío» en la tarjeta del ciclo de vida, en el mismo lugar donde aparece «Despachar». Llama a POST /orders/:order_id/shipment (TESIS-105) con createOrderShipment, que ya existía en api.ts y hasta ahora sólo usaba el asistente. Al resolver se invalida el dominio de órdenes: la tarjeta pasa a mostrar el envío pending y con él aparece «Despachar» (TESIS-134).

Decisiones que conviene mirar

Las dos acciones quedan separadas, no encadenadas. El asistente las encadena porque ahí la persona ya eligió courier en el mismo paso; acá abrir el circuito y elegir operador son decisiones distintas, y encadenarlas obligaría a cotizar a quien sólo quiere dejar la orden lista. Lo que sigue a crear el envío es que aparezca el botón de despachar.

La regla va en utils/dispatch.ts, al lado de dispatchableShipment. canOpenShipment aplica la misma exclusión que el backend (Shipments::CreateShipment::NON_SHIPPABLE_STATUSES: canceladas y nada más). Y se niega también mientras la consulta del envío carga o falla: que el envío no exista tiene que ser un hecho y no una duda, porque ofrecerlo sobre un envío que no se pudo leer invita a un 409.

El 409 no se reintenta. Significa que el envío ya existe —el asistente, u otra pestaña—, así que la mutación invalida en onSettled y la pantalla avisa que el envío ya estaba en vez de insistir. Mismo criterio que useDispatchShipment con su 409.

El id se captura fuera del callback (loadedOrderId). El angostado de los returns tempranos no alcanza adentro de una función, que TypeScript no sabe cuándo se llama; tsc -b lo marcaba.

Por qué faltaba (para el contexto de la review)

Está documentado, no fue un olvido:

• TESIS-105 planteó la decisión de si el envío se crea solo al pasar la orden a paid (opción A, que nombraba Orders::ProcessWebhookOrder) o con una acción explícita (opción B). Se eligió B, y la propia card escribió su contra: «una orden pagada puede quedarse sin envío por olvido».
• TESIS-134 llevó el despacho al detalle con encuadre de recuperación del wizard: su condición es «si la orden tiene envío pending». Al descartar su alternativa B dice «no sirve para órdenes que no entraron por el asistente» — nombra la categoría y después queda afuera del alcance.
• TESIS-105 no tenía card hermana de front. TESIS-46 la tuvo (TESIS-59) y TESIS-47 la tuvo (TESIS-134).
• Los seeds tapaban el síntoma: db/seeds.rb crea a mano el envío pending de la orden de webhook de ejemplo, así que en desarrollo esa orden siempre apareció con envío.

Cómo probar

1. npm run dev, entrar como admin@norte.com.
2. Órdenes → la orden de Shopify (feat: [TESIS-71] semantic status components (StatusBadge, StatusSelect) #11). La tarjeta del envío dice que no tiene uno y ahora ofrece «Crear envío».
3. Clic: la tarjeta pasa a mostrar el envío pending y aparece «Despachar».
4. Despachar: cotiza, se elige operador y la orden sale con su número de seguimiento.
5. Una orden cancelada (docs: [TESIS-50] add CLAUDE.md with project guidelines and architecture #8) no ofrece ninguna de las dos acciones.

Verificación

• npm run lint ✅
• npm run test ✅ — 75 archivos, 698 tests (+15 sobre master, que tiene 683)
• npm run build ✅ (tsc -b incluido)
• npm run format:check ✅

Tests nuevos: canOpenShipment (6 ejemplos, incluidos los tres estados en los que el envío es una duda), el flujo en OrderDetailPage (9: se ofrece, con qué orden, el éxito, el 409, el error, el estado «Creando…», la orden cancelada, la precedencia del despacho y la consulta sin resolver) y useCreateOrderShipment (3).

No toqué la orden #11: la dejé sin envío para que la pruebes vos desde el navegador, que es el criterio de aceptación que falta marcar.

Fuera de alcance

• Crear el envío automáticamente al ingresar la venta (opción A de TESIS-105). Si se quiere revisar esa decisión, es otra card y toca el backend.
• Listado de envíos: GET /shipments existe desde TESIS-113 y no tiene pantalla.
• Mostrar la etiqueta: el backend guarda shipping_label_url y el front no lo lee en ningún lado.

🤖 Generated with Claude Code

https://claude.ai/code/session_012xAtddb53LRNVLuyTXyELp

[Sanntinat]

Revisión — TESIS-141 (PR #77) · Crear el envío de una orden desde su detalle

Revisión de TESIS-141-create-shipment-from-order-detail (082abc0), contra origin/master de proyecto-web. La hice junto con #76 y #78, y los tres los probé también mergeados entre sí.

Check	Resultado
CI (GitHub Actions)	Los cuatro jobs en verde
Rama vs master	Al día. Mergea limpio
Local, la rama sola	lint, prettier y tsc -b limpios · 75 archivos · 700 tests · 0 fallas
Local, #76 + #77 + #78 mergeados	lint, prettier, tsc -b y build limpios · 75 archivos · 705 tests · 0 fallas
Navegador	El circuito completo con una orden de canal, contra la API de master. Detalle abajo
Conflictos con otros PRs	#78 (sólo architecture.md, mecánico), #65 y #68 (OrderDetailPage.tsx, su test y architecture.md)

✅ El circuito de canal anda de punta a punta

No tengo la orden #11 de Shopify de tu base, así que armé el mismo caso en una base de verificación: una orden de Norte paid, con external_order_id, una línea con depósito y sin envío, como la que deja el webhook.

1. El detalle muestra «La orden todavía no tiene un envío creado.» y, al lado, «Crear envío».
2. Al crear, aparece el aviso «Envío creado. Ya se puede despachar.». La tarjeta pasa a mostrar las cuatro etapas con «Pendiente», el encabezado a PENDIENTE, y el botón pasa a ser «Despachar».
3. «Despachar» abre el diálogo con el depósito de las líneas (Depósito Central) y la cotización de Andreani. Al confirmar sale el seguimiento AND-REVIEW-1.
4. Controles: la orden cancelada (#8, sin envío) no ofrece ninguna de las dos acciones. Una en tránsito (#1) tampoco.

✅ Las decisiones están bien tomadas

• Separar crear de despachar es lo correcto. En el asistente se encadenan porque ahí el courier ya está elegido; acá encadenarlos obligaría a cotizar a quien sólo quiere dejar la orden lista.
• canOpenShipment no ofrece la acción mientras el envío carga o falla, y lo dice: un envío que no se pudo leer no es un envío que no existe.
• Invalidar en onSettled para que un 409 traiga el envío que ya estaba, con un aviso propio en vez del error.

✅ Los specs tienen dientes

Rompí cada regla de a una y corrí features/orders:

Rotura	Falla
Ofrecer «Crear envío» en una orden cancelada	refuses a cancelled order, does not offer it for a cancelled order
Ofrecerlo mientras la consulta del envío carga o falla	refuses while the shipment is unknown, does not offer it while the shipment query has not resolved
Tratar el 409 como un error común	says the shipment was already there when the api answers 409
Invalidar sólo en onSuccess	refreshes the shipment also when the order already had one

🔴 El paso 3 del alta sigue diciendo que ninguna otra pantalla puede abrir el envío

Este PR cierra justamente el hueco que la card cita como prueba: el comentario de useConfirmDraftOrder que decía «sin envío, este paso sigue siendo el único lugar que lo abre». Pero no toca lo que se apoyaba en eso, y después del merge quedan cuatro cosas que dicen o hacen lo contrario de lo que este PR vuelve verdad:

• Lo que ve el operador. Si en el paso 3 falla la apertura del envío, el error dice: «Reintentalo antes de salir: la orden ya descontó el stock y todavía no tiene envío, y ninguna otra pantalla lo puede abrir.» (content.ts, carrier.errors.shipmentMissing). Ahora el detalle de la orden lo abre.
• Lo que hace el navegador. CarrierStepPage llama a useLeaveWarning(shipmentMissing), que pregunta antes de recargar o cerrar la pestaña. Ese aviso existía sólo porque no había otra salida, y ahora retiene al operador sin motivo.
• El comentario de useConfirmDraftOrder.ts:36, y la fila de hooks/useConfirmDraftOrder.ts en architecture.md («el paso 3 es el único lugar que lo abre»).
• Los tests de CarrierStepPage.test.tsx (líneas 370 y 388), que fijan ese texto y ese aviso.

El arreglo es chico, y lo propongo porque esos textos los escribí yo en TESIS-134: con #77, los dos casos de falla del paso 3 pasan a tener la misma salida. Alcanza con un solo mensaje que remita al detalle (el actual dispatchLater sirve casi tal cual), sacar useLeaveWarning y shipmentMissing, y ajustar el comentario, la fila del doc y esos tests. createdShipmentId en useConfirmDraftOrder puede quedar o irse; si nada lo lee después del cambio, mejor sacarlo.

⚪ La cuenta de tests del cuerpo del PR

Dice «700 tests (+22)». master tiene 683, así que son +17 (es lo que da el diff: 17 it nuevos y ninguno borrado). Los 700 están bien; el +22 parece medido contra los 678 de #76.

Los criterios de la card

• Una orden sin envío y no cancelada muestra «Crear envío».
• Una orden cancelada no lo muestra.
• Una orden con envío no lo muestra: «Despachar» si está pending, nada si ya salió.
• Después de crear, la tarjeta muestra el envío pending y ofrece «Despachar».
• Una orden de canal se puede crear envío y despachar de punta a punta. Lo verifiqué con una orden equivalente en una base de verificación; con la #11 real de tu base todavía falta.
• lint, test y build en verde.

Veredicto

REQUEST CHANGES, sólo por el 🔴.

El feature está bien hecho y probado, y en el navegador anda de punta a punta. Pero deja al paso 3 diciéndole al operador algo que este mismo PR vuelve falso, y frenándolo antes de salir sin necesidad. Corregido eso, lo apruebo.

[TomasMartin2004]

Corregido en c64afd1. El 🔴 era correcto, y lo verifiqué uno por uno contra master antes de tocar nada: el texto de content.ts:367, el useLeaveWarning(shipmentMissing) de CarrierStepPage.tsx:92-94, el comentario de useConfirmDraftOrder.ts:36, la fila 337 de architecture.md y los dos tests. Las cinco cosas decían lo que este PR vuelve falso.

De las dos, la que más me molestaba después de leerte es la segunda: el aviso del navegador no era un texto desactualizado, era retener al operador en una pantalla que ya tiene salida.

Qué hice

• Un solo mensaje para las dos fallas que dejan la orden creada. Usé dispatchLater como propusiste, cambiándole «despachar» por «terminar el envío desde el detalle de la orden»: el detalle ahora hace las dos cosas, abrirlo y despacharlo, y «despachar» se quedaba corto para el caso en que no hay envío todavía.
• Se van shipmentMissing, useLeaveWarning y el useEffect que lo sostenía.
• Se va createdShipmentId. Tenías razón en que quedaba sin consumidores: lo leían sólo las líneas 93 y 139 de CarrierStepPage, las dos para distinguir los casos que ahora son uno. progress.current.shipmentId sigue adentro del hook, que es lo que hace que el reintento retome en vez de crear una segunda venta.
• Comentario del hook y fila del doc reescritos.

Los tests

El del hook se llamaba tells the page whether the shipment was opened before the dispatch failed y afirmaba sobre el estado que se borró. Lo que probaba de fondo sigue importando, así que quedó como retries the shipment it could not open without creating the order twice, afirmando sobre las llamadas: createShipment dos veces, createOrder una.

En la página, los tres del bloque when the shipment could not even be opened pasan a dos: que el error remite al detalle igual que una falla de despacho, y que el reintento abre el envío sin volver a crear la orden. leaveIsBlocked se fue entero, y con él el does not ask before reloading or closing the tab del bloque de despacho: sin ningún listener registrado, afirmar que el navegador no pregunta ya no prueba nada.

Les pasé los dientes:

Rotura	Falla
El reintento vuelve a crear la orden	retries from where it failed, without creating the order again, retries the shipment it could not open without creating the order twice, retries only the dispatch, opens the shipment on the retry, without creating the order again
El error deja de remitir al detalle	points to the order detail, where the shipment can be dispatched later, points at the order detail, the same way a failed dispatch does, opens the shipment on the retry, without creating the order again

Sobre el ⚪: tenés razón, master tiene 683 y medí contra los 678 de antes de #76. Corregí el cuerpo de este PR y el de #78. La cuenta ahora: 698 tests, que son +15 sobre master — este commit saca tres ejemplos y suma uno.

lint, format:check, tsc -b, test y build en verde.

Gracias por la review: encontraste lo único que el PR dejaba inconsistente, y el arreglo terminó restando más de lo que suma.

[Sanntinat]

Re-revisión — TESIS-141 (PR #77) · Crear el envío de una orden desde su detalle

Segunda vuelta sobre TESIS-141-create-shipment-from-order-detail. La primera la hice sobre 082abc0 con REQUEST CHANGES. Desde entonces entró un commit, c64afd1.

Check	Resultado
CI (GitHub Actions)	Los cuatro jobs en verde
Rama vs master	5 commits atrás (#63, #60, #62, #73, #72). Mergea limpio
Sobre el merge con master (local)	lint, prettier y tsc -b limpios · 81 archivos · 737 tests · 0 fallas

✅ El 🔴 está resuelto, y el arreglo resta más de lo que suma

c64afd1 hace lo que pedí, y en un punto mejor que como lo propuse:

• Un solo mensaje para las dos fallas que dejan la orden creada. Cambiar «despachar el envío» por «terminar el envío desde el detalle de la orden» es más preciso que mi propuesta: el detalle ahora lo abre y lo despacha, y «despachar» se quedaba corto para la orden sin envío.
• Se van useLeaveWarning, shipmentMissing y createdShipmentId. El reintento sigue retomando desde donde quedó, porque progress.current.shipmentId vive adentro del hook.
• Los tests se reescribieron sobre el comportamiento y no sobre el estado borrado: el del hook ahora cuenta llamadas (createOrderShipment dos veces, createOrder una). Sacar leaveIsBlocked también es correcto: sin ningún listener registrado, afirmar que el navegador no pregunta no prueba nada.

El diente que declarás, probado de nuevo. Saqué el mensaje del error en CarrierStepPage y fallaron exactamente los tres de tu tabla: points to the order detail, where the shipment can be dispatched later, points at the order detail, the same way a failed dispatch does y opens the shipment on the retry, without creating the order again.

🟡 El comentario de cabecera de CarrierStepPage todavía cuenta lo de antes

Líneas 59-62 de CarrierStepPage.tsx:

Si ni siquiera se abrió el envío, esta pantalla es el único lugar que lo abre: el error lo dice y el navegador pregunta antes de recargar o cerrar la pestaña.

Es el único resto que queda: las tres afirmaciones son ahora falsas, y está en el mismo archivo que el commit tocó. Es un comentario y no lo que ve el operador, así que no bloquea; alcanza con decir que, con la orden creada, el error remite al detalle en los dos casos.

Los criterios de la card

Siguen cumplidos como en la primera vuelta. Allí verifiqué en el navegador el circuito completo con una orden de canal: «Crear envío», «Despachar», el seguimiento y la etiqueta. Este commit no toca el detalle.

Veredicto

APPROVE.

El punto que bloqueaba está resuelto, y bien. El comentario de cabecera conviene corregirlo antes de mergear, pero no hace falta otra vuelta de review para eso.