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)

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

“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ừ:

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

Modal này quan trọng, flow:

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

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.