Kho quà

Quản lý danh mục quà vật lý và digital, tồn kho theo điểm activation, cấp phát cho lượt trúng và đối soát sau campaign.

Mục tiêu

Mục tiêu	Chỉ số đo	Ngưỡng MVP
Không trao vượt số quà có thật	Số lượt trúng vượt tồn	0
Quà digital tới tay người chơi ngay	Thời gian từ trúng đến nhận mã	≤ 10 giây ở p95
Đối soát nhanh sau sự kiện	Thời gian ra biên bản đối soát một điểm	≤ 15 phút, không cần Excel thủ công
Biết trước khi hết quà	Cảnh báo tồn thấp	Gửi trước khi tồn chạm ngưỡng

Ngoài phạm vi

Mua hàng, công nợ nhà cung cấp — làm trên hệ thống mua sắm của FTEL.
Vận chuyển quà tới nhà người chơi — MVP chỉ nhận tại điểm hoặc quà digital.
Định giá kế toán, xuất hoá đơn.

Loại quà

	Quà vật lý	Quà digital
Ví dụ	Áo thun, bình nước, gấu bông Cáo, modem	Voucher giảm cước, mã nạp data, mã FPT Play, thẻ cào, điểm thưởng
Đơn vị tồn	Cái, theo từng kho	Mã, theo từng lô mã
Nguồn	Nhập tay / file khi nhận hàng	File mã (CSV/XLSX) hoặc API nhà cung cấp sinh mã khi cần
Biến thể	Có (size, màu) — mỗi biến thể tồn riêng	Có (mệnh giá)
Trao quà	Nhân viên booth quét QR của lượt trúng, giao tận tay	Hiện mã trên màn kết quả + gửi SMS/ZNS + lưu ở "Quà của tôi"
Hạn	Hạn nhận tại điểm (vd. hết ngày sự kiện)	Hạn dùng của mã (theo lô) và hạn nhận
Kênh dùng	Chủ yếu offline	Mọi kênh

Quà "chúc may mắn"Kết quả không trúng không phải là quà và không tồn trong kho. Tỉ lệ "không trúng" là phần còn lại của cơ cấu giải — xem Campaign.

Vai trò & quyền

Vai trò	Danh mục quà	Nhập / điều chuyển	Gán vào campaign	Xác nhận trao	Đối soát
Quản trị hệ thống	✓	✓	✓	✓	✓
Quản lý kho quà	✓	✓	Xem	—	✓
Quản lý campaign	Xem	—	✓ (trong tồn cho phép)	—	Xem
Nhân viên booth	—	Nhận hàng tại điểm mình	—	✓ (điểm mình)	Ký biên bản điểm mình
Người duyệt	Xem	—	Xem	—	Xem
Người xem báo cáo	—	—	—	—	Xem

Bảng tóm tắt. Khi lệch, ma trận quyền ở trang Tài khoản là đúng.

User stories

Mã	Là…	Tôi muốn…	Để…	Ưu tiên
US-QUA-01	Quản lý kho quà	tạo quà vật lý có biến thể và ảnh	campaign chọn được đúng quà	Must
US-QUA-02	Quản lý kho quà	nhập lô mã digital từ file	có mã để trao ngay khi trúng	Must
US-QUA-03	Quản lý kho quà	điều chuyển quà từ kho tổng về điểm activation	mỗi booth biết mình có bao nhiêu quà	Must
US-QUA-04	Quản lý campaign	thấy tồn khả dụng khi lập cơ cấu giải	không hứa vượt số quà có	Must
US-QUA-05	Nhân viên booth	quét QR của người chơi để xác nhận trao quà	không trao trùng, không phải ghi sổ	Must
US-QUA-06	Người chơi	xem lại mã quà digital đã trúng	dùng sau khi rời game	Must
US-QUA-07	Quản lý kho quà	nhận cảnh báo khi tồn thấp	bổ sung trước khi hết	Should
US-QUA-08	Quản lý kho quà	xuất biên bản đối soát theo điểm/campaign	quyết toán với kế toán	Must
US-QUA-09	Quản lý kho quà	kết nối API nhà cung cấp voucher	không phải nhập file mã thủ công	Could

Luồng chính

Chuẩn bị quà

Quản lý kho quà tạo quà trong danh mục (loại, biến thể, ảnh, giá trị).
Vật lý: nhập kho tổng. Digital: tải lô mã hoặc khai báo nguồn API.
Vật lý: tạo phiếu điều chuyển về điểm activation; nhân viên booth xác nhận đã nhận đủ.
Quản lý campaign gán quà vào cơ cấu giải — hệ thống giữ chỗ số lượng đó cho campaign.

Trúng và trao quà

Phiên chơi kết thúc → engine quay thưởng chọn quà theo cơ cấu giải, chỉ trong tồn khả dụng của campaign (và của điểm, nếu offline).
Tạo lượt trúng + cấp phát trạng thái Đang giữ, trừ tồn khả dụng ngay (nguyên tử).
Digital: lấy 1 mã chưa dùng → Đã cấp → hiện mã, gửi SMS/ZNS. Vật lý: hiện QR nhận quà → Đã cấp.
Vật lý: nhân viên booth quét QR, xác nhận giao → Đã nhận, trừ tồn thực tế.
Quá hạn nhận mà chưa giao → Hết hạn, quà trả lại tồn khả dụng nếu campaign còn chạy.

