Hướng dẫn sử dụng: Quản lý Phân cấp QR Tổng
Đường dẫn: Admin Panel → Quản lý QR Tổng → Phân cấp QRT
URL:/qrt-codes/hierarchy
1. Tổng quan
Trang Phân cấp QRT cho phép quản lý hệ thống mã QR Tổng (QRT) theo cấu trúc cây cha-con. QRT là lớp quản lý trung gian giữa Lô sản xuất và Tem QR1 (tem dán sản phẩm), giúp truy xuất nguồn gốc hàng hóa theo chuỗi:
Sản phẩm → Mẫu mã → Phiên bản → Lô SX → QRT (cấp 1→2→3...) → Tem QR1
Hai loại QRT
| Loại | Biểu tượng | Mô tả | Quản lý |
|---|---|---|---|
| Quản lý QRT con (ManagesQrt) | 📂 Xanh dương | QRT cha chứa QRT con bên trong | Các QRT cấp dưới |
| Quản lý QR1 (ManagesQr1) | 📱 Xanh lá | QRT lá chứa tem QR1 trực tiếp | Tem QR1 (stamps) |
2. Bảng thống kê tổng quan
Phía trên cùng trang hiển thị 4 card thống kê:
| Card | Ý nghĩa |
|---|---|
| Tổng QRT | Tổng số QRT trong hệ thống |
| Đã liên kết | Số QRT đã được gắn vào cây cha-con |
| Chưa gắn | Số QRT chưa có cha (root nodes hoặc orphan) |
| Đã niêm phong | Số QRT đã bị khóa (sealed) |
3. Giao diện chính
Trang chia làm 2 cột:
3.1. Cột trái — Cây phân cấp QRT
Hiển thị tất cả QRT dưới dạng cây (dạng cây):
- Mũi tên ▶/▼: Mở/đóng node con
- Icon loại QRT: Phân biệt ManagesQrt (📂) và ManagesQr1 (📱)
- Tên/Alias: Hiển thị alias nếu có, kèm mã rawData
- huy hiệu cấp: Cấp phân cấp (Level 1, 2, 3...)
- huy hiệu trạng thái: Nháp, Sẵn sàng, Đang dùng, Hoàn thành, Lưu trữ, Đã xóa
- huy hiệu niêm phong: 🔒 nếu đã niêm phong
- Số con: Hiển thị số node con / số lượng dự kiến
Thanh công cụ cây
| Nút | Chức năng |
|---|---|
| + Tạo QRT | Mở biểu mẫu tạo QRT mới |
| ⚙ Cấu hình cấp | Tùy chỉnh tên, icon, màu cho mỗi level |
| 🔄 Làm mới | Tải lại toàn bộ cây |
| 🔍 Lọc trạng thái | Ẩn/hiện QRT theo trạng thái (mặc định ẩn Đã xóa và Lưu trữ) |
| 📂 Mở tất cả | Mở toàn bộ cây |
| 📁 Đóng tất cả | Thu gọn toàn bộ cây |
3.2. Cột phải — Panel thao tác
Khi chọn một node QRT trên cây, panel bên phải hiện thông tin chi tiết và các nút thao tác.
Thông tin hiển thị
| Trường | Mô tả |
|---|---|
| ID | UUID của QRT (kèm nút sao chép) |
| Loại QRT | ManagesQrt hoặc ManagesQr1 |
| Cấp | Level + tên cấp tùy chỉnh |
| Lô SX | Tên lô sản xuất (link đến trang quản lý lô) hoặc "Chưa gắn lô" |
| Số con | Số con trực tiếp / dự kiến + tổng con cháu |
| Ngày tạo | Timestamp |
| Niêm phong | Trạng thái niêm phong + thời gian |
| Trạng thái | huy hiệu + thời gian đổi + lý do |
4. Các chức năng chi tiết
4.1. Tạo QRT mới
Nút: + Tạo QRT trên thanh công cụ cây
Biểu mẫu tạo bao gồm:
| Trường | Bắt buộc | Mô tả |
|---|---|---|
| QRT Cha | Không | Chọn QRT cha từ danh sách thả xuống. Nếu bỏ trống → tạo root QRT (cấp 1) |
| Loại QRT | Có | Quản lý QRT con hoặc Quản lý QR1 |
| Lô sản xuất | Không | Chọn lô từ danh sách thả xuống có tìm kiếm. Có thể bỏ trống |
| Alias | Không | Tên gợi nhớ cho QRT (VD: "Thùng A-001") |
| Nhãn cấp | Không | Nhãn tùy chỉnh thay cho tên mặc định (VD: "Thùng carton") |
| Số lượng con dự kiến | Không | Giới hạn số con tối đa |
Lưu ý:
- Hệ thống tự động sinh mã rawData (UUID) làm mã QRT
- Nếu chọn QRT cha, cấp sẽ tự động = cha + 1
- Lô sản xuất hỗ trợ tìm kiếm bằng cách gõ trực tiếp vào danh sách thả xuống
4.2. Xem chi tiết QRT
Nút: 👁 Xem chi tiết (nút đầu tiên trong panel thao tác)
Mở hộp thoại hiển thị đầy đủ thông tin QRT:
- Phần đầu: Icon loại + Alias + rawData + huy hiệu trạng thái & niêm phong
- ID: Full UUID với nút sao chép
- Mã QRT: Full rawData (font monospace) với nút sao chép
- Alias, Loại, Cấp, Lô SX: Hiện đầy đủ
- Số con: Con trực tiếp / dự kiến + tổng con cháu
- Ngày tạo, Niêm phong, Trạng thái: Chi tiết thời gian + lý do
Phần cuối hộp thoại:
Xem QR con— Chuyển đến trang danh sách con (nếu có)Lịch sử thao tác— Mở hộp thoại audit log
4.3. Đổi trạng thái
Nút: 🔄 Đổi trạng thái
Điều kiện: Không khả dụng nếu QRT đã bị xóa
Các trạng thái có thể chuyển:
| Trạng thái | huy hiệu | Mô tả |
|---|---|---|
| Nháp | Xám | Mới tạo, chưa sử dụng |
| Sẵn sàng (Sẵn sàng) | Xanh lam | Đã cấu hình xong, sẵn sàng dùng |
| Đang dùng (InUse) | Xanh dương | Đang trong quá trình sử dụng |
| Hoàn thành (Completed) | Xanh lá | Đã sử dụng xong |
| Lưu trữ (Archived) | Đen | Đã lưu kho |
| Đã xóa (Deleted) | Đỏ | Đã xóa mềm |
Lưu ý: Khi đổi trạng thái QRT cha, tất cả QRT con cũng được đổi theo.
4.4. Sửa thông tin
Nút: ✏️ Sửa thông tin
Điều kiện: Không khả dụng nếu QRT đã xóa hoặc đã lưu trữ
Có thể chỉnh sửa:
- Alias — Tên gợi nhớ
- Nhãn cấp — Tên cấp tùy chỉnh
- Số lượng con dự kiến — Giới hạn con tối đa
- Lý do chỉnh sửa — Ghi chú cho audit log
4.5. Gắn QRT con (Link)
Nút: 🔗 Gắn QRT con
Điều kiện: Không khả dụng nếu QRT đã niêm phong hoặc đã xóa
Quy trình:
- Nhấn
Gắn QRT con→ Mở hộp thoại danh sách QRT chưa có cha - Chọn ô tích một hoặc nhiều QRT cần gắn
- Nhấn
Liên kết→ Hệ thống tự động:- Gắn QRT con vào QRT cha được chọn
- Tự động điều chỉnh cấp (level) cho QRT con = cha + 1
- Tự động điều chỉnh cấp cho tất cả con cháu (đệ quy)
- Tự động đồng bộ lô nếu một bên chưa có lô
Quy tắc lô sản xuất:
- Cha có lô + Con chưa có → Con nhận lô của cha
- Cha chưa có + Con có lô → Cha nhận lô của con
- Cả hai có lô khác nhau → Chặn, không cho phép
4.6. Kéo thả (Kéo & Drop) — Chuyển QRT
Cách sử dụng:
- Giữ icon ⠿ (kéo handle) bên trái node QRT
- Di chuyển 8px để kích hoạt kéo thả (tránh xung đột với nhấn)
- Kéo đến node QRT đích → Thả ra
- Nhập lý do di chuyển → Xác nhận
Quy tắc tự động:
- Auto-Level: Cấp QRT con tự động được điều chỉnh = cấp cha đích + 1, và đệ quy cho tất cả con cháu
- Auto-Lot: Nếu một bên chưa có lô → tự động gán theo bên kia
Các trường hợp bị chặn:
| Trường hợp | Lý do |
|---|---|
| Thả lên chính nó | Vô nghĩa |
| Thả lên con cháu của chính nó | Tạo vòng lặp |
| Node đích đã niêm phong | Không thể thêm con vào node sealed |
| Node đích đã xóa | Node đã xóa không nhận con |
| Node đích đã đạt giới hạn con | Vượt quá expectedChildCount |
| Cả hai có lô khác nhau | Vi phạm tính nhất quán truy xuất |
| Node nguồn đã niêm phong/xóa | Không thể kéo node bị khóa |
4.7. Niêm phong / Mở niêm phong
Nút: 🔒 Niêm phong hoặc 🔓 Mở niêm phong
Điều kiện: Không khả dụng nếu QRT đã xóa
Niêm phong:
- Khóa QRT, không cho phép thêm/bớt con hoặc kéo thả
- Lý do niêm phong: tùy chọn
- QRT con cũng bị ảnh hưởng (không thể kéo ra)
Mở niêm phong:
- Yêu cầu nhập lý do bắt buộc
- Mở khóa QRT cho phép chỉnh sửa lại
4.8. Xem danh sách QR con
Nút: 📋 Xem N QR con (chỉ hiện khi có con > 0)
Chuyển hướng đến trang /qrt-codes/{id}/children hiển thị:
- Tab QRT con: Danh sách QRT con trực tiếp (nếu là ManagesQrt), cho phép drill-down
- Tab Tem QR1: Danh sách tem QR1 (nếu là ManagesQr1), với đầy đủ tính năng:
- Xem chi tiết tem (traceability chain)
- Xem trước nhãn
- Lịch sử trạng thái
- Xem hành trình sản phẩm
- Thu hồi tem
4.9. Xem lịch sử thao tác (Audit Log)
Nút: 📜 Xem lịch sử
Mở hộp thoại hiển thị tất cả thao tác đã thực hiện trên QRT, được trình bày dưới dạng dễ đọc (thay vì JSON thô):
| Hành động | Icon | Màu | Mô tả hiển thị |
|---|---|---|---|
| Tạo | ➕ | Xanh lá | "Tạo QRT mới" + chi tiết alias, loại, cấp |
| Link | 🔗 | Xanh dương | "Gắn QRT con" + ID con |
| Unlink | ✂️ | Cam | "Gỡ liên kết" + ID con + lý do |
| Seal | 🔒 | Đỏ | "Niêm phong" + lý do |
| Unseal | 🔓 | Vàng | "Mở niêm phong" + lý do |
| StatusChange | 🔄 | Tím | "Đổi trạng thái" + trạng thái cũ → mới + lý do |
| Cập nhật | ✏️ | Xanh nhạt | "Cập nhật thông tin" + lý do |
| Reassign | 🔀 | Xám | "Di chuyển sang cha mới" + ID cha mới + lý do |
Mỗi entry hiển thị: icon + huy hiệu hành động + mô tả chi tiết + timestamp + người thực hiện.
4.10. Xóa hẳn QRT
Nút: 🗑️ Xóa hẳn (chỉ hiện khi thỏa điều kiện)
Điều kiện cần đáp ứng ĐỒNG THỜI:
- QRT ở trạng thái Sẵn sàng (Sẵn sàng)
- QRT không có node con nào
- QRT chưa niêm phong
Lưu ý: Thao tác xóa hẳn không thể hoàn tác. QRT sẽ bị xóa vĩnh viễn khỏi database.
4.11. Lọc theo trạng thái
Nút: 🔍 (danh sách thả xuống lọc) trên thanh công cụ cây
Cho phép ẩn/hiện QRT theo từng trạng thái bằng ô tích:
- Mặc định hiện: Nháp, Sẵn sàng, Đang dùng, Hoàn thành
- Mặc định ẩn: Đã xóa, Đã lưu trữ
Bộ lọc hoạt động trên client-side (không gọi API), áp dụng đệ quy cho toàn bộ cây.
4.12. Cấu hình cấp phân cấp
Nút: ⚙ Cấu hình cấp trên thanh công cụ cây
Cho phép tùy chỉnh hiển thị cho từng cấp (Level):
| Trường | Mô tả | Ví dụ |
|---|---|---|
| Cấp | Số level | 1, 2, 3... |
| Tên cấp | Tên hiển thị | "Pallet", "Thùng", "Hộp" |
| Icon CSS | Class icon Remix | ri-stack-line |
| Màu | Mã hex | #0d6efd |
| Sức chứa mặc định | Số con mặc định khi tạo mới | 24 |
Các cấu hình đã lưu hiển thị trong bảng bên dưới biểu mẫu. Cấu hình áp dụng cho toàn bộ tổ chức.
5. Quy tắc nghiệp vụ quan trọng
5.1. Tự động điều chỉnh cấp (Auto-Level)
Khi gắn hoặc di chuyển QRT, hệ thống tự động điều chỉnh:
- Cấp QRT con = Cấp QRT cha + 1
- Đệ quy cho tất cả con cháu
- Không cần can thiệp thủ công
Ví dụ:
QRT A (Cấp 1) ← kéo QRT B (Cấp 3) vào đây
→ QRT B tự động chuyển thành Cấp 2
→ Các con của QRT B tự động chuyển thành Cấp 3, 4...
5.2. Tự động đồng bộ lô (Auto-Lot)
Khi gắn hoặc di chuyển QRT:
- Cha có lô, Con chưa có → Con tự động nhận lô của cha
- Con có lô, Cha chưa có → Cha tự động nhận lô của con
- Cả hai đều có lô khác nhau → ❌ Chặn, hiển thị lỗi
- Cả hai đều chưa có lô → Cho phép, không gán lô
5.3. Niêm phong lan truyền
QRT đã niêm phong:
- Không thể kéo thả
- Không thể nhận node con mới
- Không thể bị kéo đi
- Cần mở niêm phong (với lý do) trước khi thao tác
5.4. Trạng thái ảnh hưởng con
Khi đổi trạng thái QRT cha → tất cả QRT con cũng bị đổi theo.
6. Hướng dẫn ngữ cảnh
Trang QRT Hierarchy có hệ thống dấu "?" hướng dẫn nhỏ bên cạnh các nút và tùy chọn. Rê chuột vào "?" sẽ hiện chú thích giải thích chức năng.
Bật/Tắt hướng dẫn
Vào Hồ sơ (/profile) → tab Cài đặt → công tắc "Hướng dẫn sử dụng":
- Bật: Hiển thị dấu "?" trên tất cả trang quản lý
- Tắt: Ẩn toàn bộ dấu "?" để giao diện gọn hơn
Mẹo: Khi mới bắt đầu sử dụng, hãy bật tính năng này. Sau khi thành thạo, tắt đi cho gọn.
7. Phím tắt và mẹo sử dụng
| Thao tác | Cách dùng |
|---|---|
| Chọn nhanh | Nhấn vào node trên cây |
| Mở/đóng node | Nhấn mũi tên ▶/▼ |
| Kéo thả | Giữ icon ⠿ rồi kéo (cần di 8px trước khi kích hoạt) |
| Sao chép ID | Nhấn nút 📋 bên cạnh ID trong panel info |
| Tìm kiếm lô | Gõ trực tiếp vào danh sách thả xuống lô khi tạo QRT |
| Mở tất cả | Nhấn nút 📂 trên thanh công cụ cây |
8. Xử lý lỗi thường gặp
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
| "Không thể di chuyển: khác lô" | QRT cha và con thuộc lô khác nhau | Thay đổi lô cho một bên trước |
| "Node đích đã niêm phong" | QRT đích bị sealed | Mở niêm phong QRT đích trước |
| "Đã đạt giới hạn N con" | Vượt quá expectedChildCount | Tăng số lượng dự kiến hoặc chọn node khác |
| "Không thể di chuyển vào node con cháu" | Tạo vòng lặp | Chọn node đích khác (không phải là con cháu) |
| Nút "Xóa hẳn" không hiện | QRT không ở trạng thái Sẵn sàng, hoặc còn con, hoặc đã sealed | Đáp ứng đủ 3 điều kiện trước |
9. API Backend liên quan
| Endpoint | Method | Mô tả |
|---|---|---|
QrtCodes/Create |
POST | Tạo QRT mới |
QrtCodes/Update/{id} |
PUT | Cập nhật thông tin QRT |
QrtCodes/ChangeStatus |
POST | Đổi trạng thái |
QrtCodes/GetHierarchy/{id} |
GET | Lấy cây phân cấp từ 1 node |
QrtCodes/GetChildren/{id} |
GET | Lấy danh sách con trực tiếp |
QrtCodes/LinkChild |
POST | Gắn 1 QRT con |
QrtCodes/LinkChildren |
POST | Gắn nhiều QRT con |
QrtCodes/UnlinkChild |
POST | Gỡ liên kết QRT con |
QrtCodes/ReassignChild |
POST | Di chuyển QRT sang cha mới |
QrtCodes/Seal/{id} |
POST | Niêm phong |
QrtCodes/Unseal/{id} |
POST | Mở niêm phong |
QrtCodes/HardDelete/{id} |
Xóa | Xóa hẳn |
QrtCodes/AuditLog/{id} |
GET | Lịch sử thao tác |
QrtCodes/HierarchyStats |
GET | Thống kê tổng quan |
QrtCodes/GetAvailableChildren |
GET | QRT chưa có cha |
QrtCodes/GetAvailableParents |
GET | QRT có thể làm cha |
QrtCodes/LevelConfigs |
GET/POST | Cấu hình cấp phân cấp |
Cập nhật lần cuối: 26/03/2026
Phiên bản: Admin Panel - CheckPro VN