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ừ GATE_OUT đến EMPTY_RETURNED, 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 8 trạng thái)
• 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 ON_VESSEL hoặc DISCHARGED
Cần lấy hàng (DEM risk)	7	DISCHARGED, còn < 3 ngày free time
Quá hạn DET	3	GATE_OUT > free time DET, đang phát sinh phí
Đã trả vỏ tháng này	45	EMPTY_RETURNED trong tháng

🔍

Dashboard container — KPI và danh sách theo trạng thái

Vòng đời container

State machine 8 trạng thái:

Trạng thái	Mô tả	Trigger
BOOKED	Đã booking, chưa có container thực	Booking CONFIRMED
LOADED	Hàng đã xếp vào container tại kho	Xác nhận xếp hàng
ON_VESSEL	Container trên tàu	Tàu rời cảng (ETD)
DISCHARGED	Tàu dỡ hàng — bắt đầu tính DEM	Sự kiện ePort hoặc nhập tay
GATE_OUT	Container ra khỏi cảng — DEM kết thúc, DET bắt đầu	Sự kiện ePort hoặc nhập tay
IN_TRANSIT	Đang vận chuyển về kho khách	Trip Fleet
DELIVERED	Hàng giao tới kho đích	Trip DELIVERED
EMPTY_RETURNED	Trả container rỗng về cảng — DET kết thúc	Xác nhận trả vỏ

Ngày DISCHARGED là quan trọng nhất

DEM bắt đầu từ ngày DISCHARGED. 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 kết nối ePort để nhận tự động.

DEM/DET tracking

Theo dõi phí lưu container — tự động tính từ sự kiện DISCHARGED và GATE_OUT.

Timeline DEM/DET ví dụ (container 40HC, free time 7 ngày DEM / 5 ngày DET):

Ngày	Sự kiện	DEM	DET
01/06	DISCHARGED	Bắt đầu tính	—
05/06	GATE_OUT	DEM: 4 ngày (trong free time)	Bắt đầu tính
08/06	—	—	DET: 3 ngày (trong free time)
10/06	EMPTY_RETURNED	—	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

Kết nối ePort/ADA

Kết nối ePort (Tân Cảng) hoặc ADA (cảng Hải Phòng) để nhận sự kiện DISCHARGED và GATE_OUT tự động — xem Tích hợp API.

🔍

Countdown DEM/DET — cảnh báo tự động khi gần hết free time

Thêm / sửa container

Thêm container vào Booking:

1. Từ chi tiết Booking → + Thêm container
2. Nhập số container (validate ISO 6346 tự động)
3. Chọn loại container
4. Upload EIR → AI extract số lệnh, tình trạng

Cập nhật trạng thái thủ công:

Nếu không kết nối ePort, cập nhật thủ công:

1. Vào chi tiết Container → nút Cập nhật trạng thái
2. Chọn trạng thái mới → nhập ngày/giờ thực tế
3. Lưu → SLA tính lại ngay

Trường	Ghi chú
Ngày DISCHARGED	Ngày tàu dỡ hàng thực tế (không phải ETA)
Ngày GATE_OUT	Ngày container ra khỏi cổng cảng
Ngày EMPTY_RETURNED	Ngày trả vỏ — tính đủ DET

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.

Vòng đời container theo loại lô hàng

Hệ thống có 2 state machine riêng biệt cho IMP và EXP:

Nhập khẩu (IMP):

BOOKING_ASSIGNED → LOADING → ON_VESSEL → DISCHARGED → GATE_OUT → IN_TRANSIT → DELIVERED → EMPTY_RETURNED → COMPLETED

Xuất khẩu (EXP):

BOOKING_ASSIGNED → PICKUP → STUFFED → GATE_IN → LOADED → ON_VESSEL → COMPLETED

Trạng thái container xuất khẩu

Với EXP, GATE_IN là container vào cảng để xếp lên tàu (ngược với IMP là ra khỏi cảng). Không nhầm lẫn giữa 2 chiều.

Bảo vệ đồng thời — status guard

Mỗi lần cập nhật trạng thái container đều kiểm tra 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 nhận lỗi INVALID_STATE_TRANSITION — cần refresh và kiểm tra lại
• Không thể nhảy trạng thái (ví dụ: BOOKED → DELIVERED trực tiếp)

Cập nhật hàng loạt (bulk status):

Khi chọn nhiều container để cập nhật trạng thái cùng lúc, hệ thống hiện trước bảng xem trước (reject-preview) liệt kê container nào sẽ không áp dụng được do vi phạm quy tắc chuyển trạng thái tuần tự — giúp bạn loại bỏ container sai trước khi bấm Áp dụng, thay vì chỉ báo lỗi sau khi đã submit.

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	Sự kiện	Nguồn	Ghi chú
05/06 14:30	DISCHARGED	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 14:00	IN_TRANSIT	Fleet GPS	Trip #T-2026-0412
08/06 11:30	DELIVERED	Fleet xác nhận	Kho Bình Dương

Nguồn sự kiện:

• ePort auto / ADA auto — nhận từ API cảng (kết nối ePort/ADA)
• Nhập tay — operator cập nhật thủ công
• Fleet GPS — VietMap geofence trigger
• Fleet xác nhận — tài xế bấm confirm trên app

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

Vì sao chỉ 6 loại

Các mốc do hệ thống tự sinh (đổi trạng thái container, áp dữ liệu từ chứng từ EIR) không cho nhập tay — tránh ghi lùi ngày làm sai lệch trạng thái hoặc phí đã tính.

Khi thêm sự kiện:

1. 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)
2. 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
3. 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:

1. Đọc danh sách container từ booking document
2. Tạo Container record với type/size từ booking
3. Liên kết container vào Booking và Shipment
4. Giới hạn: tối đa 50 container/size, 200 container/lô hàng