Đối soát

Cuối ngày/cuối sự kiện, nhân viên booth đếm quà còn lại, nhập số thực tế.
Hệ thống so: tồn đầu + nhận − đã trao = tồn cuối lý thuyết; báo chênh lệch.
Quản lý kho quà xử lý chênh lệch (ghi lý do), chốt biên bản, xuất PDF/XLSX.

Màn hình

Màn	Kênh	Thành phần chính	Hành động
Danh mục quà	Quản trị	Bảng: ảnh, tên, loại, tổng tồn, đã giữ, khả dụng; lọc loại/trạng thái	Tạo, sửa, ngừng dùng
Chi tiết quà	Quản trị	Thông tin, biến thể, tồn theo kho, lô mã, lịch sử xuất nhập	Nhập kho, tải lô mã, điều chuyển
Phiếu kho	Quản trị	Loại phiếu (nhập / điều chuyển / điều chỉnh), dòng quà, số lượng, người lập, người nhận	Lập, gửi, xác nhận
Đối soát	Quản trị	Bảng theo điểm × quà: đầu kỳ, nhận, trao, lý thuyết, thực tế, lệch	Nhập số đếm, ghi lý do, chốt, xuất file
Quét trao quà	Booth (iPad/điện thoại)	Camera quét QR, thông tin quà + SĐT che `09•••••123`	Xác nhận đã giao
Quà của tôi	Web · App · Zalo	`.ds-voucher` theo trạng thái: chưa dùng, đã dùng, hết hạn	Sao chép mã, xem QR, hướng dẫn dùng

Giao diện người chơi theo Thành phần (voucher, kết quả) và Mẫu màn hình game.

Quy tắc nghiệp vụ

Mã	Quy tắc	Ví dụ
BR-QUA-01	Tồn khả dụng = tồn thực tế − đang giữ − đã gán cho campaign khác. Không gán vượt tồn khả dụng	100 áo, campaign A giữ 60 → campaign B gán tối đa 40
BR-QUA-02	Trừ tồn khi tạo lượt trúng phải nguyên tử: hai phiên trúng cùng lúc không được lấy chung 1 quà / 1 mã	Còn 1 mã, 2 người trúng cùng giây → 1 người nhận, người kia được quay lại trong quà còn tồn
BR-QUA-03	Hết quà trong cơ cấu giải → phiên chơi trả "không trúng", không báo lỗi cho người chơi
BR-QUA-04	Campaign offline: quà vật lý chỉ trúng trong tồn của điểm đang chơi	Booth Q1 hết áo → người chơi ở Q1 không trúng áo dù kho tổng còn
BR-QUA-05	Mỗi mã digital chỉ cấp một lần. Mã trùng trong file nhập bị loại và báo
BR-QUA-06	Không nhập lô mã có hạn dùng sớm hơn ngày kết thúc campaign + hạn nhận	Campaign kết thúc 31/12 → mã phải còn hạn sau 31/12
BR-QUA-07	Cảnh báo tồn thấp khi khả dụng ≤ ngưỡng (mặc định 10% số đã gán) — gửi quản lý kho quà và quản lý campaign
BR-QUA-08	Hạn nhận quà vật lý mặc định: hết ngày của điểm activation
BR-QUA-09	Quà đã gán campaign đang chạy không được xoá; chỉ "ngừng dùng" cho campaign mới
BR-QUA-10	Mã digital chỉ hiển thị đầy đủ cho chính người trúng; trang quản trị che giữa mã, xem đủ phải có quyền và được ghi nhật ký	`FPT-8K••••Q2`
BR-QUA-11	Điều chỉnh tồn (hỏng, mất) phải có lý do và người duyệt khác người lập

Trường dữ liệu

Quà

Trường	Kiểu	Bắt buộc	Ràng buộc	Ghi chú
Mã quà	Chuỗi	✓	Duy nhất, tự sinh `QUA-0001`
Tên	Chuỗi	✓	≤ 60 ký tự	Hiện cho người chơi
Loại	Chọn	✓	Vật lý · Digital	Không đổi sau khi tạo
Nhóm digital	Chọn	Digital	Voucher cước · Data · FPT Play · Thẻ cào · Điểm thưởng · Khác	Quyết định cách dùng mã
Biến thể	Danh sách	—	Tên + thuộc tính (size, màu, mệnh giá)	Mỗi biến thể tồn riêng
Ảnh	Ảnh	✓	WebP/PNG vuông, ≥ 480px, ≤ 300 KB
Giá trị	Số (VND)	✓	≥ 0	Báo cáo chi phí quà
Hướng dẫn dùng	Văn bản	Digital	≤ 500 ký tự	Hiện cạnh mã
Trạng thái	Chọn	✓	Đang dùng · Ngừng dùng

Lô mã (digital)

