chore: remove legacy specification documents and internal rules file

docs/knowledge-refs/campaign/batch_rule_processing.md

@@ -0,0 +1,46 @@
+---
+ref_id: "campaign/batch_rule_processing"
+parent_card: "campaign/cep_request, campaign/rep_rule"
+title: "Chi tiết Lịch trình chạy Batch cho CEP/REP (Batch Rule Processing Schedule)"
+domain: "campaign"
+ref_type: "process_detail"
+tags: ["batch", "schedule", "CEP", "REP", "extraction"]
+---
+
+# Chi tiết Lịch trình chạy Batch cho CEP/REP (Batch Rule Processing Schedule)
+
+## Thuộc về
+
+campaign/cep_request và campaign/rep_rule — Các card mô tả quy tắc trích xuất tự động (CEP/REP). Reference này làm rõ chi tiết các tùy chọn cấu hình lịch chạy (Run Schedule) và cách hệ thống chọn đúng Bucket để trích xuất khi Batch Job được kích hoạt.
+
+## Chi tiết
+
+### Các tùy chọn cấu hình lịch chạy (Run Schedule)
+
+Hệ thống cung cấp 5 loại lịch trình có thể cấu hình cho cả CEP và REP Batch Job:
+
+| Loại lịch chạy | Thời điểm kích hoạt Batch Job |
+|---|---|
+| **Daily** | Chạy hàng ngày vào cuối ngày (End-of-day batch stream). |
+| **Monthly on Day N of Month** | Chạy vào ngày N cố định hàng tháng. |
+| **Statement Cycle Date** | Chạy vào ngày chốt sao kê (Statement Cycle) của từng tài khoản. |
+| **N Days after AOD** | Chạy vào thời điểm chính xác N ngày sau Ngày mở tài khoản (Account Opened Date). |
+| **Annually, on Day N of Month M** | Chạy mỗi năm một lần vào ngày N tháng M. |
+
+*(Lưu ý: Trong mọi trường hợp, nếu lịch chạy rơi vào ngày hệ thống không chạy batch, job sẽ tự động lùi sang ngày chạy batch tiếp theo).*
+
+### Ma trận Quyết định (Decision Matrix) trích xuất Bucket
+
+Khi Batch Job chạy theo lịch đã định, hệ thống áp dụng ma trận dưới đây để chọn đúng Bucket (thường dùng cho CEP) để lấy giá trị:
+
+| Bucket Cấu hình (Counter Bucket to Extract) | Điều kiện trích xuất thực tế |
+|---|---|
+| **Current Bucket** | Trích xuất Bucket có Ngày hết hạn (Expiry Date) sớm nhất lớn hơn Ngày xử lý hiện tại, VÀ trạng thái State = `C` (hoặc `NULL`). |
+| **Previous Bucket** | Trích xuất Bucket có Ngày hết hạn muộn nhất nhỏ hơn Ngày xử lý hiện tại, VÀ trạng thái State = `C` (hoặc `NULL`). |
+| **Period Before Last** | Trích xuất Bucket ngay trước Previous Bucket, VÀ trạng thái State = `C` (hoặc `NULL`). |
+
+### Cập nhật Trạng thái (State Update) sau trích xuất
+
+Để tránh trích xuất trùng lặp vào chu kỳ chạy kế tiếp, trạng thái của Bucket (`C`) phải được cập nhật:
+- Nếu Counter cấu hình `Update on aware`: Đổi State từ `C` sang `A` (Awarded) nếu giao dịch ảo tạo ra từ CEP Hit được một Campaign Rule.
+- Nếu Counter cấu hình `Update on extract`: Đổi State từ `C` sang `E` (Extracted) ngay sau khi trích xuất, bất kể có Hit Rule hay không.

docs/knowledge-refs/campaign/criteria_operators.md

