Import vị trí kho
Nhập liệu hàng loạt vị trí kho từ file Excel, tự động mapping nhà kho theo mã hoặc tên.
Tính năng Import vị trí kho cho phép thêm hàng loạt vị trí kho từ file Excel (.xls, .xlsx) hoặc CSV. Hệ thống sẽ tự động tìm nhà kho dựa trên mã kho hoặc tên kho, giúp tiết kiệm thời gian khi cần tạo nhiều vị trí kho cùng lúc.
Giao diện tổng thể
- Chức năng import nằm ở cuối bảng danh sách trong trang Vị trí kho (menu Quản lý kho > Vị trí kho).
- Nhấn nút Import từ file Excel (.xlsx, .xls) để mở hộp thoại chọn file.
- Hệ thống sẽ đọc file, tự động mapping các cột, và cho phép bạn xem trước dữ liệu trước khi import.
Định dạng file import
File import có thể là Excel (.xls, .xlsx) hoặc CSV (.csv). Mỗi dòng trong file tương ứng với một vị trí kho cần thêm.
Các cột trong file Excel
| Tên cột | Bắt buộc | Mô tả | Mã code |
|---|---|---|---|
| Kho | Có | Mã kho hoặc tên kho. Hệ thống sẽ ưu tiên tìm theo mã kho trước, sau đó tên kho | warehouse |
| Mã vị trí | Có | Mã định danh duy nhất cho vị trí kho | code |
| Tên vị trí | Không | Tên mô tả vị trí kho | name |
| Loại vị trí | Không | Loại vị trí: Lưu kho, Nhập hàng, Đóng gói, Hàng trả, Hàng lỗi. Mặc định: Lưu kho | type |
| Điều kiện bảo quản | Không | Điều kiện: Kho thường, Kho lạnh, Kho đông. Mặc định: Kho thường | condition |
| Trạng thái | Không | Có hiệu lực hoặc Vô hiệu lực. Mặc định: Có hiệu lực | status |
| Ghi chú | Không | Ghi chú bổ sung cho vị trí kho | note |
Tên cột trong file không cần khớp chính xác. Hệ thống hỗ trợ nhận diện tên cột tương tự (synonyms). Ví dụ: cột "Nhà kho", "Tên kho", "Mã kho" sẽ được tự động mapping thành cột Kho.
Danh sách tên cột tương đương (synonyms)
| Cột | Tên tương đương được nhận diện |
|---|---|
| Kho | Kho, Nhà kho, Tên kho, Mã kho, Warehouse |
| Mã vị trí | Mã, Mã vị trí, Location Code, Code |
| Tên vị trí | Tên, Tên vị trí, Location Name, Name |
| Loại vị trí | Loại, Loại vị trí, Type |
| Điều kiện bảo quản | Điều kiện, Điều kiện bảo quản, Bảo quản, Condition |
| Trạng thái | Trạng thái, Status |
| Ghi chú | Ghi chú, Note |
Quy tắc tìm nhà kho
Đây là tính năng quan trọng nhất của import vị trí kho. Cột Kho trong file Excel có thể nhập bằng mã kho hoặc tên kho, hệ thống sẽ tự động tìm nhà kho phù hợp theo thứ tự ưu tiên:
- Ưu tiên 1 – Tìm theo mã kho: So khớp chính xác giá trị trong cột với Mã nhà kho (không phân biệt hoa thường).
- Ưu tiên 2 – Tìm theo tên kho: So khớp chính xác giá trị trong cột với Tên nhà kho (không phân biệt hoa thường).
- Ưu tiên 3 – Tìm tương đối theo tên kho: Tìm nhà kho có tên chứa giá trị nhập vào hoặc ngược lại.
Ví dụ: Nếu nhà kho có Mã = WS02 và Tên = Kho Bình Thạnh, bạn có thể nhập một trong các giá trị sau vào cột Kho:
WS02→ Tìm theo mã kho ✅Kho Bình Thạnh→ Tìm theo tên kho ✅Bình Thạnh→ Tìm tương đối theo tên ✅
Nếu không tìm thấy nhà kho phù hợp, dòng đó sẽ bị bỏ qua và hiển thị cảnh báo kèm số dòng trong file Excel.
File mẫu tải về
Tải file Excel mẫu để tham khảo định dạng cột và dữ liệu. Tải về, chỉnh sửa theo nhu cầu rồi dùng để import.
| File mẫu | Mô tả |
|---|---|
| warehouselocation_import_template.xlsx | File mẫu import vị trí kho với các cột Kho, Mã vị trí, Tên vị trí, Loại, Điều kiện bảo quản. |
Các bước import
- Truy cập menu Quản lý kho > Vị trí kho.
- Cuộn xuống cuối bảng danh sách, nhấn nút Import từ file Excel (.xlsx, .xls).
- Chọn file Excel hoặc CSV từ máy tính.
- Hệ thống hiển thị bảng mapping cột – kiểm tra và điều chỉnh mapping nếu cần.
- Nhấn Xử lý để bắt đầu import.
- Hệ thống hiển thị kết quả: số lượng thành công và lỗi (nếu có).
- Danh sách vị trí kho sẽ tự động refresh sau khi import hoàn tất.
Ví dụ file Excel mẫu
| Kho | Mã vị trí | Tên vị trí | Loại vị trí | Điều kiện bảo quản | Trạng thái | Ghi chú |
|---|---|---|---|---|---|---|
| 47216 | KV-HO-01 | Kệ A1 tầng 1 | Lưu kho | Kho thường | Có hiệu lực | Khu vực A tầng 1 |
| Kho HO | KV-HO-03 | Kệ B1 tầng 2 | Đóng gói | Kho thường | Có hiệu lực | Khu vực B tầng 2 |
| WS02 | KV-BT-01 | Kệ trên cùng | Lưu kho | Kho thường | Có hiệu lực | Tầng 1 |
| Kho Bình Thạnh | KV-BT-02 | Kệ dưới cùng | Hàng trả | Kho lạnh | Có hiệu lực | Tầng 1 |
| WH01 | KV-Q10-01 | Kệ chính | Lưu kho | Kho đông | Có hiệu lực | Khu vực chính |
Trong ví dụ trên, cột Kho được nhập bằng cả mã kho (47216, WS02, WH01) lẫn tên kho (Kho HO, Kho Bình Thạnh). Hệ thống sẽ tự động resolve đúng nhà kho tương ứng.
Quy tắc xử lý giá trị
Loại vị trí
| Giá trị nhập | Kết quả |
|---|---|
Lưu kho hoặc Storage | Lưu kho |
Nhập hàng hoặc Receiving | Nhập hàng |
Đóng gói hoặc Packing | Đóng gói |
Hàng trả hoặc Return | Hàng trả |
Hàng lỗi hoặc Damage | Hàng lỗi |
| Để trống | Mặc định: Lưu kho |
Điều kiện bảo quản
| Giá trị nhập | Kết quả |
|---|---|
Kho thường hoặc Normal | Kho thường |
Kho lạnh hoặc Chill | Kho lạnh |
Kho đông hoặc Frozen | Kho đông |
| Để trống | Mặc định: Kho thường |
Trạng thái
| Giá trị nhập | Kết quả |
|---|---|
Có hiệu lực hoặc Enable | Có hiệu lực |
Vô hiệu lực hoặc Disable | Vô hiệu lực |
| Để trống | Mặc định: Có hiệu lực |
Giới hạn
- Tối đa 500 dòng mỗi lần import. Nếu file có nhiều hơn 500 dòng, chỉ 500 dòng đầu tiên được xử lý, các dòng còn lại bị bỏ qua.
Danh sách lỗi
Import vị trí kho trải qua 2 giai đoạn xác thực: Frontend (resolve dữ liệu từ file Excel) và Backend (validate dữ liệu trước khi lưu). Dưới đây là danh sách đầy đủ các lỗi có thể xảy ra.
Lỗi Frontend (xử lý trên giao diện)
Các lỗi này xảy ra khi hệ thống đọc file Excel và resolve dữ liệu. Dòng bị lỗi sẽ không gửi lên server.
| Mã lỗi | Thông báo | Nguyên nhân | Cách khắc phục |
|---|---|---|---|
error_warehouse_id_required | Kho không được để trống (Dòng X) | Cột Kho để trống hoặc không có giá trị | Điền mã kho hoặc tên kho |
error_warehouse_not_found | Không tìm thấy kho '[tên/mã]' (Dòng X) | Giá trị cột Kho không khớp với bất kỳ nhà kho nào (theo mã chính xác, tên chính xác hoặc tên tương đối) | Kiểm tra lại mã/tên kho. Xem Quy tắc tìm nhà kho |
error_code_required | Mã vị trí không được để trống (Dòng X) | Cột Mã vị trí để trống | Điền mã định danh cho vị trí kho |
warning_max_rows | File có {total} dòng, chỉ xử lý {max} dòng đầu tiên | File Excel có hơn 500 dòng | Chia nhỏ file thành nhiều lần import, mỗi lần tối đa 500 dòng |
no_import_data | Không có dữ liệu để import | Tất cả các dòng đều bị lỗi, không có dòng nào hợp lệ | Kiểm tra lại toàn bộ file Excel |
Lỗi Backend (xử lý trên server)
Các lỗi này xảy ra khi server nhận dữ liệu đã resolve và validate lần cuối trước khi lưu vào database.
| Mã lỗi | Nguyên nhân | Cách khắc phục |
|---|---|---|
error_empty_items | Danh sách items gửi lên server rỗng | Đảm bảo file Excel có ít nhất 1 dòng dữ liệu hợp lệ |
error_code_required | Mã vị trí (code) trống hoặc chỉ có khoảng trắng | Điền mã vị trí kho vào cột tương ứng |
error_warehouse_id_required | warehouse_id = 0 hoặc không có | Lỗi resolve kho ở frontend – kiểm tra lại mã/tên kho |
error_warehouse_id_to_invalid | warehouse_id có giá trị nhưng không tồn tại trong hệ thống (có thể đã bị xoá) | Kiểm tra nhà kho vẫn còn tồn tại và chưa bị xoá |
error_add | Dòng dữ liệu hợp lệ nhưng không thể lưu vào database (lỗi hệ thống) | Thử lại hoặc liên hệ quản trị viên |
Lỗi logic (không hiển thị cảnh báo nhưng ảnh hưởng dữ liệu)
| Tình huống | Hành vi hệ thống | Lưu ý |
|---|---|---|
| Loại vị trí không hợp lệ | Giá trị không nằm trong danh sách loại vị trí → tự động fallback về Lưu kho (Storage) | Hệ thống không báo lỗi. Kiểm tra cột loại vị trí sau import |
| Điều kiện bảo quản không hợp lệ | Giá trị không nằm trong danh sách → tự động fallback về Kho thường (Normal) | Hệ thống không báo lỗi. Kiểm tra cột điều kiện sau import |
| Trạng thái không hợp lệ | Giá trị không nhận diện được → mặc định Có hiệu lực | Xem Quy tắc xử lý giá trị để biết các giá trị được chấp nhận |
Lỗi chung (file Excel)
| Lỗi | Nguyên nhân | Cách khắc phục |
|---|---|---|
| File không đọc được | File bị hỏng, sai định dạng hoặc không có dòng tiêu đề | Kiểm tra file có đuôi .xls, .xlsx hoặc .csv. Đảm bảo dòng đầu tiên là tiêu đề cột |
| Cột không được nhận diện | Tên cột trong file không nằm trong danh sách synonyms | Đổi tên cột theo danh sách tên cột tương đương |
Cách đọc lỗi: Khi import thất bại, hệ thống hiển thị số dòng trong file Excel (bắt đầu từ dòng 2, vì dòng 1 là tiêu đề). Ví dụ: "Dòng 5" tương ứng với dòng thứ 5 trong file Excel (dữ liệu dòng thứ 4).
Phân quyền
- Xem vị trí kho: Cần quyền Xem kho hàng (
inventory.view). - Import vị trí kho: Cần quyền Quản lý kho hàng (
inventory.manage).