Hướng dẫn Quản lý Mẫu mã & Phiên bản (Web Admin)

Đối tượng: Business Admin
Route: /products/{id}/variants + /products/variants
Cập nhật: 2026-04-21

1. Khái niệm

Mẫu mã là gì?

Mẫu mã đại diện cho biến thể đóng gói của sản phẩm. Ví dụ một sản phẩm nước giải khát có thể có:

• DEFAULT — Mẫu mặc định
• 500ML — Chai 500ml
• HOP-12 — Hộp 12 lon

Phiên bản là gì?

Phiên bản theo dõi lịch sử thay đổi nội dung bên trong mỗi mẫu mã. Ví dụ:

• r1.0 — Nguyên bản (tạo khi thêm sản phẩm)
• r1.1 — Đổi bao bì Tết 2026
• r2.0 — Thay đổi công thức mới

Tại sao cần phân biệt?

2. Truy cập quản lý mẫu mã

Cách 1: Từ trang sản phẩm

1. Vào trang chỉnh sửa sản phẩm (/products/{id}/edit)
2. Nhấn nút "Mẫu mã" → chuyển đến /products/{id}/variants

Cách 2: TreeView tổng quan

1. Từ thanh bên → Sản phẩm → Mẫu mã (/products/variants)
2. Giao diện cây thư mục 3 cấp: Sản phẩm → Mẫu mã → Phiên bản
3. Nhấn vào sản phẩm để mở rộng danh sách mẫu mã (lazy-load)
4. Nhấn vào mẫu mã để mở rộng danh sách phiên bản

3. Quản lý Mẫu mã

3.1. Danh sách mẫu mã

Giao diện bảng hiển thị:

3.2. Thêm mẫu mã mới

1. Nhấn nút "+ Thêm mẫu mã"
2. Điền thông tin trong hộp thoại:

1. Nhấn "Lưu"

Lưu ý: Mã mẫu (Code) phải duy nhất trong cùng sản phẩm. Nếu trùng, hệ thống báo lỗi.

3.3. Sửa mẫu mã

1. Nhấn nút ✏️ Sửa trên dòng mẫu mã
2. hộp thoại mở ra — trường Mã mẫu bị khóa (không cho sửa)
3. Chỉnh sửa các trường khác rồi nhấn "Lưu"

3.4. Đặt mẫu mã mặc định

1. Nhấn nút ⭐ Đặt mặc định trên dòng mẫu mã muốn đặt
2. Hệ thống tự động bỏ mặc định của mẫu mã cũ
3. Chỉ có đúng 1 mẫu mã mặc định per sản phẩm

Điều kiện: Chỉ mẫu mã đang Hoạt động mới có thể đặt làm mặc định.

3.5. Bật/tắt mẫu mã

• Tạm ngừng: danh sách thả xuống trạng thái → "Tạm ngừng". Mẫu mã không thể tạo lô mới.
• Kích hoạt lại: danh sách thả xuống → "Đang kinh doanh"

4. Quản lý Phiên bản

4.1. Xem danh sách phiên bản

1. Nhấn nút 🌿 Xem revisions trên dòng mẫu mã
2. Hoặc từ TreeView, nhấn vào mẫu mã
3. Chuyển đến trang /products/{productId}/variants/{variantId}

Bảng phiên bản hiển thị:

4.2. Thêm phiên bản mới

1. Nhấn "+ Thêm phiên bản"
2. Điền thông tin:

1. Nhấn "Lưu" → phiên bản mới ở trạng thái Bản nháp

4.3. Sao chép phiên bản (Clone)

Khi tạo phiên bản mới, có thể sao chép nội dung từ phiên bản có sẵn:

1. Trong hộp thoại tạo phiên bản, chọn danh sách thả xuống "Sao chép từ phiên bản"
2. Chọn revision nguồn (VD: r1.0)
3. Hệ thống tự động sao chép:
   • ✅ Thành phần (ingredients)
   • ✅ Thông số kỹ thuật (specifications)
   • ⚠️ Ảnh được kế thừa (không sao chép file, hiển thị chuỗi ảnh từ gốc)