@@ -0,0 +1,125 @@
+---
+ref_id: "campaign/criteria_operators"
+parent_card: "campaign/campaign_rule"
+title: "Chi tiết Criteria Operators (Rule Criteria Operators)"
+domain: "campaign"
+ref_type: "enum_detail"
+tags: ["criteria", "operators", "query builder", "AND", "OR", "condition"]
+---
+
+# Chi tiết Criteria Operators (Rule Criteria Operators)
+
+## Thuộc về
+
+campaign/campaign_rule — Card tóm tắt Criteria Operators thành 1 dòng: "Operators: String (Is in, Contains...), Number (Between, Greater...), Date (Fixed, Period...)". Reference này liệt kê TOÀN BỘ operators cho mỗi data type để model nhỏ trả lời chính xác.
+
+## Chi tiết
+
+### Operators theo Data Type
+
+#### String / Lookup
+
+| Operator | Mô tả | Ví dụ |
+|---|---|---|
+| Is in | Giá trị nằm trong danh sách | Customer Status Is in [Active, Inactive] |
+| Is not in | Giá trị KHÔNG nằm trong danh sách | MCC Is not in [5411, 5412] |
+| Contains | Chuỗi chứa text con | Customer Name Contains "Nguyễn" |
+| Equal to | Bằng chính xác | Account Type Equal to "Visa Platinum" |
+| Not equal to | Không bằng | Gender Not equal to "Male" |
+| Starts with | Bắt đầu bằng | Card No Starts with "4123" |
+| Ends with | Kết thúc bằng | Phone Ends with "999" |
+| Is null | Giá trị rỗng/null | Email Is null |
+| Is not null | Giá trị có dữ liệu | Email Is not null |
+
+#### Number
+
+| Operator | Mô tả | Ví dụ |
+|---|---|---|
+| Equal | Bằng | Transaction Count Equal 10 |
+| Not equal | Không bằng | Amount Not equal 0 |
+| Less than | Nhỏ hơn | Age Less than 18 |
+| Less than or equal | Nhỏ hơn hoặc bằng | Amount Less than or equal 500000 |
+| Greater than | Lớn hơn | Nett Amount Greater than 100000 |
+| Greater than or equal | Lớn hơn hoặc bằng | Counter Value >= 5000000 |
+| Between | Trong khoảng | Amount Between 100000 AND 500000 |
+| Is null | Giá trị rỗng | Income Is null |
+| Is not null | Giá trị có dữ liệu | Income Is not null |
+
+#### Date
+
+| Operator | Mô tả | Ví dụ |
+|---|---|---|
+| On or before | Vào ngày hoặc trước | Registration Date On or before 2024-01-01 |
+| On or after | Vào ngày hoặc sau | DOB On or after 1990-01-01 |
+| Fixed date | Đúng ngày cụ thể | Transaction Date Fixed date 2024-06-15 |
+| Between date range | Trong khoảng ngày | Transaction Date Between 2024-01-01 AND 2024-12-31 |
+| Between period from N | So sánh dynamic | Last Transaction Between period from 3 months ago |
+
+**Ghi chú Date**: Một số Date operators hỗ trợ so sánh Day/Month bỏ qua Year (VD: DOB ngày 15/03 bất kể năm nào) — dùng cho criteria sinh nhật.
+
+#### Day of Week
+
+| Operator | Mô tả | Ví dụ |
+|---|---|---|
+| Is the day of week | Ngày trong tuần | Transaction Date Is the day of week [Monday, Friday] |
+
+Giá trị: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday.
+
+#### Time
+
+| Operator | Mô tả | Ví dụ |
+|---|---|---|
+| Is between | Trong khoảng thời gian | Transaction Time Is between 09:00 AND 17:00 |
+
+Format: HH:mm (00:00 – 23:59).
+
+#### Boolean
+
+| Operator | Mô tả | Ví dụ |
+|---|---|---|
+| Is | True hoặc False | Is Primary Card Is True |
+
+### Criteria Categories
+
+Criteria được nhóm theo 6 danh mục:
+
+| Category | Áp dụng cho | Ví dụ fields |
+|---|---|---|
+| Customer | Thông tin khách hàng | CIF, Customer Status, Gender, DOB, Income, Registration Date |
+| Account | Thông tin tài khoản | Account Type, Account Status, Account Open Date |
+| Transaction | Dữ liệu giao dịch | Nett Amount, Transaction Date, Transaction Time, Currency |
+| Attribute | Custom attributes | Bất kỳ attribute nào đã cấu hình (VD: Membership Tier) |
+| Counter | Giá trị Counter tích lũy | Counter Value, Counter Bucket (Current/Previous) |
+| Merchant | Thông tin merchant | Corporation, Chain, Store, MCC (Merchant Category Code) |
+
+### Logic Grouping Rules
+
+| Rule | Mô tả |
+|---|---|
+| AND / OR | Criteria trong cùng 1 group kết hợp bằng AND hoặc OR |
+| Multi-group | 1 Rule có thể có nhiều groups, nhưng logic GIỮA các groups phải nhất quán (tất cả AND hoặc tất cả OR) |
+| NOT toggle | Mỗi condition có thể bật NOT để đảo ngược (VD: NOT MCC Is in [5411]) |
+
+## Ví dụ cụ thể
+
+**Criteria phức tạp — "Thưởng 2x cho VIP ăn uống cuối tuần":**
+
+```
+Group 1 (AND):
+  - Customer: Membership Tier Equal to "VIP"        ← Attribute operator
+  - Transaction: Nett Amount Greater than 100000     ← Number operator
+  
+Group 2 (AND):                                       ← Inter-group: AND
+  - Merchant: MCC Is in [5411, 5412, 5441, 5499]   ← String/Lookup operator
+  - Transaction: Day of week Is [Saturday, Sunday]   ← Day of week operator
+  - Transaction: Time Is between 11:00 AND 22:00     ← Time operator
+```
+
+Kết quả: Chỉ kích hoạt Rule khi khách VIP chi tiêu > 100K tại merchant ăn uống vào cuối tuần giờ 11h-22h.
+
+**Criteria đơn giản — "Thưởng cho mọi giao dịch":**
+
+```
+Group 1 (AND):
+  - Transaction: Nett Amount Greater than 0          ← Chỉ cần amount > 0
+```

