chore: remove legacy specification documents and internal rules file

docs/knowledge-cards/catalogue/catalogue_category.md

@@ -0,0 +1,81 @@
+---
+card_id: "catalogue/catalogue_category"
+title: "Danh mục và Phân nhóm (Catalogue & Category)"
+domain: "catalogue"
+related_cards:
+  - "catalogue/item_master"
+  - "catalogue/item_price"
+  - "campaign/item_redemption_rule"
+tags: ["catalogue", "category", "hierarchy", "item", "classification"]
+---
+
+# Danh mục và Phân nhóm (Catalogue & Category)
+
+## Mô tả ngắn
+
+Catalogue và Category là các thực thể dùng để tổ chức và phân loại hệ thống quà tặng/vật phẩm (Items) nhằm mục đích hiển thị cho người dùng cuối. **Catalogue** đóng vai trò là thư mục gốc (main folder) quản lý thời hạn hiển thị, trong khi **Category** là các nhóm con hỗ trợ cấu trúc cây phân cấp (hierarchy) để nhóm các vật phẩm liên quan lại với nhau. Mọi vật phẩm (Item) muốn hiển thị đều phải được gắn thẻ (tag) vào Catalogue và Category.
+
+## Thuật ngữ liên quan
+
+- **Catalogue**: Danh mục lớn nhất (gốc). Một hệ thống có thể có nhiều Catalogue hoạt động đồng thời (VD: Danh mục quà mùa hè, Danh mục quà đối tác). Mỗi Catalogue có tập hợp Items riêng.
+- **Category**: Phân nhóm con bên trong Catalogue. Hỗ trợ liên kết cha-con (Parent-Child) để tạo cây phân cấp.
+- **Item Master**: Bản ghi vật phẩm gốc. Sẽ được gắn với một Catalogue Code và một Category Code.
+- **MP (Member Portal) / Front-end system**: Hệ thống giao diện người dùng hiển thị danh mục và vật phẩm để khách hàng lựa chọn/đổi quà.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. Catalogue (Danh mục gốc)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Catalogue Code | Mã định danh Catalogue | Required. String (10). Trả về cho front-end khi truy vấn vật phẩm. |
+| Description | Mô tả mặc định của Catalogue | Required. String (50). |
+| Effective From/To Date | Thời gian hiệu lực của Catalogue | Required. Date. Catalogue chỉ hiển thị trong khoảng thời gian này. |
+| Icon | Biểu tượng của Catalogue | Optional. Image file. |
+
+### 2. Category (Phân nhóm con)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Category Code | Mã định danh Category | Required. String (10). Trả về cho front-end khi truy vấn vật phẩm. |
+| Description | Mô tả mặc định của Category | Required. String (100). |
+| Effective From/To Date | Thời gian hiệu lực của Category | Optional. Date. Nếu để trống, Category không có ngày hết hạn. |
+| Parent Category | Danh mục cha để tạo cấu trúc phân cấp | Optional. Lookup từ master data. |
+| Display Ordering | Thứ tự hiển thị trên Member Site | Numeric 9(3). |
+| Icon / Image | Biểu tượng hoặc hình ảnh đại diện | Image. Lấy từ Image Stock hoặc upload trực tiếp. |
+
+### 3. Đa ngôn ngữ (Content Configuration - Áp dụng cho cả hai)
+
+Cả Catalogue và Category đều hỗ trợ cấu hình mô tả theo từng ngôn ngữ.
+- **Language**: Chọn ngôn ngữ (ví dụ: EN, VN) từ master data.
+- **Description**: Mô tả tương ứng với ngôn ngữ đã chọn. Sẽ hiển thị trên MP (Member Portal).
+
+## Cách hoạt động (How It Works)
+
+### Tổ chức dữ liệu vật phẩm
+
+1. **Khởi tạo cấu trúc**: Quản trị viên định nghĩa các Catalogue (ví dụ: `TET_2024`, `REGULAR_GIFT`). Sau đó, định nghĩa các Category (ví dụ: `E_VOUCHER`, `PHYSICAL_GIFT`) và có thể gán `Parent Category` để tạo cây (ví dụ: `FOOD_VOUCHER` là con của `E_VOUCHER`).
+2. **Gắn kết Item**: Khi tạo mới hoặc cập nhật một **Item Master**, vật phẩm đó bắt buộc phải được gắn với một mã Catalogue và một mã Category. Việc này quyết định vật phẩm đó "nằm ở đâu" trong kho quà tặng.
+3. **Quản lý đa ngôn ngữ**: Người dùng có thể thiết lập nhiều đoạn mô tả (Description) khác nhau cho Catalogue/Category tương ứng với các ngôn ngữ mà hệ thống hỗ trợ. Nếu front-end yêu cầu một ngôn ngữ không được cấu hình, hệ thống trả về mô tả mặc định (Default Description).
+
+### Hiển thị trên Front-end (Member Portal)
+
+1. Khi khách hàng truy cập kho quà (MP), front-end sẽ gọi API lấy danh sách Catalogue.
+2. Hệ thống kiểm tra **Effective Date (Thời hạn hiệu lực)**. Chỉ những Catalogue/Category có `Processing Date` nằm trong khoảng Start/End Date mới được trả về.
+3. Front-end sử dụng **Category Hierarchy (Cây phân cấp)** và **Display Ordering (Thứ tự hiển thị)** để vẽ giao diện điều hướng (navigation menu).
+4. Khách hàng bấm vào Category, front-end dùng Category Code và Catalogue Code để truy vấn danh sách Item Master tương ứng và hiển thị.
+
+## Mối quan hệ với modules khác
+
+- **Item Master**: Mọi Item Master bắt buộc phải tham chiếu đến Catalogue Code và Category Code để có thể hiển thị ra front-end. Catalogue/Category giống như thư mục, còn Item Master là file bên trong.
+- **Image Stock**: Quản lý tập trung các hình ảnh được dùng làm Icon/Image cho Category.
+
+## Ví dụ thực tế
+
+**Tổ chức Kho quà Mùa Hè 2024**:
+- Quản trị viên tạo Catalogue: `SUMMER_24` (Từ 01/06/2024 đến 31/08/2024).
+- Trong `SUMMER_24`, tạo Category cấp 1: `TRAVEL` (Du lịch).
+- Trong `TRAVEL`, tạo Category cấp 2 (Parent = TRAVEL): `FLIGHT_TICKET`, `HOTEL`.
+- Thiết lập Content Configuration: Language = EN, Description = "Summer 2024 Travel Deals"; Language = VN, Description = "Ưu đãi du lịch Hè 2024".
+- Gắn một eVoucher "Giảm 10% vé máy bay VN Airlines" (Item Master) vào Catalogue `SUMMER_24` và Category `FLIGHT_TICKET`.
+- Kết quả: Từ 01/06 đến 31/08, khách hàng vào app sẽ thấy tab "Mùa Hè", trong đó có nhóm "Du lịch" -> "Vé máy bay" -> chứa voucher trên. Qua ngày 31/08, toàn bộ tab "Mùa Hè" tự động ẩn khỏi app.