Trường	Kiểu	Bắt buộc	Ràng buộc	Ghi chú
Quà / biến thể	Tham chiếu	✓
Nguồn	Chọn	✓	File · API	API: xem Tích hợp
Số mã	Số	✓	Đếm từ file sau khi loại trùng
Hạn dùng	Ngày	✓	Theo BR-QUA-06
Mã	Chuỗi, mã hoá khi lưu	✓	Duy nhất trong toàn hệ thống	Theo BR-QUA-10

Cấp phát

Trường	Kiểu	Ghi chú
Lượt trúng	Tham chiếu	1 lượt trúng — 1 cấp phát
Quà / biến thể	Tham chiếu
Mã đã cấp	Tham chiếu	Digital
Kho / điểm trao	Tham chiếu	Vật lý
Trạng thái	Chọn	Xem mục Trạng thái
Hạn nhận	Thời điểm
Người xác nhận trao, lúc	Tham chiếu, thời điểm	Vật lý

Trạng thái cấp phát

Đang giữ→Đã cấp→Đã nhận·Hết hạn·Huỷ

Từ	Sang	Ai / điều kiện
—	Đang giữ	Hệ thống, khi phiên chơi trúng
Đang giữ	Đã cấp	Hệ thống: digital lấy được mã; vật lý tạo QR nhận quà
Đang giữ	Huỷ	Hệ thống: lấy mã lỗi quá 3 lần, hoặc phiên chơi bị đánh dấu không hợp lệ
Đã cấp	Đã nhận	Nhân viên booth quét QR (vật lý); digital: ngay khi hiện mã
Đã cấp	Hết hạn	Hệ thống, quá hạn nhận
Đã cấp	Huỷ	Quản lý kho quà, có lý do (gian lận, trao nhầm)

Ngoại lệ & lỗi

Tình huống	Hệ thống xử lý	Thông báo hiển thị
API nhà cung cấp voucher lỗi / chậm	Thử lại 3 lần trong 30 giây; vẫn lỗi → giữ cấp phát "Đang giữ", gửi mã sau qua SMS/ZNS	"Quà của bạn đang được chuẩn bị, mã sẽ gửi qua tin nhắn trong ít phút"
Kiosk mất mạng khi trúng	Chỉ trúng trong hạn mức offline đã cấp trước cho thiết bị; đồng bộ khi có mạng	Như bình thường — xem Activation offline
Quét QR đã nhận rồi	Từ chối, hiện người và lúc đã nhận	"Quà này đã được trao lúc 14:32 bởi NV Lan"
Quét QR của điểm khác	Từ chối	"Quà này nhận tại booth Q7"
File mã sai định dạng / có mã trùng	Không nhập dòng lỗi; nhập phần hợp lệ khi người dùng xác nhận	Bảng dòng lỗi + lý do, tải về được
Đếm thực tế lệch lý thuyết	Không cho chốt biên bản khi chưa ghi lý do cho từng dòng lệch	Dòng lệch tô đỏ

Tiêu chí nghiệm thu

AC-QUA-01Cho quà còn 1 mã, khi 50 phiên trúng quà đó gửi đồng thời, thì đúng 1 phiên nhận mã, 49 phiên nhận quà khác còn tồn hoặc "không trúng".
AC-QUA-02Cho tồn khả dụng 40, khi quản lý campaign gán 41 vào cơ cấu giải, thì hệ thống chặn và hiện số tối đa 40.
AC-QUA-03Cho file 1.000 mã có 5 mã trùng, khi tải lên, thì nhập 995 mã và trả danh sách 5 dòng lỗi.
AC-QUA-04Cho QR nhận quà đã quét, khi quét lần hai, thì từ chối và hiện người, giờ đã trao.
AC-QUA-05Cho booth Q1 hết áo, khi người chơi tại Q1 trúng, thì không bao giờ ra áo.
AC-QUA-06Cho tồn khả dụng chạm ngưỡng cảnh báo, thì trong 5 phút quản lý kho quà và quản lý campaign nhận thông báo.
AC-QUA-07Cho một điểm có số đếm lệch, khi chưa ghi lý do, thì nút "Chốt biên bản" bị khoá.
AC-QUA-08Cho người chơi trúng quà digital, thì mã hiện trên màn kết quả, có trong "Quà của tôi", và có SMS/ZNS trong 60 giây.

Câu hỏi mở

#	Câu hỏi	Hỏi ai
Q-QUA-01	Nhà cung cấp voucher nào có API? Hay MVP chỉ nhập file?	FCM / Mua sắm
Q-QUA-02	Có giao quà vật lý về nhà cho campaign online không?	FCM
Q-QUA-03	Quà "Hết hạn" có trả lại kho cho người khác trúng không?	FCM
Q-QUA-04	Mẫu biên bản đối soát kế toán đang dùng?	Kế toán
Q-QUA-05	Điểm thưởng (loyalty) có tính là quà digital không, cộng vào hệ thống nào?	FCM / CRM

Lịch sử thay đổi

Bản	Ngày	Người sửa	Nội dung
0.1	2026-11-11	PM	Nháp khởi tạo — trang chuẩn cho các module khác tham khảo