docs/knowledge-refs/campaign/expiry_policies.md

@@ -0,0 +1,40 @@
+---
+ref_id: "campaign/expiry_policies"
+parent_card: "campaign/pool_definition"
+title: "Chi tiết Chính sách Hết hạn (Expiry Policies)"
+domain: "campaign"
+ref_type: "enum_detail"
+tags: ["pool", "expiry", "bucket", "policy"]
+---
+
+# Chi tiết Chính sách Hết hạn (Expiry Policies)
+
+## Thuộc về
+
+campaign/pool_definition — Card tóm tắt Expiry Policy là cách tính ngày hết hạn cho số dư nhưng THIẾU danh sách các chính sách cụ thể. Reference này bổ sung chi tiết các loại Expiry Policy áp dụng cho Pool để model hiểu rõ cách tính ngày.
+
+## Chi tiết
+
+### Danh sách Expiry Policy
+
+| Giá trị | Tên | Cách hoạt động | Tham số đi kèm |
+|---|---|---|---|
+| N_MONTHS_FROM_EARNING | N Months from month of earning | Điểm kiếm được trong tháng 1 sẽ hết hạn vào cuối tháng 1+N. | Pool Expiry Policy Parameter N |
+| N_QUARTERS_FROM_EARNING | N Quarters from quarter of earning | Điểm kiếm được trong quý 1 sẽ hết hạn vào cuối quý 1+N. | Pool Expiry Policy Parameter N |
+| SEMI_ANNUAL | Semi-annual, mid- and end-year | Điểm kiếm được nửa đầu năm hết hạn vào cuối tháng 6 năm sau; nửa cuối năm hết hạn vào cuối tháng 12 năm sau. | Không |
+| N_YEARS_FROM_EARNING | N Years from year of earning | Điểm kiếm được trong năm 1 sẽ hết hạn vào cuối năm 1+N. | Pool Expiry Policy Parameter N |
+| ANNIVERSARY | Anniversary of membership | Điểm sẽ hết hạn vào mỗi ngày kỷ niệm đăng ký thành viên của khách hàng. | Không |
+| FIXED_DATE | Fixed Date | Điểm sẽ hết hạn vào đúng một ngày cụ thể được chỉ định. | Expiry Date |
+| NO_EXPIRY | No Expiry | Điểm kiếm được sẽ không bao giờ hết hạn (mặc định ngày hết hạn là 31-Dec-2999). | Không |
+
+### Quy tắc chọn
+
+- **eVoucher Pool**: Mặc định KHÔNG CÓ Expiry Policy (trường này inactive cho Evoucher pool).
+- **Fixed Date**: Nếu chọn chính sách này, bất kỳ Campaign Rule nào cập nhật (nạp điểm) vào Pool này không được phép có End Date muộn hơn Expiry Date đã chọn.
+
+## Ví dụ cụ thể
+
+- **N Months from month of earning**: Nếu `N = 3`, điểm thưởng nhận được trong tháng 1 sẽ hết hạn vào ngày cuối cùng của tháng 4.
+- **N Quarters from quarter of earning**: Nếu `N = 2`, điểm thưởng nhận được trong khoảng 1/1 đến 31/3 (Quý 1) sẽ hết hạn sau ngày 30/9 (cuối Quý 3).
+- **N Years from year of earning**: Nếu `N = 1`, điểm thưởng nhận được trong khoảng thời gian của năm 2015 sẽ hết hạn vào ngày 31/12/2016.
+- **Anniversary**: Khách hàng tham gia (đăng ký) vào ngày 15/02/2010. Điểm kiếm được trước ngày 15/02/2011 sẽ hết hạn vào đúng ngày 15/02/2011.

docs/knowledge-refs/campaign/formula_calculation.md

