Dữ liệu nền (P1)

Danh mục khách hàng, đối tác, cảng / kho / tuyến, loại phí & đơn vị tính, tiền tệ & tỷ giá — nền cho báo giá và vận chuyển.

1.Tóm tắt

Nhóm Dữ liệu nền chứa các danh mục nghiệp vụ dùng chung cho báo giá và vận chuyển: khách hàng, đối tác, cảng / kho bãi / tuyến, loại phí & đơn vị tính, tiền tệ & tỷ giá. Các danh mục này được chọn lại ở Báo giá (khách hàng, tuyến, kho gửi / nhận, loại phí, đơn vị tính, tiền tệ, tỷ giá) và ở đơn hàng vận chuyển (Theo dõi đơn hàng: kho nguồn / kho đến, cảng đi / cảng đến, Agent).

Phạm vi (màn có trên menu)

Menu	Nội dung	Tab
Dữ liệu nền › Khách hàng	Hồ sơ khách hàng; mã khách hàng dùng để ghép mã lô hàng	—
Dữ liệu nền › Đối tác	Đại lý, hãng tàu, hãng bay, nhà xe, đại lý hải quan, kho bãi…	—
Dữ liệu nền › Cảng, kho, tuyến	Cảng biển, sân bay, ICD, cửa khẩu; kho bãi bên ngoài; tuyến cảng đi – cảng đến	Cảng · Kho bãi · Tuyến
Dữ liệu nền › Loại phí & đơn vị tính	Mã phí dùng cho báo giá; đơn vị tính của dòng phí	Loại phí · Đơn vị tính
Dữ liệu nền › Tiền tệ & tỷ giá	Tiền tệ, tỷ giá quy về VND theo ngày hiệu lực	Tiền tệ · Tỷ giá
Dữ liệu nền › Cấu hình công đoạn	Loại công đoạn mặc định của đơn hàng (mốc mẫu, người mặc định, cờ bill / hóa đơn) — mô tả ở Theo dõi đơn hàng	—

Danh mục nhân sự (chức danh, loại hợp đồng, loại nghỉ) dùng cùng kiểu màn nhưng mô tả ở Nhân sự; Đơn vị & mẫu báo giá mô tả ở Báo giá. Danh mục người dùng tự định nghĩa (nhóm, loại…) nằm ở Danh mục dùng chung.

2.Actor & quyền

Actor	Vai trò trên module
Quản trị viên hệ thống	Toàn quyền: thêm / sửa / xóa mọi danh mục, nhập tỷ giá.
Super Admin (chỉ xem)	Xem mọi danh mục, không ghi.
Người dùng	Xem mọi danh mục; mặc định được thêm / sửa khách hàng và đối tác (nhân viên kinh doanh tự khai khách mới).
Trưởng phòng	Như vai trò thường: xem; ghi theo cấu hình Ma trận phân quyền.
Hệ thống	Ghi lịch sử thay đổi từng trường vào Audit trail; chặn xóa bản ghi đang được dùng.

Bảng quyền mặc định

Màn hình	Chức năng (mã)	Quản trị viên hệ thống	Super Admin (chỉ xem)	Người dùng	Trưởng phòng
Khách hàng	Xem danh sách khách hàng `xem`	Có	Có	Có	Có
	Thêm khách hàng `them`	Có	—	Có	—
	Sửa khách hàng `sua`	Có	—	Có	—
	Xóa khách hàng `xoa`	Có	—	—	—
Đối tác	Xem danh sách đối tác `xem`	Có	Có	Có	Có
	Thêm đối tác `them`	Có	—	Có	—
	Sửa đối tác `sua`	Có	—	Có	—
	Xóa đối tác `xoa`	Có	—	—	—
Cảng, kho, tuyến	Xem cảng, kho bãi, tuyến `xem`	Có	Có	Có	Có
	Thêm cảng, kho bãi, tuyến `them`	Có	—	—	—
	Sửa cảng, kho bãi, tuyến `sua`	Có	—	—	—
	Xóa cảng, kho bãi, tuyến `xoa`	Có	—	—	—
Loại phí & đơn vị tính	Xem loại phí, đơn vị tính `xem`	Có	Có	Có	Có
	Thêm loại phí, đơn vị tính `them`	Có	—	—	—
	Sửa loại phí, đơn vị tính `sua`	Có	—	—	—
	Xóa loại phí, đơn vị tính `xoa`	Có	—	—	—
