FE: module shipment — vận đơn, thu hộ (COD) #

Phần chung (khởi tạo client, lỗi, danh sách, ngôn ngữ) ở tài liệu FE của Core: docs/fe/common.md (bản đọc: xforge-documentation, ADR-0102 của xforge-core). Sửa file này CÙNG PR khi đổi hành vi FE thấy được của module.

Một đơn (module order) có tối đa 50 vận đơn. Vận đơn ghi hãng giao (carrier: mã tự do ghn, ghtk, self…), mã theo dõi, tiền thu hộ (codAmount, tiền tệ của đơn; null = không thu hộ).

Hai trục trạng thái #

codStatus (trục tiền thu hộ, server đổi): none (không thu hộ) | pending → collected (giao xong, hãng đã thu) → remitted (hãng đã nộp tiền cho store). Vận đơn returned / cancelled khi còn pending → none.

• pending → in_transit cần đơn đã fulfilled (hàng đã xuất kho, module order) — không thì 409 shipment_order_not_fulfilled.
• failed kèm reason (lưu thành failReason, lần hỏng gần nhất); từ failed giao lại (in_transit) hoặc trả về (returned).
• Đơn fulfilled không còn vận đơn nào đang mở và có ít nhất một vận đơn delivered → đơn tự completed.
• Mốc thời gian: shippedAt, deliveredAt, failedAt, returnedAt, cancelledAt, codCollectedAt, codRemittedAt.

CMS / admin (XforgeClient) #

Menu: key shipment.shipments (quyền shipment.read).

• Tạo vận đơn khi đơn confirmed hoặc fulfilled (409 shipment_order_not_shippable); số tự sinh SH-YYYYMMDD-0001.
• Danh sách: lọc status, order_id, cod_status, carrier; q tìm số vận đơn và mã theo dõi. Màn chi tiết đơn: listShipments({ query: { order_id } }).

• Mỗi vận đơn có actions: thao tác người gọi làm được lúc này. Bật / tắt nút theo đó, đừng tự suy từ status; giá trị lạ thì bỏ qua:

  • update → updateShipment (shipment.manage, chưa kết thúc);
  • các bước kế tiếp, đúng giá trị gửi lên setShipmentStatus: in_transit, out_for_delivery, delivered, failed, returned, cancelled (shipment.manage, theo sơ đồ trên);
  • cod_remit → remitShipmentCod (shipment.reconcile, codStatus là collected).

  actions chỉ xét vận đơn: in_transit vẫn hiện khi đơn chưa xuất kho và trả 409 shipment_order_not_fulfilled. Bước đã lỗi thời (mở từ trước) → 409 shipment_invalid_transition / shipment_closed: tải lại.

• shipment.manage đủ để giao xong → đơn hoàn tất: nhân viên giao hàng đóng đơn được (cố ý).
• Đối soát COD: getShipmentCodSummary = tiền thu hộ hãng còn giữ (vận đơn collected), theo hãng + tiền tệ; danh sách chi tiết listShipments({ query: { cod_status: "collected", carrier } }). Hãng chuyển tiền → remitShipmentCod từng vận đơn kèm mã chuyển khoản. Khi tiền đã nộp của MỌI vận đơn của đơn đủ tổng đơn mà đơn còn unpaid → đơn thành paid (module payments, nhà cung cấp cod); nộp một phần chỉ đánh dấu vận đơn.

• SMS báo khách (ADR-0104 của Core): shipment.sms_notify (onInTransit — kèm hãng + mã vận đơn, onOutForDelivery, onDelivered; mặc định tắt) qua PUT /api/v1/core/configs/shipment.sms_notify. Người nhận = số của đơn.

Báo cáo shipment.cod_outstanding #

Công nợ thu hộ, quyền shipment.read, chạy qua runReport / exportReport (docs/fe/cms.md §9). Tham số bắt buộc from, to (YYYY-MM-DD, lọc theo NGÀY TẠO vận đơn, giờ store). Mỗi dòng là một tổ hợp hãng + trạng thái thu hộ + tiền tệ: carrier, codStatus, currency, shipments, amount (chuỗi), oldestCollectedAt (null khi chưa thu).

Chỉ gồm tiền CHƯA nộp về store: pending (vận đơn còn đi, chưa thu) và collected (hãng đang giữ); bỏ none, remitted, vận đơn returned / cancelled. summary là dòng tổng, null khi có nhiều tiền tệ. Khác getShipmentCodSummary: route đó chỉ tính collected, không lọc ngày.

Mẫu in shipment.delivery_note #

Phiếu giao hàng, quyền riêng shipment.print, xem qua printDocument (docs/fe/cms.md §11); không gửi email (canEmail: false). Gồm hãng, mã vận đơn, tên + số điện thoại + địa chỉ người nhận, tiền thu hộ, chỗ ký; KHÔNG có ghi chú nội bộ. Vận đơn chưa có dòng hàng riêng: phiếu liệt kê mọi dòng của đơn, kể cả khi đơn tách nhiều vận đơn. Có shipment.read mà không có shipment.print thì không in được, vì bản in lộ thông tin người nhận mà API vận đơn không trả.

Webhook gửi đi shipment.status_changed #

Đăng ký ở màn "Tích hợp" (docs/fe/cms.md §8), người đăng ký cần shipment.read. Phát cho từng vận đơn khi đổi trạng thái qua setShipmentStatus và khi huỷ đơn kéo vận đơn chờ sang cancelled. data là hợp đồng (thêm field được):

{ shipmentId, number, orderId, orderNumber, carrier, from, to, currency, codAmount, codStatus }

Không có ghi chú, lý do, mã theo dõi hay dữ liệu người nhận.

Storefront (StorefrontClient) #

• listMyShipments({ query: { order_id } }) — theo dõi giao hàng của MỘT đơn của khách đang đăng nhập (đơn của người khác → danh sách rỗng), cũ trước, tối đa 50: số vận đơn, hãng, mã theo dõi, trạng thái, tiền thu hộ, mốc gửi / giao. Hiện ở trang chi tiết đơn (getMyOrder, module order).

Lỗi cần xử lý #