4. Các trường sau KHÔNG sao chép: Loại thay đổi, Tóm tắt, Lý do, Ngày hiệu lực

4.4. Sửa phiên bản

Điều kiện:

• Trạng thái = Bản nháp
• Chưa bị Khóa 🔒

Nếu đủ điều kiện:

1. Nhấn ✏️ Sửa → hộp thoại mở ra
2. Chỉnh sửa thông tin
3. Nhấn "Lưu"

⚠️ Phiên bản bị khóa khi có Lô sản xuất gắn vào. Dữ liệu đã gắn QR không thể thay đổi để bảo vệ tính toàn vẹn truy xuất nguồn gốc.

4.5. Phát hành phiên bản

1. Trên dòng phiên bản Bản nháp, nhấn nút 📤 Phát hành
2. Hệ thống:
   • Chuyển trạng thái: Bản nháp → Đã đăng
   • Tự động đặt phiên bản này là Hiện tại
   • Phiên bản cũ vẫn giữ Đã đăng nhưng không còn là "Hiện tại"
3. Phiên bản Đã đăng mới sẽ được sử dụng khi tạo lô sản xuất

4.6. Ngừng áp dụng phiên bản

1. Trên dòng phiên bản Đã phát hành, nhấn nút 📥 Ngừng áp dụng
2. Hệ thống:
   • Chuyển trạng thái: Đã đăng → Ngừng dùng
   • Tự động gán "Hiện tại" cho phiên bản Đã đăng gần nhất (nếu có)

4.7. Phát hành lại phiên bản

1. Trên dòng phiên bản Ngừng áp dụng, nhấn 🔄 Phát hành lại
2. Phiên bản quay lại Đã đăng và trở thành "Hiện tại"

5. Tổng hợp trạng thái

Mẫu mã

Đang kinh doanh ←→ Tạm ngừng → Lưu trữ (Archived)

Phiên bản

Bản nháp → Đã phát hành ←→ Ngừng áp dụng
                         ↓
                   Hiện tại = true (tự động)
                         ↓
                   Khóa = true (khi có Lô gắn)

6. Ảnh theo mẫu mã

Ảnh kế thừa (Inherited Images)

Khi clone phiên bản, ảnh không được sao chép mà được kế thừa qua chuỗi clone:

r1.0 (có 3 ảnh)
  ↓ clone
r1.1 (kế thừa 3 ảnh từ r1.0 + có thể upload thêm)
  ↓ clone
r1.2 (kế thừa tất cả ảnh từ r1.0 + r1.1)

Quản lý ảnh kế thừa:

• Ẩn ảnh: Nhấn nút ẩn bên cạnh ảnh kế thừa → ảnh không hiển thị cho phiên bản này nhưng không bị xóa ở phiên bản gốc
• Khôi phục ảnh: Nhấn nút khôi phục → ảnh đã ẩn hiện lại
• Xóa ảnh: Chỉ xóa được ảnh do chính phiên bản này tải lên (ảnh kế thừa chỉ ẩn, không xóa)

7. Câu hỏi thường gặp

Q: Khi nào phiên bản bị khóa?
A: Khi có lô sản xuất gắn vào phiên bản đó. Mục đích: bảo vệ dữ liệu truy xuất nguồn gốc — thông tin đã in trên tem QR không được phép thay đổi.

Q: Tôi có thể xóa mẫu mã mặc định không?
A: Không. Mỗi sản phẩm luôn có đúng 1 mẫu mã mặc định. Bạn có thể tạo mẫu mã mới rồi chuyển mặc định sang mẫu mã đó.

Q: Tôi tạo nhầm phiên bản, sửa lại được không?
A: Nếu phiên bản còn ở trạng thái Bản nháp và chưa bị khóa, bạn có thể sửa thoải mái. Sau khi phát hành, không sửa được nữa.

Q: Ảnh mẫu mã hiển thị ở đâu?
A: Ảnh mẫu mã hiển thị trong:

• Tab Hình ảnh trên trang Sửa sản phẩm (khung vĩnh xanh lá)
• Trang chi tiết sản phẩm (lọc theo variant)
• Trang quét QR cho người tiêu dùng