Tiền tệ & tỷ giá	Xem tiền tệ, tỷ giá `xem`	Có	Có	Có	Có
	Thêm tiền tệ `them`	Có	—	—	—
	Sửa tiền tệ `sua`	Có	—	—	—
	Xóa tiền tệ `xoa`	Có	—	—	—
	Nhập / sửa / xóa tỷ giá `ty-gia`	Có	—	—	—

Giá trị khi cài mới. Quản trị viên chỉnh lại theo từng vai trò trên màn Ma trận phân quyền; hệ thống luôn kiểm quyền ở máy chủ, ẩn nút trên giao diện chỉ để gọn màn.

3.Use case

UC-DM-01Tra cứu danh mục
Actor	Người dùng, Quản trị viên, Super Admin
Tiền điều kiện	Có quyền Xem của màn.
Các bước	Mở menu Dữ liệu nền › màn cần xem; màn có nhiều tab thì chọn tab (vd Cảng / Kho bãi / Tuyến). Gõ ô Tìm kiếm (mã, tên, mã số thuế…), chọn bộ lọc loại nếu có, bấm Tìm. Bấm tiêu đề cột để sắp xếp; đổi số dòng / trang; dùng nút trang trước / sau.
Kết quả	Danh sách khớp điều kiện, phân trang ở máy chủ.
Quy tắc / validation	Tối đa 200 dòng / trang. Cột trạng thái / loại hiển thị nhãn tiếng Việt (mã KBN). Người dùng có thể chọn / sắp xếp cột hiển thị (lưu theo tài khoản).
Thông báo lỗi chính	Không có quyền xem màn: menu không hiện mục đó; mở thẳng đường dẫn ⇒ chuyển về Trang chủ.

UC-DM-02Thêm / sửa khách hàng
Actor	Người dùng, Quản trị viên
Tiền điều kiện	Có quyền `dl-khachhang.them` / `sua`.
Các bước	Bấm Thêm khách hàng (hoặc biểu tượng sửa trên dòng) ⇒ mở popup. Nhập mã, tên, mã số thuế, quốc gia, địa chỉ, liên hệ. Bấm Lưu.
Kết quả	Khách hàng được lưu, danh sách tải lại; thay đổi ghi Audit trail.
Quy tắc / validation	Mã 2–10 ký tự chữ / số, không đổi sau khi tạo (dùng ghép mã lô hàng). Mã số thuế: quốc gia VN (hoặc để trống quốc gia) phải gồm 10 chữ số hoặc 10 chữ số + “-” + 3 chữ số. Mã trùng (không phân biệt hoa thường) ⇒ báo trùng. Sửa đồng thời: bản gửi lên phải đúng phiên bản đang lưu (khóa lạc quan).
Thông báo lỗi chính	`E0001` “Tên không được để trống.” `E0005` “Mã đã tồn tại.” `E2006` “Mã số thuế phải gồm 10 chữ số, hoặc 10 chữ số kèm "-" và 3 chữ số chi nhánh.” `E2007` “Tên tối đa 255 ký tự.” `E0003` “Dữ liệu đã bị người khác thay đổi. Vui lòng tải lại rồi thử lại.”

UC-DM-03Thêm / sửa đối tác
Actor	Người dùng, Quản trị viên
Tiền điều kiện	Có quyền `dl-doitac.them` / `sua`.
Các bước	Bấm Thêm đối tác, chọn Loại đối tác (bảng KBN bên dưới). Nhập thông tin, tài khoản ngân hàng. Bấm Lưu.
Kết quả	Đối tác được lưu; chọn được ở kho bãi (đơn vị khai thác) và các module vận chuyển.
Quy tắc / validation	Loại đối tác bắt buộc, phải thuộc danh sách KBN `CATALOG_PARTNER_TYPE`. Mã tối đa 20 ký tự, không đổi sau khi tạo.
Thông báo lỗi chính	`E0001` “Loại đối tác không được để trống.” `E0004` “Loại đối tác không hợp lệ: ….” `E0005` “Mã đã tồn tại.”

