Vận đơn (Shipments)

Trang Vận chuyển (/app/shipments) — danh sách toàn bộ vận đơn của shop, theo dõi trạng thái và lịch sử từ hãng. Vận đơn đều đi qua Goship (TrolyShip hoặc BYOA) — xem tổng quan vận chuyển để hiểu kiến trúc.

Bố cục trang

• Tiêu đề: Vận chuyển — “Tất cả vận đơn Goship — theo dõi trạng thái, làm mới từ hãng vận chuyển.”
• Filter bar + Bảng vận đơn + Panel phải (sticky).

Filter bar

Filter	Lựa chọn
Hãng	Tất cả hãng / Goship / ViettelPost
Trạng thái	Đang xử lý / Đã giao / Đang hoàn hàng / Huỷ/thất bại
Nguồn	Mọi nguồn / Tenant (BYOA) / Platform gateway (TrolyShip)
Search	Theo mã vận đơn / mã Goship
Express	Lọc riêng đơn on-demand (AhaMove/Grab)

“Hãng” ở đây là gì

Filter Hãng = loại tích hợp (Goship aggregator vs ViettelPost riêng), KHÔNG phải từng hãng xe cụ thể (GHN/GHTK…). Hãng xe cụ thể nằm trong cột “Hãng” của từng dòng, do Goship trả về.

Bảng vận đơn — cột

Cột	Nội dung
Mã vận đơn	Mã carrier (vd VTP VTP123456789) hoặc mã Goship
Đơn hàng	Link tới Đơn hàng (vd #1024)
Khách hàng	Tên + SĐT
Hãng	Carrier cụ thể (ViettelPost / GHN / GHTK / J&T / AhaMove…)
Trạng thái	Badge + code
COD	Số tiền thu hộ (nếu có)
Phí	Phí carrier thật (sau reconcile)
Nguồn	Platform (TrolyShip) / Tenant (BYOA)
Ngày tạo	Timestamp
Express	Badge Express nếu on-demand

Panel phải (sticky)

• Tổng quan vận chuyển:
  • Tổng vận đơn (toàn account).
  • COD đang thu — tổng tiền thu hộ đang chờ.
  • Phí carrier — tổng phí ship đã trả.
  • Markup platform — markup TrolyPage cộng (chỉ TrolyShip).
• Chú giải trạng thái — giải thích màu badge.
• Link Quản lý đơn hàng → Đơn hàng.

Theo dõi vận đơn

Click vào dòng vận đơn → mở modal “Theo dõi vận đơn”:

Phần	Nội dung
Header	Tên hãng + badge carrier_code + Express (nếu on-demand) + Platform/Tenant
Thông tin	Mã vận đơn · Dịch vụ · Trạng thái + code:
Tài chính	COD · Phí (carrier) · Giá tenant + Markup (nếu platform)
Link đơn	Đơn hàng: #code · total₫ (hoặc “Đơn vận chuyển độc lập”)
Timeline	Lịch sử trạng thái từ hãng
Nút	Đóng + Làm mới trạng thái

Empty timeline

“Chưa có lịch sử cập nhật. Nhấn ‘Làm mới trạng thái’ để lấy từ hãng vận chuyển.” — bấm Làm mới trạng thái để fetch.

“Làm mới trạng thái” làm gì

Gọi POST /app/api/shipments/{id}/refresh → GoshipApiService::searchShipment() (standard) hoặc searchOndemandShipment() (express) → cập nhật timeline + reconcile phí.

Trạng thái vận đơn

Trạng thái	Code	Ý nghĩa
Đang tạo đơn	900	Mới tạo async, chờ Goship assign
Đang xử lý	—	Carrier đã nhận, đang lấy hàng
Đã giao / hoàn tất	—	Giao thành công
Đang hoàn hàng	—	Trả về shop
Huỷ / thất bại	—	Không giao được

Trạng thái 900 kéo dài

Đơn Đang tạo đơn (900) quá lâu (> 30 phút) → có thể Goship không phản hồi. Bấm Làm mới trạng thái trước, vẫn không cập nhật → liên hệ support với mã đơn.

Tạo vận đơn từ đâu

Vận đơn không tạo trực tiếp ở trang này. Tạo từ:

1. Đơn hàng — đơn đã duyệt → nút 🚚 Tạo vận đơn → mở modal ShipOrderModal.
2. Trong Hội thoại — cột phải có nút tạo vận đơn.
3. Tự động — nếu bật autoShipIfEnabled → tự tạo khi duyệt đơn (chọn hãng rẻ nhất).

Modal tạo vận đơn

Modal này quan trọng, flow:

1. Chọn kho lấy hàng (dropdown — từ Warehouses).
2. Nhập khối lượng (gram).
3. Bấm Lấy báo giá → Goship trả list hãng + phí.
4. Chọn hãng (radio — mỗi dòng: tên hãng + service + thời gian + phí).
5. (Tuỳ) Bật Giao hỏa tốc (on-demand) → chuyển sang AhaMove/Grab, cần lat/lng.
6. Bấm Tạo đơn → 200 OK → đơn pending (900).

Không có hãng phục vụ tuyến

“Không có nhà xe nào phục vụ tuyến này.” → khu vực khách carrier không tới. Fix: đổi địa chỉ khách (xem troubleshooting) hoặc dùng on-demand.

Vận đơn “độc lập”

Một số vận đơn không gắn đơn hàng TrolyPage — gọi là “đơn vận chuyển độc lập”. Xảy ra khi:

• AI/operator tạo ship trực tiếp không qua đơn.
• Đơn đã xoá nhưng ship còn.

Modal vẫn hiển thị đầy đủ tracking + tài chính, chỉ không có link “Đơn hàng: #code”.

Huỷ vận đơn

Trong modal → nút Huỷ (nếu carrier cho phép huỷ):

• Confirm dialog.
• DELETE /app/api/orders/{id}/shipments/{shipment} → Goship cancel.
• Refund (nếu carrier có chính sách).

Đã lấy hàng không huỷ được

Carrier đã tới lấy hàng → không huỷ được. Phải chờ giao hoặc yêu cầu hoàn hàng.

Bước tiếp theo

• Đơn hàng — nơi tạo vận đơn.
• Tổng quan vận chuyển — kiến trúc Goship + TrolyShip.
• Quản lý kho — kho lấy hàng.
• Troubleshooting vận chuyển — webhook 401, không cập nhật.