docs/knowledge-cards/catalogue/item_master.md

@@ -0,0 +1,91 @@
+---
+card_id: "catalogue/item_master"
+title: "Quản lý Vật phẩm (Item Master)"
+domain: "catalogue"
+related_cards:
+  - "catalogue/catalogue_category"
+  - "catalogue/item_price"
+  - "catalogue/voucher_code"
+  - "campaign/campaign_rule"
+tags: ["Item", "Redemption", "Inventory", "Localization", "eVoucher"]
+detail_refs:
+  - "catalogue/face_value_logic"
+---
+
+# Quản lý Vật phẩm (Item Master)
+
+## Mô tả ngắn
+
+Item Master là mô-đun lõi quản lý thông tin chi tiết của mọi loại vật phẩm (Item) có thể dùng để quy đổi điểm thưởng (Redemption) trên hệ thống OLS. Nó định nghĩa toàn bộ thuộc tính sản phẩm, phân loại tính chất vật lý (Miles, Physical, eVoucher, Cashback,...), kiểm soát tồn kho (Inventory) và thiết lập cơ chế kích hoạt các giao dịch đổi điểm/thưởng điểm đi kèm.
+
+## Thuật ngữ liên quan
+
+- **Item Type**: Phân loại tính chất vật lý của vật phẩm: Miles (Dặm bay), Physical (Hàng hiện vật), eVoucher (Mã điện tử), Donation (Quyên góp), Cash rebate (Hoàn tiền), Other.
+- **Redemption Transaction Code**: Mã giao dịch (OLS TC) dùng để ghi nhận log nghiệp vụ khi đổi món hàng này.
+- **Award Transaction Code**: Mã giao dịch (OLS TC) dùng để kích hoạt (Trigger) một Campaign Rule (tặng thêm điểm thưởng) ngay khi khách hàng đổi món hàng này.
+- **Track Quantity on Hand**: Cờ kiểm soát tồn kho (Inventory Control). Nếu kích hoạt, hệ thống sẽ trừ dần số lượng (Quantity) lưu trong Database mỗi khi có khách hàng đổi quà.
+- **Face Value**: Giá trị thực tế của vật phẩm (VD: số tiền cash rebate, số dặm miles). Khác với giá điểm đổi (Item Price).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. Thông tin chung (General Information)
+| Field | Description | Type |
+| --- | --- | --- |
+| Item Code / Name | Mã định danh duy nhất và Tên hiển thị mặc định của vật phẩm. | X(10) / X(50) |
+| Catalogue / Category | Catalog và Category chứa vật phẩm này. | Drop-down |
+| Redemption From / To | Thời hạn áp dụng đổi quà. *Sau khi vật phẩm đã phát sinh giao dịch Redemption đầu tiên, hệ thống sẽ khóa ngày From và chỉ cho phép sửa ngày To.* | Date |
+| Item Type | Phân loại vật phẩm (Miles, Physical, eVoucher, Donation, Cash rebate, Other). | Radio |
+| Redemption Store | Đối tác (Merchant) cung cấp hoặc tài trợ vật phẩm này. | Drop-down |
+| Redemption / Award TC | Mã OLS Transaction Code dùng để ghi log / dùng để thưởng thêm điểm (Tùy chọn). | Drop-down |
+| Display on Member Site / Hot item | Cờ bật/tắt hiển thị lên Web/App và cờ đánh dấu là Sản phẩm Nổi bật (Hot). | Switch |
+
+### 2. Định giá & Kho hàng (Value & Inventory)
+| Field | Description | Type |
+| --- | --- | --- |
+| Face value (Trị giá) | Giá trị thực tế của vật phẩm mà khách hàng nhận được (Ví dụ: Giá trị số tiền Cash rebate, số dặm Miles). *Chỉ áp dụng cho Cash rebate/eVoucher/Miles.* | 9(14,2) |
+| Voucher Code | Nếu Item Type = eVoucher, bắt buộc phải chọn tập Mã eVoucher tương ứng lấy từ mô-đun Voucher Code (quản lý kho serial code). | Drop-down |
+| Track Quantity on Hand | Bật/tắt việc theo dõi tồn kho. *Mặc định hệ thống tự động ép thành ON (và không cho tắt) nếu Item Type là eVoucher (Voucher Code).* | Switch |
+| Initialize Quantity | Số lượng kho ban đầu. *Không áp dụng cho eVoucher vì số lượng eVoucher được quản lý ngầm bởi số lượng mã khả dụng trong pool Voucher Code.* | 9(9) |
+
+### 3. Nội dung đa ngôn ngữ & Hình ảnh (Detail & Media)
+| Field | Description | Type |
+| --- | --- | --- |
+| Language Specific | Tên vật phẩm, Mô tả ngắn, Chi tiết (Content), Hướng dẫn sử dụng (How to use), Điều khoản (T&C) hỗ trợ cấu hình đa ngôn ngữ. | Text |
+| Image Group / Image / Sort | Cấu hình bộ ảnh hiển thị cho Item và thứ tự xuất hiện, chọn từ Image Stock hoặc tải lên trực tiếp (Quick Add). | Image |
+
+### 4. Thông tin liên hệ (Contact and Address)
+| Field | Description | Type |
+| --- | --- | --- |
+| City / Address / Email / Phone | (Tùy chọn) Địa chỉ và thông tin liên hệ của cửa hàng / địa điểm vật lý có thể sử dụng vật phẩm này. | Text |
+
+## Cách hoạt động (How It Works)
+
+- **Ràng buộc hiệu lực (Validation Constraint)**: OLS sẽ báo lỗi (Reject) ngay lập tức nếu quản trị viên nhập thời hạn `Redemption From / To` của Item nằm ra ngoài khoảng thời gian có hiệu lực của Catalogue/Category chứa nó.
+- **Tồn kho (Inventory)**: Khi có giao dịch Redemption thành công, hệ thống giảm `Quantity` hiện tại đi tương ứng. Nếu hết số lượng, API báo hết hàng không thể đổi quà.
+- **Nội dung Đa ngôn ngữ (T&C Injection)**: Nội dung Terms & Conditions cấu hình tại mô-đun này sẽ được API (Web Service) trả về nguyên vẹn và hệ thống tự động sử dụng đoạn Text này để nội suy (Merge) vào các mẫu email/thư thông báo đổi thưởng gửi cho khách hàng.
+- **Hành vi đặc biệt của eVoucher**: Khi Item Type = eVoucher, hệ thống tự động:
+  - Ép `Track Quantity on Hand` = ON (không cho tắt)
+  - Số lượng tồn kho = số mã Voucher No còn trạng thái `New` trong Voucher Code pool
+  - `Face Value` lấy từ cấu hình Voucher Code (không nhập thủ công)
+- **Award TC Trigger**: Nếu Item có cấu hình `Award TC`, khi khách hàng đổi quà thành công, hệ thống sẽ tạo thêm 1 giao dịch với Transaction Code đó để kích hoạt Campaign Rule (VD: tặng thêm 100 điểm bonus khi đổi quà ≥ 500 điểm).
+
+## Mối quan hệ với modules khác
+
+- **Catalogue / Category**: Item phải thuộc về 1 Catalogue → 1 Category. Thời hạn Redemption của Item bị giới hạn bởi thời hạn Category cha.
+- **Item Price**: Item Master chỉ định nghĩa thuộc tính hàng hóa. "Giá bán" (Cần bao nhiêu điểm để đổi) được cấu hình riêng lẻ tại mô-đun Item Price — hỗ trợ định giá theo tier (hạng thẻ).
+- **Voucher Code**: Nguồn cung cấp kho serial code để xả hàng nếu Item Type là eVoucher. Số lượng mã còn trạng thái `New` = Tồn kho khả dụng.
+- **Campaign Rule (Award TC)**: Nếu Item cấu hình Award TC, giao dịch đổi quà sẽ trigger thêm Campaign Rule để thưởng bổ sung.
+
+## Ví dụ thực tế
+
+**Tạo vật phẩm eVoucher "Giảm 500K Lazada":**
+
+1. Admin tạo Item mới: **Item Code** = `EVCH_LZD500K`, **Item Name** = "eVoucher Lazada giảm 500,000 VND".
+2. **Catalogue** = "Quà tặng điện tử", **Category** = "eVoucher Thương mại".
+3. **Item Type** = eVoucher → hệ thống tự bật `Track Quantity on Hand` = ON.
+4. **Voucher Code** = `LZD500K_2024Q3` (lô 10,000 mã đã upload sẵn từ đối tác Lazada).
+5. **Face Value** = 500,000 VND. **Redemption TC** = `RED_EVOUCHER`.
+6. **Award TC** = `BONUS_RED_100` (khi đổi quà thành công → tự sinh giao dịch thưởng thêm 100 điểm cho khách).
+7. Cấu hình T&C: "Mỗi tài khoản sử dụng tối đa 1 lần. Áp dụng cho đơn hàng từ 1,000,000 VND."
+8. **Redemption From** = 01/07/2024, **To** = 30/09/2024.
+9. Khi khách hàng đổi 5,000 điểm (cấu hình trong Item Price) → hệ thống trả về 1 mã Voucher ngẫu nhiên từ lô `LZD500K_2024Q3`, đồng thời tặng thêm 100 điểm bonus qua Award TC.