UC-DM-04Quản lý cảng, kho bãi, tuyến
Actor	Quản trị viên
Tiền điều kiện	Có quyền thêm / sửa của màn Cảng, kho, tuyến.
Các bước	Tab Cảng: thêm cảng (mã UN/LOCODE vd VNHPH, hoặc mã IATA cho sân bay), chọn loại cảng, quốc gia. Tab Kho bãi: thêm kho, chọn loại kho, cảng / ICD gần, đơn vị khai thác (đối tác). Tab Tuyến: chọn cảng đi, cảng đến, thời gian vận chuyển (ngày).
Kết quả	Danh mục được lưu; tuyến tự có mã `<cảng đi>-<cảng đến>` (vd VNHPH-KRPUS), tên trống thì tự đặt “Cảng đi → Cảng đến”.
Quy tắc / validation	Cảng: mã 3–10 chữ / số, quốc gia bắt buộc (2 chữ cái ISO). Tuyến: cảng đi ≠ cảng đến; cảng đi / đến khóa sau khi tạo; thời gian vận chuyển 0–365 ngày.
Thông báo lỗi chính	`E2002` “Cảng đi và cảng đến phải khác nhau.” `E2008` “Thời gian vận chuyển phải trong khoảng 0 đến 365.” `E0005` “Mã đã tồn tại.”

UC-DM-05Quản lý loại phí, đơn vị tính
Actor	Quản trị viên
Tiền điều kiện	Có quyền thêm / sửa màn Loại phí & đơn vị tính.
Các bước	Tab Loại phí: nhập mã, tên, nhóm phí, ĐVT, tiền tệ, đơn giá mặc định, thuế VAT. Tab Đơn vị tính: nhập mã, tên.
Kết quả	Loại phí chọn được trên dòng phí báo giá (tự điền ĐVT, tiền tệ, đơn giá, VAT mặc định).
Quy tắc / validation	Nhóm phí bắt buộc (KBN `CATALOG_CHARGE_GROUP`). Đơn giá mặc định ≥ 0, tối đa 16 chữ số phần nguyên, 2 chữ số lẻ.
Thông báo lỗi chính	`E2009` “Đơn giá mặc định có tối đa 2 chữ số thập phân.” `E2008` “Đơn giá mặc định phải trong khoảng 0 đến 9999999999999999.99.”

UC-DM-06Quản lý tiền tệ và tỷ giá
Actor	Quản trị viên
Tiền điều kiện	Có quyền `dl-tiente.them/sua`; nhập tỷ giá cần `ty-gia`.
Các bước	Tab Tiền tệ: thêm mã 3 chữ cái (USD, EUR…), số lẻ hiển thị. Tab Tỷ giá: chọn tiền tệ, ngày hiệu lực, tỷ giá quy về VND.
Kết quả	Báo giá / chứng từ lấy tỷ giá có ngày hiệu lực gần nhất ≤ ngày chứng từ.
Quy tắc / validation	Tiền tệ gốc VND không nhập tỷ giá, không xóa được. Tỷ giá > 0, tối đa 12 chữ số nguyên, 6 chữ số lẻ. Số lẻ 0–4.
Thông báo lỗi chính	`E2004` “Tiền tệ gốc VND không cần nhập tỷ giá.” `E2003` “Không xóa được tiền tệ gốc VND.” `E2005` “Chưa có tỷ giá USD hiệu lực tại ngày 29/10/2026.”

UC-DM-07Xóa bản ghi danh mục
Actor	Quản trị viên (Hệ thống kiểm)
Tiền điều kiện	Có quyền Xóa của màn.
Các bước	Bấm biểu tượng xóa trên dòng. Xác nhận ở hộp thoại.
Kết quả	Bản ghi bị xóa mềm (ẩn khỏi danh sách, vẫn giữ lịch sử).
Quy tắc / validation	Bản ghi đang được dùng ở bản ghi khác (vd khách hàng đã có báo giá, cảng thuộc tuyến) ⇒ không xóa được.
Thông báo lỗi chính	`C0001` “Bạn có chắc muốn xóa khách hàng DEMOA?” `E2001` “Khách hàng DEMOA đang được dùng ở 3 bản ghi, không xóa được.”

UC-DM-08Ghi lịch sử thay đổi
Actor	Hệ thống
Tiền điều kiện	Có thao tác thêm / sửa / xóa thành công.
Các bước	Hệ thống so giá trị trước – sau từng trường. Ghi người sửa, thời điểm, trường, giá trị cũ / mới.
Kết quả	Tra được ở Audit trail.
Quy tắc / validation	Không ghi khi không có trường nào đổi.
Thông báo lỗi chính	—

4.Luồng màn hình

Mọi màn danh mục dùng chung một khung: danh sách + popup form. Không có sidebar ở module này.

