Argo Fulfillment Callbacks — E2E Handoff 보드

henriette checkout_fa985857ca4d (세피라샷, qty=2, 오늘출발) 으로 풀루프 검증 완료. PAID → PROCESSING → SHIPPED → DELIVERED 자동 전이 + Argo 분리포장 발생까지 실증.

검증 결과 (체인 전체)

단계	트리거 / 신호	MAKITT 상태
1	POST /manual-payment/checkout_fa985857ca4d	Order PAID + FO PENDING + Outbox OrderPaid PUBLISHED + Argo OMS CO0000000365517 생성 + wms-outbound SH0000000172835 INIT
2	wms-outbound-order-state-changed (INIT/OUTBOUND_CREATED/READY_TO_PICK ...)	PartnerOutbound INSERT + state_history 누적 (10단계), ArgoOutboundStateChanged publish, ArgoOutboundStateChangedHandler 가 FO PENDING→PROCESSING + Order PAID→PROCESSING
3	argo-outbound-complete (SH0000000172835 OUTBOUND_COMPLETED)	ArgoOutboundCompletedHandler 가 Shipment INSERT (shp_91e81f953b71, SHIPPED 직행), partnerExternalIds.argoShipmentId=SH... 박힘, FulfillmentLineItem.shippedQuantity 누적, FO SHIPPED, propagateToOrder allShipped → Order SHIPPED
4	oms-common-shipment-tracking DELIVERY_COMPLETED (kcat produce)	PartnerShipmentEvent INSERT, ArgoShipmentTracking publish, ArgoShipmentTrackingHandler 가 Shipment markDelivered → propagateDeliveryStatus → FO COMPLETED → Order DELIVERED

shop-api OrderDetail 최종 payload 검증 (cust_81ffefc884c4)

• Order.status = DELIVERED (description "배송 완료")
• availableActions = [REQUEST_RETURN, REQUEST_EXCHANGE, REVIEW, REORDER]
• FulfillmentOrder.status = COMPLETED, lineItems[0].shippedQuantity = 2
• Shipment.status = DELIVERED, shippedAt + deliveredAt 채움, items[0].lineItemId 매핑 정상

#	증상	원인	Fix
F1	OutboundOrderStateChangeMessage.eventAt deserialize MismatchedInputException	Argo LocalDateTimeSerializer 가 epoch ms (long) 으로 직렬화, 우리 mirror 가 LocalDateTime 로 받음	Long 으로 변경 + Instant.ofEpochMilli
F2	Toggle 차단 시 handler 침묵	ConsumerToggleService.shouldProcess()=false 시 ack 만 하고 빠짐, 디버깅 1시간 손실	handler 3종 진입 직후 log.debug("toggle skip. active={}") 추가
F3	Redis consumer:active raw 값을 redis-cli 로 SET 시 Kryo deserialize 실패	redisson 이 RBucket Kryo codec 사용	/api/v1/admin/redis 통해 SET (dev token 발급 후 Bearer)
F4	Shipment.trackingCarrier/trackingUrl null 노출	Argo RouteDto 실 필드명이 deliveryCompany/routeType 인데 우리 mirror 가 deliveryCompanyCode/routeTypeCode 로 잘못 박음 → Jackson deserialize 시 routeInfo 의 모든 필드 null	OutboundCompleteMessage.RouteDto 필드명 정정 + getDeliveryCompany() 사용
F5	Argo dev 환경에서 routeInfo 자체가 null 들어올 수 있음	distribution 의 outbound_order_route 가 비어있는 케이스	ArgoOutboundCompletedHandler 가 PartnerOutbound (state-changed 메시지로 누적된) 의 deliveryCompanyCode 로 fallback
F6	Argo 분리포장(SPLIT) 시 두 번째 SH 가 ShipmentItem 빌드 실패 ("no shipment items resolved")	buildShipmentItems 의 "line item 1개" short-circuit 이 첫 SH 가 remainingQuantity 전체를 흡수해버려 두 번째 SH 도착 시 0	short-circuit 제거. 항상 PartnerOutbound.skus 의 실 출고 quantity 우선. PartnerSku 역조회 + BOM skuId 매칭
F7	FulfillmentSummaryDto.estimatedShipDate 항상 null	PDD/EXSD 매핑 누락	ArgoShipmentTrackingConsumer 가 raw 적재 시점에 originalOrderId (=foId) + pdd 로 FO.estimatedShipDate 갱신 (best-effort)
F8	OrderDelivered 셀러 알림 룰 불가능	EventCatalog 미등록 + publish 안 함	OrderDeliveredPayload 신설 + OrderStateApplication.deliver 가 publish + EventCatalog 등록

