📂 Quản lý chứng từ

Upload, trích xuất và áp dụng dữ liệu từ chứng từ thương mại vào tờ khai và lô hàng. Route: /documents.

⬆️ Upload

Upload chứng từ để AI trích xuất dữ liệu tự động — hỗ trợ PDF và ảnh.

Định dạng hỗ trợ: PDF, JPEG, PNG, TIFF, WEBP (tối đa 50MB/file)

Loại chứng từ nhận diện tự động:

• Commercial Invoice (Invoice thương mại)
• Packing List
• Bill of Lading (B/L) / Airway Bill (AWB)
• Certificate of Origin (CO) — Form D, Form E, Form AK, EUR.1...
• Phytosanitary Certificate / Fumigation Certificate
• EIR (Equipment Interchange Receipt)
• Chứng từ tổng quát (PDF khác)

Cách upload:

1. Vào /documents → nút + Upload chứng từ
2. Kéo thả file hoặc click chọn file từ máy tính
3. Hệ thống tự nhận diện loại chứng từ
4. AI bắt đầu trích xuất trong nền (30–120 giây tuỳ độ phức tạp)
5. Nhận thông báo khi trích xuất xong

Upload hàng loạt

Chọn nhiều file cùng lúc (Ctrl+Click hoặc Shift+Click) — hệ thống xử lý song song, không cần chờ từng file.

🔍

Drag & drop nhiều file — AI nhận diện loại và trích xuất song song

📋 Danh sách

Quản lý toàn bộ chứng từ trong workspace.

Bộ lọc và tìm kiếm:

Bộ lọc	Giá trị
Loại chứng từ	Invoice, Packing List, B/L, CO, EIR, Khác
Trạng thái	Đang xử lý, Đã trích xuất, Lỗi, Chờ review
Ngày upload	Khoảng ngày
Đã áp dụng	Lọc chứng từ đã/chưa apply vào lô hàng

Trạng thái trích xuất:

Trạng thái	Mô tả
Đang xử lý	AI đang OCR và phân tích
Đã trích xuất	Dữ liệu sẵn sàng, có thể apply
Cần review	AI không chắc một số trường — cần người dùng xác nhận
Lỗi	File hỏng, mật khẩu, hoặc định dạng không hỗ trợ

🔍

Danh sách chứng từ với trạng thái trích xuất và nút apply

🔬 Trích xuất

Xem dữ liệu AI đã trích xuất từ chứng từ — chỉnh sửa và xác nhận trước khi dùng.

Dữ liệu trích xuất từ Invoice:

Trường	Ví dụ
Số Invoice	INV-2026-00142
Ngày phát hành	2026-05-20
Người bán	ABC Trading Co., Ltd
Người mua	XYZ Import JSC
Tổng giá trị	USD 12,500.00
Điều kiện thanh toán	T/T 30 days
Dòng hàng	Tên, HS gợi ý, số lượng, đơn giá, thành tiền

Chỉnh sửa inline

Click vào bất kỳ trường nào để sửa trực tiếp. Thay đổi được lưu và dùng khi apply vào tờ khai.

Chi phí trích xuất: ~1.500 token/trang PDF phức tạp (ảnh scan), ~300 token/trang PDF có text layer.

🔍

Dữ liệu trích xuất từ Invoice — chỉnh sửa inline trước khi apply

🔗 Apply to Shipment

Áp dụng dữ liệu chứng từ vào lô hàng hoặc booking container.

Cách apply:

1. Từ trang chi tiết chứng từ → click Apply to Shipment
2. Chọn lô hàng đích (hoặc tạo mới)
3. Xem preview mapping: trường nào từ chứng từ → điền vào trường nào của lô hàng
4. Điều chỉnh nếu cần → click Xác nhận apply

Ví dụ mapping EIR → Container:

Trường từ EIR	Điền vào Container
Số container	containerNumber
Số lệnh	sealNumber
Loại/size	containerType
Ngày gate-out	gateOutDate
Tình trạng	damageNote

Không override dữ liệu đã có

Nếu trường đích đã có dữ liệu, hệ thống hỏi trước khi ghi đè. Chọn Giữ nguyên hoặc Ghi đè.