Màn hìnhPopup (hộp thoại)Sidebar phảiThao tác chuyển mànHệ thống tự chuyển / quay về

Popup: form danh mục mở dạng popup giữa màn; bấm Hủy / dấu × để đóng không lưu. Lưu thành công thì popup đóng và danh sách tải lại; lỗi kiểm tra thì popup giữ nguyên, lỗi gắn dưới ô tương ứng.

5.Màn hình

Khách hàng

**Mobile 375px: lưới chuyển sang dạng thẻ, bộ lọc xếp dọc**

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Mã	Có	2–10 ký tự	Chữ không dấu hoặc số, tự viết HOA	Không đổi sau khi tạo; không trùng
Tên	Có	≤ 255	Văn bản
Mã số thuế	—	≤ 20	Quốc gia VN: 10 số hoặc 10 số-3 số	Quốc gia khác: tự do
Quốc gia (ISO 2)	—	2 ký tự	2 chữ cái, vd VN, KR	Mặc định VN
Địa chỉ	—	≤ 500	Văn bản
Điện thoại	—	≤ 50	Văn bản
Email	—	≤ 255	Dạng `ten@mien.vn`
Người liên hệ	—	≤ 255	Văn bản
Ghi chú	—	≤ 1000	Văn bản

Đối tác

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Mã	Có	≤ 20	Chữ không dấu, số, dấu `.` `_` `-`; bắt đầu bằng chữ hoặc số; tự viết HOA	Không đổi sau khi tạo
Tên	Có	≤ 255	Văn bản
Loại đối tác	Có	—	KBN `CATALOG_PARTNER_TYPE`	Xem bảng ở mục 6
Mã số thuế	—	≤ 50	Văn bản
Quốc gia (ISO 2)	—	2 ký tự	2 chữ cái	Mặc định VN
Địa chỉ	—	≤ 500
Điện thoại	—	≤ 50
Email	—	≤ 255	Dạng `ten@mien.vn`
Người liên hệ	—	≤ 255
Số tài khoản	—	≤ 50
Ngân hàng	—	≤ 255
Ghi chú	—	≤ 1000

Cảng, kho, tuyến

**Tab Cảng**
Thanh tab: Cảng · Kho bãi · Tuyến
Lọc theo loại cảng

Cảng

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Mã	Có	3–10 ký tự	Chữ / số, tự viết HOA	UN/LOCODE (VNSGN) hoặc IATA (SGN); không đổi sau khi tạo
Tên	Có	≤ 255
Loại cảng	Có	—	KBN `CATALOG_PORT_TYPE`
Quốc gia (ISO 2)	Có	2 ký tự	2 chữ cái
Thành phố	—	≤ 100
Ghi chú	—	≤ 1000

Kho bãi

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Mã	Có	≤ 20	Chữ không dấu, số, dấu `.` `_` `-`; bắt đầu bằng chữ hoặc số; tự viết HOA	Không đổi sau khi tạo
Tên	Có	≤ 255
Loại kho	Có	—	KBN `CATALOG_WAREHOUSE_TYPE`
Cảng / ICD gần	—	—	Chọn từ danh mục cảng
Đơn vị khai thác	—	—	Chọn từ danh mục đối tác
Địa chỉ	—	≤ 500
Điện thoại	—	≤ 50
Ghi chú	—	≤ 1000

Tuyến

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Cảng đi	Có	—	Chọn từ danh mục cảng	Khóa sau khi tạo
Cảng đến	Có	—	Chọn từ danh mục cảng; khác cảng đi	Khóa sau khi tạo
Tên	—	≤ 255		Trống ⇒ “Cảng đi → Cảng đến”
Thời gian vận chuyển (ngày)	—	0–365	Số nguyên
Ghi chú	—	≤ 1000

Loại phí & đơn vị tính

**Tab Đơn vị tính (cài sẵn: Cont 20/40, CBM, Kg, Tấn, Kiện, Bộ, Lô hàng, Vận đơn, Chuyến xe)**

Loại phí

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Mã	Có	≤ 20	Chữ không dấu, số, dấu `.` `_` `-`; bắt đầu bằng chữ hoặc số; tự viết HOA	Không đổi sau khi tạo
Tên	Có	≤ 255
Nhóm phí	Có	—	KBN `CATALOG_CHARGE_GROUP`
Đơn vị tính	—	—	Chọn từ tab Đơn vị tính	Mặc định khi thêm dòng phí báo giá
Tiền tệ	—	—	Chọn từ danh mục tiền tệ
Đơn giá mặc định	—	0 … 9.999.999.999.999.999,99	Số, ≤ 2 chữ số lẻ
Thuế VAT	—	—	KBN `CATALOG_VAT_RATE`
Ghi chú	—	≤ 1000

