chore: remove legacy specification documents and internal rules file

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