@@ -0,0 +1,45 @@
+---
+ref_id: "campaign/formula_calculation"
+parent_card: "campaign/campaign_rule"
+title: "Chi tiết Tính toán Công thức (Formula Calculation)"
+domain: "campaign"
+ref_type: "enum_detail"
+tags: ["formula", "calculation", "amount to use", "cap"]
+---
+
+# Chi tiết Tính toán Công thức (Formula Calculation)
+
+## Thuộc về
+
+campaign/campaign_rule — Card đề cập đến phần tính toán công thức (Formula Amount to Use, Formula result is rounded, Award limit) nhưng THIẾU chi tiết các công thức cụ thể (F1, F4, F6, F7, F8...). Reference này nhằm bổ sung các công thức thưởng (Award/Redeem).
+
+## Chi tiết
+
+[SOURCE_NEEDED] Thông tin chi tiết về các loại Formula (F1, F4, F6, F7, F8...) hiện đang nằm trong tài liệu đính kèm (attached file) của FSD gốc và không có sẵn trong spec text markdown hiện tại. Cần bổ sung tài liệu đính kèm để định nghĩa chi tiết từng công thức.
+
+### Nguồn lấy giá trị A (Amount to Use in Formula)
+
+Biến `A` trong công thức tính toán có thể được lấy từ:
+
+| Nguồn giá trị | Mô tả |
+|---|---|
+| **Numeric Attribute** | Lấy từ bất kỳ thuộc tính nào có kiểu dữ liệu là Số (Numeric Attribute). |
+| **Active Counter** | Lấy giá trị từ bộ đếm (Counter) đang hoạt động (bao gồm current/previous/before last bucket). |
+| **Code Management** | Các cấu hình mặc định (tra cứu từ bảng `Code_Management` với loại `amt-to-use-formula`). |
+
+### Rounding (Làm tròn kết quả công thức)
+
+| Option | Cách làm tròn |
+|---|---|
+| **Down** | Làm tròn xuống (ví dụ 1.9 -> 1). |
+| **To Nearest** | Làm tròn tới số nguyên gần nhất (ví dụ 1.5 -> 2, 1.4 -> 1). |
+| **Up** | Làm tròn lên (ví dụ 1.1 -> 2). |
+
+### Giới hạn thưởng (Award Limit)
+
+- **Cap A not more than**: Giới hạn biến số `A` trước khi đưa vào tính toán công thức (có thể giới hạn cứng hoặc giới hạn dựa trên 1 Counter - gọi là Cap-tracking Counter).
+- **Give At Least / No More Than**: Giới hạn tổng số lượng trả thưởng (Result) sau khi tính xong. `At Least` (Tặng tối thiểu) chỉ áp dụng cho 1 Campaign Rule. `No More Than` (Tặng tối đa) có thể giới hạn trên mỗi Campaign Rule hoặc liên kết với một Counter tổng.
+
+## Ví dụ cụ thể
+
+[SOURCE_NEEDED] Cần cung cấp ví dụ về cách áp dụng F1, F6, F7, F8 khi có đủ thông tin chi tiết về các công thức này.

docs/knowledge-refs/campaign/velocity_control_detail.md

