chore: remove legacy specification documents and internal rules file

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.