Giao diện
Container
TKHQ theo dõi vòng đời từng container vật lý — tự động tính DEM/DET, cảnh báo trước hạn, và ghi lịch sử sự kiện append-only — từ khi booking đến khi trả vỏ.
Theo dõi vòng đời container — từ gán booking đến trả vỏ (EMPTY_RETURN), DEM/DET tự động. Route: /containers.
Tổng quan
Mỗi Container record theo dõi một đơn vị container vật lý trong hệ thống:
- Số container (ISO 6346)
- Loại / size (20DC, 40HC, 40RF...)
- Trạng thái vòng đời — state machine riêng theo loại lô hàng (IMPORT 11 bước / EXPORT 8 bước / TRANSIT 7 bước)
- DEM/DET countdown tự động
- Liên kết với Booking → Shipment
Chỉ số tổng quan workspace:
| KPI | Giá trị ví dụ | Ý nghĩa |
|---|---|---|
| Container đang vận chuyển | 24 | Đang IN_TRANSIT hoặc đã VESSEL_ARRIVED/VESSEL_LOADED |
| Cần lấy hàng (DEM risk) | 7 | Đã VESSEL_ARRIVED/RELEASED, còn < 3 ngày free time DEM |
| Quá hạn DET | 3 | Đã CARGO_PICKUP quá free time DET, đang phát sinh phí |
| Đã trả vỏ tháng này | 45 | Chuyển EMPTY_RETURN trong tháng |
Vòng đời container theo loại lô hàng
Container không có một state machine chung — mỗi loại lô hàng (flowType, suy từ Shipment.type hoặc Booking.bookingType khi chưa có shipment) có một chuỗi trạng thái xuôi riêng. Không có đường đi lùi; huỷ (CANCELLED) luôn khả dụng từ bất kỳ bước nào chưa kết thúc.
| # | Trạng thái | Ý nghĩa |
|---|---|---|
| 1 | PENDING | Mới tạo, chưa gán booking |
| 2 | BOOKING_ASSIGNED | Đã gán vào Booking |
| 3 | VESSEL_LOADED | Hàng đã lên tàu (theo B/L phát hành) |
| 4 | IN_TRANSIT | Đang trên đường vận chuyển (theo Arrival Notice, gửi trước ETA) |
| 5 | VESSEL_ARRIVED | Hàng đã về đến cảng (theo D/O hoặc ePort) — DEM bắt đầu tính |
| 6 | CUSTOMS_HOLD | (tuỳ chọn) đang giữ chờ thông quan |
| 7 | RELEASED | Đã thông quan, được giải phóng |
| 8 | CARGO_PICKUP | Đã lấy hàng khỏi cảng — DEM kết thúc, DET bắt đầu |
| 9 | CARGO_UNLOADED | Đã dỡ hàng tại kho khách |
| 10 | EMPTY_RETURN | Đã trả vỏ container — DET kết thúc |
| 11 | COMPLETED | Kết thúc vòng đời |
CUSTOMS_HOLD là bước tuỳ chọn (chỉ IMPORT)
Không tự sinh dòng "bước bù" trên timeline khi bỏ qua, và nút "Bước tiếp theo" cũng bỏ qua nó — ở VESSEL_ARRIVED, bấm "Bước tiếp theo" đi thẳng RELEASED. Vẫn chọn được bằng tay qua dropdown khi cần phản ánh đúng thực tế container bị giữ hải quan.
Sub-state EIR (EIR_ISSUED, GATE_IN) — chỉ đọc, không ghi tay được
Hai giá trị này do EIR applier ghi khi trích xuất phiếu giao nhận container, biểu diễn vị trí "nằm giữa" hai bước trong bảng trên (ví dụ IMPORT GATE_IN neo về VESSEL_ARRIVED). Không xuất hiện trong dropdown cập nhật trạng thái thủ công — PENDING → GATE_IN bằng tay bị từ chối.
Trạng thái tự cập nhật từ đâu
Container tự đẩy trạng thái khi hệ thống nhận được các tín hiệu sau — luôn tiến (xuôi-only), và bị chặn vĩnh viễn một khi đã đẩy tay xa hơn hoặc container đã kết thúc/huỷ:
| Nguồn tín hiệu | IMPORT | EXPORT | TRANSIT |
|---|---|---|---|
| Áp dụng chứng từ Bill of Lading | VESSEL_LOADED | VESSEL_LOADED | — |
| Áp dụng chứng từ Arrival Notice | IN_TRANSIT | — | — |
| Áp dụng chứng từ Delivery Order | VESSEL_ARRIVED | — | — |
Tờ khai chuyển SUBMITTED (chỉ khi đã ≥ VESSEL_ARRIVED) | CUSTOMS_HOLD | — | — |
Tờ khai chuyển COMPLETED (chỉ khi đã ≥ VESSEL_ARRIVED) | RELEASED | — | — |
Sự kiện gate ra (EIR GATE_OUT/lệnh lấy hàng) | CARGO_PICKUP | EMPTY_PICKUP | CARGO_PICKUP |
Sự kiện gate vào (EIR GATE_IN kèm lệnh trả rỗng) | EMPTY_RETURN | CARGO_LOADED | AT_TERMINAL |
| Chuyến (Trip) chuyển trạng thái theo Mục đích chuyến | xem Fleet | xem Fleet | xem Fleet |
Sự kiện tạo tay không đẩy trạng thái
Chỉ sự kiện do hệ thống ghi (chứng từ, ePort, EIR, chuyến xe) mới tự đẩy trạng thái container. Sự kiện bạn tạo tay qua "+ Thêm sự kiện" (kể cả trùng loại GATE_OUT/EMPTY_RETURN) chỉ ghi vào lịch sử timeline — không làm container chuyển trạng thái.
Kết nối ePort/ADA — tuỳ chọn, cần tài khoản của bạn
Kết nối ePort (Tân Cảng) hoặc ADA (cảng Hải Phòng) bằng tài khoản riêng của workspace để nhận thêm tín hiệu tự động (hàng về cảng, thông quan, trả/lấy vỏ...) — xem Tích hợp API. Không kết nối vẫn dùng được toàn bộ workflow; cập nhật bằng tay hoặc qua nút "Bước tiếp theo".
DEM/DET tracking
Theo dõi phí lưu container — tự động tính từ mốc VESSEL_ARRIVED (bắt đầu DEM) và CARGO_PICKUP (kết thúc DEM, bắt đầu DET).
Timeline DEM/DET ví dụ (container 40HC, free time 7 ngày DEM / 5 ngày DET):
| Ngày | Trạng thái | DEM | DET |
|---|---|---|---|
| 01/06 | VESSEL_ARRIVED | Bắt đầu tính | — |
| 05/06 | CARGO_PICKUP | DEM: 4 ngày (trong free time) | Bắt đầu tính |
| 08/06 | — | — | DET: 3 ngày (trong free time) |
| 10/06 | EMPTY_RETURN | — | DET: 5 ngày (đúng free time, không phát sinh phí) |
Cảnh báo tự động:
- DEM còn 2 ngày: Telegram + In-app
- DET còn 2 ngày: Telegram + In-app
- Quá hạn: Email escalate OWNER
Mốc VESSEL_ARRIVED là quan trọng nhất
DEM bắt đầu từ mốc VESSEL_ARRIVED. Nếu nhập sai hoặc bỏ sót, SLA tính sai và cảnh báo không đúng lúc. Ưu tiên áp Delivery Order hoặc kết nối ePort để nhận tự động thay vì nhập tay.
Thêm / sửa container
Thêm container vào Booking:
- Từ chi tiết Booking → + Thêm container
- Nhập số container (validate ISO 6346 tự động)
- Chọn loại container
- Upload EIR → AI extract số lệnh, tình trạng
Cập nhật trạng thái — 3 cách:
- Nút "Bước tiếp theo" ở đầu trang chi tiết Container — 1 click đẩy thẳng sang bước xuôi kế tiếp trong bảng flow (tự bỏ qua
CUSTOMS_HOLD). - Nút tương tự ở từng dòng danh sách/lịch sử — có hộp thoại xác nhận trước khi ghi.
- Dropdown "Cập nhật trạng thái thủ công" — chỉ liệt kê các trạng thái còn ở phía trước trong flow (kể cả trạng thái tuỳ chọn) và
CANCELLED; không hiện được trạng thái đã qua hoặc sub-state EIR.
Nhảy nhiều bước trong 1 lần
Chọn thẳng một trạng thái xa hơn 1 bước (ví dụ PENDING → RELEASED) — hệ thống tự ghi bù các bước trung gian bị bỏ qua lên timeline, đánh dấu chip "Bước bù". Các dòng bù dùng chung thời điểm ghi, không gửi email mốc vận chuyển cho khách và không mở milestone SLA (milestone có mốc bắt đầu bị bù giữ nguyên "chưa bắt đầu" thay vì báo hoàn thành sai).
Dòng nào do hệ thống tự đẩy (từ chứng từ, tờ khai, sự kiện gate, hoặc chuyến xe) hiện nhãn "Tự động · <nguồn>" trên timeline thay vì tên người cập nhật.
Thẻ EIR trên chi tiết Container:
Sau khi upload EIR, chi tiết Container hiện thẻ EIR tổng hợp thông tin đã trích xuất/nhập:
| Trường | Ghi chú |
|---|---|
| Số EIR | Số phiếu giao nhận container (nếu có) |
| Ngày cấp | Ngày phát hành EIR |
| Hết hạn EIR | Đếm ngược tới hạn — dùng cho cảnh báo DEM/DET |
Thẻ chỉ hiện khi có ít nhất một trong ba trường trên.
Cảnh báo xung đột hạn lấy hàng
Trường "Ngày lấy hàng" của container có thể được điền từ nhiều nguồn khác nhau: nhập tay, chứng từ EIR, hoặc sự kiện chuyến xe (Fleet). Khi một nguồn đến sau đề xuất một ngày khác với giá trị đang có trên container, hệ thống không tự ghi đè — mà để bạn quyết định.
Khi xảy ra xung đột:
- Một biểu tượng cảnh báo (tam giác) hiện ngay cạnh trường "Ngày lấy hàng".
- Bấm biểu tượng → hộp thoại "Xung đột hạn lấy hàng" hiển thị song song:
- Hiện tại — giá trị đang lưu, kèm nguồn (nhập tay / chứng từ EIR / sự kiện chuyến xe)
- Đề xuất — giá trị mới đến sau, kèm nguồn
Cách xử lý: chọn một trong hai nút
| Nút | Kết quả |
|---|---|
| Giữ nguyên | Bỏ giá trị đề xuất, giữ nguyên ngày hiện tại |
| Dùng giá trị đề xuất | Thay ngày lấy hàng bằng giá trị mới |
Sau khi chọn, cảnh báo biến mất và trường được cập nhật theo lựa chọn của bạn.
Chỉ khác ngày mới tính là xung đột
Hệ thống so sánh theo ngày (không tính giờ) — hai nguồn ghi cùng một ngày nhưng khác giờ không bị coi là xung đột.
Bảo vệ đồng thời — status guard
Mỗi lần cập nhật trạng thái container đều đọc lại trạng thái hiện tại trước khi ghi:
- Nếu 2 người cùng cập nhật container một lúc, chỉ người đầu tiên thành công; người thứ 2 thua race được đọc lại state 1 lần — nếu trạng thái đã ≥ đích mong muốn thì coi như thành công (no-op), tránh lỗi giả.
- Chỉ tiến được (không lùi); đích ghi phải là bước ở trong flow của đúng loại lô hàng, hoặc
CANCELLED. - Container chưa xác định được loại lô hàng (không có cả shipment lẫn booking) → mọi cập nhật trạng thái trả lỗi
CONTAINER_FLOW_TYPE_UNKNOWN.
Cập nhật hàng loạt (bulk status):
Chọn tối đa 50 container để cập nhật cùng lúc. Nếu các container được chọn thuộc nhiều loại lô hàng khác nhau (ví dụ vừa IMPORT vừa EXPORT), nút cập nhật hàng loạt bị vô hiệu hoá kèm ghi chú lý do — mỗi loại lô hàng có flow trạng thái riêng nên không thể áp chung một đích. Chọn container cùng loại lô hàng để bật lại nút.
Phí DEM/DET tích lũy → sinh báo nợ
Song song với countdown DEM/DET, hệ thống tự động cộng dồn số tiền phí DEM/DET dựa trên bảng giá (tariff) đã cấu hình cho hãng tàu — hiển thị ngay trên chi tiết Container:
| Trường | Ý nghĩa |
|---|---|
| DEM tích lũy | Số tiền DEM phát sinh tính đến sự kiện gần nhất (₫) |
| DET tích lũy | Số tiền DET phát sinh tính đến sự kiện gần nhất (₫) |
| Lưu kho tích lũy | Số tiền phí lưu kho (storage) phát sinh tính đến sự kiện gần nhất (₫) |
Số tiền được tính lại (ghi đè, không cộng dồn trùng lặp) mỗi khi container có sự kiện GATE_OUT (lấy hàng) hoặc GATE_IN (trả vỏ) — nên luôn phản ánh đúng trạng thái mới nhất kể cả khi EIR được áp lại nhiều lần.
Khi có số tiền tích lũy (DEM, DET, hoặc lưu kho) > 0 và container chưa được lập báo nợ, nút "Sinh báo nợ DEM/DET" xuất hiện trên chi tiết container. Bấm nút này hiện hộp thoại xác nhận trước khi tạo — bấm Xác nhận để tạo Debit Note nháp ngay từ số liệu tích lũy, tránh phải tính tay và nhập lại vào Finance.
Bảng giá DEM/DET/STORAGE
Bảng giá theo hãng tàu (free days + phí/ngày cho từng loại phí Demurrage/Detention/Lưu bãi) được cấu hình tại Partner 360 của hãng tàu — xem Đối tác.
Container events — lịch sử append-only
Mọi cập nhật container đều ghi vào bảng container_events — không bao giờ xoá. Đây là nguồn sự thật duy nhất cho timeline container.
Xem lịch sử sự kiện:
Từ chi tiết Container → tab Timeline → thấy toàn bộ sự kiện theo thứ tự thời gian:
| Thời gian | Trạng thái/sự kiện | Nguồn | Ghi chú |
|---|---|---|---|
| 05/06 14:30 | VESSEL_ARRIVED | ePort auto | Tàu MSC AURORA cập cảng |
| 07/06 09:15 | GATE_OUT | Nhập tay | Lái xe Nguyễn Văn A |
| 07/06 09:16 | CARGO_PICKUP | Tự động · gate | Đẩy theo sự kiện GATE_OUT hệ thống |
| 10/06 11:30 | EMPTY_RETURN | Tự động · trip | Trip #T-2026-0412 hoàn tất |
Nguồn sự kiện:
ePort auto/ADA auto— nhận từ API cảng (kết nối ePort/ADA của workspace, tuỳ chọn)Nhập tay— operator cập nhật thủ công (chỉ ghi timeline, không đổi trạng thái)Tự động · <nguồn>— hệ thống tự đẩy trạng thái từ chứng từ/tờ khai/gate/ePort/trip
Thêm sự kiện thủ công
Nếu container chưa kết nối ePort/ADA hoặc cần ghi bổ sung một mốc đã xảy ra, thêm sự kiện thủ công từ mục Lịch sử sự kiện trên trang chi tiết Lô hàng (biểu tượng "+" cạnh tiêu đề) — sự kiện được gắn vào container đầu tiên của lô hàng đó.
6 loại sự kiện được phép nhập tay:
| Loại sự kiện | Ý nghĩa |
|---|---|
| Vào cổng | GATE_IN |
| Ra cổng | GATE_OUT |
| Lấy hàng | CARGO_PICKUP |
| Trả cont rỗng | EMPTY_RETURN |
| Bắt đầu lưu kho | STORAGE_START |
| Ghi chú thủ công | MANUAL_NOTE — không đổi trạng thái, chỉ lưu vết |
Sự kiện thủ công không đổi trạng thái container
Kể cả khi loại sự kiện tay trùng tên với một tín hiệu hệ thống thường dùng để đẩy trạng thái (ví dụ GATE_OUT, EMPTY_RETURN), sự kiện bạn tạo tay qua dialog này chỉ ghi vào timeline — không kích hoạt đẩy trạng thái container. Chỉ sự kiện do hệ thống/tích hợp ghi (EIR applier, ePort, chuyến xe) mới đẩy trạng thái.
Khi thêm sự kiện:
- Chọn loại sự kiện, nhập mô tả (tuỳ chọn), chọn thời điểm xảy ra (để trống = hiện tại)
- Tick "Gửi email mốc vận chuyển cho khách" nếu muốn thông báo ngay cho khách hàng — mặc định TẮT
- Hệ thống cảnh báo: sự kiện sẽ tính vào DEM/DET và không thể xoá sau khi tạo
Sự kiện thủ công là immutable
Giống mọi sự kiện container khác, một khi đã lưu, sự kiện thủ công không xoá/sửa được — chỉ có thể thêm sự kiện mới để bổ sung. Cân nhắc kỹ trước khi xác nhận, đặc biệt với GATE_OUT/EMPTY_RETURN vì ảnh hưởng trực tiếp đến số tiền DEM/DET tích luỹ.
Spawn container từ Booking
Khi apply Booking Confirmation vào Shipment, hệ thống tự tạo container:
- Đọc danh sách container từ booking document
- Tạo Container record với type/size từ booking
- Liên kết container vào Booking và Shipment
- Giới hạn: tối đa 50 container/size, 200 container/lô hàng