makitt-server

• OutboundCompleteMessage.RouteDto — Argo 실 필드명 정정 (deliveryCompany/routeType/routeCode/subRouteCode/deliveryCenter/regionCode/deliveryAccountCode)
• OutboundOrderStateChangeMessage.eventAt — LocalDateTime → Long (epoch ms)
• ArgoOutboundCompletedHandler — PartnerOutbound deliveryCompanyCode/shippingLabel fallback + multi-line BOM 정밀 매핑 (indexLineItemsByBomSkuId) + line item 개수 무관 PartnerOutbound.skus 실 quantity 우선
• ArgoShipmentTrackingConsumer — FulfillmentOrderService 의존성 추가 + PDD → FO.estimatedShipDate 갱신
• handler 3종 — toggle skip debug 로그
• OrderStateApplication.deliver — publishOrderDelivered
• OrderDeliveredPayload.java 신설 + EventCatalog OrderDelivered 항목 추가
• FulfillmentSummaryDto.estimatedShipDate Schema description 보강 ("배달 약속일 (PDD)")

argo-test skill (~/.codex/skills/argo-test/SKILL.md)

• run-order 의 S11 에 SPLIT 자동 감지 + 미완료 SH 처리 가이드 추가
• 신규 Action complete-outbound <SH> — 단일 SH (READY_TO_PACK/PACKING/PACKED) 를 outbound-complete 까지 한 번에
• 알려진 함정에 SPLIT 항목 추가

makitt-server 의 모든 변경사항 + argo-test SKILL.md 변경사항이 미커밋 상태. 다음 사이클 시작 전 commit + push 권장.

README.md 의 "향후 확장" + 본 검증의 Inbox 잔재:

1. Argo cancel/refund outbound path — MAKITT 이 OrderCancelled 이벤트를 makitt-order-event 로 발행 → Argo OMS consume + cancel 처리. PG 환불 (PayPal/NaverPay/Toss/Stripe) 별도 path. 사용자 별도 세션에서 진행 예정.
2. commerce_platforms / LinkedSalesChannelInfo.mallId 자동 sync — 사용자 별도 세션 진행 예정.
3. F6 정밀 매핑 회귀 검증 — 이번 사이클에서 short-circuit fix 후 새 multi-shipment 결제로 첫 SH=PARTIALLY_SHIPPED, 두 번째 SH=SHIPPED 단계 확인 필요. 다음 multi-shipment 결제 시.
4. PartnerOutbound.partner_raw 의 skus null 직렬화 — Jackson type info 누락. 디버깅용 raw 라 도메인 영향 0, 후순위.
5. ArgoXxx platform event 셀러 카탈로그 노출 검토 — 운영 데이터 쌓이고 셀러 요구 시.
6. DELIVERY_FAILED 이후 재배송/반송 분기 — 운영 데이터 의존.
7. IN_TRANSIT/OUT_FOR_DELIVERY 등 중간 trackingStatusCode — Argo 측이 정형화 메시지로 발행하는 책임. MAKITT 은 raw 핸들링 안 함 (정책 확정).

항목	값
checkout	checkout_fa985857ca4d
order	order_dff986938b62 (ORD-20260501-AB08)
customer	cust_81ffefc884c4 (test@henriette.world)
FO	fo_b74c5e66f81c (오늘출발 ARGO-376-SHIPPING_SAMEDAY)
Argo OMS	CO0000000365517 (vendor 900938, channel 11200)
outbound (origin)	SH0000000172835 (PACKED → OUTBOUND_COMPLETED)
outbound (split)	SH0000000172836 (별도 SH, 별도 outbound-complete 처리)
Shipment (MAKITT)	shp_91e81f953b71 (SHIPPED → DELIVERED, label TEST-LABEL-SH0000000172835)
PartnerOutbound	2건 (SH172835/SH172836), state_history 10/3단계 누적
PartnerShipmentEvent	DELIVERY_COMPLETED row 1건