@@ -0,0 +1,51 @@
+---
+ref_id: "campaign/velocity_control_detail"
+parent_card: "campaign/pool_definition"
+title: "Chi tiết Thiết lập Giới hạn và Cảnh báo (Velocity Control)"
+domain: "campaign"
+ref_type: "edge_cases"
+tags: ["velocity control", "limit", "alert", "pool"]
+---
+
+# Chi tiết Thiết lập Giới hạn và Cảnh báo (Velocity Control)
+
+## Thuộc về
+
+campaign/pool_definition — Card định nghĩa cấu trúc của Pool nhưng chưa đi sâu vào cơ chế chống gian lận và giới hạn. Reference này bổ sung chi tiết cấu hình Velocity Control để giới hạn số lượng giao dịch/điểm và kích hoạt cảnh báo tự động.
+
+## Chi tiết
+
+### Khái niệm Velocity Control
+
+Velocity Control là cơ chế kiểm soát tần suất và dung lượng giao dịch trên một Quỹ thưởng (Pool) nhằm ngăn chặn việc phát sinh điểm bất thường (do lỗi cấu hình rule hoặc gian lận). Nếu số lượng vượt quá ngưỡng (Maximum), hệ thống sẽ từ chối giao dịch hoặc gửi thông báo cảnh báo (Alert).
+
+### Cấu hình Giới hạn (Threshold Settings)
+
+Để thiết lập Velocity Control, người dùng cần cấu hình các tham số sau:
+
+| Tham số | Ý nghĩa | Lựa chọn / Giá trị |
+|---|---|---|
+| **Transaction Type** | Loại giao dịch nào sẽ bị kiểm soát. | Award (Cộng), Redeem (Đổi), Adjust (Điều chỉnh). |
+| **Maximum** | Ngưỡng giới hạn (số lượng điểm/vật phẩm). | Số thập phân. |
+| **Units** | Đơn vị tính toán cho Maximum. | `Per Pool units` (Tính theo tổng điểm Pool) hoặc `Per transaction` (Tính trên từng giao dịch đơn lẻ). |
+| **Per Period** | Khoảng thời gian chu kỳ để reset bộ đếm giới hạn. | Quarter, Month, Week, Day. |
+| **Per Entity 1 / 2** | (Tuỳ chọn) Giới hạn mức thực thể. | Entity 1: Customer, Account, Card.<br>Entity 2: Corporation, Chain, Store, Terminal. |
+
+### Cảnh báo (Alert Flow)
+
+Khi một giao dịch phát sinh khiến tổng số lượng trong chu kỳ (`Per Period`) vượt qua ngưỡng (`Maximum`), luồng cảnh báo sẽ được kích hoạt:
+
+1. **Chặn hoặc Cảnh báo**: Giao dịch gây vượt ngưỡng sẽ bị gắn cờ (Flagged).
+2. **Alert Template**: Hệ thống lấy nội dung thông báo từ mẫu tin nhắn đã chọn trong cấu hình.
+3. **Alert Group**: Hệ thống tự động gửi email/tin nhắn thông báo đến nhóm người nhận (Recipient Group) đã được thiết lập để có biện pháp can thiệp (ví dụ: Security Team hoặc Admin OLS).
+
+## Ví dụ cụ thể
+
+- **Tình huống**: Ngân hàng muốn ngăn chặn việc một Khách hàng lạm dụng lỗ hổng để tích lũy quá nhiều điểm thưởng vào ví "Điểm Thường Niên" trong 1 ngày.
+- **Cấu hình**: 
+  - Transaction Type = `Award`
+  - Maximum = `100,000`
+  - Units = `Per Pool units`
+  - Per Period = `Day`
+  - Per Entity 1 = `Customer`
+- **Kết quả**: Bất kỳ khách hàng nào nhận được số điểm (Award) vượt mức 100,000 điểm trong một ngày sẽ kích hoạt Alert. Hệ thống gửi email cảnh báo ngay lập tức cho nhóm Admin OLS để kiểm tra log giao dịch của khách hàng đó.

docs/knowledge-refs/catalogue/fulfillment_lifecycle.md

@@ -0,0 +1,49 @@
+---
+ref_id: "catalogue/fulfillment_lifecycle"
+parent_card: "catalogue/voucher_code"
+title: "Chi tiết Vòng đời Fulfillment của Voucher (Fulfillment Lifecycle)"
+domain: "catalogue"
+ref_type: "process_detail"
+tags: ["voucher", "fulfillment", "status", "lifecycle"]
+---
+
+# Chi tiết Vòng đời Fulfillment của Voucher (Fulfillment Lifecycle)
+
+## Thuộc về
+
+catalogue/voucher_code — Card tóm tắt 5 trạng thái vòng đời nhưng chưa giải thích rõ event nào trigger việc chuyển đổi trạng thái và hệ thống xử lý thế nào. Reference này bổ sung chi tiết luồng chuyển trạng thái Fulfillment Status của từng Voucher No.
+
+## Chi tiết
+
+### Các trạng thái Fulfillment Status
+
+Mỗi Voucher Detail (Voucher No) đều có một trạng thái theo dõi suốt vòng đời, được hệ thống cập nhật dựa trên các sự kiện (events):
+
+| Trạng thái (Status) | Giải thích | Trigger Event (Sự kiện kích hoạt) |
+|---|---|---|
+| **New** | Mã chưa được sử dụng, đang nằm trong kho. | Khi Voucher được khởi tạo tự động hoặc upload từ file vào OLS. |
+| **Issued** | Mã đã được cấp phát cho khách hàng. | Khi khách hàng thao tác đổi điểm lấy mã này thành công trên hệ thống OLS. |
+| **Fulfilled** | Khách hàng đã dùng mã thành công tại đối tác. | Khi đối tác gửi xác nhận (qua API hoặc file batch) rằng mã đã được chấp nhận và thanh toán. |
+| **Cancelled** | Mã bị hủy sau khi đã Issued. | Khi khách hàng chủ động hủy giao dịch đổi điểm, hoặc hệ thống phát sinh lỗi cần rollback giao dịch. |
+| **Rejected** | Đối tác từ chối sử dụng mã này. | Khi đối tác trả về lỗi (Mã vi phạm T&C, đã đổi ở nơi khác, v.v.). |
+
+### Luồng chuyển trạng thái (State Transition Flow)
+
+1. **Upload/Generate**: `(Chưa có) -> New`
+2. **Redeem (Đổi điểm)**: `New -> Issued`
+3. **Usage (Sử dụng)**: 
+   - Hợp lệ: `Issued -> Fulfilled`
+   - Bị từ chối: `Issued -> Rejected`
+4. **Cancel (Hủy đổi)**: `Issued -> Cancelled`
+
+### Xử lý Ngoại lệ (Error Handling)
+
+| Ngoại lệ | Hành động của hệ thống |
+|---|---|
+| Hủy mã (Cancelled) | Tuỳ thuộc cấu hình hệ thống, mã bị Cancelled có thể được tái tạo lại (trở về New) để cấp cho người khác, hoặc bị khóa vĩnh viễn và hoàn điểm lại cho khách hàng. |
+| Từ chối (Rejected) | Ghi log giao dịch lỗi, nhân viên vận hành sẽ phải đối soát lại với Vendor. |
+
+## Ví dụ cụ thể
+
+- **Luồng thành công**: Khách hàng đổi điểm lấy mã Grab. OLS lấy 1 mã từ kho đang ở trạng thái `New` và gán cho khách, đổi thành `Issued`. Khách nhập mã vào app Grab đi xe thành công. Grab gọi API thông báo về OLS, OLS đổi trạng thái mã thành `Fulfilled`.
+- **Luồng thất bại do Hủy**: Khách đổi mã CGV (`Issued`) nhưng ứng dụng gặp lỗi mạng (timeout) không hiển thị được vé. Hệ thống tự động rollback giao dịch hoàn điểm, voucher chuyển thành `Cancelled`.

