Container

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

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)

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

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