Thu hồi Sản phẩm (Product Recall)

Hệ thống thu hồi sản phẩm cho phép cơ quan quản lý (Gov) ra lệnh thu hồi, doanh nghiệp xác nhận, và người tiêu dùng nhận cảnh báo khi quét mã.

Tổng quan luồng

Cơ quan quản lý (Gov)          Doanh nghiệp (Enterprise)         Đại lý + Người tiêu dùng
        │                              │                                │
  1. Phát hiện vi phạm                 │                                │
  2. Nhấn "Cảnh báo"                  │                                │
  3. Gửi yêu cầu recall ──────►  4. Nhận thông báo                    │
        │                         5. Xem chi tiết                      │
        │                         6. Xác nhận / Từ chối                │
        │                              │                                │
        │                      [Nếu XÁC NHẬN]                          │
        │                         7. Toàn bộ tem → RECALLED ───►  8. Đại lý nhận thông báo
        │                              │                           9. Quét mã → Banner đỏ

Vai trò trong quy trình

Vai trò	Quyền	Mô tả
Gov (Cơ quan quản lý)	Gửi yêu cầu recall	Xem dashboard, nhấn "Cảnh báo" trên sản phẩm vi phạm
TENANT_ADMIN	Xác nhận / Từ chối	Xem yêu cầu thu hồi, quyết định xác nhận hoặc từ chối
DEALER	Nhận thông báo	Nhận thông báo ngừng bán sản phẩm bị thu hồi
Người tiêu dùng	Xem cảnh báo	Quét QR thấy banner cảnh báo đỏ

1. Cơ quan quản lý gửi yêu cầu thu hồi

Đường dẫn: /gov/dashboard

Thao tác

Truy cập Gov Dashboard
Tìm sản phẩm trong bảng "Sản phẩm tiêu biểu"
Nhấn nút "Cảnh báo" (màu đỏ)
Xác nhận trong popup → Hệ thống gửi yêu cầu

API Backend

POST /api/gov/products/:id/recall-request
Body: { "reason": "Phát hiện vi phạm tiêu chuẩn chất lượng" }

Kết quả

Sản phẩm chuyển sang govStatus = PENDING_RECALL
Thông báo RECALL được gửi đến toàn bộ TENANT_ADMIN của doanh nghiệp

2. Doanh nghiệp xử lý yêu cầu thu hồi

Đường dẫn: /supply/recalls

Quản lý Thu hồi

Thống kê

Thẻ	Mô tả
Chờ xác nhận	Số sản phẩm đang chờ doanh nghiệp xử lý
Đã thu hồi	Số sản phẩm đã xác nhận thu hồi
Đã từ chối	Số sản phẩm đã từ chối thu hồi

Bảng danh sách

Cột	Mô tả
Sản phẩm	Tên + Mã sản phẩm
Trạng thái	⏳ Chờ xác nhận / 🚨 Đã thu hồi / ✅ Đã từ chối
Lý do thu hồi	Lý do từ cơ quan quản lý
Ngày yêu cầu	Thời điểm nhận yêu cầu
Ngày xử lý	Thời điểm xác nhận hoặc từ chối
Thao tác	Xác nhận Thu hồi / Từ chối

Xác nhận Thu hồi

Nhấn "Xác nhận Thu hồi" (nút đỏ)
Đọc cảnh báo: "Tất cả tem Active và đang tại đại lý sẽ bị chuyển sang RECALLED"
Nhấn "Thu hồi ngay"

Kết quả:

govStatus → RECALLED
Toàn bộ tem Active + AT_DEALER → RECALLED
Đại lý nhận thông báo ngừng bán
Người tiêu dùng quét QR sẽ thấy banner cảnh báo đỏ

Từ chối Thu hồi

Nhấn "Từ chối" (nút xanh)
Nhập lý do từ chối (bắt buộc)
Nhấn "Gửi"

Kết quả:

govStatus → RECALL_REJECTED
Cơ quan quản lý sẽ thấy lý do từ chối trên Dashboard

3. Trạng thái vòng đời Thu hồi

NORMAL ──► PENDING_RECALL ──┬──► RECALLED
                            │
                            └──► RECALL_REJECTED

Trạng thái	Badge	Ý nghĩa
`NORMAL`	🟢 Bình thường	Sản phẩm hoạt động bình thường
`PENDING_RECALL`	🟡 Chờ xác nhận	Cơ quan quản lý đã gửi yêu cầu thu hồi
`RECALLED`	🔴 Đã thu hồi	Doanh nghiệp xác nhận → Toàn bộ tem bị vô hiệu
`RECALL_REJECTED`	🟢 Đã từ chối	Doanh nghiệp từ chối yêu cầu (kèm lý do)

4. Cảnh báo người tiêu dùng

Khi người tiêu dùng quét mã QR sản phẩm đã bị thu hồi:

Trên Zalo Mini App

Banner đỏ lớn hiển thị ngay dưới thông tin sản phẩm
Tiêu đề: 🚨 SẢN PHẨM ĐÃ BỊ THU HỒI
Nội dung: Lý do thu hồi + Ngày thu hồi
Cảnh báo: "Vui lòng NGỪNG SỬ DỤNG và liên hệ nhà sản xuất"

Trên Web (truy xuất công khai)

Trang truy xuất vẫn hiển thị đầy đủ thông tin sản phẩm
Nhưng có banner cảnh báo nổi bật phía trên
Màu sắc: Đỏ (RECALLED) / Vàng (PENDING_RECALL)

💡 Lưu ý: Thông tin sản phẩm vẫn hiển thị đầy đủ để người tiêu dùng biết mình đang có sản phẩm gì. Chỉ thêm cảnh báo, không chặn truy cập.

5. Thông báo tự động

Hệ thống tự động gửi thông báo qua module Notification:

Sự kiện	Người nhận	Nội dung
Yêu cầu thu hồi	TENANT_ADMIN	⚠️ Yêu cầu thu hồi: [Tên SP]. Lý do: ...
Xác nhận thu hồi	DEALER	🚨 Thu hồi sản phẩm: [Tên SP]. Ngừng bán và liên hệ doanh nghiệp

6. API Reference

Method	Endpoint	Mô tả	Vai trò
`POST`	`/api/gov/products/:id/recall-request`	Gửi yêu cầu thu hồi	Gov
`GET`	`/api/gov/products/:id/recall-status`	Xem trạng thái thu hồi	Gov
`GET`	`/api/gov/recalls/pending`	Danh sách sản phẩm cần xử lý	Enterprise
`POST`	`/api/gov/products/:id/confirm-recall`	Xác nhận thu hồi	Enterprise
`POST`	`/api/gov/products/:id/reject-recall`	Từ chối thu hồi	Enterprise

Thu hồi Sản phẩm (Product Recall) ​

Tổng quan luồng ​

Vai trò trong quy trình ​

1. Cơ quan quản lý gửi yêu cầu thu hồi ​

Thao tác ​

API Backend ​

Kết quả ​

2. Doanh nghiệp xử lý yêu cầu thu hồi ​

Thống kê ​

Bảng danh sách ​

Xác nhận Thu hồi ​

Từ chối Thu hồi ​

3. Trạng thái vòng đời Thu hồi ​

4. Cảnh báo người tiêu dùng ​

Trên Zalo Mini App ​

Trên Web (truy xuất công khai) ​

5. Thông báo tự động ​

6. API Reference ​

Tiếp theo ​