docs/knowledge-refs/catalogue/redemption_pricing_detail.md

@@ -0,0 +1,44 @@
+---
+ref_id: "catalogue/redemption_pricing_detail"
+parent_card: "catalogue/item_price"
+title: "Chi tiết Tính toán Partial Redemption (Partial Redemption Calculation)"
+domain: "catalogue"
+ref_type: "edge_cases"
+tags: ["partial redemption", "cash per point", "pricing"]
+---
+
+# Chi tiết Tính toán Partial Redemption (Partial Redemption Calculation)
+
+## Thuộc về
+
+catalogue/item_price — Card có đề cập cơ bản về đổi một phần (Partial Redemption) nhưng thiếu công thức toán học chính xác và các ngoại lệ. Reference này bổ sung chi tiết công thức tính số tiền mặt cần bù và các validation rule khi cấu hình.
+
+## Chi tiết
+
+### Công thức tính tiền bù (Cash Calculation)
+
+Khi chức năng `Partial Redemption Allowed = ON`, hệ thống cho phép khách hàng đổi quà bằng cách kết hợp Điểm và Tiền mặt. Số tiền mặt phải bù được tính theo công thức:
+
+`Số tiền mặt = (Price_in_point - Số_điểm_khách_hàng_dùng) * Cash_per_point + Applicable_Taxes`
+
+| Tham số | Ý nghĩa | Ràng buộc |
+|---|---|---|
+| **Price_in_point** | Giá trị món quà quy ra điểm (Full redemption price) | Phải > 0 |
+| **Số_điểm_khách_hàng_dùng** | Số điểm mà khách hàng chọn để đổi (thường khách sẽ dùng tối đa điểm mình đang có) | Phải `>= Minimum Partial Redeem Points` VÀ `<= Price_in_point` |
+| **Cash_per_point** | Số tiền phạt/bù cho mỗi 1 điểm còn thiếu | Phải > 0 |
+| **Applicable Taxes** | Tiền thuế tương ứng với phần tiền mặt giao dịch | Dựa theo cấu hình Tax Rate Maintenance |
+
+### Các Rules đặc biệt
+
+| Rule / Ngoại lệ | Giải thích |
+|---|---|
+| **Đổi 100% bằng tiền mặt** | Chỉ được phép nếu `Minimum Partial Redeem Points = 0`. Khi đó khách hàng có thể dùng `Số_điểm_dùng = 0`. |
+| **Full Redemption ưu tiên** | Nếu khách hàng có đủ điểm (Số dư >= `Price_in_point`), khách hàng vẫn có quyền chọn Partial Redemption để giữ lại điểm (miễn là phần điểm dùng lớn hơn mức Minimum). |
+
+## Ví dụ cụ thể
+
+- **Tình huống**: Quà tặng "Tai nghe Bluetooth" có giá Full (`Price_in_point`) là 10,000 điểm. Cấu hình Partial cho phép tối thiểu `Minimum = 2,000` điểm, `Cash_per_point = 50 VND/điểm`.
+- **Trường hợp hợp lệ**: Khách hàng A có 3,000 điểm. Khách hàng dùng toàn bộ 3,000 điểm (thoả mãn `>= 2,000`).
+  Số điểm thiếu: 10,000 - 3,000 = 7,000 điểm.
+  Số tiền mặt cần thanh toán: 7,000 * 50 = 350,000 VND (Cộng thêm thuế nếu có).
+- **Trường hợp bị Reject**: Khách hàng B chỉ có 1,500 điểm. Hệ thống chặn giao dịch vì 1,500 < 2,000 (Minimum limit). Khách hàng B không thể đổi quà dù có sẵn tiền mặt.

