chore: remove legacy specification documents and internal rules file

docs/knowledge-cards/CHANGE_HISTORY.md

@@ -0,0 +1,6 @@
+# Change History
+
+| Date | Card ID | Action | Description |
+|---|---|---|---|
+| 2026-07-26 | targeting/segmentation | UPDATE | Freshness Check: Added missing body text explanation for `customer/customer_overview` to resolve QC-4/QC-10 (Body-Frontmatter Sync) failure. |
+| 2026-07-26 | campaign/campaign_rule | UPDATE | Freshness Check: Added missing 'Mối quan hệ với modules khác' and 'Ví dụ thực tế' sections to resolve QC-3A (Tier 1 structure) failure. |

docs/knowledge-cards/campaign/account_type_group.md

@@ -0,0 +1,69 @@
+---
+card_id: "campaign/account_type_group"
+title: "Nhóm loại tài khoản (Account Type Group)"
+domain: "campaign"
+related_cards:
+  - "campaign/pool_definition"
+  - "campaign/campaign_rule"
+tags: ["account type", "ATG", "sequence", "deduction", "validation"]
+---
+
+# Nhóm loại tài khoản (Account Type Group)
+
+## Mô tả ngắn
+
+Account Type Group (ATG) là một nhóm các loại tài khoản (Account Type) được sắp xếp theo mức độ ưu tiên (Sequence Number). Thực thể này được liên kết trực tiếp với Quỹ thưởng (Pool) để kiểm soát những loại tài khoản nào được phép tích lũy điểm vào Pool, cũng như thứ tự ưu tiên trừ điểm khi khách hàng sử dụng (Redeem) hoặc khi hệ thống xử lý giao dịch.
+
+## Thuật ngữ liên quan
+
+- **Account Type**: Sự kết hợp giữa Product Account Level (Hạng tài khoản) và Product Account Type (Loại tài khoản).
+- **ATG**: Account Type Group, thực thể dùng để gom nhóm các Account Type.
+- **ATGSN (Sequence Number)**: Số thứ tự ưu tiên của một Account Type trong ATG. Số càng nhỏ, độ ưu tiên càng cao.
+- **CIF Number**: Mã định danh khách hàng duy nhất. Khách hàng có thể có nhiều Account Type khác nhau.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+| Field | Description | Type |
+|---|---|---|
+| Account Type Group Id | Mã định danh nhóm loại tài khoản, liên kết với Pool. Sự kết hợp giữa ATG Id và Account Type là duy nhất. | X(10) |
+| Description | Mô tả ngắn về nhóm ATG này. | X(100) |
+| Product Account Level | Hạng tài khoản (PAL), chọn từ danh mục được cấu hình trên hệ thống. | Drop-down |
+| Product Account Type | Loại tài khoản (PAT), tương ứng với Hạng tài khoản đã chọn. | Drop-down |
+| Sequence No | Số thứ tự ưu tiên của Account Type trong nhóm ATG (>= 0). Số nhỏ hơn có ưu tiên cao hơn. | 9(04) |
+
+### Danh sách Pool liên kết (Linked Pool)
+Phần này hiển thị danh sách các Pool đang sử dụng ATG này:
+| Field | Description | Type |
+|---|---|---|
+| Pool | Tên và mã của Pool Definition được liên kết với ATG. | Display |
+| Campaign Rule | Tên và mã của Campaign Rule (nếu có) đang cấu hình trả thưởng vào Pool trên. | Display |
+| Effective Date | Ngày bắt đầu và kết thúc hiệu lực của Campaign Rule đó. | Display |
+
+## Cách hoạt động (How It Works)
+
+ATG đóng vai trò là một bộ lọc và phân giải (resolver) trong 3 trường hợp chính của hệ thống giao dịch:
+
+- **1. Ưu tiên trừ điểm (Deduction Sequence)**:
+  Khi khách hàng đổi điểm (Redeem) hoặc bị điều chỉnh giảm từ một Customer-level Pool, hệ thống dựa vào ATG để tìm thứ tự ưu tiên trừ. Các Bucket được ưu tiên trừ theo: (1) Ngày hết hạn sớm nhất -> (2) Ngày bắt đầu sớm nhất -> (3) Sequence No của Account Type nhỏ nhất trong ATG.
+- **2. Định tuyến giao dịch chỉ có mã khách hàng (CIF Only Routing)**:
+  Khi giao dịch chỉ gửi lên mã khách hàng (CIF) mà không chỉ định chính xác tài khoản nào:
+  Hệ thống sẽ lấy: [Tất cả Account Type của khách hàng] GIAO VỚI [Các Account Type trong ATG của Pool].
+  - Nếu kết quả RỖNG: Giao dịch bị từ chối.
+  - Nếu có nhiều kết quả: Hệ thống tự động đẩy giao dịch vào tài khoản có Sequence No nhỏ nhất (ưu tiên cao nhất).
+- **3. Xác thực tính hợp lệ (Validation)**:
+  Bất kỳ giao dịch nào (Award, Adjust) có chỉ định sẵn số tài khoản/số thẻ, hệ thống đều kiểm tra loại tài khoản đó có nằm trong danh sách ATG của Pool hay không. Nếu không, giao dịch bị từ chối.
+
+## Mối quan hệ với modules khác
+
+- **Pool Definition**: Mỗi Pool có thể gắn với một (và chỉ một) ATG để định nghĩa tập hợp các loại tài khoản hợp lệ của Pool đó.
+- **Campaign Rule**: Vì Campaign Rule thao tác trực tiếp lên Pool (để trả thưởng hoặc xét điều kiện), ATG gián tiếp giới hạn những tài khoản nào thực sự được hưởng lợi từ Campaign.
+
+## Ví dụ thực tế
+
+Pool "Quỹ điểm Thẻ Tín Dụng" có gắn với một ATG gồm 2 loại tài khoản:
+1. Thẻ Platinum (Sequence = 10)
+2. Thẻ Gold (Sequence = 20)
+
+Khách hàng Nguyễn Văn A sở hữu cả 2 thẻ này dưới cùng một mã CIF.
+- Khi A được thưởng điểm và hệ thống chỉ truyền mã CIF, điểm sẽ tự động được ghi nhận vào thẻ Platinum (do Sequence 10 < 20).
+- Khi A đổi điểm (Redemption) nhưng điểm nằm rải rác trên cả 2 thẻ có cùng ngày hết hạn, hệ thống sẽ ưu tiên trừ điểm từ thẻ Platinum trước, nếu thiếu mới trừ tiếp sang thẻ Gold.

docs/knowledge-cards/campaign/campaign_rule.md

@@ -0,0 +1,93 @@
+---
+card_id: "campaign/campaign_rule"
+title: "Quy tắc Chiến dịch (Campaign Rule)"
+domain: "campaign"
+related_cards:
+  - "campaign/reward_campaign"
+  - "campaign/transaction_codes"
+  - "customer/pool_balance"
+tags: ["rule", "criteria", "award", "redeem", "adjust", "formula"]
+detail_refs:
+  - "campaign/criteria_operators"
+  - "campaign/formula_calculation"
+---
+
+# Quy tắc Chiến dịch (Campaign Rule)
+
+## Mô tả ngắn
+
+Quy tắc Chiến dịch (Campaign Rule) là thực thể trung tâm chứa toàn bộ logic kinh doanh (Business Logic) để xác định xem một giao dịch có hợp lệ để nhận thưởng hay không, và phần thưởng đó được tính toán như thế nào. Một Campaign Rule hoàn chỉnh bao gồm: Điều kiện hiệu lực, Định tuyến giao dịch, Bộ lọc tiêu chí (Criteria), Công thức tính (Formula) và Phân bổ chi phí (Contributor).
+
+## Thuật ngữ liên quan
+
+- **Execution Sequence**: Thứ tự thực thi. Khi một giao dịch (mang một OLS TC) khớp với nhiều Rules, hệ thống sẽ chạy các Rules theo thứ tự này.
+- **Stop if criteria met**: Cờ báo hiệu hệ thống dừng xử lý các Rules tiếp theo (cùng TC) nếu Rule hiện tại đã được khớp (hit) thành công.
+- **Contributor**: Đơn vị (thường là Merchant / Chain) chịu chi phí tài trợ cho phần thưởng được cấp ra từ Rule này.
+- **Absorb Remainder**: Đơn vị chịu trách nhiệm gánh phần số dư lẻ (do làm tròn) sau khi đã chia tỷ lệ % cho các Contributors khác.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Một Rule được cấu thành từ 5 khối dữ liệu logic chính:
+
+### 1. Thông tin chung & Hiệu lực (General & Effect)
+- **Campaign ID**: Chiến dịch chứa Rule này.
+- **Rule Type**: Loại quy tắc (Award - Tặng thưởng, Redeem - Đổi điểm, Adjust - Điều chỉnh, v.v.).
+- **Effective Period**: Từ ngày - Đến ngày. Có thể đánh giá thời gian này dựa trên *Transaction Date* (Ngày giao dịch gốc) hoặc *System Batch Date* (Ngày hệ thống xử lý).
+- **Pool ID**: Đích đến - Ví điểm sẽ được cộng/trừ kết quả tính toán của Rule này.
+- **Do not update pool**: Nếu BẬT, Rule này chỉ dùng để tính toán và cập nhật vào Bộ đếm (Counter) chứ không thực sự cộng điểm vào Pool Balance.
+
+### 2. Liên kết Giao dịch (Transaction Link)
+- **OLS Transaction Code**: Xác định loại giao dịch nào (Ví dụ: `PURCHASE`) sẽ kích hoạt Rule này.
+- Một Rule có thể link với nhiều TC.
+- Không cho phép gán TC đảo chiều (Reversal TC) cho Rule thuộc loại Adjustment hoặc Rule đánh vào Evoucher Pool.
+
+### 3. Tiêu chí Xét duyệt (Rule Criteria)
+Sử dụng cấu trúc truy vấn động (Query Builder) kết hợp bởi nhiều nhóm điều kiện (AND/OR). Hỗ trợ các tiêu chí từ:
+- **Transaction**: MCC, Quốc gia, Loại tiền tệ...
+- **Customer / Account**: Hạng tài khoản, Tuổi, Phân khúc...
+- **Transaction Category**: Tái sử dụng cụm điều kiện vĩ mô (xem thêm card Transaction Codes).
+- **Counter**: Xét điều kiện dựa trên tổng giá trị tích lũy trong quá khứ (Ví dụ: Tổng chi tiêu tháng trước > 1000$).
+- **Hỗ trợ Exclusion**: Cho phép phủ định một tiêu chí (NOT).
+
+### 4. Công thức và Giới hạn (Formula & Cap Limits)
+- **Amount to Use (A)**: Đầu vào của công thức. Có thể lấy từ Gross Amount, Nett Amount của giao dịch, hoặc lấy từ giá trị của một Bộ đếm (Counter).
+- **Cap Limit cho (A)**: Giới hạn trên của đầu vào (Ví dụ: Giao dịch 10 triệu, nhưng chỉ lấy tối đa 5 triệu để tính điểm).
+- **Result Award Limit**: Giới hạn tổng kết quả đầu ra.
+  - *Give No more than*: Giới hạn tổng số điểm thưởng cấp ra không vượt quá X. Có thể giới hạn trên nội bộ 1 Rule, hoặc giới hạn chung dựa trên một Counter (ví dụ: Tổng quỹ thưởng của Campaign không quá 1 tỷ điểm).
+- **Rounding**: Phương thức làm tròn kết quả (Up / Down / Nearest).
+
+### 5. Phân bổ Chi phí (Contributor Details)
+- Xác định ai sẽ "trả tiền" cho số điểm thưởng vừa cấp.
+- Cho phép cấu hình nhiều đơn vị (Chain) với tỷ lệ phần trăm (Contributor Percentage).
+- Tổng tỷ lệ phải bằng 100%. Bắt buộc phải có đúng 1 đơn vị được gán cờ `Absorb Remainder`.
+- Nếu không cấu hình, mặc định Merchant nơi phát sinh giao dịch sẽ chịu 100% chi phí.
+
+## Cách hoạt động (How It Works)
+
+1. Giao dịch đổ vào Transaction Processing Engine (TP).
+2. Engine tìm các Rules đang Active, còn trong thời hạn (Effective Date) và khớp OLS TC.
+3. Engine sắp xếp các Rules theo `Execution Sequence`.
+4. Engine chạy qua Rule Criteria. Nếu giao dịch thỏa mãn toàn bộ tiêu chí -> Rule Hit.
+5. Engine tính toán phần thưởng dựa trên Formula (A), áp dụng các bộ lọc giới hạn (Caps).
+6. Nếu `Do not update pool = OFF`, kết quả được cộng vào Pool Balance của khách hàng. Phân bổ chi phí được ghi nhận cho Contributors.
+7. Nếu `Stop if criteria met = TRUE`, Engine bỏ qua các Rules còn lại của giao dịch đó.
+
+## Mối quan hệ với modules khác
+
+- **Reward Campaign**: Chứa các Rule này. Một chiến dịch không thể hoạt động nếu không có Rule.
+- **Transaction Codes**: Liên kết trực tiếp để định tuyến. Giao dịch phải có TC khớp với cấu hình của Rule thì mới kích hoạt Rule.
+- **Pool Balance**: Điểm đến cuối cùng của các giao dịch thưởng/trừ do Rule sinh ra.
+
+## Ví dụ thực tế
+
+Tạo Rule thưởng nhân 2 điểm (x2) cho Khách hàng hạng Gold vào cuối tuần:
+- **Campaign**: "Weekend Double Points"
+- **Rule Type**: Award
+- **OLS Transaction Code**: `PURCH_NORMAL`
+- **Criteria**: 
+  - (Account Level = 'Gold') AND 
+  - (Day of Week IN 'Saturday', 'Sunday')
+- **Formula**: `Amount to Use = Gross Amount`. Công thức: `A * 0.02` (Giả sử mặc định là 1%, nhân đôi là 2%).
+- **Contributor**: Merchant A chịu 100% chi phí.
+
+Khi khách hàng Gold mua 1,000,000 VND vào Thứ 7, giao dịch khớp toàn bộ điều kiện. Hệ thống tính: 1,000,000 * 0.02 = 20,000 điểm. 20,000 điểm này được cộng vào Pool của khách hàng và Merchant A chịu ghi nhận nợ 20,000 điểm trên sổ cái.

docs/knowledge-cards/campaign/cep_request.md

@@ -0,0 +1,76 @@
+---
+card_id: "campaign/cep_request"
+title: "Yêu cầu Trích xuất và Xử lý Bộ đếm (CEP Request)"
+domain: "campaign"
+related_cards:
+  - "campaign/campaign_rule"
+  - "campaign/counter_definition"
+  - "campaign/transaction_codes"
+tags: ["CEP", "counter", "extract", "batch", "schedule"]
+detail_refs:
+  - "campaign/batch_rule_processing"
+---
+
+# Yêu cầu Trích xuất và Xử lý Bộ đếm (CEP Request)
+
+## Mô tả ngắn
+
+Counter Extract & Process (CEP) Request là một loại Quy tắc Chiến dịch (Campaign Rule) đặc biệt, hoạt động như một công cụ lập lịch (scheduler) tự động. Nhiệm vụ của CEP là định kỳ trích xuất số dư từ các Bộ đếm (Counter), sau đó chuyển hóa giá trị này thành các giao dịch ảo trong hệ thống. Các giao dịch ảo này mang theo Mã giao dịch (Transaction Code) được chỉ định để kích hoạt các Campaign Rule khác (như rule tính toán trả thưởng cuối kỳ).
+
+## Thuật ngữ liên quan
+
+- **CEP (Counter Extract & Process)**: Tiến trình trích xuất giá trị từ Counter và xử lý thành giao dịch.
+- **Run Schedule**: Lịch trình chạy của tiến trình CEP (Hàng ngày, Hàng tháng, Theo kỳ sao kê...).
+- **Counter Bucket**: Nhóm lưu trữ số dư của bộ đếm trong một chu kỳ nhất định (Current, Previous).
+- **State (C, A, E)**: Trạng thái của Bucket (C = Created, A = Awarded/Closed, E = Extracted).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. Thông tin chung (General Information)
+| Field | Description | Type |
+|---|---|---|
+| Campaign ID / Rule ID / Name | Mã chiến dịch, mã quy tắc và tên của quy tắc CEP này. | Display / X |
+| Rule Type | Loại quy tắc, mặc định là "Counter Extract & Process [CEP]". | Display |
+| Effective Date From / To | Khoảng thời gian CEP Rule này có hiệu lực hoạt động. | Date |
+
+### 2. Cấu hình Trích xuất (Rule Setting)
+| Field | Description | Type |
+|---|---|---|
+| Counter / Bucket to extract | Bộ đếm và Bucket cụ thể sẽ được trích xuất (Current, Previous, Period before Last). Giá trị rút ra sẽ làm "Số tiền giao dịch" (Transaction Amount). | Drop-down |
+| Transaction Code | Mã giao dịch ảo sẽ được gắn cho giao dịch sinh ra từ CEP để kích hoạt các Rule nhận thưởng. | Drop-down |
+| -ve Bal. Adjust. Transaction Code | Nếu giá trị Counter rút ra bị âm, hệ thống sẽ dùng mã giao dịch này để kích hoạt Rule điều chỉnh giảm (Negative Adjustment). | Drop-down |
+| Execution Sequence Number | Thứ tự ưu tiên thực thi nếu có nhiều CEP request cùng chạy. | 9(4) > 0 |
+
+### 3. Lịch chạy (Run Schedule)
+Lịch chạy quyết định thời điểm CEP Batch Job quét và xử lý quy tắc này:
+- **Day / Month / Annually**: Chạy lặp lại mỗi N ngày / N tháng (vào ngày cụ thể) / N năm.
+- **Statement Cycle**: Chạy vào ngày chốt sao kê của tài khoản.
+- **N days after AOD**: Chạy sau N ngày kể từ Ngày mở tài khoản (Account Opened Date).
+
+## Cách hoạt động (How It Works)
+
+- **Trích xuất dữ liệu**: Đến thời điểm chạy đã lên lịch (Run Schedule), CEP Batch Job sẽ tìm Counter được chỉ định và bóc tách Bucket mong muốn (Ví dụ: cuối tháng thì bóc "Previous Bucket" của tháng trước). Giá trị tổng lũy kế trong Bucket đó được lấy ra làm `Transaction Amount`.
+- **Sinh giao dịch ảo**: Dữ liệu vừa lấy được đóng gói thành một giao dịch (dưới dạng Award hoặc Adjustment tùy thuộc giá trị dương hay âm) với `Transaction Code` đã thiết lập.
+- **Kích hoạt Rule đích**: Giao dịch ảo này được đẩy vào hệ thống xử lý giao dịch. Các Campaign Rule khác (đang lắng nghe `Transaction Code` này) sẽ bắt được giao dịch, lấy `Transaction Amount` để đưa vào công thức tính toán và tiến hành trả thưởng.
+- **Cập nhật Trạng thái Bucket**: Để tránh trích xuất trùng lặp vào kỳ chạy sau, trạng thái của Bucket sau khi trích xuất sẽ được cập nhật (phụ thuộc vào cấu hình của Counter Definition):
+  - Đổi từ `C` sang `A` nếu giao dịch sinh ra có thỏa mãn điều kiện nhận thưởng (Hit CP Rule).
+  - Đổi từ `C` sang `E` nếu chỉ cần trích xuất xong là cập nhật (bất kể có nhận thưởng hay không).
+
+## Mối quan hệ với modules khác
+
+- **Counter Definition**: CEP lấy dữ liệu đầu vào trực tiếp từ Counter. Không có Counter thì CEP không có dữ liệu để trích xuất.
+- **Transaction Code (TC)**: CEP đóng vai trò là "nguồn phát" giao dịch ảo. Mã TC do CEP gắn vào sẽ quyết định hướng đi của giao dịch.
+- **Campaign Rule**: Các quy tắc trả thưởng thông thường đóng vai trò "người nhận", lắng nghe các giao dịch do CEP tạo ra để hoàn tất khâu tính toán và trả điểm.
+
+## Ví dụ thực tế
+
+Chiến dịch: "Hoàn tiền 5% tổng chi tiêu tháng trước".
+1. Hệ thống có một Counter tích lũy tổng chi tiêu hàng tháng.
+2. Thiết lập một CEP Request với cấu hình:
+   - Counter to extract: Tổng chi tiêu.
+   - Bucket to extract: Previous Bucket.
+   - Transaction Code: "CALC_CASHBACK".
+   - Run Schedule: Monthly, vào ngày 1 hàng tháng.
+3. Ngày 1/5, CEP Batch Job chạy. Nó rút "Previous Bucket" (tổng chi tiêu tháng 4) của Khách hàng A, thấy giá trị là 10,000,000 VND.
+4. CEP tạo một giao dịch ảo với mã "CALC_CASHBACK" và Amount = 10,000,000.
+5. Một Campaign Rule khác nhận giao dịch này, áp dụng công thức 5% * 10,000,000 = 500,000 VND, và cộng thẳng vào Pool hoàn tiền của Khách hàng A.