🔍

Preview mapping trường từ EIR vào Container trước khi xác nhận

📤 Xuất dữ liệu

Xuất dữ liệu đã trích xuất ra Excel hoặc JSON để tích hợp với hệ thống khác.

Định dạng xuất:

• Excel (.xlsx) — mỗi sheet là một loại chứng từ, có header chuẩn
• JSON — cấu trúc đầy đủ, dùng cho API integration
• CSV — cho import vào ERP/phần mềm kế toán

Cách xuất:

1. Chọn một hoặc nhiều chứng từ (checkbox)
2. Click Xuất → chọn định dạng
3. File download về máy

Xuất hàng loạt

Chọn Tất cả và lọc theo ngày/loại trước khi xuất — tránh xuất toàn bộ lịch sử không cần thiết.

🧠 Extraction cache — idempotency

Hệ thống cache kết quả trích xuất để tránh gọi AI lặp lại cho cùng một file:

Cache key được tính từ:

sha256(file_content) : mimeType : declarationType : documentType : bookingType : v1

• Cùng file, cùng context → trả kết quả cache ngay, không tốn token
• Cache TTL: 7 ngày kể từ lần trích xuất cuối
• Dọn dẹp cache hàng ngày lúc 02:00 để xoá bản ghi hết hạn

Khi nào cache bị bypass:

Tình huống	Hành vi
Đổi bookingType (Import → Export)	Re-extract (cache key thay đổi)
Upload lại cùng file	Trả cache (cache key giống)
Nhấn "Trích xuất lại"	Force bypass cache, gọi AI lại
File bị sửa trước khi upload	Re-extract (sha256 khác)

Tiết kiệm token với cache

Nếu cần test nhiều lần với cùng chứng từ, không cần nhấn "Trích xuất lại" — cache sẽ trả kết quả tức thì và không tốn token.

🔍 Các chiến lược trích xuất theo loại chứng từ

Mỗi loại chứng từ dùng một strategy khác nhau để tối ưu độ chính xác:

Loại chứng từ	Strategy	Đặc điểm
Commercial Invoice	InvoiceStrategy	Trích xuất parties, goods list, value, incoterm
Packing List	PackingListStrategy	Tập trung vào dims, weight, packageCount per item
Bill of Lading	BillOfLadingStrategy	vessel, voyage, POL/POD, ETD/ETA, containerList
Shipping Instruction	ShippingInstructionStrategy	SI cutoff, booking reference, cargo details
VAT Invoice	VatInvoiceStrategy	MST, tax amount, đơn vị tính VN
Certificate of Origin	CertOfOriginStrategy	originCountry, FTA form type, HS codes
Contract	ContractStrategy	parties, payment terms, validity period
EIR	EirStrategy	containerNumber, sealNumber, GATE event
Export Declaration	ExportDeclarationStrategy	declarant, goods, HS codes
Booking Confirmation	BookingStrategy	bookingNo, carrier, container list, direction

OCR fallback: Nếu PDF không có text layer (scan ảnh), hệ thống dùng Tesseract OCR với auto-detect xoay ảnh — sau đó mới chạy AI extract trên text đã OCR.

📊 Content pipeline theo định dạng file

Định dạng	Pipeline xử lý
PDF (có text layer)	Extract text trực tiếp → AI
PDF (scan)	Tesseract OCR → AI
JPEG/PNG/TIFF	Resize → AI vision model trực tiếp
XLSX	Chuyển thành Markdown table → AI
DOCX	mammoth.js → HTML → text → AI

Tesseract tự phát hiện góc xoay của ảnh (orientation detection) — không cần xoay ảnh trước khi upload.

🔗 Apply vào Tờ khai hải quan

Ngoài Apply to Shipment, chứng từ còn có thể apply vào Tờ khai hải quan:

• Từ trang tạo tờ khai (Bước 1) → upload chứng từ
• Hoặc từ chi tiết tờ khai → tab Chứng từ → Thêm và apply
• Xung đột khi nhiều chứng từ cung cấp dữ liệu khác nhau → hộp thoại resolve conflict