docs/knowledge-refs/customer/adjustment_deduction_logic.md

@@ -0,0 +1,53 @@
+---
+ref_id: "customer/adjustment_deduction_logic"
+parent_card: "customer/operations_adjustment"
+title: "Chi tiết Logic Bù Trừ và Trừ Điểm (Adjustment Deduction Logic)"
+domain: "customer"
+ref_type: "edge_cases"
+tags: ["adjustment", "offset", "deduction", "negative balance", "fifo"]
+---
+
+# Chi tiết Logic Bù Trừ và Trừ Điểm (Adjustment Deduction Logic)
+
+## Thuộc về
+
+customer/operations_adjustment — Card mô tả quy tắc bù trừ (offset) và trừ điểm (deduction) chung chung. Reference này làm rõ chi tiết thứ tự trừ điểm giữa các bucket, cách xử lý negative balance để đảm bảo model hiểu cách tính toán điểm chính xác khi có điều chỉnh.
+
+## Chi tiết
+
+### Logic Bù trừ (Offset) khi Cộng Điểm (Positive Adjustment)
+
+Khi một giao dịch Positive Adjustment được duyệt, hệ thống phân bổ số điểm được cộng theo thứ tự ưu tiên sau:
+
+| Trình tự | Điều kiện kiểm tra | Hành động |
+|---|---|---|
+| 1 | Tìm các Bucket đang có số dư âm (Negative Balance) | Điểm cộng thêm được ưu tiên dùng để bù đắp (offset) cho bucket đang âm về 0. |
+| 2 | Nếu có nhiều Bucket âm | Ưu tiên bù trừ cho Bucket có Expiry Date sớm nhất. |
+| 3 | Điểm cộng vẫn còn dư (sau khi offset hết các bucket âm) | Số điểm dư sẽ được tạo thành một Bucket mới với Expiry Date được cấu hình trong giao dịch điều chỉnh. |
+
+### Logic Trừ Điểm (Deduction) khi Điều chỉnh Âm (Negative Adjustment)
+
+Người dùng có hai lựa chọn khi thực hiện Negative Adjustment:
+
+| Tùy chọn | Cơ chế xử lý |
+|---|---|
+| **Chỉ định đích danh Bucket** | Nếu người dùng chọn cụ thể 1 Bucket để trừ điểm (dựa trên Bucket Expiry Date), hệ thống sẽ CHỈ trừ điểm trên Bucket đó. Nếu số lượng trừ lớn hơn số dư của Bucket, Bucket đó sẽ bị âm (nếu Pool cho phép âm). |
+| **Không chỉ định Bucket (Mặc định)** | Hệ thống tự động trừ điểm theo phương pháp **FIFO (First-In, First-Out) dựa trên Expiry Date**. Điểm sẽ được trừ dần từ Bucket có ngày hết hạn sớm nhất đến ngày hết hạn muộn nhất cho đến khi đủ số lượng. |
+
+### Validation Rules
+
+| Rule | Khi nào check | Reject nếu |
+|---|---|---|
+| Cho phép âm (Allow Negative Balance) | Khi thực hiện Negative Adjustment mà số lượng trừ lớn hơn tổng số dư khả dụng | Pool Definition được cấu hình `Allow Negative Balance = OFF` |
+
+## Ví dụ cụ thể
+
+1. **Ví dụ Bù trừ (Offset)**:
+   - Tình trạng: Khách hàng đang có 1 Bucket âm `-50` điểm (hết hạn 31/12/2024).
+   - Hành động: Nhân viên thực hiện Positive Adjustment `+100` điểm (hết hạn 31/12/2025).
+   - Kết quả: Hệ thống lấy 50 điểm bù cho Bucket cũ (về 0). 50 điểm còn lại vào Bucket mới (Balance 50, hết hạn 31/12/2025).
+
+2. **Ví dụ Trừ điểm theo FIFO**:
+   - Tình trạng: Khách hàng có Bucket A (50 điểm, hết hạn T6/2024) và Bucket B (100 điểm, hết hạn T12/2024).
+   - Hành động: Nhân viên thực hiện Negative Adjustment `-70` điểm không chỉ định Bucket.
+   - Kết quả: Hệ thống trừ 50 điểm ở Bucket A (về 0) và tiếp tục trừ 20 điểm ở Bucket B (còn 80).