docs/knowledge-cards/campaign/counter_definition.md

@@ -0,0 +1,62 @@
+---
+card_id: "campaign/counter_definition"
+title: "Định nghĩa Bộ đếm (Counter Definition)"
+domain: "campaign"
+related_cards:
+  - "campaign/campaign_rule"
+  - "customer/customer_overview"
+  - "customer/account"
+  - "customer/card"
+tags: ["counter", "bucket", "tracking", "spend", "frequency", "state counter"]
+---
+
+# Định nghĩa Bộ đếm (Counter Definition)
+
+## Mô tả ngắn
+
+Counter Definition (Định nghĩa Bộ đếm) là công cụ được sử dụng để theo dõi và cộng dồn các chỉ số (tổng chi tiêu, tổng điểm thưởng, số lượng giao dịch...) trong những chu kỳ thời gian nhất định. Các bộ đếm này đóng vai trò quan trọng trong việc thiết lập điều kiện (criteria) cho các Campaign Rule, ví dụ: "tặng thưởng nếu tổng chi tiêu trong tháng lớn hơn $1,000".
+
+## Thuật ngữ liên quan
+
+- **Counter (Bộ đếm)**: Cấu hình logic định nghĩa cách thức hệ thống đếm và tích lũy dữ liệu.
+- **Bucket (Nhóm lưu trữ)**: Nơi chứa giá trị lũy kế của Counter trong một chu kỳ thời gian cụ thể.
+- **State Counter**: Loại bộ đếm đặc biệt, không tự động đóng chu kỳ theo thời gian mà dựa vào một trạng thái (State) do quy trình khác (như Campaign Rule) cập nhật thành "Closed".
+- **AOD / COD**: Account Opened Date (Ngày mở tài khoản) / Card Opened Date (Ngày mở thẻ).
+- **Late transaction**: Giao dịch bị ghi nhận trễ so với thời gian thực tế phát sinh.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+| Field | Description | Type |
+|---|---|---|
+| Counter Id / Name / Description | Định danh hệ thống, Tên và Mô tả chi tiết của bộ đếm. | X(10) / X(50) / X(200) |
+| Effective From / To Date | Khoảng thời gian bộ đếm này có hiệu lực hoạt động. | Date |
+| Entity | Cấp độ thực thể mà bộ đếm được theo dõi (Customer, Account, Card). | Drop-down |
+| Bucket Period Unit | Chu kỳ của Bucket (Ví dụ: Day, Month, Quarter, Days from AOD/COD, Fixed Date, Non Expiry). | Drop-down |
+| Bucket Period Duration(N) | Độ dài của chu kỳ (N). Ví dụ: N=3 và Unit=Month => Bucket 3 tháng. | 9(02) |
+| What to count | Chỉ số mà bộ đếm sẽ theo dõi (Ví dụ: Số tiền chi tiêu, Tần suất, Số đơn vị Pool). | Drop-down |
+| Reset type / Value | Loại khởi tạo lại (về 0 hoặc về số dư thừa) khi chạm mức Reset Value. Mặc định là 999999999. | Drop-down / 9(14,2) |
+| First Start Date (Is Fixed) | Cấu hình cho phép cố định ngày bắt đầu chu kỳ đếm đầu tiên. | Switch / Date |
+| Update State When | Thời điểm tự động đóng bucket (chuyển State = 'A'): khi được trích xuất và thỏa Rule (On ward), khi trích xuất (On extract), hoặc không bao giờ (Never). | Radio button |
+| Late transaction Posting Option | Cách xử lý giao dịch trễ: Cập nhật vào "Late counter value" hoặc "Current counter bucket". | Radio button |
+
+## Cách hoạt động (How It Works)
+
+- **Nguyên lý Bucket hóa**: Khi một giao dịch thỏa mãn điều kiện tích lũy của Counter, hệ thống sẽ xác định thời gian giao dịch để tìm (hoặc tạo mới) một Bucket có chu kỳ tương ứng và cộng dồn giá trị vào đó.
+- **Cơ chế đóng Bucket (State)**: 
+  - Mặc định Bucket có trạng thái "C" (Created).
+  - Nó có thể bị đóng chu kỳ ("Closed" hoặc "A") tự động dựa theo khoảng thời gian (Transaction/Batch Date) hoặc bị đóng ép buộc (đối với State Counter) bởi một quy trình Campaign. 
+  - Sau khi bị đóng, mọi cập nhật mới của Counter sẽ tạo ra và rơi vào một "Bucket hiện tại" (current bucket) mới.
+- **Xử lý giao dịch trễ (Late Posting)**: Nếu giao dịch được gửi đến hệ thống khi Bucket tương ứng của nó đã bị đóng (State != C), hệ thống sẽ nhìn vào cấu hình để quyết định: (1) Cộng vào một giá trị "Late Value" riêng biệt của Bucket cũ, hoặc (2) Cộng dồn vào Bucket đang Active ở hiện tại dựa theo ngày ghi nhận (Post date).
+- **Ràng buộc cập nhật**: Chỉ cho phép gia hạn (kéo dài End Date) hoặc đổi Tên/Mô tả nếu Counter đã phát sinh dữ liệu (tồn tại trong bảng `counter_stock`). Không cho phép xóa khi đã có dữ liệu.
+
+## Mối quan hệ với modules khác
+
+- **Campaign Rule**: Counter được khai báo trong Campaign Rule như một phần của điều kiện xét duyệt (Ví dụ: Counter A > 1000) hoặc dùng làm biến đầu vào để tính toán công thức thưởng.
+- **Customer Overview / Account / Card**: Dữ liệu đếm (Bucket) được liên kết và lưu trữ theo từng thực thể khách hàng hoặc tài khoản cụ thể.
+
+## Ví dụ thực tế
+
+Thiết lập một "Bộ đếm tần suất thanh toán" (Counter) ở cấp độ **Card**, với **Bucket Period Unit** là `Month Counter` và **Duration(N)** là `1`.
+Bộ đếm này theo dõi "Số lượng giao dịch" (Frequency). 
+Mỗi khi khách hàng cà thẻ, hệ thống cộng 1 vào Bucket của tháng hiện tại.
+Một Campaign Rule được tạo với điều kiện: Nếu vào ngày cuối tháng, Bộ đếm này >= 5 (đã thanh toán 5 lần), hệ thống sẽ thưởng cho thẻ đó 50,000 VND. Sau tháng đó, hệ thống tự động tạo Bucket mới có giá trị = 0 cho tháng tiếp theo.

docs/knowledge-cards/campaign/item_redemption_rule.md

@@ -0,0 +1,71 @@
+---
+card_id: "campaign/item_redemption_rule"
+title: "Quy tắc Đổi quà (Item Redemption Rule)"
+domain: "campaign"
+related_cards:
+  - "campaign/campaign_rule"
+  - "campaign/transaction_codes"
+  - "catalogue/item_price"
+tags: ["ITRD", "redemption", "item", "criteria", "validation"]
+---
+
+# Quy tắc Đổi quà (Item Redemption Rule)
+
+## Mô tả ngắn
+
+Item Redemption Rule (Mã loại quy tắc: ITRD) là một loại Quy tắc Chiến dịch chuyên biệt được sử dụng để kiểm duyệt và đánh giá các giao dịch đổi quà (đổi vật phẩm từ Catalogue). ITRD Rule đóng vai trò như một "người gác cổng", sử dụng bộ lọc tiêu chí (Criteria) để quyết định xem khách hàng hoặc giao dịch có đủ điều kiện đổi quà hay không.
+
+## Thuật ngữ liên quan
+
+- **ITRD**: Item Redemption Rule Type.
+- **Item Price**: Cấu hình giá trị của món quà, nơi định nghĩa chính xác món quà đó sẽ trừ bao nhiêu điểm và trừ từ Quỹ (Pool) nào.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Vì ITRD là một nhánh của Campaign Rule, cấu trúc của nó vay mượn phần lớn từ quy tắc thưởng (Award Rule), nhưng **bị lược bỏ hoàn toàn 3 thành phần**: Không có Quỹ thưởng (Reward Pool), Không có Công thức tính (Formula), và Không có Phân bổ chi phí (Contributor).
+
+### 1. Thông tin chung (General Information)
+| Field | Description | Type |
+|---|---|---|
+| Campaign ID / Rule ID / Name | Mã chiến dịch, mã quy tắc và tên của quy tắc. Có thể nằm độc lập hoặc thuộc một Campaign. | Display / X |
+| Rule Type | Loại quy tắc, cấu hình cố định là "Item Redemption". | Display |
+| Effective Date From / To | Thời gian hiệu lực của quy tắc. | Date |
+
+### 2. Cấu hình Quy tắc (Rule Setting)
+| Field | Description | Type |
+|---|---|---|
+| Effective Period is Based On | Tiêu chí tính ngày hiệu lực dựa trên Ngày giao dịch thực tế (Transaction Date) hay Ngày hệ thống xử lý (Batch Date). | Radio button |
+| Message Template ID | Mẫu tin nhắn (SMS/Email) tự động gửi cho khách hàng nếu giao dịch đổi quà khớp (hit) quy tắc này. | Drop-down |
+| Stop if criteria met | Nếu BẬT (Yes), hệ thống sẽ ngừng xét duyệt các quy tắc ITRD tiếp theo nếu quy tắc này đã khớp. | Switch |
+
+### 3. Liên kết Mã giao dịch (Linked Transaction Code)
+| Field | Description | Type |
+|---|---|---|
+| Transaction Code | Mã giao dịch (OLS TC) dùng để kích hoạt Rule này. Bắt buộc phải có ít nhất 1 TC và duy nhất trong nội bộ Rule. | Drop-down |
+| Execution Sequence | Trình tự thực thi của quy tắc. Dùng để xếp hạng ưu tiên khi hệ thống xử lý nhiều quy tắc cùng gắn chung 1 TC. | 9(04) > 0 |
+
+### 4. Tiêu chí Xét duyệt (Rule Criteria)
+- Sử dụng Query Builder giống hệt cấu trúc Criteria của Award Rule để cấu hình các điều kiện hợp lệ. (Ví dụ: Chỉ áp dụng cho hạng thẻ Platinum).
+
+## Cách hoạt động (How It Works)
+
+- **Cấu hình độc lập với Cấu trúc giá**: Khác với quy tắc tặng thưởng (phải định nghĩa tặng bao nhiêu, từ quỹ nào), ITRD chỉ trả lời câu hỏi "Được phép hay Không được phép đổi?". Còn việc "Trừ bao nhiêu điểm và trừ quỹ nào?" được hệ thống lấy từ cấu hình giá (Item Price) của chính món quà đó trong Catalogue.
+- **Xác thực giao dịch (Validation)**: Khi một yêu cầu đổi quà gửi đến hệ thống kèm theo một Mã giao dịch (Redemption TC), hệ thống quét tìm tất cả các ITRD Rule gắn với TC đó.
+- **Duyệt điều kiện**: Hệ thống chạy kiểm tra thông tin khách hàng/giao dịch với bộ lọc Criteria của Rule. Nếu thỏa mãn toàn bộ điều kiện, giao dịch được đánh giá là Hợp lệ và tiến trình trừ điểm bắt đầu. Nếu không có ITRD Rule nào được cấu hình hoặc giao dịch trượt mọi Criteria, yêu cầu đổi quà bị từ chối.
+
+## Mối quan hệ với modules khác
+
+- **Campaign Rule**: ITRD là một biến thể của Campaign Rule, kế thừa logic kiểm tra điều kiện (Criteria) nhưng khác biệt về luồng xử lý đầu ra.
+- **Transaction Codes**: Đóng vai trò là cầu nối định tuyến giao dịch đổi quà vào đúng bộ quy tắc ITRD để kiểm tra.
+- **Item Price**: ITRD phụ trách mảng "Kiểm duyệt điều kiện", trong khi Item Price phụ trách mảng "Thanh toán/Trừ điểm". Hai module này kết hợp với nhau để hoàn tất một luồng đổi quà.
+
+## Ví dụ thực tế
+
+Ngân hàng muốn tung ra chương trình: "Chỉ khách hàng hạng Platinum mới được phép đổi Tai nghe Apple AirPods".
+1. Trong Catalogue, cấu hình `Item Price` cho AirPods là 500,000 điểm.
+2. Quản trị viên thiết lập một `Item Redemption Rule (ITRD)`:
+   - Gắn với `Transaction Code` = "REDEEM_VIP_GIFT".
+   - Thiết lập `Criteria`: Hạng tài khoản (Account Level) = 'Platinum'.
+3. Khi khách hàng thao tác đổi tai nghe, ứng dụng gửi giao dịch kèm mã "REDEEM_VIP_GIFT".
+4. Khách hàng A (Hạng Gold) -> Trượt `Criteria` của ITRD -> Giao dịch bị từ chối.
+5. Khách hàng B (Hạng Platinum) -> Khớp `Criteria` của ITRD -> Hệ thống cho qua vòng kiểm duyệt, chuyển sang đọc `Item Price` và tiến hành trừ 500,000 điểm của B.

docs/knowledge-cards/campaign/pool_conversion_rate.md

@@ -0,0 +1,62 @@
+---
+card_id: "campaign/pool_conversion_rate"
+title: "Tỷ lệ chuyển đổi Quỹ (Pool Conversion Rate)"
+domain: "campaign"
+related_cards:
+  - "campaign/pool_definition"
+  - "customer/transaction_history"
+tags: ["conversion rate", "buy rate", "sell rate", "currency", "GL"]
+---
+
+# Tỷ lệ chuyển đổi Quỹ (Pool Conversion Rate)
+
+## Mô tả ngắn
+
+Pool Conversion Rate (Tỷ lệ chuyển đổi Quỹ) quản lý tỷ giá quy đổi giữa đơn vị của một Pool (ví dụ: Điểm) và đồng tiền cơ sở (Base Currency) của hệ thống (ví dụ: VND). Tỷ lệ này được sử dụng để định giá các giao dịch cấp phát (award), đổi điểm (redeem), và điều chỉnh (adjustment) nhằm ghi nhận vào hệ thống Sổ cái (GL - General Ledger).
+
+## Thuật ngữ liên quan
+
+- **Base Currency**: Đồng tiền cơ sở của hệ thống để làm chuẩn quy đổi giá trị tài chính.
+- **Buy Rate**: Tỷ giá mua, là lượng Base Currency cần thiết để mua 1 đơn vị Pool.
+- **Sell Rate**: Tỷ giá bán, là lượng Base Currency thu lại khi tiêu/đổi 1 đơn vị Pool.
+- **Effective Record**: Bản ghi tỷ giá đang trong thời gian có hiệu lực (từ Start Date đến End Date).
+- **GL (General Ledger)**: Sổ cái kế toán, nơi ghi nhận các hạch toán tài chính của các giao dịch cấp phát/tiêu điểm.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### Mã tỷ lệ chuyển đổi (Pool Conversion Rate Code)
+| Field | Description | Type |
+|---|---|---|
+| Pool conversion Rate Code | Mã đại diện cho tỷ lệ chuyển đổi, chứa ít nhất một chữ cái. | X(10) |
+| Description | Tên mô tả của loại tiền tệ/tỷ giá (hiển thị trên dropdown, báo cáo). | X(30) |
+
+### Chi tiết Tỷ lệ chuyển đổi (Pool conversion Rate)
+| Field | Description | Type |
+|---|---|---|
+| Buy Rate | Số lượng Base Currency cần để mua 1 đơn vị Pool. Dùng để định giá các giao dịch cộng điểm/cấp phát để hạch toán lên GL. | 9(6,2) > 0 |
+| Sell Rate | Số lượng Base Currency nhận được khi đổi 1 đơn vị Pool. Dùng để định giá các giao dịch tiêu điểm/trừ điểm (non-catalogue) để hạch toán lên GL. | 9(6,2) > 0 |
+| Effective From Date | Ngày bắt đầu hiệu lực của tỷ giá. | Date |
+| Effective End Date | Ngày kết thúc hiệu lực của tỷ giá (phải >= From Date). | Date |
+
+## Cách hoạt động (How It Works)
+
+- **Định giá giao dịch cộng điểm (Award/Positive Adjust)**: Khi có giao dịch thưởng điểm hoặc điều chỉnh tăng, hệ thống dùng **Buy Rate** có hiệu lực tại thời điểm đó để tính giá trị tài chính của điểm, sau đó gửi thông tin này để ghi sổ cái (GL).
+- **Định giá giao dịch trừ điểm (Redeem/Negative Adjust)**: Khi có giao dịch đổi điểm (cho các phần thưởng không nằm trong catalogue) hoặc điều chỉnh giảm, hệ thống dùng **Sell Rate** có hiệu lực tại thời điểm đó để tính toán chi phí (cost) và ghi sổ cái.
+- **Xác định tỷ giá có hiệu lực**: Một Pool Conversion Rate Code có thể có nhiều bản ghi tỷ giá với khoảng thời gian khác nhau (Start Date - End Date). Trong trường hợp có nhiều bản ghi cùng có hiệu lực tại một thời điểm, hệ thống sẽ ưu tiên sử dụng bản ghi có Start Date gần nhất (latest).
+
+## Mối quan hệ với modules khác
+
+- **Pool Definition**: Mỗi Pool phải được gắn với một Pool Conversion Rate Code. Khi xử lý giao dịch trên Pool, tỷ lệ quy đổi của Code này sẽ được áp dụng.
+- **Transaction History**: Các giao dịch phát sinh sẽ tra cứu tỷ giá từ cấu hình này để lưu giá trị tài chính quy đổi.
+
+## Ví dụ thực tế
+
+Tạo mã quy đổi "PNT_VND" cho quỹ điểm Loyalty.
+Base Currency là VND.
+Cấu hình tỷ giá:
+- Buy Rate = 100 (Cần 100 VND để sinh ra 1 điểm).
+- Sell Rate = 80 (Khách hàng tiêu 1 điểm tương đương 80 VND).
+- Effective: 01/01/2026 đến 31/12/2026.
+
+Khi khách hàng được thưởng 50 điểm, hệ thống tính toán giá trị: 50 * 100 = 5,000 VND và đẩy bút toán ghi nợ 5,000 VND vào GL.
+Khi khách hàng tiêu 20 điểm, chi phí ghi nhận là 20 * 80 = 1,600 VND.

docs/knowledge-cards/campaign/pool_definition.md

