sonpx/loyalty-agent-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
911d5be3b27da059bd8e6066e240f1544afb737f
loyalty-agent-service/docs/knowledge-cards/catalogue/voucher_code.md

6.8 KiB
Raw Blame History

card_id, title, domain, related_cards, tags, detail_refs
card_id title domain related_cards tags detail_refs
catalogue/voucher_code Quản lý kho mã điện tử (Voucher Code) catalogue
catalogue/item_master
campaign/item_redemption_rule
voucher
eVoucher
stock
promo code
fulfillment
catalogue/fulfillment_lifecycle

Quản lý kho mã điện tử (Voucher Code)

Mô tả ngắn

Voucher Code là mô-đun quản lý kho chứa các mã serial điện tử (eVoucher/Promo code) được sử dụng để trả thưởng cho khách hàng. Hệ thống hỗ trợ tổ chức mã theo lô (Voucher Code), cấu hình chung về hạn sử dụng, giá trị khuyến mãi, đồng thời quản lý vòng đời sử dụng (Lifecycle) của từng mã chi tiết (Voucher Detail) bên trong lô đó. Kho mã này có thể được tải lên (upload) từ đối tác bên ngoài hoặc do hệ thống OLS tự động sinh ra.

Thuật ngữ liên quan

  • Voucher Code (Lô mã): Định danh một chiến dịch mã hoặc một nhóm mã có chung thuộc tính (Ví dụ: lô mã Giảm 50K của Highland Coffee).
  • Voucher Detail / Voucher No (Mã chi tiết): Chuỗi ký tự (serial number) duy nhất mà khách hàng thực sự nhận được khi đổi thưởng.
  • Expiry Policy: Quy tắc tính ngày hết hạn của Voucher Detail (theo ngày cố định, theo ngày đổi, hoặc theo ngày giao dịch ghi sổ).
  • Promo code: Cờ đánh dấu lô voucher này dùng làm mã giảm giá (Discount/Cashback) kèm theo tỷ lệ hoặc số tiền cụ thể.

Cấu trúc dữ liệu (Data Schema)

Mô-đun được chia thành 2 cấp độ: Thông tin Lô mã (Voucher Code) và Thông tin từng mã (Voucher Detail).

1. Thông tin Lô mã (Voucher Code)

Field Name Description Constraints / Rules
Voucher Code / Description Mã định danh và mô tả lô mã X(10) / X(100).
Supplier Đối tác/nhà cung cấp phát hành lô mã này Bắt buộc. Drop-down.
Expiry Policy Chính sách hạn sử dụng: Fixed Date, N days from Transaction/Post Date, N months from Transaction/Post Date Bắt buộc chọn 1. Không cho sửa sau khi tạo.
Expiry Date / N Param Tham số tương ứng với Expiry Policy (Chọn Fixed Date -> nhập Ngày cố định; Chọn N days -> nhập số N) Tuỳ thuộc vào Expiry Policy.
Generate Voucher Bật: OLS tự sinh số lượng mã. Tắt: User phải tải file CSV chứa kho mã từ đối tác Switch. Mặc định OFF. Không sửa sau khi đã đổi mã.
Quantity (Chỉ hiện khi Generate = ON). Số lượng mã hệ thống cần tự sinh 9(5). Sau khi duyệt, tự sinh N mã tương ứng.
This is a promo code Bật nếu lô mã này là mã giảm giá/cashback Switch. Mặc định OFF.
Promotion Type & Value (Nếu Promo = ON). Loại khuyến mãi: % Discount, Fixed Monetary Discount, Cashback, Gift Voucher VÀ Giá trị tương ứng Bắt buộc nếu là Promo. > 0.

2. Thông tin Mã chi tiết (Voucher Detail)