docs/knowledge-cards/catalogue/item_price.md

@@ -0,0 +1,96 @@
+---
+card_id: "catalogue/item_price"
+title: "Định giá Vật phẩm (Item Price)"
+domain: "catalogue"
+related_cards:
+  - "catalogue/item_master"
+  - "campaign/pool_definition"
+  - "campaign/account_type_group"
+tags: ["price", "redemption", "points", "cash", "partial redemption"]
+detail_refs:
+  - "catalogue/redemption_pricing_detail"
+---
+
+# Định giá Vật phẩm (Item Price)
+
+## Mô tả ngắn
+
+Item Price là mô-đun định nghĩa "giá bán" cho các vật phẩm (đã được tạo trong Item Master). Một vật phẩm có thể có nhiều mức giá khác nhau tùy thuộc vào các điều kiện (Criteria) như: hạng thẻ khách hàng (Account Level), loại tài khoản (Account Type), kênh đổi thưởng (Redemption Channel) hoặc các tiêu chí tuỳ chỉnh khác. Mô-đun hỗ trợ cả đổi bằng điểm toàn phần (Full Redemption) và đổi kết hợp điểm + tiền mặt (Partial Redemption).
+
+## Thuật ngữ liên quan
+
+- **Full Redemption**: Đổi vật phẩm thanh toán 100% bằng điểm.
+- **Partial Redemption**: Đổi vật phẩm thanh toán bằng kết hợp điểm (tối thiểu là một số lượng nhất định) và tiền mặt (bù cho phần điểm còn thiếu).
+- **Redemption Pool**: Nguồn lưu trữ (ví/tài khoản điểm) mà hệ thống sẽ trừ điểm khi khách hàng đổi vật phẩm này.
+- **Cash per point**: Tỉ lệ quy đổi (Ví dụ: 1 điểm thiếu = 100 VND). Dùng để tính toán số tiền mặt khách hàng phải trả bù trong giao dịch Partial Redemption.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. Thông tin chung & Hạn mức áp dụng
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Price Code / Name | Mã định danh và Tên của mức giá này | X(10) / X(100). |
+| Effective Start/End Date | Thời gian mức giá này có hiệu lực | Bắt buộc. Date. |
+| Redemption Channel | Kênh áp dụng mức giá (VD: Call Center, Mobile App, Internet Banking) | Bắt buộc chọn 1. |
+| Account Type Group / Level / Type | Giới hạn mức giá này chỉ dành cho một nhóm thẻ hoặc hạng thẻ cụ thể (VD: Chỉ dành cho thẻ Platinum) | Tùy chọn. Nếu Account Type Group được chọn thì Account Level/Type bị khoá và ngược lại. |
+| Redemption Pool | Ví điểm sẽ bị trừ khi khách hàng đổi quà với giá này | Bắt buộc chọn 1 Pool. |
+| Use Only Points from Selected PA Type | Bật: Chỉ cho phép dùng điểm kiếm được từ các loại tài khoản đã cấu hình ở trên để đổi | Switch. Mặc định OFF. |
+
+### 2. Định giá (Pricing)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Face Value | Giá trị thực nhận của khách (VD: 500 Miles). Ghi đè lên Face Value cấu hình tại Item Master nếu có | 9(12,2). > 0. |
+| Price in point (Full redemption) | Giá của vật phẩm nếu đổi 100% bằng điểm | Bắt buộc. 9(12,2). > 0. |
+| Original price | Giá gốc (hiển thị để khách tham khảo giá trị thật của món quà) | 9(12,2). > 0. |
+
+### 3. Đổi kết hợp điểm & tiền (Partial Redemption)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Partial Redemption Allowed | Bật chế độ cho phép thanh toán mix giữa điểm và tiền mặt | Switch. Mặc định OFF. |
+| Minimum Partial Redeem Points | (Chỉ hiện khi Allow = ON). Khách phải dùng TỐI THIỂU bao nhiêu điểm để được phép bù tiền | 9(12,2) >= 0. Nếu = 0 tức là cho phép đổi 100% bằng tiền mặt. |
+| Cash per point | (Chỉ hiện khi Allow = ON). Số tiền phải trả cho 1 điểm còn thiếu | 9(12,2) > 0. |
+| Applicable Taxes | Thuế áp dụng cho giao dịch tiền mặt | Tham chiếu từ "Tax Rate Maintenance". |
+
+### 4. Điều kiện áp dụng tuỳ chỉnh (Item Criteria)
+
+Giống như Campaign Rule, Item Price cho phép ghép thêm các nhóm điều kiện phức tạp (Logic AND/OR/NOT).
+- Giao diện kéo thả (Drag/Drop) các thuộc tính khách hàng, giao dịch để tạo thành bộ lọc.
+- **Ví dụ**: Giá A chỉ áp dụng nếu khách hàng là Nữ (Gender = Female) VÀ Điểm đổi quà > 10,000.
+
+## Cách hoạt động (How It Works)
+
+1. **Khởi tạo mức giá**: Admin chọn một Item Master và thiết lập `Item Price`. Một Item Master có thể thiết lập nhiều mức giá (Ví dụ: Giá cho thẻ hạng Vàng, Giá cho thẻ hạng Kim cương).
+2. **Quy trình truy vấn giá hợp lệ (Valid Price)**:
+   - Khi có request truy vấn món đồ, hệ thống tìm tất cả các mức giá của món đồ đó.
+   - Loại bỏ các mức giá ngoài khoảng `Effective Date`.
+   - Kiểm tra `Account Type/Level` của khách hàng xem có khớp không.
+   - Kiểm tra `Item Criteria` (điều kiện tuỳ chỉnh) xem khách hàng có thỏa mãn không.
+   - Kết quả: Trả về danh sách các mức giá mà khách hàng ĐƯỢC PHÉP nhìn thấy và áp dụng.
+3. **Tính toán Partial Redemption**:
+   - Nếu vật phẩm giá 5,000 điểm. Khách hàng chỉ có 3,000 điểm và muốn đổi một phần.
+   - Minimum Partial Redeem = 2,000 điểm, Cash per point = 100 VND.
+   - Khách muốn dùng 3,000 điểm. Số điểm còn thiếu: 5,000 - 3,000 = 2,000 điểm.
+   - Vì 3,000 > 2,000 (Min allowed) -> Hợp lệ.
+   - Số tiền mặt phải bù: 2,000 điểm thiếu * 100 VND/điểm = 200,000 VND (+ Thuế nếu có).
+
+## Mối quan hệ với modules khác
+
+- **Item Master**: Item Price không thể tồn tại độc lập mà phải luôn được gắn với một Item Master cụ thể.
+- **Pool Definition**: Item Price chỉ định chính xác trừ điểm ở Pool nào (ví dụ: điểm thưởng, điểm hoàn tiền).
+- **Account Type Group**: Dùng để phân quyền truy cập giá (chỉ hạng thẻ cao mới thấy giá rẻ hơn).
+
+## Ví dụ thực tế
+
+**Item: Mã Voucher vé xem phim (Item Master)**
+- **Mức giá 1 (Dành cho thành viên thường)**:
+  - Account Level: Standard
+  - Price in point: 1,500 điểm
+  - Partial Redemption: OFF (Chỉ được đổi 100% bằng 1,500 điểm).
+- **Mức giá 2 (Dành cho thành viên VIP - Ưu đãi lớn)**:
+  - Account Level: Platinum
+  - Price in point: 1,000 điểm
+  - Partial Redemption: ON (Tối thiểu 500 điểm, phần thiếu tính 1 điểm = 50 VND).
+- **Trải nghiệm**: Khách VIP vào App sẽ thấy món quà giá 1,000 điểm. Khách đang có 800 điểm -> Có thể dùng 800 điểm và trả thêm 200 * 50 = 10,000 VND để lấy Voucher. Khách Standard vào App sẽ thấy món quà giá 1,500 điểm và không có tùy chọn bù tiền mặt.

docs/knowledge-cards/catalogue/voucher_code.md

@@ -0,0 +1,91 @@
+---
+card_id: "catalogue/voucher_code"
+title: "Quản lý kho mã điện tử (Voucher Code)"
+domain: "catalogue"
+related_cards:
+  - "catalogue/item_master"
+  - "campaign/item_redemption_rule"
+tags: ["voucher", "eVoucher", "stock", "promo code", "fulfillment"]
+detail_refs:
+  - "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`.