@@ -0,0 +1,74 @@
+---
+card_id: "campaign/pool_definition"
+title: "Định nghĩa Quỹ Thưởng (Pool Definition)"
+domain: "campaign"
+related_cards:
+  - "customer/customer_overview"
+  - "customer/account"
+  - "customer/card"
+  - "campaign/account_type_group"
+  - "campaign/campaign_rule"
+tags: ["pool", "bucket", "balance", "expiry policy", "velocity control"]
+detail_refs:
+  - "campaign/expiry_policies"
+  - "campaign/velocity_control_detail"
+---
+
+# Định nghĩa Quỹ Thưởng (Pool Definition)
+
+## Mô tả ngắn
+
+Pool Definition là một cấu trúc dữ liệu cốt lõi dùng để theo dõi và quản lý các giá trị được lưu trữ như điểm thưởng (rewards), tiền mặt (cash balances), vé rút thăm trúng thưởng (lucky draw chances), hoặc E-voucher. Mỗi Pool được gắn với một loại phần thưởng cụ thể, sử dụng một đơn vị tiền tệ riêng (Currency Code), và quản lý số dư theo các nhóm (Buckets) dựa trên hạn sử dụng.
+
+## Thuật ngữ liên quan
+
+- **Pool (Quỹ)**: Nơi lưu trữ và theo dõi số dư của một loại phần thưởng cụ thể.
+- **Bucket (Nhóm số dư)**: Một phần của Pool chứa số dư có cùng ngày hết hạn và loại tài khoản (Account Type).
+- **Currency Code**: Đơn vị tính toán số dư trong Pool (VD: VND cho tiền mặt, PNT cho điểm thưởng).
+- **Expiry Policy (Chính sách hết hạn)**: Quy tắc xác định ngày hết hạn cho các số dư khi được cộng vào Pool.
+- **Velocity Control**: Cơ chế kiểm soát và giới hạn số lượng điểm (thưởng/đổi/điều chỉnh) dựa trên thực thể và thời gian (ví dụ: giới hạn đổi điểm mỗi tháng).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### Thông tin chung (General Information)
+| Field | Description | Type |
+|---|---|---|
+| Pool Id / Name | Định danh hệ thống và tên của quỹ thưởng. | X(10) / X(30) |
+| Pool Type | Loại quỹ thưởng (Points, Cash Rebate, Lucky Draw chances, EVoucher). | Drop-down |
+| Expiry Policy | Xác định cách hệ thống tính ngày hết hạn cho số dư mới (Inactive cho Evoucher). | Drop-down |
+| Ripening Period | Số ngày kể từ ngày giao dịch sau đó phần thưởng mới đủ điều kiện đổi (Redemption). | 9(5) |
+| Pool Conversion Rate Code | Mã tiền tệ hoặc tỷ lệ quy đổi đại diện cho một đơn vị thưởng trong Pool. | Drop-down |
+| Allow Negative Balance | Cờ cho phép số dư Pool bị âm trong các trường hợp điều chỉnh hoặc hoàn tác (reversal). | Switch |
+| Entity level | Cấp độ theo dõi số dư Pool: Customer (Khách hàng), Account (Tài khoản), hoặc Card (Thẻ). | Radio button |
+| Grace Period | Số tháng giữ lại các bucket đã hết hạn trước khi xóa hẳn. | 9(2) |
+
+### Thông số kiểm soát (Velocity Control & Specific Policy)
+| Field | Description | Type |
+|---|---|---|
+| Product Account Level / Type | Cấp độ và loại tài khoản bị giới hạn chỉ được dùng Pool này. | Drop-down |
+| Maximum | Số lượng đơn vị Pool tối đa, nếu vượt quá sẽ kích hoạt cảnh báo (Alert). | 9(10,2) |
+| Transaction Type | Loại giao dịch bị kiểm soát (Award, Redeem, Adjust). | Drop-down |
+| Units | Đơn vị kiểm soát (Trên số đơn vị Pool hoặc Trên mỗi giao dịch). | Drop-down |
+| Per period | Chu kỳ kiểm soát (Quarter, Month, Week, Day). | Drop-down |
+| Alert Template / Group | Mẫu thông báo và nhóm người nhận sẽ được gửi cảnh báo nếu vượt mức. | Drop-down |
+
+## Cách hoạt động (How It Works)
+
+- **Cấu trúc lưu trữ (Buckets)**: Khi số dư trong Pool được tăng lên (earned), hệ thống sử dụng Expiry Policy để xác định ngày hết hạn. Số lượng này sau đó được lưu vào một "Bucket" tương ứng. Mỗi Pool có thể có nhiều Bucket khác nhau, phân tách bằng Ngày hết hạn và Loại tài khoản.
+- **Phân cấp thực thể (Entity Level)**:
+  - Nếu Pool cấu hình ở cấp độ **Card**, mỗi bucket sẽ tương ứng với một thẻ cụ thể (Card number) và khoảng thời gian nhất định.
+  - Nếu cấu hình ở cấp độ **Account** hoặc **Customer**, bucket sẽ tương ứng với Account đó.
+- **Quy tắc hết hạn (Expiry & Grace Period)**: Khi bucket đến hạn, số dư chuyển sang trạng thái "Số dư quá hạn" (Expired balance). Số dư này tiếp tục được giữ lại trong khoảng thời gian ân hạn (Grace Period) trước khi bị xóa bỏ hoàn toàn (forfeited).
+- **Kiểm soát vận tốc (Velocity Control)**: Pool có thể thiết lập các mức trần cho các giao dịch (thưởng/đổi) trong một khoảng thời gian (Ngày, Tuần, Tháng, Quý) trên từng thực thể. Nếu vượt qua giới hạn này, cảnh báo (alert) sẽ tự động gửi đi.
+
+## Mối quan hệ với modules khác
+
+- **Customer Overview / Account / Card**: Pool phải thuộc về một Loyalty Account cụ thể, được định nghĩa thông qua Entity level (cấp Khách hàng, Tài khoản, hoặc Thẻ).
+- **Campaign Rule**: Pool Definition được sử dụng làm đích đến để trả thưởng trong các Campaign Rule. Mỗi Rule thưởng phải chỉ định nạp vào Pool nào.
+- **Account Type Group**: Có thể được cấu hình (optional) để giới hạn các giao dịch của các loại tài khoản thuộc nhóm này mới được thao tác vào Pool.
+
+## Ví dụ thực tế
+
+Tạo một Pool tên "Quỹ Điểm Thưởng Khách Hàng VIP" (Pool Type: Points) với Entity level là Customer. Tỷ lệ hết hạn (Expiry Policy) là 1 năm kể từ ngày thưởng.
+Mỗi khi khách hàng phát sinh giao dịch nhận điểm, điểm này được cho vào một Bucket có ngày hết hạn tương ứng là đúng 1 năm sau.
+Pool này cài đặt Velocity Control: Chỉ cho phép đổi điểm (Redeem) tối đa 10,000 điểm mỗi tháng. Nếu khách hàng thực hiện lệnh đổi 12,000 điểm, hệ thống sẽ chặn 2,000 điểm vượt mức và kích hoạt thông báo (Alert Template) gửi về trung tâm vận hành.

docs/knowledge-cards/campaign/rep_rule.md

@@ -0,0 +1,75 @@
+---
+card_id: "campaign/rep_rule"
+title: "Quy tắc Đổi thưởng và Xử lý tự động (REP Rule)"
+domain: "campaign"
+related_cards:
+  - "campaign/campaign_rule"
+  - "campaign/pool_definition"
+  - "campaign/transaction_codes"
+tags: ["REP", "redemption", "extract", "cash rebate", "batch"]
+detail_refs:
+  - "campaign/batch_rule_processing"
+---
+
+# Quy tắc Đổi thưởng và Xử lý tự động (REP Rule)
+
+## Mô tả ngắn
+
+Redemption Extract & Process (REP) Rule là một loại Quy tắc Chiến dịch đặc biệt, đóng vai trò như một tác vụ lên lịch tự động (batch job). REP có nhiệm vụ định kỳ quét và trích xuất toàn bộ số dư từ một Quỹ thưởng (Pool) được chỉ định, sau đó tự động thực hiện lệnh đổi thưởng (Redeem) để xuất ra dưới dạng tiền hoàn (Cash Rebate) hoặc điểm đối tác (VD: dặm bay bay) chuyển đến hệ thống bên ngoài.
+
+## Thuật ngữ liên quan
+
+- **REP (Redeem Extract & Process)**: Quy trình tự động trích xuất số dư quỹ và sinh giao dịch đổi thưởng.
+- **Cash Rebate**: Hoàn tiền mặt, một dạng output phổ biến của REP khi trích xuất điểm để quy đổi thành tiền đẩy về tài khoản thanh toán của khách.
+- **Minimum Pool Balance**: Số dư quỹ tối thiểu cần phải có để REP kích hoạt việc rút điểm.
+- **Output Redemption As**: Hình thức và kênh xuất dữ liệu sau khi đổi thưởng (Ví dụ: xuất file ghi nhận Cash Rebate gửi hệ thống Core Banking).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. Thông tin chung (General Information)
+| Field | Description | Type |
+|---|---|---|
+| Campaign ID / Rule ID / Name | Mã chiến dịch, mã quy tắc và tên của quy tắc REP. | Display / X |
+| Rule Type | Loại quy tắc, cấu hình cố định là "Redeem Extract & Process [REP]". | Display |
+| Effective Date From / To | Khoảng thời gian REP Rule này có hiệu lực hoạt động. | Date |
+
+### 2. Cấu hình Đổi thưởng (Rule Setting)
+| Field | Description | Type |
+|---|---|---|
+| Pool to Extract | Quỹ thưởng (Pool) sẽ bị rút sạch số dư (full amount) để đổi thưởng. Các chiến dịch dùng REP nên cấu hình Pool chuyên biệt để tránh rút nhầm số dư của chiến dịch khác. | Drop-down |
+| Minimum Pool Balance | Số điểm tối thiểu mà Pool phải đạt được thì REP Batch mới thực hiện trích xuất. | 9(12,2) |
+| Trigger Campaign rule | Nếu bật (ON), REP sẽ kích hoạt thêm một Campaign Rule khác để kiểm tra điều kiện phụ và tính toán lại số điểm được rút (Rút mức nhỏ hơn giữa số dư hiện tại và kết quả công thức). | Switch |
+| Redeem TC | Mã giao dịch (Transaction Code) sẽ được hệ thống gán cho giao dịch đổi điểm sinh ra. | Drop-down |
+| Redeem Transaction Description | Mô tả ngắn ghi nhận trên giao dịch đổi thưởng. | X(50) |
+| Output Redemption As | Kênh xuất file hoặc định dạng đầu ra cho hệ thống bên ngoài (Ví dụ: Cash Rebate to External System). | Drop-down |
+| -ve Bal. Adjust. Transaction Code | Mã giao dịch điều chỉnh giảm (Negative Adjustment) sẽ dùng nếu quá trình trích xuất gặp số dư âm. | Drop-down |
+
+### 3. Lịch chạy (Run Schedule)
+Lịch cấu hình thời điểm hệ thống tự động chạy REP Batch:
+- **Day / Month / Annually**: Chạy lặp lại mỗi N ngày / tháng / năm tại một thời điểm nhất định.
+- **Statement Cycle**: Chạy vào kỳ sao kê. Hệ thống chỉ bóc tách các tài khoản có ngày sao kê trùng với ngày chạy batch.
+- **N days/months from AOD**: Chạy vào N ngày hoặc N tháng sau Ngày mở tài khoản (Account Opened Date).
+
+## Cách hoạt động (How It Works)
+
+- **Quét theo lịch trình**: Theo đúng lịch cấu hình (Run Schedule), hệ thống REP Batch khởi động và tìm kiếm những khách hàng/tài khoản thỏa mãn điều kiện thời gian.
+- **Kiểm tra số dư (Balance Check)**: Hệ thống tra cứu Pool được cấu hình (`Pool to Extract`) của tài khoản đó. Nếu số dư hiện tại lớn hơn hoặc bằng `Minimum Pool Balance`, hệ thống sẽ tiếp tục.
+- **Đổi thưởng tự động (Auto-Redemption)**: Hệ thống trích xuất toàn bộ số dư khả dụng trong Pool đó và tạo ra một giao dịch Redeem với mã `Redeem TC` tương ứng. Giao dịch này sẽ trừ sạch điểm trong Pool (hoặc trừ theo mức đã tính toán lại nếu có bật `Trigger Campaign rule`).
+- **Gửi hệ thống ngoài (Output)**: Số điểm vừa bị trừ đi sẽ được hệ thống đóng gói theo định dạng cấu hình ở `Output Redemption As` và chuyển đến hệ thống khác (ví dụ: tạo file chuyển tiền cho Core Banking).
+
+## Mối quan hệ với modules khác
+
+- **Pool Definition**: Điểm đến của REP. REP trực tiếp thao tác rút sạch số dư của một Pool.
+- **Campaign Rule**: REP có thể đóng vai trò kích hoạt (trigger) một Campaign Rule thông thường để vay mượn logic kiểm tra điều kiện phức tạp trước khi đổi thưởng.
+- **Transaction Code**: REP tạo ra các giao dịch tự động nên cần mượn cấu hình Transaction Code để ghi nhận đúng vào hệ thống kế toán.
+
+## Ví dụ thực tế
+
+Ngân hàng có chương trình "Hoàn tiền thẻ tín dụng hàng tháng".
+1. Khi khách quẹt thẻ, một Campaign Rule cấp phát điểm Cash-back vào Pool "Hoàn Tiền Thẻ".
+2. Ngân hàng thiết lập một quy tắc REP (REP Rule) chạy vào ngày mùng 5 hàng tháng (Run Schedule: Monthly, Day = 5).
+3. Cấu hình REP: 
+   - Pool to Extract = "Hoàn Tiền Thẻ"
+   - Minimum Pool Balance = 100,000. 
+   - Output Redemption As = "Cash Rebate to External System".
+4. Ngày 5/5, Batch chạy. Khách hàng B có 150,000 điểm trong Pool "Hoàn Tiền Thẻ". Do 150,000 > 100,000, REP trích xuất toàn bộ 150,000 điểm, tạo giao dịch Redeem trừ sạch Pool của khách, đồng thời sinh file gửi Core Banking để nạp 150,000 VND vào thẻ tín dụng cho khách hàng B.

docs/knowledge-cards/campaign/reward_campaign.md

@@ -0,0 +1,78 @@
+---
+card_id: "campaign/reward_campaign"
+title: "Chiến dịch Thưởng (Reward Campaign)"
+domain: "campaign"
+related_cards:
+  - "campaign/campaign_rule"
+  - "customer/pool_balance"
+  - "campaign/cep_request"
+tags: ["campaign", "award", "accumulate", "counter", "redemption"]
+---
+
+# Chiến dịch Thưởng (Reward Campaign)
+
+## Mô tả ngắn
+
+Chiến dịch Thưởng (Reward Campaign) là thực thể cốt lõi định nghĩa các chương trình ưu đãi, cấp điểm thưởng hoặc hoàn tiền cho khách hàng. Mỗi chiến dịch có thể chứa nhiều Quy tắc (Campaign Rules). Tùy vào cách cấu hình, chiến dịch có thể hoạt động theo cơ chế cấp thưởng ngay lập tức trên từng giao dịch, hoặc tích lũy tổng chi tiêu qua một bộ đếm (Counter) để xét thưởng vào cuối kỳ.
+
+## Thuật ngữ liên quan
+
+- **Base / Tactical Campaign**: Base là chiến dịch nền tảng áp dụng rộng rãi và lâu dài; Tactical là chiến dịch ngắn hạn với mục tiêu cụ thể (ví dụ: đẩy mạnh chi tiêu ngoại tệ tháng này).
+- **Counter (Bộ đếm)**: Thực thể lưu trữ cộng dồn các chỉ số (tổng chi tiêu, số lượng giao dịch, tổng điểm) của một khách hàng trong một khoảng thời gian (Period).
+- **Auto-redemption**: Cơ chế tự động đổi phần thưởng vừa cấp (VD: dặm bay) để chuyển trực tiếp sang hệ thống đối tác bên ngoài mà khách hàng không cần tự thao tác.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Thực thể Chiến dịch (Campaign) chỉ lưu trữ các thông tin định danh và mục tiêu cấp cao, trong khi logic kinh doanh chi tiết được đẩy xuống các Campaign Rules.
+
+### 1. Định danh và Phân loại
+- **Campaign ID / Name**: Mã và tên định danh chiến dịch.
+- **Campaign Type**: Loại chiến dịch (Base hoặc Tactical).
+- **Campaign Period**: Không được nhập tay ở cấp độ Campaign, mà được hệ thống **tính toán động (derived)**: Start Date bằng ngày bắt đầu sớm nhất của Rule, và End Date bằng ngày kết thúc muộn nhất của Rule trong chiến dịch đó.
+
+### 2. Mục tiêu (Target Metrics)
+- **Target Active Customer Count**: Số lượng khách hàng dự kiến tham gia.
+- **Target Average Transaction Value**: Mục tiêu tổng giá trị chi tiêu cần đạt.
+*(Các chỉ số này dùng để so sánh với kết quả thực tế trên Dashboard Insight).*
+
+### 3. Bộ đếm (Counter Definition)
+Counter là một phần cấu trúc quan trọng hỗ trợ Campaign, bao gồm:
+- **Entity**: Cấp độ đếm (Customer, Account, Card, Store, v.v.).
+- **Entity Counted**: Chỉ số cần đếm: GA (Gross Amount), NA (Nett Amount), PT (Points), TX (Transactions), QT (Quantity).
+- **Period Unit & Length**: Đơn vị tính chu kỳ (Day, Week, Month, Quarter) và độ dài. (VD: 1 Month).
+- **FSD (First Start Date) & BED (Bucket End Date)**: Ngày bắt đầu của chu kỳ đếm đầu tiên, và ngày chốt sổ của chu kỳ. Hệ thống tự động xoay vòng BED cho các chu kỳ tiếp theo.
+- **Reset Value / Keep Remainder**: Mức giá trị để reset bộ đếm, và có giữ lại phần dư hay không (modulus).
+
+## Phân loại Cơ chế Cấp thưởng (Campaign Mechanics)
+
+### 1. Award on Every Transaction (Cấp thưởng tức thời)
+- Áp dụng cho các chiến dịch có rule đơn giản (VD: mua 100K tặng 10 điểm).
+- **Luồng xử lý**: Giao dịch (từ Core, POS hoặc qua CEP) chạy vào hệ thống -> Quét Campaign Rule -> Tính toán theo công thức -> Trích điểm từ Reward Pool và cộng trực tiếp vào Pool Balance của khách hàng ngay tại thời điểm xử lý (Real-time hoặc Batch).
+
+### 2. Accumulate Then Award (Tích lũy rồi cấp thưởng)
+- Áp dụng khi phần thưởng phụ thuộc vào tổng mức độ hoàn thành trong một kỳ (VD: chi tiêu tổng > 1,000$ trong tháng mới được thưởng 20%).
+- **Luồng xử lý**:
+  - Giao dịch phát sinh -> Quét Campaign Rule 1 -> Cộng dồn giá trị vào **Counter** tương ứng.
+  - Đến ngày chốt kỳ (BED) -> Quét Campaign Rule 2 -> Lấy tổng giá trị trong Counter ra làm Input -> Tính toán công thức -> Cấp thưởng.
+
+## Cơ chế Trừ điểm (Bucket Deduction Sequence)
+
+Mặc dù quy tắc cấp thưởng được định nghĩa ở Campaign, hệ thống có một quy chuẩn cố định về việc trừ điểm khi khách hàng sử dụng (Redeem) như sau:
+1. **Ưu tiên Expiry Date**: Các Buckets có ngày hết hạn sớm nhất (Earliest Expiry Date) sẽ bị trừ trước (FIFO).
+2. **Ưu tiên Account Type**: Nếu có nhiều buckets cùng ngày hết hạn, hệ thống sẽ dựa vào mức độ ưu tiên của Account Type được cấu hình để trừ.
+3. Không tự động trừ vào các buckets đã hết hạn (Expired), trừ phi có sự can thiệp thủ công từ Supervisor qua màn hình Admin (Operations Adjustment).
+
+## Mối quan hệ với modules khác
+
+- **Campaign Rule**: Campaign là "vỏ" chứa nhiều Rule. Rule mới quyết định công thức tính điểm và giới hạn.
+- **Pool Balance / LAB**: Kết quả của Campaign là sinh ra các giao dịch (Awards) làm tăng số dư trong Pool của khách.
+- **CEP (Complex Event Processing)**: Sinh ra các giao dịch ảo kích hoạt Campaign (VD: Khách hàng sinh nhật).
+
+## Ví dụ thực tế
+
+Tạo chiến dịch "Kích cầu chi tiêu Hè" (Tactical):
+- Mục tiêu khách hàng (Target): 10,000 khách.
+- Cơ chế **Accumulate Then Award**: Khách chi tiêu thẻ Visa > 50,000,000 VND trong 1 tháng sẽ được tặng 5,000 điểm.
+- Hệ thống thiết lập 1 **Counter** (Entity Counted = Nett Amount, Period Unit = Month, Length = 1).
+- Rule 1: Cộng dồn mọi giao dịch mua sắm thẻ Visa vào Counter.
+- Rule 2 (kích hoạt cuối tháng): Nếu Counter.Balance > 50,000,000 -> Award 5,000 điểm.

docs/knowledge-cards/campaign/transaction_codes.md