docs/knowledge-refs/marketing/omr_execution_flow.md

@@ -0,0 +1,48 @@
+---
+ref_id: "marketing/omr_execution_flow"
+parent_card: "marketing/marketing_campaign"
+title: "Chi tiết Luồng thực thi OMR (OMR Execution Flow)"
+domain: "marketing"
+ref_type: "process_detail"
+tags: ["OMR", "batch", "schedule", "execution", "targeting"]
+---
+
+# Chi tiết Luồng thực thi OMR (OMR Execution Flow)
+
+## Thuộc về
+
+marketing/marketing_campaign — Card mô tả tổng quan về OneMarketing Request (OMR). Reference này đi sâu vào quy trình xử lý nội bộ của OMR Batch Job khi nó được chạy, từ lúc lập lịch đến lúc xuất ra kết quả (Tin nhắn hoặc Trigger Giao dịch).
+
+## Chi tiết
+
+### Cấu hình Lịch trình (Run Schedule)
+
+Nếu OMR được thiết lập chạy theo lịch (`Schedule`), người dùng có thể cấu hình các tần suất sau:
+- **One time**: Chạy một lần duy nhất vào một Ngày và Giờ cố định.
+- **Daily**: Chạy lặp lại mỗi N ngày (VD: 3 ngày 1 lần) vào Giờ cố định.
+- **Weekly**: Chạy mỗi N tuần vào các Ngày cụ thể trong tuần (Ví dụ: Thứ 2 và Thứ 5 hàng tuần).
+- **Monthly**: Chạy mỗi N tháng. Hỗ trợ 2 tùy chọn:
+  - Option 1: Chạy vào các ngày cố định trong tháng (Ví dụ: Ngày 15 và 30). Hỗ trợ tùy chọn tự động lùi về "Ngày cuối cùng của tháng" nếu tháng đó không đủ ngày (VD: tháng 2).
+  - Option 2: Chạy vào tuần thứ tự (Ví dụ: Thứ Hai của tuần đầu tiên trong tháng).
+- **Annually**: Chạy mỗi N năm vào một Ngày và Tháng cố định.
+
+### Luồng thực thi của OMR Batch Job
+
+Batch Job của OMR (thường chạy song song với hệ thống Loyalty) hoạt động theo trình tự sau:
+
+1. **Quét OMR hiệu lực (Scan Effective Requests)**:
+   - Batch Job so sánh Ngày xử lý hệ thống (Processing Date) với khoảng thời gian `Effective Date From/To` của tất cả OMR.
+   - Từ danh sách OMR đang có hiệu lực, Job đối chiếu với `Run Schedule` để xác định chính xác OMR nào có lịch chạy trùng với ngày/giờ hiện tại.
+
+2. **Xác định Khách hàng mục tiêu (Targeting)**:
+   - Đối với các OMR được chọn, hệ thống đọc điều kiện `Targeting Method`.
+   - Nếu là **OMR Criteria**: Quét toàn bộ CSDL khách hàng (hoặc dựa trên bảng Transaction Log) để xuất ra danh sách (Audience) thoả mãn điều kiện (AND/OR/NOT).
+   - Nếu là **Upload file**: Sử dụng trực tiếp danh sách CIF/Account ID từ file đã tải lên.
+
+3. **Thực thi Hành động (Action Execution)**:
+   - **Với Notification**: Duyệt qua danh sách Audience, kiểm tra quy tắc `Frequency Capping`. Nếu khách hàng chưa vượt quá số lượng tin nhắn cho phép, tiến hành gửi `Message template` đến khách hàng qua các kênh tích hợp.
+   - **Với Trigger Campaign Rule**: Duyệt qua danh sách Audience, hệ thống tự động sinh ra một Batch Giao dịch ảo mang mã `OLS Transaction Code` đã cấu hình và đẩy vào hệ thống Campaign Engine để kích toán thưởng.
+
+### Tương tác với Transaction Log
+
+Đặc biệt, OMR Batch Job có thể được cấu hình để trích xuất (extract) giao dịch trực tiếp từ bảng Transaction Log. Thay vì quét toàn bộ hồ sơ khách hàng, OMR lấy các giao dịch (batch events) để tìm ra tập khách hàng mục tiêu một cách tối ưu nhất.