Đơn vị tính

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Mã	Có	≤ 20	Chữ không dấu, số, dấu `.` `_` `-`; bắt đầu bằng chữ hoặc số; tự viết HOA	Không đổi sau khi tạo
Tên	Có	≤ 100
Ghi chú	—	≤ 1000

Tiền tệ & tỷ giá

**Tab Tiền tệ — VND là tiền gốc (không có nút xóa)**

Tiền tệ

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Mã	Có	3 ký tự	Đúng 3 chữ cái (VND, USD)	Không đổi sau khi tạo
Tên	Có	≤ 100
Số lẻ	Có	0–4	Số nguyên	Số chữ số thập phân khi hiển thị tiền; mặc định 2

Tỷ giá

Tên trường	Bắt buộc	Độ dài / khoảng	Giá trị hợp lệ	Ghi chú
Tiền tệ	Có	—	Khác tiền gốc VND	Khóa sau khi tạo
Ngày hiệu lực	Có	—	Ngày
Tỷ giá (VND)	Có	0,000001 … 999.999.999.999,999999	Số, ≤ 6 chữ số lẻ
Ghi chú	—	≤ 500

Hai phía cùng kiểm: mọi ràng buộc trong các bảng trên được kiểm ngay trên form (báo lỗi dưới ô, khóa nút Lưu) và kiểm lại ở máy chủ; gửi dữ liệu sai thẳng vào hệ thống vẫn bị từ chối với thông báo gắn đúng ô.

6.Trạng thái & quy tắc

Danh mục không có vòng đời trạng thái; bản ghi chỉ có Đang dùng hoặc bị xóa mềm.

Mã phân loại (KBN)

Loại đối tác — CATALOG_PARTNER_TYPE

Mã	Nhãn hiển thị
`AGENT`	Đại lý (Agent)
`SHIPPING_LINE`	Hãng tàu
`AIRLINE`	Hãng hàng không
`CO_LOADER`	Co-loader / NVOCC
`TRUCKING`	Nhà xe (vận tải bộ)
`CUSTOMS_BROKER`	Đại lý hải quan
`WAREHOUSE`	Kho bãi
`OTHER`	Khác

Loại cảng — CATALOG_PORT_TYPE

Mã	Nhãn hiển thị
`SEA`	Cảng biển
`AIR`	Sân bay
`ICD`	Cảng cạn (ICD)
`BORDER`	Cửa khẩu

Loại kho — CATALOG_WAREHOUSE_TYPE

Mã	Nhãn hiển thị
`CFS`	Kho CFS
`DEPOT`	Bãi container
`BONDED`	Kho ngoại quan
`GENERAL`	Kho thường

Nhóm phí — CATALOG_CHARGE_GROUP

Mã	Nhãn hiển thị
`FREIGHT`	Cước vận chuyển (Freight)
`LOCAL_CHARGE`	Phí địa phương (Local charge)
`SURCHARGE`	Phụ phí (Surcharge)
`TRUCKING`	Vận tải nội địa (Trucking)
`CUSTOMS`	Thủ tục hải quan
`POB`	Chi hộ (Pay on behalf)
`OTHER`	Khác

Thuế VAT — CATALOG_VAT_RATE

Mã	Nhãn hiển thị
`0`	0%
`8`	8%
`10`	10%
`KCT`	Không chịu thuế

Quy tắc chung

Mã trùng kiểm không phân biệt hoa thường; mã khóa sau khi tạo.
Tỷ giá áp dụng = bản ghi tỷ giá của tiền tệ đó có ngày hiệu lực gần nhất và ≤ ngày chứng từ (ngày báo giá). Không có ⇒ E2005 “Chưa có tỷ giá USD hiệu lực tại ngày 29/10/2026.”.
Xóa: bản ghi đang được tham chiếu ⇒ E2001 “Cảng VNHPH đang được dùng ở 2 bản ghi, không xóa được.”.
Sửa trùng lúc với người khác ⇒ E0003 “Dữ liệu đã bị người khác thay đổi. Vui lòng tải lại rồi thử lại.”