@@ -0,0 +1,65 @@
+---
+card_id: "campaign/transaction_codes"
+title: "Định danh Giao dịch (Transaction Codes & Category)"
+domain: "campaign"
+related_cards:
+  - "campaign/campaign_rule"
+  - "customer/operations_transaction"
+tags: ["transaction code", "TC", "mapping", "category", "criteria"]
+---
+
+# Định danh Giao dịch (Transaction Codes & Category)
+
+## Mô tả ngắn
+
+Để hệ thống OLS có thể hiểu và định tuyến các giao dịch (từ bên ngoài hoặc nội bộ) vào đúng các quy tắc chiến dịch (Campaign Rules) phù hợp, hệ thống sử dụng cơ chế ánh xạ thông qua 3 thực thể cấu hình: **External Transaction Code** (Mã giao dịch ngoài), **OLS Transaction Code** (Mã giao dịch nội bộ) và **Transaction Category** (Danh mục giao dịch).
+
+## Thuật ngữ liên quan
+
+- **TC (Transaction Code)**: Mã giao dịch, dùng để định danh loại nghiệp vụ (ví dụ: Thanh toán POS, Rút tiền mặt, Hoàn tiền).
+- **External TC**: Mã giao dịch nguyên bản được truyền vào từ các hệ thống nguồn (Core Banking, Card System).
+- **OLS TC**: Mã giao dịch được chuẩn hóa bên trong hệ thống OLS. Đây là chìa khóa đầu tiên (First key) để hệ thống tra cứu xem giao dịch sẽ kích hoạt Rule nào.
+
+## Cấu trúc dữ liệu và Ánh xạ (Data Schema & Mapping)
+
+### 1. External Transaction Code
+- **External TC**: Mã định danh (ví dụ: `TC4000`, `ATM_WDL`).
+- **Description**: Mô tả loại giao dịch từ hệ thống nguồn để dễ nhận diện.
+- **Ràng buộc**: Mỗi External TC khi được nhận vào hệ thống **bắt buộc** phải được ánh xạ (map) tới duy nhất một OLS TC.
+
+### 2. OLS Transaction Code
+- **OLS TC**: Mã chuẩn hóa nội bộ của OLS.
+- **Mapping (1-N)**: Một OLS TC có thể nhận ánh xạ từ một hoặc nhiều External TCs (Ví dụ: `TC4000` của hệ thống thẻ Credit và `TC5000` của hệ thống thẻ Debit cùng map về OLS TC `PURCHASE`).
+- **Nguồn nội bộ**: OLS TC không bắt buộc phải có External TC đi kèm. Các giao dịch phát sinh hoàn toàn từ nội bộ (như CEP sinh ra, hoặc Award Transaction thủ công) có thể dùng thẳng OLS TC mà không cần qua bước mapping.
+- **Reversal Indicator**: Cờ (công tắc) báo hiệu đây là giao dịch hoàn trả/hủy (Reversal) hay giao dịch bình thường (Normal).
+
+### 3. Transaction Category (Danh mục giao dịch)
+- **Định nghĩa**: Là một cấu hình tập hợp nhiều tiêu chí (Criteria) tạo thành một biểu thức logic phức tạp, được lưu lại dưới một cái tên (Code) duy nhất.
+- **Cấu trúc**:
+  - Transaction Category Code & Name.
+  - Configuration: Sử dụng Query Builder (kéo thả) để tạo các nhóm tiêu chí (AND/OR). Hỗ trợ cả công tắc đảo ngược logic (NOT) để loại trừ (Exclusion).
+- **Mục đích (Tái sử dụng)**: Thay vì phải cấu hình một cụm điều kiện dài dòng (Ví dụ: `MCC = Dining AND Currency = Local AND Is_DCC = True`) lặp đi lặp lại trên nhiều Campaign Rules, người quản trị cấu hình thành `TxCat1`. Sau đó, trong Campaign Rule, chỉ cần chọn tiêu chí `Transaction Category = TxCat1`.
+
+## Cách hoạt động (How It Works)
+
+1. **Giai đoạn tiếp nhận giao dịch**:
+   - Giao dịch đổ vào hệ thống mang theo External TC (ví dụ `05`).
+   - Hệ thống tra bảng ánh xạ, chuyển `05` thành OLS TC `RETAIL_SPEND`.
+2. **Giai đoạn định tuyến Rule**:
+   - Engine tìm kiếm tất cả các Campaign Rules đang Active có khai báo OLS TC là `RETAIL_SPEND`.
+   - Nếu Rule đó có sử dụng Transaction Category làm tiêu chí (Criteria), engine sẽ "bung" category đó ra để đối chiếu thêm các trường dữ liệu thực tế (MCC, Currency, Amount) của giao dịch có khớp với biểu thức Category hay không.
+3. **Giai đoạn xử lý**: Nếu toàn bộ điều kiện khớp, giao dịch được tính hợp lệ để chạy công thức cấp thưởng.
+
+## Mối quan hệ với modules khác
+
+- **Campaign Rule**: Sử dụng OLS TC và Transaction Category như một phần cốt lõi trong "Rule Criteria" để lọc giao dịch.
+- **Operations Transaction**: Khi nhân viên tạo "Award Transaction" thủ công (để giả lập giao dịch gửi vào Rule Engine), họ sẽ phải chọn trực tiếp OLS TC (không dùng External TC).
+
+## Ví dụ thực tế
+
+Ngân hàng chạy chiến dịch: "Tặng 5% khi ăn uống bằng ngoại tệ" và "Tặng 2% khi ăn uống trong nước".
+Thay vì cấu hình lại nguyên cụm MCC Ẩm thực nhiều lần:
+1. Tạo Transaction Category 1: `CAT_DINING` = (MCC in [5812, 5814]).
+2. Tạo Campaign Rule 1: TC = `PURCHASE` AND Transaction Category = `CAT_DINING` AND Currency != `VND`. Rate = 5%.
+3. Tạo Campaign Rule 2: TC = `PURCHASE` AND Transaction Category = `CAT_DINING` AND Currency = `VND`. Rate = 2%.
+Khi giao dịch đến mang External TC `TC4000` (được map về OLS TC `PURCHASE`), hệ thống sẽ đối chiếu và chia nhánh xử lý mượt mà.

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`.

docs/knowledge-cards/customer/account.md

@@ -0,0 +1,74 @@
+---
+card_id: "customer/account"
+title: "Tài khoản Sản phẩm (Account)"
+domain: "customer"
+related_cards:
+  - "customer/customer_overview"
+  - "customer/card"
+tags: ["account", "PAL", "PAT", "CIF"]
+---
+
+# Tài khoản Sản phẩm (Account)
+
+## Mô tả ngắn
+
+Account (Tài khoản Sản phẩm) là thực thể đại diện cho các tài khoản tài chính hoặc dịch vụ của khách hàng trong hệ thống. Các tài khoản này có thể được đồng bộ từ hệ thống bên ngoài hoặc được tạo trực tiếp trên hệ thống Loyalty thông qua quyền quản trị. Mỗi tài khoản bắt buộc thuộc về một khách hàng duy nhất.
+
+## Thuật ngữ liên quan
+
+- **CIF**: Customer Information File - Mã định danh duy nhất của khách hàng trên hệ thống.
+- **PAL**: Product Account Level - Hạng tài khoản sản phẩm.
+- **PAT**: Product Account Type - Loại tài khoản sản phẩm, phải thuộc về một PAL tương ứng.
+- **ASN**: Account Sequence Number - Số thứ tự tài khoản duy nhất trong hệ thống kết hợp từ Account Type và Account No.
+- **OLSACCT**: Tên luồng batch xử lý đồng bộ dữ liệu tài khoản từ hệ thống bên ngoài.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### Thông tin chung (Account Information)
+
+| Field (EN/VN) | Description | Data type / Rules |
+| --- | --- | --- |
+| CIF number | Mã khách hàng sở hữu tài khoản. | Hiển thị (Lookup). |
+| Product Account Level (PAL) | Hạng tài khoản (VD: Gold, Silver). | Lookup từ danh mục PAL. |
+| Product Account Type (PAT) | Loại tài khoản thuộc về PAL. PAL + PAT = Account Type. | Lookup từ danh mục PAT. |
+| Account Number | Số tài khoản sản phẩm. | X(20). Kết hợp Account Type + Account Number phải là DUY NHẤT. |
+| Account Open Date | Ngày mở tài khoản. | Date. |
+| Account Indicator | Chỉ thị tài khoản (VD: P-Personal, C-Corporate). | Lookup (Acct-indicator). |
+| Account block code | Mã chặn tài khoản (dùng validate chặn giao dịch). | X(10). |
+| Block code reason | Lý do chặn. | X(100). |
+| Block code last update date | Ngày cập nhật trạng thái chặn cuối cùng. | Date. |
+| Cycle | Ngày sao kê. | 9(02). Phải > 0. |
+| Account status | Trạng thái tài khoản (dùng để chặn giao dịch nếu cần). | Lookup từ danh mục trạng thái. |
+
+### Thông tin thẻ liên kết (Card Information)
+
+| Field | Description | Rules |
+| --- | --- | --- |
+| Card number | Số thẻ liên kết. | Lookup qua bảng liên kết. |
+| Card status | Trạng thái thẻ. | Lookup mô tả. |
+| Card Indicator | Chỉ thị thẻ. | Lookup mô tả. |
+| Card Creation / Expiry Date | Ngày tạo và ngày hết hạn. | Date. |
+| Card block code | Mã chặn thẻ. | Lookup. |
+
+## Cách hoạt động (How It Works)
+
+- **Nguồn dữ liệu**: Tài khoản có thể được thêm từ giao diện quản trị hoặc đồng bộ qua batch OLSACCT từ hệ thống bên ngoài. Các tài khoản được tạo/cập nhật qua batch không được phép sửa từ màn hình quản trị (có thể cấu hình tắt rule này qua App Param).
+- **Thêm mới (Add)**: 
+  - Hệ thống kiểm tra sự tồn tại của bộ đôi `Account No` + `Account Type`. Nếu đã có tài khoản đang active (Status = "A"), yêu cầu bị từ chối.
+  - Nếu hợp lệ, hệ thống tạo bản ghi trong bảng `PRODUCT_ACCOUNT` và bảng liên kết `LOYALTY_ACCOUNT_PRODUCT`.
+- **Cập nhật (Update)**: 
+  - Yêu cầu cập nhật bị từ chối nếu không tìm thấy bộ `Account No` + `Account Type` hiện hữu.
+  - Nếu hợp lệ, hệ thống lưu lại lịch sử thay đổi vào bảng lịch sử và cập nhật dữ liệu mới.
+  - Việc đổi chủ tài khoản (CIF) không được phép thực hiện thủ công, phải thông qua batch CIF Merge.
+- **Xóa (Delete)**: 
+  - Nếu tài khoản có thẻ (Card) đang ở trạng thái Active (Status = "A") liên kết với nó, hành động xóa sẽ bị từ chối.
+  - Xóa hợp lệ sẽ chuyển trạng thái bản ghi và bản ghi liên kết `LOYALTY_ACCOUNT_PRODUCT` sang bảng lịch sử, không xóa vật lý ngay lập tức.
+
+## Mối quan hệ với modules khác
+
+- **Customer Overview**: Mỗi Account thuộc về một Customer duy nhất được định danh qua số CIF.
+- **Card**: Một Account có thể liên kết với một hoặc nhiều Card (Thẻ). Trạng thái của Card có thể ngăn chặn việc xóa Account.
+
+## Ví dụ thực tế
+
+Khách hàng Nguyễn Văn A (CIF: 123456) mở một tài khoản tín dụng. Hệ thống bên ngoài đồng bộ bản ghi này qua batch OLSACCT. Tài khoản được ghi nhận với PAL là "Credit" và PAT là "Platinum", kết hợp với số tài khoản "987654321" tạo thành định danh duy nhất (ASN). Vài ngày sau, ngân hàng phát hành một thẻ cứng liên kết với tài khoản này. Cả thẻ và tài khoản đều được lưu vết trong hệ thống và có thể dùng để thực hiện giao dịch.

docs/knowledge-cards/customer/attribute_counter.md

@@ -0,0 +1,69 @@
+---
+card_id: "customer/attribute_counter"
+title: "Thuộc tính và Bộ đếm (Attribute & Counter)"
+domain: "customer"
+related_cards:
+  - "customer/customer_overview"
+  - "customer/account"
+  - "customer/card"
+  - "campaign/campaign_rule"
+tags: ["attribute", "counter", "bucket", "entity level"]
+---
+
+# Thuộc tính và Bộ đếm (Attribute & Counter)
+
+## Mô tả ngắn
+
+Attribute (Thuộc tính) và Counter (Bộ đếm) là các trường thông tin mở rộng được gắn vào các thực thể cốt lõi (Khách hàng, Tài khoản, Thẻ). 
+- **Attribute** thường lưu trữ các giá trị tĩnh hoặc bán tĩnh có thời hạn (ví dụ: phân khúc, sở thích) được cập nhật qua batch hoặc cấu hình. 
+- **Counter** lưu trữ các giá trị tích lũy động (ví dụ: tổng chi tiêu tháng) được cập nhật liên tục thông qua giao dịch, chia thành các khoảng thời gian (Bucket).
+
+## Thuật ngữ liên quan
+
+- **Entity Level**: Cấp độ thực thể được gắn dữ liệu (Customer [CU], Account [PA], Card [CA]).
+- **Entity ID**: Mã định danh tương ứng với cấp độ (CIF cho CU, Account Number cho PA, Card Number cho CA).
+- **Counter Bucket**: Khoảng thời gian cụ thể của một bộ đếm (Ví dụ: Bucket tháng 10, Bucket tháng 11).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Dữ liệu được chia thành 2 phần riêng biệt, đều xoay quanh trục "Entity Level".
+
+### 1. Thuộc tính thực thể (Attribute Value)
+Dữ liệu lưu tại bảng `ATTRIBUTE_VALUE`.
+- **Attribute Group / ID / Name**: Nhóm, mã và tên của thuộc tính.
+- **Entity & Entity ID**: Cấp độ (Customer/Account/Card) và mã định danh tương ứng (CSN, ASN, PSN).
+- **Account Type**: Loại tài khoản (chỉ áp dụng nếu Entity là Account).
+- **Attribute Value**: Giá trị của thuộc tính.
+- **Effective Date From / To**: Khoảng thời gian giá trị thuộc tính này có hiệu lực.
+- **Campaign Information**: Nếu thuộc tính được tham chiếu trong một Campaign Rule (làm tiêu chí hoặc công thức), hệ thống sẽ hiển thị Campaign ID, Campaign Name, Rule Name và thời gian hiệu lực của Rule đó.
+
+### 2. Bộ đếm thực thể (Counter Value)
+Dữ liệu lưu tại bảng `Campaign_Counter`, được cập nhật thông qua quá trình xử lý giao dịch.
+- **Counter & What to count**: Mã bộ đếm và tiêu chí được đếm (ví dụ: đếm số tiền, đếm số lần giao dịch).
+- **Entity & Entity ID**: Cấp độ và mã định danh thực thể.
+- **Counter Value**: Giá trị tích lũy hiện tại của bộ đếm.
+- **Bucket Number & Period**: Số thứ tự bucket, kèm theo Ngày bắt đầu (Start Date) và Ngày kết thúc (End Date) của bucket.
+- **Counter State**: Trạng thái bộ đếm (A: Awarded, C: New).
+- **Transaction Details**: Thông tin giao dịch gần nhất làm thay đổi bộ đếm (Reference No, Post Date, Giá trị cập nhật, Ngày cập nhật, Updated by).
+
+## Cách hoạt động (How It Works)
+
+- **Cập nhật dữ liệu**: 
+  - Attribute thường được cập nhật hàng loạt (batch process) hoặc thông qua giao diện bảo trì (Maintenance batch).
+  - Counter được cập nhật chủ yếu thông qua các giao dịch kích hoạt Campaign Rule.
+- **Tính thời điểm (Effective/Bucket)**:
+  - Cả hai đều có tính "thời điểm". Attribute dùng khái niệm **Effective Date** để xác định giá trị hợp lệ hiện tại. 
+  - Counter dùng **Bucket** để lưu trữ giá trị lũy kế theo từng chu kỳ (ví dụ: đếm theo ngày, tuần, tháng). Hệ thống so sánh ngày xử lý (processing date) với kỳ của bucket/effective date để hiển thị bản ghi "hiện hành" (Active).
+- **View-only**: Màn hình này cung cấp góc nhìn tổng hợp ở cấp độ Khách hàng (Customer Profile) để xem toàn bộ Attribute/Counter của CIF đó cũng như các Account/Card trực thuộc. Không cho phép thao tác cập nhật trực tiếp tại đây.
+
+## Mối quan hệ với modules khác
+
+- **Customer / Account / Card**: Đóng vai trò là thực thể chủ quản (Entity) để gắn Attribute và Counter.
+- **Campaign Rule**: Counter là công cụ cốt lõi để theo dõi điều kiện thưởng của Campaign Rule (ví dụ: "Chi tiêu đạt 10 triệu"). Attribute cũng có thể được dùng làm điều kiện lọc (Criteria) trong Rule.
+- **Transaction**: Mỗi giao dịch đều có khả năng cập nhật giá trị của một hoặc nhiều Counter Bucket.
+
+## Ví dụ thực tế
+
+Khách hàng A (CIF: 123) có:
+- **Attribute**: "Hạng thành viên" = "GOLD" (Entity: Customer, ID: 123, Hiệu lực: 01/01/2026 - 31/12/2026).
+- **Counter**: Tham gia chương trình "Tiêu dùng tháng 10". Hệ thống tạo "Counter: Tổng chi tiêu", Bucket: 01/10/2026 - 31/10/2026. Sau 2 lần quẹt thẻ, "Counter Value" cập nhật thành 5,000,000 VNĐ. Record hiển thị rõ giao dịch gần nhất (Reference No: TXN889) đã cộng thêm 1,000,000 VNĐ vào bộ đếm này.

docs/knowledge-cards/customer/card.md

@@ -0,0 +1,64 @@
+---
+card_id: "customer/card"
+title: "Thẻ Sản phẩm (Card)"
+domain: "customer"
+related_cards:
+  - "customer/account"
+  - "customer/customer_overview"
+tags: ["card", "replacement", "supplement card", "OLSCARD"]
+---
+
+# Thẻ Sản phẩm (Card)
+
+## Mô tả ngắn
+
+Card (Thẻ Sản phẩm) đại diện cho các thẻ vật lý hoặc ảo liên kết với một tài khoản của khách hàng (Account). Thông tin thẻ chủ yếu được đồng bộ từ hệ thống bên ngoài (External System) qua luồng batch hoặc có thể được bổ sung thông qua giao diện quản trị. Một thẻ luôn phải liên kết với một tài khoản hợp lệ.
+
+## Thuật ngữ liên quan
+
+- **CIF**: Customer Information File - Mã định danh khách hàng sở hữu thẻ.
+- **Principal Card**: Thẻ chính. Số CIF của thẻ chính phải trùng với số CIF của Account.
+- **Supplement Card**: Thẻ phụ. Có thể có số CIF khác với CIF của Account.
+- **PSN**: Plastic Sequence Number - Số thứ tự phát hành thẻ.
+- **OLSCARD**: Tên luồng batch xử lý đồng bộ dữ liệu thẻ từ hệ thống bên ngoài.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+| Field (EN/VN) | Description | Data type / Rules |
+| --- | --- | --- |
+| CIF number | Mã khách hàng của thẻ. Có thể đổi nếu là thẻ phụ. | Lookup từ danh sách Client. |
+| Account Type | Loại tài khoản (kết hợp PAL và PAT). | Lookup từ tài khoản của CIF. |
+| Account number | Số tài khoản liên kết với thẻ. | Lookup từ danh sách tài khoản hợp lệ. |
+| Card number | Số thẻ. | X(20). Bắt buộc DUY NHẤT trên toàn hệ thống. |
+| Cardholder Name | Tên chủ thẻ được in trên thẻ. | X(50). |
+| Card Indicator | Chỉ thị loại thẻ (Thẻ chính - P, Thẻ phụ - S, Thẻ doanh nghiệp - K...). | Lookup. |
+| Card status | Trạng thái thẻ (dùng validate khi tính toán). | Lookup. |
+| Card block code | Mã chặn thẻ (dùng chặn giao dịch). | X(10). |
+| Card activation date | Ngày kích hoạt thẻ. | Date. |
+| Card creation date | Ngày mở thẻ. | Date. |
+| Card expiry date | Ngày thẻ hết hạn. | Date. |
+| Old Card Number | Số thẻ cũ (dùng trong trường hợp thay thế thẻ). | Lookup. Cùng chung Account với thẻ mới. |
+
+## Cách hoạt động (How It Works)
+
+- **Đồng bộ và phân quyền**: Dữ liệu thẻ chủ yếu cập nhật từ hệ thống ngoài qua batch OLSCARD nên hệ thống cung cấp chức năng xem (view) là chính. Nếu thẻ được tạo/cập nhật bằng batch, hệ thống không cho phép sửa từ màn hình quản trị (có thể tắt việc chặn này qua App Param).
+- **Thêm mới (Add)**: 
+  - Thẻ được thêm vào bảng `CARD` và tạo liên kết với Account qua bảng `CARD_PRODUCT_ACCOUNT_REL`.
+  - Hệ thống từ chối nếu số thẻ đã tồn tại, hoặc Account/CIF không hợp lệ.
+  - Không cho phép đổi CIF hoặc Account cho một thẻ từ màn hình quản trị (phải dùng batch CIF Merge nếu cần).
+- **Cập nhật và Xóa (Update / Delete)**: 
+  - Cập nhật hợp lệ sẽ ghi đè dữ liệu mới và chuyển bản ghi cũ vào bảng lịch sử.
+  - Xóa thẻ thực chất là xóa logic (chuyển bản ghi `CARD` và `CARD_PRODUCT_ACCOUNT_REL` sang bảng lịch sử).
+- **Quy trình thay thế thẻ (Replace Card)**:
+  - Khi thẻ bị mất hoặc hỏng, hệ thống phát hành thẻ mới để thay thế thẻ cũ. Bản ghi thẻ mới được sinh ra nhưng giữ nguyên PSN của thẻ cũ.
+  - Toàn bộ Thuộc tính (Attributes), Bộ đếm (Counters) và Ví điểm (Pool Buckets) của thẻ cũ sẽ tự động liên kết sang thẻ mới.
+  - Thẻ cũ vẫn tồn tại trong hệ thống cho tới khi Trạng thái thẻ hoặc Block Code được cập nhật thành không hợp lệ.
+
+## Mối quan hệ với modules khác
+
+- **Account**: Mọi thẻ bắt buộc phải liên kết với một tài khoản (Account).
+- **Customer Overview**: Quản lý thông tin định danh (CIF) cho chủ thẻ chính và thẻ phụ.
+
+## Ví dụ thực tế
+
+Khách hàng Trần Thị B (CIF: 111222) làm mất thẻ tín dụng vật lý. Ngân hàng tiến hành phát hành thẻ mới. Trong hệ thống Loyalty, thẻ mới được tạo với trường "Old Card Number" trỏ về số thẻ bị mất. Ngay lập tức, hệ thống tự động kế thừa toàn bộ điểm thưởng, các bộ đếm chi tiêu và dữ liệu ưu đãi từ thẻ cũ sang thẻ mới để đảm bảo trải nghiệm khách hàng không bị gián đoạn. Thẻ cũ sau đó được cập nhật trạng thái "Blocked" từ bên ngoài vào để chặn các giao dịch phát sinh.

docs/knowledge-cards/customer/customer_overview.md

@@ -0,0 +1,84 @@
+---
+card_id: "customer/customer_overview"
+title: "Hồ sơ & Quản lý khách hàng (Customer Overview & 360)"
+domain: "customer"
+related_cards:
+  - "customer/operations"
+  - "customer/account"
+  - "customer/card"
+  - "customer/pool_balance"
+  - "customer/transaction_history"
+tags: ["Customer Profile", "Customer 360", "CIF", "Dashboard", "Batch Sync"]
+---
+
+# Hồ sơ & Quản lý khách hàng (Customer Overview & 360)
+
+## Mô tả ngắn
+
+Mô-đun Quản lý khách hàng (Customer Management) cung cấp góc nhìn toàn diện về khách hàng thông qua hai chức năng chính: **Customer Profile** (Hồ sơ khách hàng cơ bản) và **Customer 360 Dashboard** (Góc nhìn toàn cảnh). Hồ sơ khách hàng trên OLS phần lớn là "chỉ đọc" (view-only) và được đồng bộ dữ liệu từ hệ thống nguồn thông qua batch job.
+
+## Thuật ngữ liên quan
+
+- **CIF (Customer Information File)**: Mã định danh duy nhất của khách hàng trên hệ thống.
+- **Customer 360**: Màn hình tổng hợp toàn bộ hoạt động (Transactions, Pools, Cards/Accounts, Most Redeemed Items) giúp quản trị viên phân tích hành vi khách hàng một cách trực quan.
+- **Record Status (A/H)**: Trạng thái bản ghi (Active/History). Xoá khách hàng thực chất là chuyển bản ghi sang History table (Logically delete/Soft delete).
+- **Customer Segmentation**: Phân nhóm khách hàng dựa trên nhân khẩu học (Demographic) và hành vi (Behavior) phục vụ cho chiến lược tặng thưởng (VD: VIP, Tần suất mua sắm).
+- **OLSCUST**: Batch job đồng bộ dữ liệu khách hàng từ hệ thống nguồn (Core Banking) vào OLS.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. Customer Profile
+| Field | Description | Type |
+| --- | --- | --- |
+| CIF number | Mã số khách hàng duy nhất. | X(30) |
+| First Name / Last Name | Tên và Họ của khách hàng. Ghép lại thành Customer Name. | X(50) |
+| Customer Status | Trạng thái khách hàng (Active, Inactive, Blocked). | Drop-down |
+| Customer Block Code | Mã chặn (Block code) ngăn chặn các giao dịch đổi điểm. | X(10) |
+| ID Type / Cardholder ID | Loại giấy tờ tuỳ thân (CMND, Passport) và Số ID tương ứng. | X(30) |
+| Country Origin | Quốc tịch của khách hàng. | Drop-down |
+| Gender | Giới tính (Male, Female, Others). | Drop-down |
+| Date of Birth (DOB) | Ngày sinh — dùng cho Rule Criteria sinh nhật. | Date |
+
+### 2. Contact Detail (Liên hệ)
+| Field | Description | Type |
+| --- | --- | --- |
+| Address Type | Loại địa chỉ (Home, Business, Shipping). Mỗi loại là duy nhất. | Drop-down |
+| Phone number / Email | Số điện thoại và Email liên hệ (theo định dạng chuẩn). | X(30) / X(50) |
+| State / City / Zip Code | Mã Tỉnh/Thành phố/Mã bưu điện. Dùng để gửi SMS hoặc giao quà vật lý. | Drop-down |
+
+### 3. Customer 360 Dashboard Metrics
+| Metric | Description | Source |
+| --- | --- | --- |
+| Total Points & Cash back | Số dư khả dụng tổng cộng của khách hàng theo loại Pool. | LAB table |
+| Account / Card List | Danh sách Tài khoản/Thẻ, Trạng thái và Ngày hết hạn. | PRODUCT_ACCOUNT, CARD |
+| Transaction Statistic | Biểu đồ (Line/Combo) thể hiện xu hướng Earn/Redeem/Adjust theo thời gian. | TRANSACTIONS |
+| Most Redeemed Items | Top 10 sản phẩm khách hàng hay đổi nhất (theo Số lượng). | CAT_CATALOGUE_TRANS_DETAIL |
+| Balance information | Thông tin chi tiết các Quỹ điểm (Pool) và số dư sắp hết hạn. | LAB table |
+
+## Cách hoạt động (How It Works)
+
+- **Đồng bộ dữ liệu (Sync)**: Dữ liệu khách hàng được đổ vào hệ thống OLS thông qua batch `OLSCUST`. Hệ thống tự động tạo bản ghi trong bảng `CLIENT` và sinh ra một `LOYALTY_ACCOUNT` mặc định (Cấp Customer) tương ứng.
+- **Xóa khách hàng**: Khi có yêu cầu xoá, hệ thống thực hiện Soft Delete bằng cách dời bản ghi sang bảng History, bao gồm cả Loyalty Account. Nếu khách hàng vẫn còn Tài khoản (Account) ở trạng thái Active, yêu cầu xóa sẽ bị hệ thống Reject.
+- **Giao diện Customer 360**: Cung cấp bộ lọc theo Thời gian (This month, Last 3 months), Pool và Loại tài khoản, giúp cập nhật biểu đồ thống kê thời gian thực (real-time dashboard).
+- **Ràng buộc dữ liệu**: CIF number là duy nhất toàn hệ thống. Một CIF có thể sở hữu nhiều Account, mỗi Account liên kết với nhiều Card.
+
+## Mối quan hệ với modules khác
+
+- **Account Management**: Một CIF sở hữu nhiều Tài khoản (Account). Xóa CIF yêu cầu tất cả Account phải Inactive trước.
+- **Card Management**: Thẻ (Card) liên kết gián tiếp với khách hàng thông qua Account.
+- **Pool Balance**: Dashboard 360 hiển thị tổng hợp số dư của tất cả Pool mà khách hàng có.
+- **Transaction History**: Dashboard 360 pull dữ liệu giao dịch để vẽ biểu đồ xu hướng Earn/Redeem.
+- **Batch System**: Cập nhật thông tin thông qua End-of-Day (EOD) Batch OLSCUST.
+- **Catalogue**: Tích hợp hiển thị danh sách quà tặng (Most Redeemed Items) trên dashboard.
+- **Targeting / Campaign**: Dữ liệu hồ sơ khách hàng là đầu vào cho engine phân khúc (Segmentation) để đẩy tệp đối tượng (Audience) vào chiến dịch.
+
+## Ví dụ thực tế
+
+**Nhân viên CS tra cứu khách hàng khiếu nại "Không nhận được điểm":**
+
+1. CS nhập CIF `VN20230001` vào Customer Search → mở Customer Profile.
+2. Kiểm tra **Customer Status** = `Active`, **Block Code** = trống → khách hàng không bị chặn.
+3. Chuyển sang tab **Customer 360** → lọc Pool "Loyalty Points" + Time range "Last 3 months".
+4. Dashboard hiển thị: 5 giao dịch Earn trong 3 tháng qua, tổng cộng 2,500 điểm. Giao dịch gần nhất ngày 15/07 có số tiền 800,000 VND nhưng không sinh điểm.
+5. CS click vào giao dịch → redirect sang **No-Hit Transaction** → thấy Error: "MCC 7995 (Gambling) — MCC không hợp lệ cho Campaign Rule #CR001".
+6. CS giải thích cho khách: giao dịch tại MCC Gambling bị loại trừ khỏi chương trình tặng thưởng.

docs/knowledge-cards/customer/no_hit_transaction.md

@@ -0,0 +1,74 @@
+---
+card_id: "customer/no_hit_transaction"
+title: "Giao dịch không hợp lệ (No-Hit Transaction)"
+domain: "customer"
+related_cards:
+  - "customer/account"
+  - "customer/card"
+  - "campaign/campaign_rule"
+  - "campaign/pool_definition"
+tags: ["transaction", "no-hit", "orphan", "error", "troubleshooting"]
+---
+
+# Giao dịch không hợp lệ (No-Hit Transaction)
+
+## Mô tả ngắn
+
+No-Hit Transaction là bản ghi lưu vết các giao dịch đầu vào được gửi đến OLS nhằm kích hoạt Campaign Rule nhưng **không được ghi nhận thưởng** (do không thỏa mãn điều kiện hoặc không có rule nào phù hợp). Entity này được sử dụng chủ yếu để tra cứu (troubleshoot) nguyên nhân từ chối trả thưởng cho khách hàng.
+
+> [!NOTE]
+> Theo đặc tả, nếu tính năng "Rule Evaluation" được triển khai hoàn chỉnh, hệ thống tracking này có thể trở nên dư thừa. 
+
+## Thuật ngữ liên quan
+
+- **CIF Number**: Mã định danh khách hàng cốt lõi.
+- **CP Rule**: Campaign Rule, quy tắc chiến dịch định nghĩa điều kiện trả thưởng.
+- **OLS_ORPHAN_TXN_NO_HIT**: Bảng dữ liệu vật lý lưu trữ các giao dịch không hợp lệ trên OLS.
+- **DCC Indicator**: Chỉ báo giao dịch chuyển đổi tiền tệ động (Dynamic Currency Conversion).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Bản ghi No-Hit được trích xuất từ incoming transaction và chi tiết lỗi:
+
+### 1. Thông tin tài khoản (Account Information)
+- **CIF Number**: Mã khách hàng thực hiện giao dịch (lookup qua Account/Card nếu incoming không có).
+- **Product Account No / Type**: Số và loại tài khoản sản phẩm (lookup qua Card nếu cần).
+- **Card Number**: Số thẻ (từ incoming transaction).
+
+### 2. Chi tiết giao dịch (Transaction Detail)
+- **Invoice No**: Số hóa đơn duy nhất do OLS sinh ra cho incoming transaction.
+- **Transaction Type**: Loại giao dịch của rule (AWD - Award, RED - Redeem, ADJ - Adjust).
+- **OLS Transaction Code**: Mã giao dịch dùng để map với CP Rule.
+- **Transaction Amount**: Giá trị gộp (Award/Redeem) hoặc điểm điều chỉnh (Adjust).
+- **Corporate / Chain / Store / Terminal**: Thông tin điểm chấp nhận giao dịch, tra cứu từ transaction store.
+- **Transaction MCC**: Mã danh mục đơn vị chấp nhận thẻ.
+- **Date / Currency / Description**: Ngày, loại tiền tệ và mô tả giao dịch.
+- **Transaction Mode / POS Entry Mode**: Phương thức giao dịch và nhập liệu.
+- **DCC / Tap2Pay / Token Requestor ID**: Các chỉ báo phụ trợ từ incoming transaction.
+- **Salary Credit**: Chỉ báo tài khoản nhận lương định kỳ.
+
+### 3. Danh sách lỗi Campaign Rule (CP Rule Listing)
+- **Campaign ID / Campaign Rule**: Chiến dịch và mã Rule mà giao dịch kích hoạt nhưng bị trượt.
+- **Pool ID**: Pool thưởng tương ứng của Rule.
+- **Error Code / Error Descriptions**: Mã và mô tả chi tiết lỗi từ OLS (VD: do không đạt tiêu chí giá trị, sai MCC, vv).
+
+## Cách hoạt động (How It Works)
+
+- **Ghi nhận ngoại lệ**: Khi một incoming transaction chạy qua rule engine, nếu nó kích hoạt Rule A nhưng không thỏa mãn Rule Criteria, hệ thống ghi bản ghi này vào bảng `OLS_ORPHAN_TXN_NO_HIT`.
+- **Đa điều kiện trượt**: Nếu một giao dịch kích hoạt Rule A (thành công) nhưng trượt Rule B, nó **vẫn** sinh ra bản ghi No-Hit để ghi nhận lý do trượt Rule B.
+- **Cung cấp nguyên nhân**: Quá trình xử lý (TP) bắt buộc trả về mô tả lỗi chi tiết (Error Description) ghi rõ lý do trượt (VD: criteria nào bị fail) để hiển thị/lưu trữ.
+- **Tra cứu và khắc phục (View-only)**: Người dùng (VD: Customer Service) dùng thông tin này để giải thích cho khách hàng lý do không được nhận thưởng, hoặc dùng làm cơ sở điều chỉnh (adjust) giao dịch thủ công nếu Campain Rule bị cấu hình sai.
+
+## Mối quan hệ với modules khác
+
+- **Account** / **Card**: Định danh chủ thể thực hiện giao dịch bị lỗi.
+- **Campaign Rule**: Quy tắc mà giao dịch cố gắng kích hoạt nhưng thất bại. Chi tiết lỗi liên kết trực tiếp với Rule này.
+- **Pool Definition**: Pool dự định sẽ nhận điểm nếu giao dịch thành công.
+
+## Ví dụ thực tế
+
+Khách hàng quẹt thẻ tín dụng tại siêu thị, hóa đơn 400.000 VNĐ. Hệ thống nhận giao dịch, cố gắng kích hoạt "Campaign Rule: Mua sắm siêu thị > 500K".
+Giao dịch thất bại do không đủ định mức. OLS ghi nhận:
+- **Transaction Detail**: Amount = 400.000, MCC = 5411.
+- **CP Rule Listing**: Campaign Rule = "RULE_SIEU_THI_500K", Error Code = "ERR_MIN_AMOUNT", Error Description = "Transaction amount 400,000 is less than minimum criteria 500,000".
+CSD dựa vào record này để giải thích cho khách hàng.

docs/knowledge-cards/customer/operations_adjustment.md

@@ -0,0 +1,79 @@
+---
+card_id: "customer/operations_adjustment"
+title: "Nghiệp vụ Điều chỉnh Điểm (Adjustment Operations)"
+domain: "customer"
+related_cards:
+  - "customer/pool_balance"
+  - "customer/account"
+  - "customer/card"
+tags: ["adjustment", "transfer", "re-instatement", "maker-checker", "manual"]
+detail_refs:
+  - "customer/adjustment_deduction_logic"
+---
+
+# Nghiệp vụ Điều chỉnh Điểm (Adjustment Operations)
+
+## Mô tả ngắn
+
+Nghiệp vụ Điều chỉnh Điểm bao gồm các công cụ quản trị (OA) cho phép nhân viên vận hành can thiệp thủ công vào số dư ví điểm (Pool Balance) của khách hàng. Có 3 loại nghiệp vụ chính: **Adjustment** (Điều chỉnh cộng/trừ), **Transfer Balance** (Điều chuyển điểm) và **Re-instatement** (Gia hạn điểm). Tất cả các giao dịch này đều phải tuân thủ quy trình phê duyệt Maker-Checker.
+
+## Thuật ngữ liên quan
+
+- **Maker-Checker**: Cơ chế phê duyệt hai cấp. Người tạo (Maker) sinh ra giao dịch ở trạng thái Pending, người duyệt (Checker) Approve thì giao dịch mới có hiệu lực.
+- **Forfeited (Thu hồi)**: Trạng thái điểm đã quá hạn và bị hệ thống xóa bỏ vĩnh viễn. Chỉ có thể Re-instatement khi điểm đã hết hạn nhưng chưa bị Forfeited (nằm trong thời gian ân hạn).
+- **Transfer Mode**: Chế độ điều chuyển (Internal - trong cùng 1 khách hàng; External - giữa các khách hàng khác nhau).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Dữ liệu đầu vào cho một giao dịch Điều chỉnh (bất kể loại nào) luôn phải có các thông tin cốt lõi sau:
+
+### 1. Định danh thực thể (Entity Identification)
+- **Posted transaction by**: Cấp độ tạo giao dịch (CIF, Account, hoặc Card).
+- **From / To (Chỉ dùng cho Transfer)**: Nguồn đi và đích đến (được xác định bằng CIF, Account, hoặc Card).
+- **Pool ID**: Mã Ví điểm chịu ảnh hưởng. (Hệ thống ràng buộc Pool Level phải tương thích với Entity Level được chọn).
+
+### 2. Thông tin điều chỉnh (Adjustment Info)
+- **Transaction Type**: Loại điều chỉnh (Positive - Cộng, Negative - Trừ).
+- **Adjustment Quantity / Transfer Amount**: Số lượng điểm điều chỉnh hoặc điều chuyển.
+- **Expiry Date**: Ngày hết hạn mới cho số điểm được cộng thêm/gia hạn.
+- **Bucket to Re-instate (Chỉ dùng cho Re-instatement)**: Xác định đích danh bucket đã hết hạn cần được gia hạn.
+
+### 3. Tracking & Phân loại (Audit & Classification)
+- **Transaction Date / Code**: Ngày giao dịch và Mã giao dịch OLS.
+- **Reason Code**: Mã lý do điều chỉnh (Rất quan trọng để hệ thống định khoản GL).
+- **Store / Remarks**: Đơn vị cửa hàng và Ghi chú thêm.
+
+## Cách hoạt động (How It Works)
+
+### 1. Adjustment (Điều chỉnh âm/dương)
+- **Positive (Cộng điểm)**: Nếu có bucket nào đang bị âm (Negative balance), số điểm cộng thêm sẽ được dùng để bù đắp (offset) cho bucket đó về 0 trước. Phần điểm dư còn lại mới được tạo thành bucket mới với Expiry Date chỉ định.
+- **Negative (Trừ điểm)**: Có thể chọn đích danh một Bucket để trừ. Nếu không chọn, hệ thống sẽ trừ theo quy tắc chuẩn (thường là FIFO - hết hạn trước trừ trước).
+
+### 2. Transfer Balance (Điều chuyển điểm)
+- Có thể chuyển số dư của toàn bộ Pool hoặc một lượng điểm nhất định.
+- Khi được duyệt, hệ thống sinh ra **2 giao dịch đồng thời**: 1 giao dịch Negative Adjustment cho tài khoản "From" và 1 giao dịch Positive Adjustment cho tài khoản "To".
+- Expiry Date của điểm điều chuyển sẽ được giữ nguyên như bucket gốc trừ khi người dùng chỉ định một ngày mới.
+
+### 3. Re-instatement (Gia hạn điểm)
+- Dùng để "cứu" các điểm đã hết hạn nhưng vẫn nằm trong Grace Period (chưa Forfeited).
+- Khi thực thi: Số dư của bucket hết hạn sẽ bị set về 0. Hệ thống sinh ra một bucket mới chứa số điểm này, áp dụng Expiry Date mới.
+- Nếu điểm đã bị Forfeited, không thể dùng chức năng này mà phải dùng "Positive Adjustment" để đền bù điểm.
+
+### 4. Quy trình Maker-Checker
+- Sau khi lưu, giao dịch nằm ở tab Pending. Lúc này có thể Edit/Delete.
+- Người dùng có thẩm quyền (Checker) phải Approve giao dịch. Sau khi Approve, giao dịch chuyển sang trạng thái Active, ghi nhận vào Transaction History và cập nhật Pool Balance.
+- Hệ thống sẽ validate kỹ lưỡng tình trạng Block Code của thẻ/tài khoản trước khi Approve.
+
+## Mối quan hệ với modules khác
+
+- **Pool Balance**: Đối tượng bị thay đổi trực tiếp bởi các giao dịch này.
+- **Account / Card**: Các thực thể làm nguồn (From) hoặc đích (To) cho giao dịch.
+- **Transaction History**: Nơi ghi nhận log cuối cùng sau khi giao dịch được Approve.
+- **Reason Code**: Định nghĩa nguyên nhân và định tuyến hạch toán kế toán (GL) cho giao dịch.
+
+## Ví dụ thực tế
+
+Khách hàng khiếu nại chưa nhận được điểm hoàn tiền 50K. Nhân viên CSKH kiểm tra và xác nhận lỗi hệ thống.
+1. CSKH (Maker) tạo một **Positive Adjustment**: Chọn Account của khách, Pool "Hoàn tiền", số lượng 50,000, Reason Code "Lỗi hệ thống", lưu thành Pending.
+2. Trưởng ca (Checker) vào xem xét giao dịch Pending, bấm Approve.
+3. Hệ thống sinh ra giao dịch cộng 50,000 vào Pool Balance, chèn log vào Transaction History. Khách hàng thấy điểm tăng ngay lập tức.

docs/knowledge-cards/customer/operations_transaction.md

@@ -0,0 +1,73 @@
+---
+card_id: "customer/operations_transaction"
+title: "Giao dịch Vận hành (Operations Transaction)"
+domain: "customer"
+related_cards:
+  - "catalogue/item_master"
+  - "campaign/campaign_rule"
+  - "customer/pool_balance"
+tags: ["redemption", "award transaction", "manual entry", "call center"]
+---
+
+# Giao dịch Vận hành (Operations Transaction)
+
+## Mô tả ngắn
+
+Giao dịch Vận hành (Operations Transaction) bao gồm các chức năng trên màn hình quản trị (OA) cho phép nhân viên vận hành hoặc tổng đài viên (Call Center) thay mặt khách hàng thực hiện các nghiệp vụ: **Đổi quà (Item Redemption)** và **Tạo giao dịch thưởng (Award Transaction)**. Các giao dịch này sau khi được duyệt sẽ được xử lý thời gian thực tương tự như luồng giao dịch tự động.
+
+## Thuật ngữ liên quan
+
+- **Redemption Mode**: Chế độ đổi quà, bao gồm "Fixed Points" (chỉ dùng điểm) hoặc "Fixed Partial" (dùng điểm + tiền mặt).
+- **FFP (Frequent Flyer Program)**: Chương trình khách hàng thường xuyên của đối tác hàng không (dùng để đổi Dặm bay - Miles).
+- **Transaction Context**: Ngữ cảnh giao dịch (Amount, MCC, Store, Terminal) cần thiết để giả lập một giao dịch thực tế.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Dữ liệu đầu vào được chia làm 2 loại nghiệp vụ chính:
+
+### 1. Item Redemption (Đổi quà thủ công)
+- **Định danh**: Người đổi (CIF, Account hoặc Card).
+- **Redemption Channel & Date**: Kênh đổi (thường là OA/Call Center) và ngày đổi.
+- **Item Details**:
+  - **Catalogue & Item**: Chọn danh mục và vật phẩm (Bắt buộc phải có cấu hình giá hợp lệ tại thời điểm đổi).
+  - **Redemption Mode**: Fixed Points hoặc Fixed Partial (nếu Item Price cho phép).
+  - **Unit Price / Cash Amount**: Giá điểm và giá tiền mặt cho mỗi đơn vị. (Với Fixed Partial, nhân viên có thể điều chỉnh số điểm sử dụng nhưng không được thấp hơn mức tối thiểu quy định).
+  - **Redemption Quantity**: Số lượng đổi (không được vượt quá Quantity on hand của kho).
+- **Thông tin bổ sung (theo loại Item)**:
+  - **Miles**: Mã số FFP, Tên, Họ (để gửi đối tác).
+  - **Physical/Evoucher**: Địa chỉ, Zip code, Tên người nhận, SĐT, Email (để giao hàng).
+
+### 2. Award Transaction (Tạo giao dịch thưởng)
+- **Định danh**: Người thực hiện giao dịch (CIF, Account hoặc Card).
+- **Transaction Context (Ngữ cảnh giả lập)**:
+  - **OLS Transaction Code (TC)**: Mã định danh loại nghiệp vụ (sẽ dùng để dò tìm Campaign Rule).
+  - **Transaction Date**: Ngày giao dịch thực tế.
+  - **Gross Amount / Currency**: Giá trị giao dịch và loại tiền tệ.
+  - **Store / Terminal / MCC / Country Code**: Thông tin điểm chấp nhận thẻ.
+  - **POS Entry Mode / Channel / Salary Indicator**: Các chỉ báo phụ trợ đi kèm.
+
+## Cách hoạt động (How It Works)
+
+### 1. Xử lý Đổi quà (Item Redemption)
+- **Tính năng Real-time**: Khi tạo và (nếu cần) Approve thành công, hệ thống lập tức trừ điểm trong Pool Balance tương ứng theo logic FIFO (trừ bucket hết hạn gần nhất).
+- **Ràng buộc**: Số lượng tồn kho (Quantity on hand) được kiểm tra tức thời. Giao dịch bị từ chối nếu không đủ điểm (Redeemable Balance) hoặc không đủ tồn kho.
+- **Tích hợp đối tác**: Cuối ngày (EOD), các giao dịch đổi quà thành công (đặc biệt là Evoucher/Miles) sẽ được xuất ra file để gửi đối tác hoặc hệ thống fulfillment xử lý bước tiếp theo.
+
+### 2. Xử lý Tạo giao dịch thưởng (Award Transaction)
+- **Giả lập giao dịch Core**: Chức năng này không cộng trực tiếp điểm vào Pool (như Positive Adjustment), mà tạo ra một bản ghi Transaction đẩy vào Transaction Processing Engine (TP).
+- **Rule Evaluation**: Engine sẽ dùng TC Code và các tham số (Amount, MCC...) nhập trên form để quét qua tập hợp các Campaign Rule đang Active. Nếu thỏa mãn Rule Criteria, hệ thống mới thực hiện cộng điểm (Award) cho khách hàng.
+- **Ứng dụng**: Dùng để xử lý các giao dịch ngoại lệ bị rớt từ hệ thống Core, hoặc các chiến dịch đặc biệt cần ghi nhận thủ công tại quầy (Store).
+
+## Mối quan hệ với modules khác
+
+- **Pool Balance**: Đổi quà sẽ trực tiếp kiểm tra và trừ số dư Khả dụng (Redeemable Balance) từ Pool.
+- **Item Master**: Cung cấp danh sách vật phẩm, giá cả (Price) và tồn kho (Quantity) cho nghiệp vụ đổi quà.
+- **Campaign Rule**: Award Transaction phụ thuộc hoàn toàn vào cấu hình của Rule để xác định xem khách hàng có được thưởng điểm hay không.
+
+## Ví dụ thực tế
+
+Khách hàng B gọi lên tổng đài báo muốn đổi "Voucher Starbucks 50K".
+- Nhân viên CSKH mở tab "Item Redemption", chọn số thẻ của khách.
+- Chọn Catalogue "Ẩm thực", Item "Voucher SB 50K", Mode = "Fixed Points", Quantity = 1.
+- Hệ thống hiển thị Unit Price = 500 điểm. Kiểm tra Pool Balance khách có 1,000 điểm.
+- Nhân viên xác nhận. Giao dịch lập tức trừ 500 điểm của khách và xuất hiển thị mã Evoucher cho nhân viên cung cấp cho khách hàng.

docs/knowledge-cards/customer/pool_balance.md

@@ -0,0 +1,70 @@
+---
+card_id: "customer/pool_balance"
+title: "Số dư Ví điểm (Pool Balance)"
+domain: "customer"
+related_cards:
+  - "customer/customer_overview"
+  - "campaign/pool_definition"
+  - "customer/account"
+  - "customer/card"
+tags: ["pool", "balance", "bucket", "LAB", "redeemable"]
+---
+
+# Số dư Ví điểm (Pool Balance)
+
+## Mô tả ngắn
+
+Pool Balance (Số dư Ví điểm) là thực thể đại diện cho tổng hợp số dư điểm, dặm thưởng hoặc đơn vị giá trị khác của khách hàng trong hệ thống. Dữ liệu này là kết quả tổng hợp (aggregation) từ các ví nhỏ (buckets) trong bảng dữ liệu LAB (Loyalty Account Bucket), giúp xác định số điểm hiện có, số điểm khả dụng và thời hạn của điểm.
+
+## Thuật ngữ liên quan
+
+- **Pool**: Ví điểm/Kho điểm - Nơi lưu trữ điểm thưởng theo một loại cụ thể.
+- **Bucket**: Nhóm điểm/Lô điểm - Một phần của Pool, chứa điểm có cùng ngày sinh và ngày hết hạn.
+- **LAB**: Loyalty Account Bucket - Bảng lưu trữ chi tiết từng bucket điểm của khách hàng.
+- **ASN**: Account Sequence Number - Định danh tài khoản.
+- **CSN**: Card Sequence Number - Định danh thẻ.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Dữ liệu tổng hợp số dư Ví điểm:
+
+| Field (EN/VN) | Description | Data type / Rules |
+| --- | --- | --- |
+| Pool ID | Mã ví điểm. | Lookup từ Pool Definition. |
+| Pool Name | Tên ví điểm. | Lookup từ Pool Definition. |
+| Pool type | Loại ví điểm. | Lookup từ Pool Definition. |
+| Pool Entity level | Cấp độ thực thể của ví điểm (VD: Khách hàng, Tài khoản, Thẻ). | Lookup. |
+| Balance | Tổng số dư hiện có. | Tính tổng (Sum) tất cả các buckets của Pool từ bảng LAB. |
+| Redeemable Balance | Số dư khả dụng. | Tính tổng các buckets chưa hết hạn (non-expired) và có thể sử dụng (available) từ LAB. |
+| Next Expiring Balance | Số dư sắp hết hạn. | Số dư của bucket có ngày hết hạn gần nhất (sắp đến hạn nhưng chưa hết hạn) từ LAB. |
+| Account type | Loại tài khoản (PAL + PAT). | Lookup từ Product_Account bằng ASN. |
+| Account No | Số tài khoản liên kết. | Lookup bằng ASN. |
+| Card Number | Số thẻ liên kết (chỉ có nếu Pool Entity Level là Card). | Hiển thị dựa trên thẻ liên kết. |
+| Expiry Date | Ngày hết hạn của bucket điểm. | Được nhóm (Group by) theo Ngày hết hạn / Pool ID / ASN / CSN. |
+
+## Cách hoạt động (How It Works)
+
+- **Bản chất dữ liệu**: Số dư ví điểm (Pool Balance) không được lưu thành một con số cứng tĩnh lẻ tẻ mà được tính toán/tổng hợp động từ nhiều lô điểm (buckets) thuộc bảng LAB.
+- **Phân loại số dư**:
+  - **Balance**: Tổng cộng mọi điểm đang tồn tại trong Pool.
+  - **Redeemable Balance**: Chỉ tính những điểm hợp lệ (có thể sử dụng), loại bỏ các điểm đã hết hạn hoặc bị phong tỏa (blocked).
+  - **Next Expiring**: Hệ thống dò tìm bucket có ngày hết hạn gần nhất ở tương lai để hiển thị con số sẽ bị mất nếu không sử dụng kịp thời.
+- **Cấp độ (Entity Level)**: Tùy thuộc vào cấu hình của Pool (Pool Entity Level), số dư có thể gắn ở cấp độ toàn bộ Khách hàng (Customer), từng Tài khoản (Account) hoặc từng Thẻ (Card).
+- **Read-only**: Dữ liệu này hoàn toàn là kết quả tính toán hiển thị (chỉ xem), mọi sự thay đổi điểm số phải thông qua các giao dịch phát sinh (award/redeem) hoặc điều chỉnh (adjustment) tác động trực tiếp vào các buckets.
+
+## Mối quan hệ với modules khác
+
+- **Pool Definition**: Định nghĩa các tham số của ví điểm (Tên, Loại, Cấp độ).
+- **Customer Overview**: Nơi hiển thị tổng quan các ví điểm của toàn bộ khách hàng.
+- **Account / Card**: Số dư có thể được gắn cụ thể vào một tài khoản hoặc một thẻ tùy thuộc vào Entity Level của Pool.
+
+## Ví dụ thực tế
+
+Khách hàng sở hữu ví điểm "Cashback" (Pool ID: P01). Trong bảng LAB, khách có 2 lô điểm (buckets):
+1. Bucket 1: 50,000 điểm, hết hạn 31/12/2026.
+2. Bucket 2: 20,000 điểm, hết hạn 30/06/2026.
+Hệ thống sẽ tổng hợp Pool Balance như sau:
+- **Balance**: 70,000 điểm (50K + 20K).
+- **Redeemable Balance**: 70,000 điểm (giả sử cả 2 đều đang khả dụng).
+- **Next Expiring Balance**: 20,000 điểm (vì bucket 2 hết hạn sớm nhất).
+- **Expiry Date**: 30/06/2026.

docs/knowledge-cards/customer/statement.md

@@ -0,0 +1,67 @@
+---
+card_id: "customer/statement"
+title: "Sao kê điểm thưởng (Statement)"
+domain: "customer"
+related_cards:
+  - "customer/account"
+  - "campaign/pool_definition"
+  - "customer/transaction_history"
+tags: ["statement", "balance", "cycle", "monthly"]
+---
+
+# Sao kê điểm thưởng (Statement)
+
+## Mô tả ngắn
+
+Sao kê điểm thưởng (Statement) là bản ghi tổng hợp định kỳ (thường là hàng tháng) về tình hình biến động điểm thưởng của một tài khoản. Bản ghi chốt số dư đầu kỳ, tổng điểm phát sinh (cộng/trừ/điều chỉnh) trong kỳ, số dư cuối kỳ và điểm sắp hết hạn. Sao kê được tính toán tự động bởi các batch jobs của hệ thống OLS.
+
+## Thuật ngữ liên quan
+
+- **Statement Pool**: Pool điểm thưởng được cấu hình để sinh sao kê (chỉ tính điểm từ Pool này).
+- **Cycle**: Chu kỳ sao kê, khoảng thời gian mà các giao dịch được tổng hợp lại để tính số dư.
+- **Loyalty Account Number**: Số tài khoản khách hàng thân thiết nội bộ của hệ thống.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Bản ghi Statement Enquiry bao gồm thông tin tổng hợp chu kỳ và chi tiết giao dịch phát sinh:
+
+### 1. Thông tin tài khoản & Chu kỳ (Account & Cycle Info)
+- **Loyalty Account Number**: Số tài khoản Loyalty.
+- **Product Account Number / Type**: Số và loại tài khoản sản phẩm (lookup từ ASN trong bảng Statement).
+- **Pool ID**: Mã Pool cấu hình sao kê.
+- **Cycle Start Date / Cycle Statement Date**: Ngày bắt đầu và kết thúc (chốt) của chu kỳ sao kê.
+
+### 2. Thông tin số dư (Balance Summary)
+- **Statement Opening Balance**: Số dư điểm đầu kỳ (mang từ cuối kỳ trước sang).
+- **Total Award**: Tổng số điểm thưởng kiếm được trong kỳ.
+- **Total Redeem**: Tổng số điểm đã sử dụng (đổi quà) trong kỳ.
+- **Total Adjust**: Tổng số điểm được điều chỉnh trong kỳ.
+- **Statement Closing Balance**: Số dư điểm tích lũy cuối kỳ.
+- **Expired Points**: Số dư điểm trong các bucket đã quá hạn nhưng chưa bị hệ thống thu hồi (forfeited).
+
+### 3. Chi tiết giao dịch trong kỳ (Transaction Summary)
+- **Last Transaction Date**: Ngày post giao dịch cuối cùng trong chu kỳ này.
+- **Reference Number**: Số tham chiếu giao dịch OLS.
+- **Transaction Type**: Loại giao dịch (Award/Redeem/Adjust).
+- **Unit**: Giá trị điểm phát sinh (được nhóm theo Reference No, Post Date, Transaction Date và Txn Type).
+- **Post Date / Transaction Date**: Ngày đăng và ngày giao dịch thực tế.
+
+## Cách hoạt động (How It Works)
+
+- **Cấp độ lưu trữ**: OLS hỗ trợ sao kê ở cấp độ Khách hàng (Customer) và Tài khoản (Account). Tuy nhiên, bản ghi vật lý luôn được lưu trữ ở cấp độ Tài khoản cho từng Statement Pool tương ứng.
+- **Xử lý tự động (Batch)**: Các bản ghi sao kê không sinh ra realtime (thời gian thực) mà được tổng hợp định kỳ bởi OLS batch jobs khi kết thúc chu kỳ.
+- **View-only**: Màn hình Statement Enquiry cung cấp tính năng tra cứu (Read-only) các bản ghi sao kê đã được chốt (active statement records), không cho phép thao tác sửa xóa.
+- **Công thức chốt số**: `Closing Balance = Opening Balance + Total Award - Total Redeem ± Total Adjust`.
+
+## Mối quan hệ với modules khác
+
+- **Account**: Sao kê luôn gắn liền với một Tài khoản (Account) cụ thể.
+- **Pool Definition**: Bản ghi sao kê chỉ theo dõi biến động điểm của một Pool nhất định (Statement Pool).
+- **Transaction History**: Chi tiết các giao dịch hiển thị trong sao kê chính là các bản ghi từ lịch sử giao dịch phát sinh trong chu kỳ (Cycle Start Date đến Cycle Statement Date).
+
+## Ví dụ thực tế
+
+Tài khoản Thẻ tín dụng A có chu kỳ sao kê từ 01/10 đến 31/10 cho Pool "Điểm thưởng thường niên".
+- **Opening Balance** (01/10): 1,000 điểm.
+- **Trong kỳ** (01/10 - 31/10): Phát sinh 3 giao dịch mua sắm (Tổng Award = 500 điểm), đổi quà 1 lần (Tổng Redeem = 200 điểm).
+- **Batch job** chạy đêm 31/10 sẽ chốt bản ghi Statement tháng 10 cho tài khoản A: Total Award = 500, Total Redeem = 200, Closing Balance = 1,300 điểm.

docs/knowledge-cards/customer/transaction_history.md

@@ -0,0 +1,83 @@
+---
+card_id: "customer/transaction_history"
+title: "Lịch sử giao dịch (Transaction History)"
+domain: "customer"
+related_cards:
+  - "customer/account"
+  - "customer/card"
+  - "campaign/campaign_rule"
+  - "campaign/pool_definition"
+  - "campaign/counter_definition"
+tags: ["transaction", "history", "reward", "redemption", "counter"]
+---
+
+# Lịch sử giao dịch (Transaction History)
+
+## Mô tả ngắn
+
+Transaction History là bản ghi lưu vết tất cả các giao dịch của khách hàng trên hệ thống OLS (bao gồm cả giao dịch hủy), thường hiển thị cho 12 tháng gần nhất (dựa trên tham số housekeep). Mỗi bản ghi chứa thông tin chi tiết về tài khoản, giá trị giao dịch, điểm thưởng/đổi/điều chỉnh, cập nhật bộ đếm và chi tiết đổi quà.
+
+## Thuật ngữ liên quan
+
+- **OLS Transaction Code**: Mã giao dịch trên hệ thống OLS để định danh loại nghiệp vụ.
+- **Housekeep parameter**: Tham số hệ thống quyết định thời gian lưu trữ hiển thị (VD: 12 tháng).
+- **MCC (Merchant Category Code)**: Mã danh mục của đơn vị chấp nhận thẻ.
+- **POS Entry Mode**: Phương thức nhập dữ liệu giao dịch tại thiết bị thanh toán.
+- **Pool Unit**: Đơn vị điểm thưởng tương ứng với một Pool cụ thể (Earn/Redeem/Adjust).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Bản ghi Transaction tổng hợp thông tin từ nhiều khía cạnh:
+
+### 1. Chi tiết tài khoản (Account Detail)
+- **Account Number / Type / Level**: Số tài khoản, loại và hạng tài khoản sản phẩm thực hiện giao dịch.
+- **Card Number**: Số thẻ thực hiện giao dịch.
+
+### 2. Chi tiết giao dịch (Transaction Detail)
+- **Invoice No / Reference No**: Số hóa đơn nội bộ sinh bởi OLS và Số tham chiếu giao dịch.
+- **Source Reference Number**: Số tham chiếu từ hệ thống nguồn bên ngoài.
+- **OLS Transaction Code**: Mã giao dịch trên OLS.
+- **Gross / Nett Amount**: Giá trị giao dịch gộp và ròng.
+- **Award / Redeem / Adjust Points**: Tổng điểm thưởng, đổi, hoặc điều chỉnh (giá trị này bằng tổng của tất cả các Campaign Rules được áp dụng).
+- **Date Information**: Ngày giao dịch, Ngày đăng (Post Date), Ngày ghi sổ (Settlement Date).
+- **MCC / Store / Terminal**: Thông tin điểm chấp nhận giao dịch, mã cửa hàng, thiết bị đầu cuối.
+- **Cancellation Indicator**: Chỉ thị xác định giao dịch đã hủy.
+- **Transaction Mode / Channel**: Phương thức và kênh giao dịch.
+
+### 3. Chi tiết phân bổ thưởng (Reward Details - Quick View)
+- **Campaign Rule**: Mã quy tắc chiến dịch đã áp dụng.
+- **Transaction Type / OLS Code**: Loại giao dịch và mã OLS tương ứng.
+- **Pool & Pool Unit**: Pool nhận điểm và số lượng/giá trị Pool Unit được cộng/trừ.
+
+### 4. Chi tiết cập nhật bộ đếm (Counter Details)
+- **Campaign Rule**: Mã quy tắc kích hoạt.
+- **Counter & Entity**: Bộ đếm được cập nhật và Cấp thực thể (Entity level).
+- **Counter Value**: Giá trị bộ đếm thay đổi.
+- **Bucket Info**: Số thứ tự bucket, Ngày bắt đầu và kết thúc của bucket được cập nhật.
+
+### 5. Chi tiết đổi quà (Item Redemption Details)
+- **Item**: Mã vật phẩm (Item) được đổi.
+- **Redeemed Quantity / Points**: Số lượng và tổng điểm đã sử dụng.
+- **Cash Amount Used**: Số tiền mặt (nếu có) dùng để đổi kèm.
+
+## Cách hoạt động (How It Works)
+
+- **Lưu trữ tổng hợp**: Một record Transaction Detail là sự kết hợp của tất cả các trường đầu vào được gán cho một OLS Reference No duy nhất. Nó ghi nhận cả giá trị tài chính (Gross/Nett) lẫn logic Loyalty (Points).
+- **Tính nhất quán dữ liệu**: Tổng số điểm thưởng (Award), điểm đổi (Redeem) và điểm điều chỉnh (Adjust) hiển thị ở Transaction Detail PHẢI BẰNG tổng các giá trị chi tiết được sinh ra bởi từng Campaign Rule tương ứng trong mục Reward Details.
+- **View-only**: Chức năng/bản ghi này chủ yếu dùng để tra cứu (View only) phục vụ Customer 360, bao gồm cả các giao dịch đã bị hủy.
+- **Gắn kết quy tắc**: Một giao dịch có thể kích hoạt không, một hoặc nhiều Campaign Rule, dẫn đến việc sinh ra nhiều bản ghi phân bổ Pool hoặc cập nhật Counter đồng thời.
+
+## Mối quan hệ với modules khác
+
+- **Account** / **Card**: Transaction luôn được gắn với một tài khoản và/hoặc thẻ cụ thể.
+- **Campaign Rule**: Giao dịch thỏa điều kiện sẽ kích hoạt Rule, ghi nhận vào chi tiết thưởng của giao dịch.
+- **Pool Definition**: Điểm thưởng/đổi/điều chỉnh của giao dịch được hạch toán vào các Pool cụ thể.
+- **Counter Definition**: Giao dịch có thể làm thay đổi giá trị của một hoặc nhiều bộ đếm (cập nhật vào bucket tương ứng).
+- **Item Master**: Giao dịch đổi quà (Redemption) sẽ liên kết với Item được đổi.
+
+## Ví dụ thực tế
+
+Khách hàng quẹt thẻ tín dụng tại siêu thị (MCC 5411) số tiền 500.000 VNĐ. Hệ thống OLS sinh ra bản ghi Transaction:
+- **Transaction Detail**: Gross Amount = 500.000, MCC = 5411, Award Points = 50, OLS Transaction Code = "RETAIL_PURCHASE".
+- **Reward Detail**: Áp dụng "Campaign Rule: Mua sắm siêu thị cuối tuần", cộng 50 Pool Unit vào "Pool: Điểm tiêu dùng".
+- **Counter Detail**: Cập nhật "Counter: Tổng chi tiêu tháng 10" thêm 500.000 vào giá trị hiện tại.

docs/knowledge-cards/marketing/ab_testing.md

@@ -0,0 +1,78 @@
+---
+card_id: "marketing/ab_testing"
+title: "Thử nghiệm A/Bn (A/Bn Testing)"
+domain: "marketing"
+related_cards:
+  - "marketing/marketing_campaign"
+  - "marketing/marketing_message"
+tags: ["marketing", "AB testing", "content", "targeting", "optimization"]
+---
+
+# Thử nghiệm A/Bn (A/Bn Testing)
+
+## Mô tả ngắn
+
+A/Bn Testing là chức năng dùng để đánh giá và tối ưu hóa các chiến dịch tiếp thị. Bằng cách so sánh nhiều biến thể (A, B, ..., n) của nội dung tin nhắn hoặc của tập khách hàng mục tiêu, hệ thống giúp người dùng xác định phương án mang lại tương tác và hiệu quả cao nhất.
+
+## Thuật ngữ liên quan
+
+- **A/Bn Testing**: Thử nghiệm nhiều hơn hai biến thể cùng một lúc (A, B, C, D...).
+- **Content Marketing Testing**: Thử nghiệm các nội dung (Message Template) khác nhau trên cùng một tập khách hàng mục tiêu.
+- **Target Customer Testing**: Thử nghiệm cùng một nội dung trên các tập khách hàng mục tiêu (OMR Criteria) khác nhau.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+*Cấu hình thử nghiệm A/Bn chia làm hai loại: Nội dung (Content) và Khách hàng (Targeting).*
+
+### Thông tin chung (Chung cho cả hai loại)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Campaign ID | Mã định danh duy nhất của chiến dịch thử nghiệm | Không chứa ký tự đặc biệt. |
+| Message Channel | Kênh gửi tin nhắn (SMS, Email, Push Notification) | Bắt buộc chọn 1. |
+| Effective Date From / To | Thời gian hiệu lực của chiến dịch thử nghiệm | Bắt buộc. |
+| Run Schedule | Lịch chạy chiến dịch (One time, Daily, Weekly, Monthly, Annually) | Bắt buộc chọn và cấu hình chi tiết giống Marketing Campaign (OMR). |
+
+### Cấu hình Content Marketing Testing
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| OMR Criteria | Điều kiện lọc danh sách khách hàng mục tiêu (Target Customer) chung | Chỉ có 1 tập khách hàng duy nhất cho tất cả biến thể. |
+| Variant A, B, ... n | Các biến thể nội dung tin nhắn (Message Template) | Bắt buộc có ít nhất 2 biến thể. Tên mỗi biến thể phải là duy nhất. |
+
+### Cấu hình Target Customer Testing
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Variant A, B, ... n | Các biến thể tập khách hàng mục tiêu (OMR Criteria) khác nhau | Bắt buộc có ít nhất 2 biến thể. Cùng sử dụng chung 1 nội dung tin nhắn. |
+
+## Cách hoạt động (How It Works)
+
+- **Kích hoạt Batch Job**: Hệ thống (ABn Job) chạy định kỳ để quét các chiến dịch A/Bn đang trong thời gian hiệu lực và có lịch chạy (Run Schedule) khớp với ngày hiện tại.
+- **Xử lý Content Testing**:
+  - Hệ thống lấy ra tập khách hàng mục tiêu chung dựa trên cấu hình *OMR Criteria*.
+  - Chia tập khách hàng này thành các nhóm nhỏ và gửi các *Variant Nội dung* (Message Template) khác nhau cho từng nhóm.
+  - Phối hợp với đối tác thứ ba (Third-party) để thu thập dữ liệu về Tỷ lệ mở (Open Rate), Tỷ lệ click (Click-through Rate) của từng biến thể nội dung, từ đó lập báo cáo so sánh.
+- **Xử lý Target Customer Testing**:
+  - Hệ thống áp dụng từng cấu hình *Variant Tập khách hàng* (Criteria A, B, n...) để lấy ra các danh sách khách hàng khác nhau.
+  - Sau khi batch job chạy xong, người dùng có thể xem kết quả quy mô và đặc điểm (số lượng, giới tính...) của từng tập khách hàng thu được để đánh giá điều kiện lọc nào tiếp cận đúng đối tượng hơn.
+
+## Mối quan hệ với modules khác
+
+- **Marketing Campaign**: Cả hai tính năng đều sử dụng chung cách cấu hình điều kiện lọc khách hàng (OMR Criteria) và cấu hình lịch chạy (Run Schedule).
+- **Marketing Message**: Các nội dung tin nhắn (Message Template) đã tạo trước đó sẽ được sử dụng để làm các biến thể (Variant) trong loại thử nghiệm Content Marketing.
+
+## Ví dụ thực tế
+
+**1. Thử nghiệm Nội dung (Content Testing):**
+- Mục tiêu: Xem thông điệp nào thu hút khách hàng nữ click vào link hơn.
+- Cấu hình: Target chung là "Khách hàng Nữ, độ tuổi 20-30".
+- Biến thể A: Gửi mẫu tin SMS "Giảm 50% thời trang nữ cuối tuần, [Link]".
+- Biến thể B: Gửi mẫu tin SMS "Freeship cho đơn hàng từ 200k, [Link]".
+Hệ thống gửi ngẫu nhiên cho tập mục tiêu và theo dõi SMS nào có tỷ lệ click link cao hơn.
+
+**2. Thử nghiệm Tập khách hàng (Targeting Testing):**
+- Mục tiêu: Xem nhóm khách hàng nào có quy mô lớn hơn với cùng một điều kiện chi tiêu.
+- Biến thể A: OMR Criteria là "Khách hàng chi tiêu > 5 triệu VÀ ở Hà Nội".
+- Biến thể B: OMR Criteria là "Khách hàng chi tiêu > 5 triệu VÀ ở TP.HCM".
+Sau khi chạy thử nghiệm, người dùng xem báo cáo sẽ biết Variant nào trả về danh sách khách hàng nhiều hơn.

docs/knowledge-cards/marketing/audience_filter.md

@@ -0,0 +1,75 @@
+---
+card_id: "marketing/audience_filter"
+title: "Bộ lọc đối tượng (Audience Filter: Blacklist & Whitelist)"
+domain: "marketing"
+related_cards:
+  - "marketing/marketing_campaign"
+  - "marketing/frequency_capping"
+tags: ["blacklist", "whitelist", "filter", "audience", "exclude"]
+---
+
+# Bộ lọc đối tượng (Audience Filter: Blacklist & Whitelist)
+
+## Mô tả ngắn
+
+Audience Filter là module quản lý các danh sách khách hàng đặc biệt để can thiệp vào luồng gửi thông điệp của hệ thống Marketing. Nó bao gồm **Blacklist** (Danh sách đen: chặn khách hàng nhận mọi thông điệp, thường dùng cho khách hàng fraud) và **Whitelist** (Danh sách trắng: loại trừ khách hàng khỏi các quy tắc Frequency Capping, đảm bảo họ luôn nhận được thông điệp mà không bị giới hạn số lượng).
+
+## Thuật ngữ liên quan
+
+- **Blacklist**: Danh sách khách hàng bị chặn (block) không nhận thông báo khuyến mãi/chiến dịch marketing.
+- **Whitelist**: Danh sách khách hàng được ưu tiên, loại trừ khỏi quy tắc Frequency Capping mặc định.
+- **CIF (Customer Information File) number**: Mã định danh khách hàng trên hệ thống OLS (Core System), dùng để thêm khách hàng vào danh sách.
+- **Frequency Capping**: Quy tắc giới hạn tần suất gửi tin nhắn marketing.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+Cấu trúc dữ liệu của Blacklist và Whitelist là tương tự nhau.
+
+### Thông tin chung
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| ID | Mã định danh danh sách (Blacklist/Whitelist Identifier) | Tự sinh, String (10). |
+| Name List | Tên của danh sách (Blacklist/Whitelist) | Required. String (50). |
+| Description | Mô tả chi tiết mục đích của danh sách | Optional. String (200). |
+| Input Type | Phương thức nhập liệu danh sách khách hàng | Enum: "Input from screen" hoặc "Upload file". |
+
+### Quản lý danh sách khách hàng (Customer List)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Customer List (Dropdown) | Chọn trực tiếp khách hàng theo mã CIF (nếu Input Type = "Input from screen") | Multi-select. Phải nhập ít nhất 4 ký tự của CIF để tìm kiếm nhằm đảm bảo hiệu năng. |
+| Upload file | Tải lên file danh sách khách hàng (nếu Input Type = "Upload file") | Cho phép định dạng CSV, xls, xlsx. Dung lượng ≤ 50MB. |
+
+## Cách hoạt động (How It Works)
+
+### Quản lý danh sách
+
+1. **Tạo danh sách**: Người dùng (có quyền tương ứng) tạo một Blacklist hoặc Whitelist mới.
+2. **Thêm khách hàng**: Có hai cách để đưa khách hàng vào danh sách:
+   - **Nhập thủ công (Input from screen)**: Tìm kiếm và chọn mã CIF của khách hàng từ hệ thống OLS.
+   - **Tải file (Upload file)**: Tải lên một file (.csv, .xls, .xlsx) chứa danh sách khách hàng. Hệ thống sẽ validate định dạng và dung lượng file (tối đa 50MB). Nếu có lỗi, hệ thống báo lỗi và yêu cầu tải lại file khác. Trạng thái xử lý file được hiển thị rõ ràng.
+3. **Phê duyệt**: Sau khi tạo, danh sách cần được review và approve (phê duyệt) tương tự như các màn hình cấu hình khác trong hệ thống.
+4. **Truy xuất & Tải xuống**: Người dùng có thể xem trước danh sách trên màn hình hoặc tải file danh sách về (hệ thống sẽ sinh file CSV cho danh sách nhập thủ công, hoặc trả về file gốc nếu danh sách được tạo qua upload).
+
+### Ứng dụng trong chiến dịch Marketing
+
+- **Blacklist**: Khi một chiến dịch Marketing chuẩn bị gửi thông điệp, hệ thống sẽ đối chiếu với Blacklist (nếu được áp dụng). Bất kỳ khách hàng nào nằm trong Blacklist sẽ tự động bị loại khỏi tập đối tượng mục tiêu, thông điệp sẽ không được gửi đi.
+- **Whitelist**: Theo mặc định, tập khách hàng trong Whitelist sẽ được bypass (bỏ qua) mọi quy tắc giới hạn của **Frequency Capping**. Nếu một giới hạn tần suất cụ thể (Cap rules) nào đó VẪN MUỐN áp dụng lên Whitelist, người dùng cần chỉ định rõ Whitelist đó trong cấu hình Cap rules. Điều này hữu ích để gửi tin liên tục cho các mục đích testing, hoặc cho tập khách hàng VIP.
+
+## Mối quan hệ với modules khác
+
+- **Marketing Campaign**: Cấu hình chiến dịch cần kiểm tra đối chiếu danh sách Blacklist để chặn thông điệp đối với các tập khách hàng rủi ro.
+- **Frequency Capping**: Whitelist có liên kết trực tiếp với Frequency Capping, cho phép cấu hình một số khách hàng vượt qua quy tắc giới hạn tần suất gửi tin.
+
+## Ví dụ thực tế
+
+**Tạo danh sách chặn (Blacklist)**:
+- Ngân hàng phát hiện 500 khách hàng có hành vi trục lợi khuyến mãi (fraud).
+- User tạo một Blacklist tên "Fraud_Customer_Q3", chọn `Input Type = Upload file` và tải lên file `.xlsx` chứa 500 số CIF.
+- Sau khi được approve, hệ thống lưu danh sách này. Các chiến dịch Marketing sau đó sẽ không bao giờ gửi SMS/Email tới 500 người này.
+
+**Tạo danh sách ưu tiên (Whitelist)**:
+- Đội ngũ UAT cần test luồng gửi Email cho một campaign mới.
+- User tạo một Whitelist tên "UAT_Testers", chọn `Input Type = Input from screen` và nhập 5 mã CIF của các nhân viên test.
+- Khi test, dù chiến dịch có quy định "Mỗi user chỉ nhận 1 email/ngày", các testers vẫn có thể nhận nhiều email thử nghiệm liên tiếp do được bypass quy định Frequency Capping.

docs/knowledge-cards/marketing/frequency_capping.md

@@ -0,0 +1,76 @@
+---
+card_id: "marketing/frequency_capping"
+title: "Giới hạn Tần suất (Frequency Capping)"
+domain: "marketing"
+related_cards:
+  - "marketing/marketing_campaign"
+  - "marketing/marketing_message"
+  - "targeting/segmentation"
+tags: ["marketing", "capping", "limit", "notification", "spam"]
+---
+
+# Giới hạn Tần suất (Frequency Capping)
+
+## Mô tả ngắn
+
+Frequency Capping là cấu hình giới hạn số lượng tin nhắn tối đa được phép gửi đến một khách hàng thông qua một kênh liên lạc cụ thể (SMS, Email, Push Notification) trong một khoảng thời gian nhất định. Mục đích là để bảo vệ trải nghiệm khách hàng, tránh tình trạng spam và tối ưu hóa chi phí gửi tin nhắn của hệ thống OneMarketing.
+
+## Thuật ngữ liên quan
+
+- **Notification Channel**: Kênh gửi thông báo (SMS, Email, Push Notifications).
+- **Capping Period**: Chu kỳ giới hạn (Daily, Weekly, Monthly).
+- **Whitelist**: Danh sách khách hàng ngoại lệ, được phép bỏ qua các quy tắc giới hạn tần suất chung.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### Thông tin giới hạn chung
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Frequency Cap Id | Mã định danh cấu hình giới hạn tần suất | Bắt buộc. |
+| Notification Channel | Kênh thông báo áp dụng giới hạn (SMS, Email, Push Notifications) | Bắt buộc. Chỉ được có 1 cấu hình hiệu lực cho 1 kênh tại 1 thời điểm. |
+| Effective Date From / To | Thời gian cấu hình có hiệu lực | Bắt buộc. |
+| Description | Mô tả cấu hình | Không bắt buộc. |
+
+### Cấu hình chu kỳ (Period Units)
+
+*Một cấu hình có thể bao gồm nhiều chu kỳ (Period Unit) khác nhau.*
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Capping Period | Chu kỳ áp dụng giới hạn: Daily (Hàng ngày), Weekly (Hàng tuần), Monthly (Hàng tháng) | Bắt buộc. Không được cấu hình trùng chu kỳ trong cùng 1 channel. |
+| Maximum number | Số lượng tin nhắn tối đa được phép gửi cho 1 khách hàng trong chu kỳ | Bắt buộc. Lớn hơn 0. |
+
+### Danh sách ngoại lệ (Whitelist)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Include Whitelist | Cờ đánh dấu có áp dụng ngoại lệ cho tệp khách hàng đặc biệt hay không | Mặc định OFF. |
+| Customer list | Danh sách khách hàng đặc biệt được bỏ qua giới hạn tần suất (nhận được nhiều tin nhắn hơn bình thường) | Bắt buộc nếu Include Whitelist = ON. Lookup từ hệ thống phân tập (Segmentation). |
+
+## Cách hoạt động (How It Works)
+
+- **Cấu hình**: Quản trị viên thiết lập số lượng thông báo tối đa cho từng kênh (VD: SMS tối đa 1 tin/ngày, 3 tin/tuần). Các cấu hình này được áp dụng chung cho tất cả chiến dịch Marketing (OMR) trên toàn hệ thống.
+- **Theo dõi**: Hệ thống tự động theo dõi (track) số lượng tin nhắn mà mỗi khách hàng đã nhận được trên từng kênh và trên từng chu kỳ (ngày, tuần, tháng).
+- **Kiểm tra trước khi gửi**: Khi một chiến dịch Marketing (`marketing/marketing_campaign`) chuẩn bị gửi tin nhắn cho khách hàng:
+  - Hệ thống kiểm tra số lượng tin đã gửi trong kỳ so với giới hạn cấu hình.
+  - Nếu đã đạt hoặc vượt ngưỡng giới hạn (Maximum number) → tin nhắn sẽ KHÔNG được gửi đi cho khách hàng đó.
+  - Nếu chưa đạt ngưỡng → tin nhắn được gửi và hệ thống cộng dồn bộ đếm.
+- **Ngoại lệ (Whitelist)**: Nếu khách hàng nằm trong "Customer list" của Whitelist, hệ thống sẽ bỏ qua kiểm tra giới hạn và cho phép gửi tin bình thường, đảm bảo các tin nhắn quan trọng đến được nhóm khách VIP hoặc nhóm nội bộ.
+
+## Mối quan hệ với modules khác
+
+- **Marketing Campaign (OMR)**: OMR là nơi phát sinh yêu cầu gửi tin nhắn, Frequency Capping đóng vai trò như một màng lọc cuối cùng chặn tin nhắn nếu vi phạm giới hạn.
+- **Marketing Message**: Nội dung được gửi đi qua các kênh (SMS/Email/Push), chịu sự kiểm soát của Frequency Capping.
+- **Segmentation**: Nguồn cung cấp danh sách khách hàng để cấu hình vào mục Whitelist (Customer list).
+
+## Ví dụ thực tế
+
+**Tránh spam SMS hàng ngày:**
+- Cấu hình Kênh = SMS.
+- Period Unit 1: Daily = Tối đa 2 tin/ngày.
+- Period Unit 2: Weekly = Tối đa 5 tin/tuần.
+Nếu một khách hàng đã nhận 2 SMS quảng cáo vào buổi sáng, thì bất kỳ chiến dịch Marketing nào định gửi thêm SMS thứ 3 trong ngày hôm đó cho họ sẽ bị hệ thống tự động chặn lại.
+
+**Ngoại lệ cho nhân viên (Whitelist):**
+- Trong lúc testing, team marketing cấu hình Include Whitelist = ON và chọn danh sách "Nhân viên nội bộ". Dù giới hạn là 1 tin/ngày, các nhân viên trong danh sách này vẫn có thể nhận 10 tin/ngày để kiểm thử tính năng gửi tin của OMR mà không bị chặn.

docs/knowledge-cards/marketing/marketing_campaign.md

@@ -0,0 +1,84 @@
+---
+card_id: "marketing/marketing_campaign"
+title: "Yêu cầu Tiếp thị (OneMarketing Request - OMR)"
+domain: "marketing"
+related_cards:
+  - "marketing/marketing_message"
+  - "marketing/frequency_capping"
+  - "campaign/campaign_rule"
+  - "campaign/transaction_codes"
+tags: ["marketing", "campaign", "OMR", "notification", "schedule", "trigger"]
+detail_refs:
+  - "marketing/omr_execution_flow"
+---
+
+# Yêu cầu Tiếp thị (OneMarketing Request - OMR)
+
+## Mô tả ngắn
+
+OneMarketing Request (OMR) là chức năng lọc và chọn danh sách khách hàng mục tiêu thỏa mãn các điều kiện tiếp thị. OMR cho phép gửi thông báo (Notification) tự động hoặc kích hoạt quy tắc chiến dịch thưởng (Trigger Campaign Rule) dựa trên lịch trình cài đặt sẵn hoặc khi có sự kiện hệ thống phát sinh.
+
+## Thuật ngữ liên quan
+
+- **OMR (OneMarketing Request)**: Yêu cầu tiếp thị, chứa điều kiện lọc khách hàng và hành động thực thi.
+- **Notification**: Chức năng gửi tin nhắn/thông báo đến khách hàng.
+- **Trigger Campaign Rule (TCR)**: Chức năng tự động kích hoạt Rule thưởng (cộng/trừ/đổi điểm) cho khách hàng.
+- **Run Schedule**: Lịch trình tự động chạy OMR (một lần, hàng ngày, hàng tuần, hàng tháng, hàng năm).
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### Thông tin chung (General Information)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Request ID | Mã định danh duy nhất của OMR | Không chứa ký tự đặc biệt. |
+| Description | Mô tả chi tiết OMR | Bắt buộc. |
+| Effective Date From/To | Khoảng thời gian OMR có hiệu lực | Bắt buộc. |
+| Marketing Function | Hành động: Notification (gửi tin) hoặc Trigger Campaign Rule (chạy Rule thưởng) | Bắt buộc chọn 1. |
+
+### Cài đặt Lịch & Nội dung (Run Schedule & Message Content)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Trigger method | Phương thức kích hoạt: Schedule (theo lịch) hoặc Event trigger (theo sự kiện) | Bắt buộc. |
+| Run Schedule | Lịch chạy: One time, Daily, Weekly, Monthly, Annually | Cần thiết nếu chọn Schedule. |
+| Business Event | Sự kiện kích hoạt OMR (VD: đăng nhập, xem số dư) | Cần thiết nếu chọn Event trigger. |
+| Message template | Mẫu tin nhắn gửi cho khách hàng | Bắt buộc nếu Marketing Function = Notification. |
+| OLS Transaction Code | Mã giao dịch kích hoạt hệ thống thưởng | Bắt buộc nếu Marketing Function = Trigger Campaign Rule. |
+
+### Điều kiện mục tiêu (Targeting)
+
+| Field Name | Description | Constraints / Rules |
+|---|---|---|
+| Targeting Method | Phương pháp chọn mục tiêu: OMR Criteria (cấu hình điều kiện) hoặc Upload file | Bắt buộc. |
+| OMR Criteria | Các điều kiện (AND/OR) để lọc khách hàng, hỗ trợ loại trừ (NOT) | Áp dụng khi chọn OMR Criteria. |
+| Upload file | File danh sách khách hàng mục tiêu có sẵn | Áp dụng khi chọn Upload file. |
+
+## Cách hoạt động (How It Works)
+
+- **Kích hoạt theo lịch (Schedule)**: Hệ thống chạy OMR Batch Job định kỳ. Job này tìm các OMR đang trong thời gian hiệu lực và có lịch chạy trùng với ngày/giờ hiện tại.
+- **Kích hoạt theo sự kiện (Event trigger)**: Khi một sự kiện nghiệp vụ xảy ra (VD: qua API hoặc Frontend event), hệ thống gọi Backend kiểm tra xem có OMR nào gắn với sự kiện này không để kích hoạt lập tức.
+- **Xử lý Hành động (Marketing Function)**:
+  - Nếu chức năng là **Notification**: OMR lấy danh sách khách hàng từ phần *Targeting* và gửi *Message template* đến họ. Quá trình gửi sẽ dừng lại nếu chạm ngưỡng giới hạn cấu hình trong Frequency Capping.
+  - Nếu chức năng là **Trigger Campaign Rule**: OMR gọi hệ thống Rule, tạo một giao dịch giả lập với *OLS Transaction Code* đã chọn để kích hoạt tính toán thưởng (cộng/trừ điểm/cashback) cho tập khách hàng mục tiêu.
+
+## Mối quan hệ với modules khác
+
+- **Marketing Message**: OMR sử dụng Message để làm mẫu nội dung gửi cho khách hàng khi chức năng là Notification.
+- **Frequency Capping**: Cấu hình giới hạn tần suất gửi tin, giúp OMR biết khi nào phải dừng gửi thông báo để tránh spam khách hàng.
+- **Campaign Rule**: Nếu chức năng là Trigger Campaign Rule, OMR sẽ đóng vai trò như một nguồn phát sinh giao dịch để kích hoạt các Rule tính thưởng.
+- **Transaction Codes**: OMR cần truyền một Transaction Code cụ thể để hệ thống Loyalty nhận diện và đánh giá đúng Campaign Rule tương ứng.
+
+## Ví dụ thực tế
+
+**1. Gửi SMS chúc mừng sinh nhật:**
+- **General**: Function = Notification.
+- **Schedule**: Trigger = Schedule, Daily vào lúc 8:00 sáng.
+- **Message**: Template "Chúc mừng sinh nhật khách hàng".
+- **Targeting**: OMR Criteria chọn điều kiện "Khách hàng có sinh nhật trong hôm nay".
+
+**2. Tặng 100 điểm thưởng nhân dịp Tết:**
+- **General**: Function = Trigger Campaign Rule.
+- **Schedule**: Trigger = Schedule, One time vào ngày mùng 1 Tết.
+- **TC**: OLS Transaction Code = "TET_BONUS".
+- **Targeting**: Upload file danh sách 10.000 khách hàng thân thiết. Khi chạy, hệ thống sẽ trigger TC "TET_BONUS" cho 10.000 khách hàng này để cộng điểm (theo Rule đã cấu hình bên Loyalty).

docs/knowledge-cards/marketing/marketing_message.md

@@ -0,0 +1,74 @@
+---
+card_id: "marketing/marketing_message"
+title: "Mẫu thông báo (Marketing Message)"
+domain: "marketing"
+related_cards:
+  - "campaign/campaign_rule"
+  - "catalogue/item_master"
+tags: ["Message", "SMS", "Email", "Push Notification", "OMR-type"]
+---
+
+# Mẫu thông báo (Marketing Message)
+
+## Mô tả ngắn
+
+Marketing Message là module quản lý và định nghĩa các thông báo gửi đến khách hàng mục tiêu qua nhiều kênh giao tiếp (Channels) khác nhau như SMS, Email, và Push Notification. Hệ thống hỗ trợ tạo thông báo từ nội dung chữ thuần (text) hoặc HTML template, kết hợp các tham số động (message parameters) để cá nhân hoá nội dung.
+
+## Thuật ngữ liên quan
+
+- **Channel**: Kênh giao tiếp, ví dụ: SMS, Email, Push Notification.
+- **Richer Push / Carousel Push**: Các định dạng thông báo Push trên ứng dụng có hỗ trợ đính kèm một ảnh (Richer) hoặc nhiều ảnh vuốt ngang (Carousel).
+- **Message Parameter**: Tham số động có thể kéo/thả vào nội dung (VD: Tên khách hàng, Số dư điểm) để cá nhân hóa khi gửi.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. SMS Message
+| Field | Description | Type |
+| --- | --- | --- |
+| Message ID / Description | Mã định danh duy nhất và mô tả thông báo. | Character |
+| SMS Type | Loại SMS: Promotion/Marketing hoặc Transaction. | Drop-down |
+| Effective Date (From-To) | Thời gian hiệu lực của mẫu thông báo. | Date |
+| SMS Brand Name | Tên hiển thị người gửi SMS (Sender). | Drop-down |
+| Message | Nội dung Unicode, không hỗ trợ hình ảnh/đính kèm. Cho phép chèn Message Parameters. | Character |
+| Send Sample | Nút test thông báo qua SĐT thực tế. | Button |
+
+### 2. Email Message
+| Field | Description | Type |
+| --- | --- | --- |
+| Email Type | Loại Email: Promotion/Marketing hoặc Transaction. | Drop-down |
+| Use type | Chọn cách tạo: Viết trực tiếp (Use message) hoặc Upload HTML (Upload template). | Checkbox |
+| Sender Name / From email | Tên hiển thị người gửi và Email gốc đã cấu hình. | Character |
+| Subject / Preview Text | Tiêu đề Email và văn bản Preheader (hiển thị tóm tắt trên hộp thư). | Character |
+| Message / Upload file | Nội dung soạn thảo HTML hoặc file HTML được upload. | Character/File |
+
+### 3. Push Notification
+| Field | Description | Type |
+| --- | --- | --- |
+| Notification Type | Loại Push: Promotion/Marketing hoặc Transaction. | Drop-down |
+| Message Title | Tiêu đề chính hiển thị trên thông báo. | Character |
+| Image type | Tùy chọn ảnh: Single (Không ảnh), Richer (1 ảnh), Carousel (Nhiều ảnh). | Drop-down |
+| Upload Image / Link URL | Hình ảnh đính kèm và đường link điều hướng khi click. | File/Character |
+| Send Sample | Nút gửi test bằng cách nhập số CIF để xác định thiết bị nhận. | Button |
+
+## Cách hoạt động (How It Works)
+
+- **Cá nhân hóa nội dung:** Người dùng soạn thông báo có thể kéo thả các Message Parameters (như `{{CustomerName}}`) vào nội dung. Khi gửi, hệ thống thay thế tham số bằng thông tin thật của khách hàng.
+- **Kiểm thử thông báo (Send Sample):** Hỗ trợ test hiển thị trước khi áp dụng:
+  - *SMS*: Nhập số điện thoại.
+  - *Email*: Nhập địa chỉ Email.
+  - *Push*: Nhập CIF Number để hệ thống dò Registration Token của thiết bị.
+- **Upload Template:** Với kênh Email, người dùng có thể upload file thiết kế dạng HTML có sẵn và chỉnh sửa trực tiếp. Với kênh Push, hỗ trợ đính kèm hình ảnh và URL điều hướng.
+
+## Mối quan hệ với modules khác
+
+- **Campaign Rule**: Các rule kịch bản chiến dịch (`campaign/campaign_rule`) sử dụng mẫu thông báo này để gửi tự động cho khách hàng khi họ thoả điều kiện thưởng.
+- **Item Master**: Mẫu thông báo cũng có thể được dùng trong luồng đổi quà (`catalogue/item_master`) để gửi xác nhận đổi quà thành công.
+
+## Ví dụ thực tế
+
+**Tạo mẫu Email thông báo đổi điểm:**
+1. Marketer tạo Message mới chọn kênh **Email**, loại **Transaction**.
+2. Thiết lập Sender là `CSKH Loyalty`, Subject là `Xác nhận đổi quà thành công`.
+3. Trong nội dung, nhập: `Chào {{Customer_Name}}, bạn đã đổi thành công {{Item_Name}}. Số dư hiện tại là {{Pool_Balance}} điểm.`
+4. Chọn **Send Sample**, nhập email của chính mình để test. Hệ thống gửi email preview về hộp thư.
+5. Sau khi lưu, mẫu này được gắn vào Item Master hoặc Campaign Rule để tự động kích hoạt.

docs/knowledge-cards/system/application_parameter.md

@@ -0,0 +1,68 @@
+---
+card_id: "system/application_parameter"
+title: "Tham số hệ thống (Application Parameter)"
+domain: "system"
+related_cards:
+  - "customer/account"
+  - "customer/card"
+tags: ["Application Parameter", "System", "Configuration", "Access Control"]
+---
+
+# Tham số hệ thống (Application Parameter)
+
+## Mô tả ngắn
+
+Tham số hệ thống (Application Parameter) cung cấp bộ cấu hình chuẩn để điều khiển hành vi ứng dụng. Module này giúp quản lý các thiết lập liên quan đến bảo mật tài khoản (Access Control), hiển thị giao diện (Display Setting) và chức năng hoạt động chéo (Functionality).
+
+## Thuật ngữ liên quan
+
+- **Access Control**: Các quy tắc kiểm soát quyền truy cập và bảo mật mật khẩu của người dùng.
+- **Processing Date**: Ngày xử lý giao dịch do người dùng cấu hình, chủ yếu dùng cho mục đích kiểm thử (testing).
+- **Cross Function Update**: Quyền cho phép cập nhật chéo dữ liệu giữa các luồng chức năng.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. Access Control (Kiểm soát truy cập)
+| Field | Description | Type |
+| --- | --- | --- |
+| Same User Cannot Approve | Không cho phép người dùng tự phê duyệt bản ghi do chính họ tạo (Mặc định: OFF). | Switch button |
+| Same User Cannot Modify Own Profile | Không cho phép người dùng tự đổi thông tin cá nhân (Mặc định: OFF). | Switch Button |
+| User Session Inactivity Time-out | Hết hạn phiên đăng nhập nếu không có thao tác trong N phút (Mặc định: 30). | Numeric |
+| Maximum Failed Password Attempts | Khóa tài khoản nếu nhập sai mật khẩu liên tiếp N lần (Mặc định: 5). | Numeric |
+| Inactivate User Id after N days | Tự động vô hiệu hóa tài khoản sau N ngày không đăng nhập (Mặc định: 30). | Numeric |
+| Remind User to Change password | Nhắc đổi mật khẩu trước N ngày tính tới ngày hết hạn (Mặc định: 5). | Numeric |
+| Password expiration [days] | Số ngày hiệu lực của mật khẩu trước khi bị khóa (Mặc định: 180). | Numeric |
+| Disallow re-use of passwords | Không cho phép dùng lại N mật khẩu gần nhất (Mặc định: 2). | Numeric |
+| Password length (Max/Min) | Độ dài tối đa (Mặc định: 50) và tối thiểu (Mặc định: 8) của mật khẩu. | Numeric |
+| Password rules | Yêu cầu số lượng ký tự tối thiểu: Numeric, Upper case, Lower case, Special character (Mặc định: mỗi loại 1 ký tự). | Numeric |
+
+### 2. Display Setting (Thiết lập hiển thị)
+| Field | Description | Type |
+| --- | --- | --- |
+| Date format | Định dạng hiển thị ngày trên hệ thống (Mặc định: DD/MM/YYYY). | Drop-down |
+| Time format | Định dạng hiển thị giờ trên hệ thống (Mặc định: HH:mm: ss). | Drop-down |
+| Amount display format | Định dạng số tiền (VD: American `999,999.99` hoặc European `999.999,99`). | Character |
+
+### 3. Functionality (Chức năng)
+| Field | Description | Type |
+| --- | --- | --- |
+| Processing Date | Ngày xử lý áp dụng cho giao dịch trực tuyến (Chỉ dùng cho testing, Mặc định: Trống - dùng ngày hệ thống). | Date |
+| Allow Cross Function Update | Cho phép cập nhật chéo dữ liệu khách hàng, tài khoản, thẻ (Mặc định: ON). | Switch button |
+
+## Cách hoạt động (How It Works)
+
+- **Kiểm soát bảo mật:** Hệ thống áp dụng các quy tắc Access Control để tự động cảnh báo (hết phiên, sắp hết hạn mật khẩu) hoặc khóa tài khoản (nhập sai nhiều lần, lâu không đăng nhập, hết hạn mật khẩu).
+- **Quy tắc tạo mật khẩu:** Khi tạo hoặc đổi mật khẩu mới, hệ thống validate độ dài, thành phần ký tự và kiểm tra lịch sử để đảm bảo không trùng với N mật khẩu cũ.
+- **Ngày xử lý giao dịch:** Nếu `Processing Date` được thiết lập, hệ thống dùng ngày này cho giao dịch trực tuyến. Nếu trống (trên Production), hệ thống sử dụng ngày hiện tại của máy chủ.
+
+## Mối quan hệ với modules khác
+
+- **Account Management**: Các tham số bảo mật và phiên đăng nhập tác động trực tiếp tới quá trình đăng nhập và bảo mật của tài khoản người dùng (`customer/account`).
+- **Card Management**: Cấu hình cập nhật chéo (`Cross Function Update`) ảnh hưởng tới dữ liệu khách hàng, tài khoản và thẻ (`customer/card`).
+
+## Ví dụ thực tế
+
+**Trường hợp quản trị viên cấu hình chính sách bảo mật mới:**
+1. Quản trị viên truy cập màn hình Application Parameters.
+2. Cập nhật `Maximum Failed Forgotten Password Attempts` từ 5 thành 3.
+3. Khi người dùng hệ thống nhập sai mật khẩu 3 lần liên tiếp, tài khoản của họ sẽ tự động bị khóa thay vì 5 lần như trước đó.

docs/knowledge-cards/targeting/segmentation.md

@@ -0,0 +1,56 @@
+---
+card_id: "targeting/segmentation"
+title: "Phân khúc khách hàng & Tệp đối tượng (Segmentation & Audience Upload)"
+domain: "targeting"
+related_cards:
+  - "campaign/campaign_rule"
+  - "customer/customer_overview"
+tags: ["Segmentation", "Audience Upload", "Targeting", "Demographic", "Behavior"]
+---
+
+# Phân khúc khách hàng & Tệp đối tượng (Segmentation & Audience Upload)
+
+## Mô tả ngắn
+
+Phân khúc khách hàng (Segmentation) là công cụ cho phép nhóm các khách hàng có chung đặc điểm (nhân khẩu học, hành vi giao dịch) thành các tập khách hàng mục tiêu. Hệ thống cung cấp hai cách tiếp cận: thiết lập logic động (segmentation rules) và upload danh sách tĩnh (Audience Upload).
+
+## Thuật ngữ liên quan
+
+- **Segmentation**: Phân đoạn khách hàng dựa trên sự kết hợp của nhiều tiêu chí (Demographic, Behavior, Psychographic).
+- **Audience Upload**: Quá trình đưa danh sách khách hàng tĩnh (file CSV/Excel) vào hệ thống để dùng làm tập khách hàng mục tiêu cho các chiến dịch.
+- **Demographic**: Các yếu tố nhân khẩu học như tuổi, giới tính, thu nhập, tình trạng hôn nhân.
+
+## Cấu trúc dữ liệu (Data Schema)
+
+### 1. Phân khúc khách hàng (Logic criteria)
+*Segmentation sử dụng Query Builder để tạo logic lọc. Các tiêu chí phổ biến:*
+- **Demographic**: Age, Gender, Income, Marital Status, DOB, Location.
+- **Tenure**: Customer's Tenure, Account's Tenure (Dựa trên ngày đăng ký hoặc AOD).
+- **Behavior (Giao dịch)**: Last transaction date (Recency), Transaction Frequency, Total spending value, Merchant/MCC.
+- **Psychographic**: Favorite Item/Category (Dựa trên khảo sát hoặc lịch sử).
+
+### 2. Tệp đối tượng tĩnh (Audience Upload)
+| Field | Description | Type |
+| --- | --- | --- |
+| File ID | ID định danh hệ thống sinh ra cho tệp (dùng nội bộ). | Character |
+| Audience Name | Tên tệp khách hàng, bắt buộc phải duy nhất trên hệ thống. | Character |
+| Description | Thông tin mô tả tệp. | Character |
+| Upload file | File upload chứa danh sách khách hàng (Định dạng CSV, XLS, XLSX; dung lượng <= 50MB). | File |
+
+## Cách hoạt động (How It Works)
+
+- **Tạo Segment bằng Logic:** Người dùng sử dụng Query Builder kéo/thả các tiêu chí thuộc tính (Attribute Criteria) để tạo Segment. Một Segment có thể kết hợp nhiều điều kiện (VD: *Nữ giới + Có giao dịch tháng qua + Mua tại Merchant ABC*).
+- **Sử dụng tệp tĩnh:** Người dùng có danh sách cụ thể có thể sử dụng chức năng Audience Upload để tải lên file CSV/Excel (<50MB). Hệ thống sẽ validate các field bắt buộc và định dạng của file để tạo thành Audience.
+- **Ứng dụng Segment:** Các Segment hoặc Audience tạo ra được tái sử dụng trên module Marketing để nhắm mục tiêu (Targeting) cho chiến dịch.
+
+## Mối quan hệ với modules khác
+
+- **Campaign Rule**: Segment được sử dụng trực tiếp làm tiêu chí đầu vào (Targeting Criteria) khi thiết lập các chiến dịch thưởng (`campaign/campaign_rule`).
+- **Customer Overview**: Phân khúc động (Logic Criteria) truy xuất các trường dữ liệu nhân khẩu học và hành vi từ Hồ sơ khách hàng chung (`customer/customer_overview`) để tạo bộ lọc.
+
+## Ví dụ thực tế
+
+**Tạo chiến dịch tri ân khách hàng thân thiết:**
+1. Marketing tạo một Segment dựa trên Behavior: `Total spending value` > 50,000,000 VND và `Last transaction` trong vòng 3 tháng qua.
+2. Ngoài ra, họ dùng `Audience Upload` tải lên file CSV danh sách 500 khách VIP do bộ phận CSKH lập sẵn.
+3. Cả Segment động và Audience tĩnh này đều có thể được gán vào chiến dịch "Mừng Sinh Nhật Công Ty" để gửi quà tặng.