Field Name Description Constraints / Rules
Voucher No Chuỗi ký tự mã serial thực tế gửi cho khách Hiển thị dạng lưới (Grid).
Redemption Date Ngày khách hàng đổi mã Tự động cập nhật.
Expiry Date Ngày mã hết hạn (tính toán dựa vào Expiry Policy của lô mã) Tự động tính toán.
Redemption Indicator Cờ đánh dấu trạng thái sử dụng của mã No (Chưa dùng) / Yes (Đã dùng).
Fulfillment Status Vòng đời trạng thái chi tiết của mã (Xem phần Cách hoạt động) New, Issued, Fulfilled, Cancelled, Rejected.

Cách hoạt động (How It Works)

1. Khởi tạo kho mã (Stock In)

  • Cách 1 - Upload file: Dành cho mã do đối tác cấp (VD: Shopee, Lazada). Người dùng tạo một lô Voucher Code (Generate = OFF) và dùng chức năng Upload để nạp danh sách hàng nghìn Voucher No vào lô này.
  • Cách 2 - Auto Generate: Dành cho mã do hệ thống nội bộ phát hành. Người dùng tạo lô Voucher Code (Generate = ON, Quantity = 1000). Sau khi duyệt, hệ thống tự sinh 1000 mã ngẫu nhiên đưa vào kho.

2. Vòng đời của Mã chi tiết (Lifecycle)

Mỗi Voucher No bắt đầu với Redemption Indicator = No và trải qua các trạng thái Fulfillment Status sau:

  1. New: Mã vừa được tạo/tải lên, sẵn sàng để cấp cho khách. Trạng thái Indicator: No.
  2. Issued: Khách hàng đã đổi điểm lấy mã này thành công trên OLS. Trạng thái Indicator chuyển thành Yes.
  3. Fulfilled: (Thành công tuyệt đối) Khách đã dùng mã tại hệ thống đối tác và đối tác ghi nhận chấp nhận mã.
  4. Cancelled: Khách hàng tự hủy giao dịch đổi mã, hoặc hệ thống hủy vì lý do lỗi. Trạng thái có thể quay lại để tái sử dụng tùy cấu hình hệ thống.
  5. Rejected: Đối tác từ chối mã (Ví dụ: vi phạm điều khoản, hết hạn, mã lỗi).

3. Dashboard Thống kê

Trên màn hình của mỗi lô Voucher Code (chỉ bản ghi Active), hệ thống hiển thị realtime 5 thông số:

  • Total Voucher: Tổng số mã đã khởi tạo/nạp vào.
  • Available Vouchers: Số mã chưa đổi và chưa hết hạn.
  • Redeemed Vouchers: Số mã đổi thành công.
  • Cancelled Vouchers: Số mã bị huỷ.
  • Expired Vouchers: Số mã chưa đổi nhưng đã qua Expiry Date.

Mối quan hệ với modules khác

  • Item Master: Voucher Code cung cấp "Hàng hoá" (Stock) cho các vật phẩm Item Master có thuộc tính Item Type = eVoucher. Số lượng Available Vouchers ở đây chính là Quantity on Hand (tồn kho) thực tế của Item Master.

Ví dụ thực tế

Ngân hàng muốn tung ra 1,000 mã "Giảm 50K khi mua sắm tại CGV".

  1. Admin vào Voucher Code, tạo lô mã CGV_50K. Chọn Supplier là CGV.
  2. Expiry Policy chọn N days from Transaction Date, N = 30 (Mã có hạn 30 ngày kể từ ngày khách đổi).
  3. Do mã do CGV cấp, chọn Generate = OFF. Sau đó lưu lại.
  4. Admin nhận file Excel chứa 1,000 serial number từ CGV, vào hệ thống click Upload file vào lô CGV_50K.
  5. Hệ thống thống kê: Total = 1,000, Available = 1,000, New = 1,000.
  6. Admin sang màn hình Item Master, tạo một món quà tên "Voucher CGV 50K" và liên kết nó vào Voucher Code CGV_50K.
  7. Khách hàng vào App đổi điểm lấy Voucher -> Số lượng Available còn 999, Redeemed = 1. Fulfillment Status của mã bị đổi chuyển thành Issued.