sonpx/loyalty-agent-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: remove legacy specification documents and internal rules file

Browse Source
This commit is contained in:
Son Phung
2026-07-27 18:28:46 +07:00
parent 4534e4ecb8
commit 911d5be3b2
151 changed files with 26567 additions and 7922 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
.cursor/rules/codegraph.mdc
View File

@@ -1,38 +0,0 @@
---
description: CodeGraph MCP usage guide — when to use which tool
alwaysApply: true
---
<!-- CODEGRAPH_START -->
## CodeGraph
This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
### When to prefer codegraph over native search
Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
| Question | Tool |
|---|---|
| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
| "What calls function Y?" | `codegraph_callers` |
| "What does Y call?" | `codegraph_callees` |
| "What would break if I changed Z?" | `codegraph_impact` |
| "Show me Y's signature / source / docstring" | `codegraph_node` |
| "Give me focused context for a task/area" | `codegraph_context` |
| "See several related symbols' source at once" | `codegraph_explore` |
| "What files exist under path/" | `codegraph_files` |
| "Is the index healthy?" | `codegraph_status` |
### Rules of thumb
- **Answer directly — don't delegate exploration.** For "how does X work" / architecture / trace questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
- **Don't loop `codegraph_node` over many symbols** — one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
### If `.codegraph/` doesn't exist
The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*
<!-- CODEGRAPH_END -->

BIN
docs/Formula validation.docx Normal file
View File

Binary file not shown.

BIN
docs/Formula.docx Normal file
View File

Binary file not shown.

6
docs/knowledge-cards/CHANGE_HISTORY.md Normal file
View File

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

69
docs/knowledge-cards/campaign/account_type_group.md Normal file
View File

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

93
docs/knowledge-cards/campaign/campaign_rule.md Normal file
View File

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

76
docs/knowledge-cards/campaign/cep_request.md Normal file
View File

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

62
docs/knowledge-cards/campaign/counter_definition.md Normal file
View File

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

71
docs/knowledge-cards/campaign/item_redemption_rule.md Normal file
View File

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

62
docs/knowledge-cards/campaign/pool_conversion_rate.md Normal file
View File

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

74
docs/knowledge-cards/campaign/pool_definition.md Normal file
View File

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

75
docs/knowledge-cards/campaign/rep_rule.md Normal file
View File

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

78
docs/knowledge-cards/campaign/reward_campaign.md Normal file
View File

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

65
docs/knowledge-cards/campaign/transaction_codes.md Normal file
View File

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

81
docs/knowledge-cards/catalogue/catalogue_category.md Normal file
View File

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

91
docs/knowledge-cards/catalogue/item_master.md Normal file
View File

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

96
docs/knowledge-cards/catalogue/item_price.md Normal file
View File

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

91
docs/knowledge-cards/catalogue/voucher_code.md Normal file
View File

@@ -0,0 +1,91 @@
---
card_id: "catalogue/voucher_code"
title: "Quản lý kho mã điện tử (Voucher Code)"
domain: "catalogue"
related_cards:
- "catalogue/item_master"
- "campaign/item_redemption_rule"
tags: ["voucher", "eVoucher", "stock", "promo code", "fulfillment"]
detail_refs:
- "catalogue/fulfillment_lifecycle"
---
# Quản lý kho mã điện tử (Voucher Code)
## Mô tả ngắn
Voucher Code là mô-đun quản lý kho chứa các mã serial điện tử (eVoucher/Promo code) được sử dụng để trả thưởng cho khách hàng. Hệ thống hỗ trợ tổ chức mã theo lô (Voucher Code), cấu hình chung về hạn sử dụng, giá trị khuyến mãi, đồng thời quản lý vòng đời sử dụng (Lifecycle) của từng mã chi tiết (Voucher Detail) bên trong lô đó. Kho mã này có thể được tải lên (upload) từ đối tác bên ngoài hoặc do hệ thống OLS tự động sinh ra.
## Thuật ngữ liên quan
- **Voucher Code (Lô mã)**: Định danh một chiến dịch mã hoặc một nhóm mã có chung thuộc tính (Ví dụ: lô mã Giảm 50K của Highland Coffee).
- **Voucher Detail / Voucher No (Mã chi tiết)**: Chuỗi ký tự (serial number) duy nhất mà khách hàng thực sự nhận được khi đổi thưởng.
- **Expiry Policy**: Quy tắc tính ngày hết hạn của Voucher Detail (theo ngày cố định, theo ngày đổi, hoặc theo ngày giao dịch ghi sổ).
- **Promo code**: Cờ đánh dấu lô voucher này dùng làm mã giảm giá (Discount/Cashback) kèm theo tỷ lệ hoặc số tiền cụ thể.
## Cấu trúc dữ liệu (Data Schema)
Mô-đun được chia thành 2 cấp độ: Thông tin Lô mã (Voucher Code) và Thông tin từng mã (Voucher Detail).
### 1. Thông tin Lô mã (Voucher Code)
| Field Name | Description | Constraints / Rules |
|---|---|---|
| Voucher Code / Description | Mã định danh và mô tả lô mã | X(10) / X(100). |
| Supplier | Đối tác/nhà cung cấp phát hành lô mã này | Bắt buộc. Drop-down. |
| Expiry Policy | Chính sách hạn sử dụng: Fixed Date, N days from Transaction/Post Date, N months from Transaction/Post Date | Bắt buộc chọn 1. Không cho sửa sau khi tạo. |
| Expiry Date / N Param | Tham số tương ứng với Expiry Policy (Chọn Fixed Date -> nhập Ngày cố định; Chọn N days -> nhập số N) | Tuỳ thuộc vào Expiry Policy. |
| Generate Voucher | Bật: OLS tự sinh số lượng mã. Tắt: User phải tải file CSV chứa kho mã từ đối tác | Switch. Mặc định OFF. Không sửa sau khi đã đổi mã. |
| Quantity | (Chỉ hiện khi Generate = ON). Số lượng mã hệ thống cần tự sinh | 9(5). Sau khi duyệt, tự sinh N mã tương ứng. |
| This is a promo code | Bật nếu lô mã này là mã giảm giá/cashback | Switch. Mặc định OFF. |
| Promotion Type & Value | (Nếu Promo = ON). Loại khuyến mãi: % Discount, Fixed Monetary Discount, Cashback, Gift Voucher VÀ Giá trị tương ứng | Bắt buộc nếu là Promo. > 0. |
### 2. Thông tin Mã chi tiết (Voucher Detail)
| Field Name | Description | Constraints / Rules |
|---|---|---|
| Voucher No | Chuỗi ký tự mã serial thực tế gửi cho khách | Hiển thị dạng lưới (Grid). |
| Redemption Date | Ngày khách hàng đổi mã | Tự động cập nhật. |
| Expiry Date | Ngày mã hết hạn (tính toán dựa vào Expiry Policy của lô mã) | Tự động tính toán. |
| Redemption Indicator | Cờ đánh dấu trạng thái sử dụng của mã | `No` (Chưa dùng) / `Yes` (Đã dùng). |
| Fulfillment Status | Vòng đời trạng thái chi tiết của mã (Xem phần Cách hoạt động) | `New`, `Issued`, `Fulfilled`, `Cancelled`, `Rejected`. |
## Cách hoạt động (How It Works)
### 1. Khởi tạo kho mã (Stock In)
- **Cách 1 - Upload file**: Dành cho mã do đối tác cấp (VD: Shopee, Lazada). Người dùng tạo một lô Voucher Code (Generate = OFF) và dùng chức năng Upload để nạp danh sách hàng nghìn Voucher No vào lô này.
- **Cách 2 - Auto Generate**: Dành cho mã do hệ thống nội bộ phát hành. Người dùng tạo lô Voucher Code (Generate = ON, Quantity = 1000). Sau khi duyệt, hệ thống tự sinh 1000 mã ngẫu nhiên đưa vào kho.
### 2. Vòng đời của Mã chi tiết (Lifecycle)
Mỗi Voucher No bắt đầu với `Redemption Indicator` = **No** và trải qua các trạng thái `Fulfillment Status` sau:
1. **New**: Mã vừa được tạo/tải lên, sẵn sàng để cấp cho khách. Trạng thái Indicator: `No`.
2. **Issued**: Khách hàng đã đổi điểm lấy mã này thành công trên OLS. Trạng thái Indicator chuyển thành `Yes`.
3. **Fulfilled**: (Thành công tuyệt đối) Khách đã dùng mã tại hệ thống đối tác và đối tác ghi nhận chấp nhận mã.
4. **Cancelled**: Khách hàng tự hủy giao dịch đổi mã, hoặc hệ thống hủy vì lý do lỗi. Trạng thái có thể quay lại để tái sử dụng tùy cấu hình hệ thống.
5. **Rejected**: Đối tác từ chối mã (Ví dụ: vi phạm điều khoản, hết hạn, mã lỗi).
### 3. Dashboard Thống kê
Trên màn hình của mỗi lô Voucher Code (chỉ bản ghi Active), hệ thống hiển thị realtime 5 thông số:
- **Total Voucher**: Tổng số mã đã khởi tạo/nạp vào.
- **Available Vouchers**: Số mã chưa đổi và chưa hết hạn.
- **Redeemed Vouchers**: Số mã đổi thành công.
- **Cancelled Vouchers**: Số mã bị huỷ.
- **Expired Vouchers**: Số mã chưa đổi nhưng đã qua Expiry Date.
## Mối quan hệ với modules khác
- **Item Master**: Voucher Code cung cấp "Hàng hoá" (Stock) cho các vật phẩm Item Master có thuộc tính `Item Type` = `eVoucher`. Số lượng `Available Vouchers` ở đây chính là `Quantity on Hand` (tồn kho) thực tế của Item Master.
## Ví dụ thực tế
Ngân hàng muốn tung ra 1,000 mã "Giảm 50K khi mua sắm tại CGV".
1. Admin vào Voucher Code, tạo lô mã `CGV_50K`. Chọn Supplier là CGV.
2. Expiry Policy chọn `N days from Transaction Date`, `N = 30` (Mã có hạn 30 ngày kể từ ngày khách đổi).
3. Do mã do CGV cấp, chọn `Generate = OFF`. Sau đó lưu lại.
4. Admin nhận file Excel chứa 1,000 serial number từ CGV, vào hệ thống click Upload file vào lô `CGV_50K`.
5. Hệ thống thống kê: Total = 1,000, Available = 1,000, New = 1,000.
6. Admin sang màn hình **Item Master**, tạo một món quà tên "Voucher CGV 50K" và liên kết nó vào Voucher Code `CGV_50K`.
7. Khách hàng vào App đổi điểm lấy Voucher -> Số lượng Available còn 999, Redeemed = 1. Fulfillment Status của mã bị đổi chuyển thành `Issued`.

74
docs/knowledge-cards/customer/account.md Normal file
View File

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

69
docs/knowledge-cards/customer/attribute_counter.md Normal file
View File

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

64
docs/knowledge-cards/customer/card.md Normal file
View File

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

84
docs/knowledge-cards/customer/customer_overview.md Normal file
View File

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

74
docs/knowledge-cards/customer/no_hit_transaction.md Normal file
View File

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

79
docs/knowledge-cards/customer/operations_adjustment.md Normal file
View File

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

73
docs/knowledge-cards/customer/operations_transaction.md Normal file
View File

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

70
docs/knowledge-cards/customer/pool_balance.md Normal file
View File

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

67
docs/knowledge-cards/customer/statement.md Normal file
View File

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

83
docs/knowledge-cards/customer/transaction_history.md Normal file
View File

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

78
docs/knowledge-cards/marketing/ab_testing.md Normal file
View File

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

75
docs/knowledge-cards/marketing/audience_filter.md Normal file
View File

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

76
docs/knowledge-cards/marketing/frequency_capping.md Normal file
View File

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

84
docs/knowledge-cards/marketing/marketing_campaign.md Normal file
View File

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

74
docs/knowledge-cards/marketing/marketing_message.md Normal file
View File

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

68
docs/knowledge-cards/system/application_parameter.md Normal file
View File

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

56
docs/knowledge-cards/targeting/segmentation.md Normal file
View File

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

46
docs/knowledge-refs/campaign/batch_rule_processing.md Normal file
View File

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

125
docs/knowledge-refs/campaign/criteria_operators.md Normal file
View File

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

40
docs/knowledge-refs/campaign/expiry_policies.md Normal file
View File

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

45
docs/knowledge-refs/campaign/formula_calculation.md Normal file
View File

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

51
docs/knowledge-refs/campaign/velocity_control_detail.md Normal file
View File

@@ -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 đó.

49
docs/knowledge-refs/catalogue/fulfillment_lifecycle.md Normal file
View File

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

44
docs/knowledge-refs/catalogue/redemption_pricing_detail.md Normal file
View File

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

53
docs/knowledge-refs/customer/adjustment_deduction_logic.md Normal file
View File

@@ -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).

48
docs/knowledge-refs/marketing/omr_execution_flow.md Normal file
View File

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

27
docs/specs/00_MIGRATION_REPORT.md
View File

@@ -1,27 +0,0 @@
# Migration Report
## Summary
The migration of the monolithic FSD (Functional Specification Document) Markdown files to the OpenSpec standard is complete. The goal was to decompose massive, human-oriented Word-converted markdown files into Agent-Friendly, atomic, and structured OpenSpec documents.
## Completed Tasks
1. **Decomposition:** All major monolithic files have been decomposed into domain-specific subdirectories.
2. **Archiving:** The original monolithic markdown files have been moved to `docs/specs/archive/`.
3. **Format Standardization:** The newly created documents follow the OpenSpec format, including proper YAML frontmatter (`title`, `type`, `status`, `domain`).
4. **Cleanup:** Unnecessary UI clutter, malformed artifacts (e.g. `[Image Removed]`), and verbose narrative instructions were removed or converted into structured business rules and data schemas.
## Output Structure
The new documentation is organized into the following domains under `docs/specs/`:
* `customer_management/`: Profiles, Accounts, Cards, Pool Balances, Transactions, Adjustments, etc.
* `reward_campaign/`: Campaign Structures, Rules, Criteria, Formulas, Counter Definitions, Transaction Categories, etc.
* `onetargeting/`: Segmentation, Audiences.
* `onecatalogue/`: Catalogues, Categories, Master Items, Vouchers.
* `onemarketing/`: Messages, Campaigns, A/B Testing, Whitelists, Blacklists.
* `oneaccess/`: Users, Permissions, Profiles.
* `oneadmin/`: Framework behavior.
* `system_management/`: Application parameters.
* `introduction/`: Terminology.
* `reference/`: References, Change History.
## Next Steps
- Implement Agent tooling capable of reading these OpenSpec files to generate test cases or boilerplate code.
- Ensure any future updates to the requirements are made directly to the atomic OpenSpec files, not the archived monolithic documents.

34
docs/specs/00_MIGRATION_TRACKER.md
View File

@@ -1,34 +0,0 @@
# Migration Tracker: FSD to OpenSpec
## Objective
Convert `docs/FSD P1_Finnal Version.docx` to a structured, modular Knowledge Base based on the OpenSpec format.
## Stages
- [x] **Step 1:** Convert `.docx` to HTML using Python (`mammoth`), then to Markdown (`markdownify`) to preserve tables and structure. (Script: `convert_fsd.py`)
- [x] **Step 2:** Generate the Master Markdown file (`docs/FSD_Master_Clean.md`).
- [x] **Step 3:** Analyze the Master Markdown file to extract domains (e.g., Campaign, Customer, OneAccess).
- [x] **Step 4:** Split the content into modular OpenSpec Markdown files under `docs/specs/`, clean up heavy image tags, and apply standard headings.
- [x] **Step 5:** Finalize migration and generate report (`docs/specs/00_MIGRATION_REPORT.md`), remove temporary files.
## Extracted Domains
1. `overview.md` (Overview)
2. `scope_and_assumption.md` (Scope & Assumption)
3. `one_access.md` (OneAccess)
4. `one_loyalty.md` (OneLoyalty / Campaign)
5. `customer_management.md` (Customer Management)
6. `one_marketing.md` (OneMarketing)
7. `one_catalogue.md` (OneCatalogue)
8. `one_targeting.md` (OneTargeting)
## Decomposed and Verified
- [x] `onetargeting.md` -> `onetargeting/segmentation.md`, `onetargeting/audience_upload.md`, `onetargeting/customer_audience.md`
- [x] `application_parameter.md` -> `system_management/application_parameter.md`
- [x] `introduction.md` -> `introduction/terminology.md`
- [x] `reference.md` -> `reference/change_history.md`, `reference/document_references.md`
- [x] `oneaccess.md` -> `oneaccess/user_group.md`, `oneaccess/permission_management.md`, `oneaccess/user_profile.md`
- [x] `oneadmin.md` -> `oneadmin/framework_behavior.md`
- [x] `onecatalogue.md` -> `onecatalogue/catalogue.md`, `onecatalogue/category.md`, `onecatalogue/item_master.md`, `onecatalogue/item_price.md`, `onecatalogue/voucher_code.md`
- [x] `onemarketing.md` -> `onemarketing/marketing_message.md`, `onemarketing/marketing_campaign.md`, `onemarketing/frequency_capping.md`, `onemarketing/ab_testing.md`, `onemarketing/blacklist.md`, `onemarketing/whitelist.md`
- [x] `customer_management.md` -> `customer_management/customer_profile.md`, `customer_management/customer_360.md`, `customer_management/account.md`, `customer_management/card.md`, `customer_management/pool_balance_detail.md`, `customer_management/transaction_history.md`, `customer_management/no_hit_cp_transaction.md`, `customer_management/statement.md`, `customer_management/attribute.md`, `customer_management/counter.md`, `customer_management/adjustment.md`, `customer_management/transfer_balance.md`, `customer_management/re_instatement.md`, `customer_management/item_redemption.md`, `customer_management/award_transaction.md`
- [x] `reward_campaign_management.md` -> `reward_campaign/campaign_structure.md`, `reward_campaign/external_transaction_code.md`, `reward_campaign/ols_transaction_code.md`, `reward_campaign/pool_definition.md`, `reward_campaign/counter_definition.md`, `reward_campaign/transaction_category.md`, `reward_campaign/account_type_group.md`, `reward_campaign/reward_campaign.md`, `reward_campaign/reward_campaign_rule.md`, `reward_campaign/campaign_rule_criteria.md`, `reward_campaign/campaign_rule_formula.md`, `reward_campaign/campaign_rule_contributor.md`, `reward_campaign/cep_rule.md`, `reward_campaign/rep_rule.md`, `reward_campaign/item_redemption_rule.md`, `reward_campaign/campaign_insight.md`
1

45
docs/specs/archive/introduction.md
View File

@@ -1,45 +0,0 @@
---
title: "Introduction"
type: OpenSpec
status: Draft
---
# Introduction
## Scope of Document
## Terminology
1. The following sets out the definition of terms which are used in this document:
| | **Term** | **Definition** |
| --- | --- | --- |
| | Amount vs Quantity | * In OLS, “Amount” is used in connection with monetary amounts – i.e. when the unit of measure is an actual currency such as Dollars, Pesos, and Indonesian Rupiah etc. For example, “Transaction Amount” is the most frequently encountered “amount” entity. * Quantity is used to refer to the number of units of an entity, but not to monetary value. For example, the number of points awarded is typically referred to as the “Award Quantity”, and the number of points redeemed is the “Redeem Quantity”, whereas the value of the award is the “Award Amount” and the value of the redemption is the “Redeem Amount” |
| | Pool Blance Bucket (Bucket) | * It is used in the context of a Reward Pool Bucket, per bucket: based on pool entity level and expiring date to determine a pool balance bucket. |
| | Bucket Expiry Date | * If used in the context of a Counter, see Counter. * If used in the context of a Reward Pool Bucket, see Pool. |
| | Campaign Rule (Rule) | * A Rule is a business rule defining the conditions under which a reward will be given, including the type and quantity of reward. * The Rule includes a set of “**Rule Criteria**” that defines the conditions to be met in order that the quantity of rewards to be calculated with the formula and parameters that are defined in the “**Rule Formula**” is to be given to the customer. |
| | CEP | * “Counter Extract & Process” is a module for setting up job requests to extract a specified counter based on criteria set up in the request, and using the counter value as transaction amount, to form a transaction to process against Campaign Rules linked to the transaction through a Transaction Code and other Rule Criteria. * The module includes the corresponding batch processes to execute the requests. |
| | Contributor | * Identifies an entity which funds the rewards given under a given Rule. * One or more Contributors can be set up for rewards of each Rule. * If there is more than one Contributor for a Rule, the “**Rule Contributor Settings**” function is used to define the percentage of reward to be billed to each Contributor. The total contribution percentage must be 100%. * If the business entity with which the customer is transacting is the only Contributor for the rewards, then no setting has to be done in the “**Rule Contributor Settings**”, as BLP will consider the transacting entity as the default Contributor. * The Contributor setting is used in the end-of-day Contributor settlement report to calculate the amount due from each Contributor, for each reward transaction. |
| | Counter | * Counters are used to track customer’s transaction statistics. * Counters can be defined on demand to track a spend frequency or spend total for a given set of criteria. * For example, a Counter can be configured to track the number of transactions done by each customer in a specific Merchant Category Code or MCC. * If the count to be tracked is periodic – e.g. monthly – then the Counter can be configured to track the count for each period in a separate “**Counter Bucket**”, where each Counter Bucket has a “**Counter Bucket Date**” equal to the end date of the month. * What is tracked depends on which “**Counter Method**” is selected. * Counters are identified by “Counter Ids”. |
| | Effective Period | * Many parameters have a Start Date and End Date range during which the parameter is effective. * The general rule is that the Start Date starts on and after 00:00:00 hours and the End Date ends at 23:59:59. * Note that in BLP, time is considered a discrete quantity in seconds. * This definition applies for all cases where we have the “Start Date” and “End Date” parameters – e.g. campaign rules, currency rates, item price schedules, etc, where the corresponding start and end times are not specified. |
| | Expiry Policy | * See more on the Pool Definition section |
| | Formula | * This part of the Rule defines the calculation formula or formulae to be used for calculating the quantity (number of units in the Reward Pool – e.g. number of points, number of coupons) of reward to be given for a given transaction if the conditions set in the Rule Criteria are fulfilled. * The Formula comprises 2 parts: the Formula Header and the Formula Detail. * “**Formula Header**” defines a set of parameters to be adopted by all formulas selected in the Formula Detail – e.g. the maximum amount of reward to be given, the rounding rule (round down, round up, etc), the quantity to use for calculation (whether the Gross Amount or Nett Amount). * “**Formula Detail**” defines the details of the formula to be used in the calculations. Each Formula Detail can have one or more Formula. * **Execution Sequence**. A Rule has one or more Formula Details. Each Formula Detail is assigned an Execution Sequence number that determines the order in which the Formula is executed during transaction processing. The higher the numbers are executed first. |
| | Gross Amount | * See Transaction Amount. |
| | Pool | * Each type of reward – e.g. points or coupons, is tracked in a “**Pool**” or “**Reward Pool”**. * Each Reward Pool is associated with a “**Pool Expiry Policy**”, also referred to as “**Expiry Policy**”. * The Pool Expiry Policy selected for the Pool determines how the reward earned in that Pool is expired. * An example of a Pool Expiry Policy is “Expire 2 calendar quarters after earning”. * This would cause all the rewards earned in a given calendar quarter to be put in a Pool Bucket with an Bucket Expiry Date set to the end date 2 calendar quarters from the quarter in which the rewards were earned. * Rewards that expire on a given date are tracked in a separate “**Pool Bucket**”. * Example, if **Expiry Policy** for a Reward Pool is “Expire rewards 6 months from month of earning”, then all the points earned in each month will be stored in a separate bucket, each “Pool Bucket” having its own **Bucket Expiry Date**. * To meet the requirements of UNIRMs, new policy based on Card Types will be provided. For details of this, see “Expiry Policy” definition. |
| | REP | * “Redeem, Extract and Process” is a module for setting up a request to redeem a specified Pool, subject to criteria set up as part of the request, and to then output the redemption transaction details according to the selection set up in the request. |
| | Rule Criteria | * See Campaign Rule Criteria |
| | Rule Pool | * The Rule Pool is a Reward Pool which is updated with the results of the Rule Formula or Formulae. * Each Rule is associated with one Rule Pool. |
| | Transaction Amount | * Each transaction record in OLS for award processing has a mandatory column identified as the Transaction Amount. The Transaction Amount is used as the principal quantity for reward calculation in the Formula. * If the transaction is a payment transaction: + The Transaction Amount is the payment amount + If the transaction request includes a request to offset the payment amount by redeeming any available rewards, the amount remaining after deducting the available rewards value from the payment amount is referred to as the “**Nett Amount**”. + The payment amount before the deduction is the “**Gross Amount**”. * The Transaction Amount is always logged in OLS as the “Gross Amount”. |
| | OLS Transaction Code (TC) | * Each transaction record received in OLS for award processing has a column identified as the Transaction Code or TC. * The TC is used as the key to locate applicable Rules. * If no Rule is linked to TC, no reward calculation is done for that transaction. * TC is user-defined but it must be set up in the Transaction Code look-up table. |
## Structure of Document
The rest of this document is made up of the following sections:
1. Introduction
2. OneAcess
3. Customer Management
4. Campaign Management
5. OneCatalouge
6. OneMarketing
7. OneTargeting

243
docs/specs/archive/oneaccess.md
View File

@@ -1,243 +0,0 @@
---
title: "OneAccess"
type: OpenSpec
status: Draft
---
# OneAccess
## Overview
1. OneAccess™ is the module for managing user access rights to OLS administration functions.
2. The Access control Management functions are comprised of:
* User Group definition
* User Profile set-up (defining user IDs for logging into the system).
* Permission Management setup 2 permission type: Particular user/ User Group.
1. Report permission
* To identify reports each Permission Group is allowed to access.
1. View filter Management
Every screen can be configured with a filter based on the value of fields in the screen (View Filter). The View Filter restricts which fields in which screens are displayed to users in a User Group. The View Filter can also be used to block the entire view from the users in a User Group.
**In phase 1, we are focusing on item #1 first and allow automation to approve when user/edit record.**
## User Group
### Business Requirement
1. The User Group module is utilized to categorize users who share identical permissions within OLS.
2. Use this screen to define the group to be assigned to a particular user or group of users. When adding a new user to the system, select this group for that user.
### Process Flow
=TBD=
### Trigger
1. A new user group needs to be defined.
2. An existing user group needs to be modified or the user needs to review the existing group to make any decision.
### Post –Condition
1. Users have to have the access right on this screen to access this screen.
2. Depending on the user’s access rights, they can view/add/edit user group records.
### Wireframe
Please refer to the wireframe on the Figma.
### Business Rules
* + - * 1. The user group ID must be a unique value.
2. If the required user group has not been defined, click on the User group icon in the Main Menu to bring up the summary list as illustrated in section [Wireframe](#_Wireframe_18)
3. Click on Add button ([Image Removed]) in the screen to bring up the edit form; clicking on the MoreOutLined icon (⋮) then click on Edit icon (!) also brings up the same edit form. The edit form for User Group is illustrated in section [Wireframe](#_Wireframe_18).
4. Screen description:
| | | | |
| --- | --- | --- | --- |
| **Index** | **Field** | **Description** | **Data type** |
| **Genneral information** | | | |
| | User Group ID\*/ Id nhóm người dùng | The identify of user group | ~~X(20)~~ X(10) |
| | User group Name\*/ Tên nhóm người dung | The name of the user group For reference only | X(100) |
| | Description /Mô tả | Description for user group | X(200) |
| **Group users: List all active User Profile record are assigned to this group.** **This part is display when user click to view any active record only** | | | |
| | User ID\* / ID người dùng | The identify of the user who be long to the chosen group | Display |
| | User name\*/Tên người dung | The name of the user | Display |
| | Email \*/Địa chỉ email | Email | Display |
### Post –Condition
* 1. The data is updated in the DB and relation screen (if needed).
### Exception Flow
1. Input data are not passed all validations and then user choose cancel the action then use case ends in failure.
## Permission Management
### Business requirement
1. The Permission Management module is used to maintain Access Rights Groups – i.e. to define:
1. Which modules and functions can be accessed by users in a group, and
2. Which of the applicable actions can be performed by the users in each of the functions within each of the modules in the group:
| | | |
| --- | --- | --- |
| * + 1. Add | * + 1. Change | * + 1. View |
| * + 1. Delete | * + 1. Approve (or Reject) | * + 1. Copy |
| * + 1. View History | h. Save as Template | |
### Process Flow
TBD
### Trigger
* + 1. New user group to be defined then need to add permission to this group.
### Post-Conditions
1. Users have to have the access right on this screen in order to access this screen.
2. Depending on the user’s access rights, they can view/add/edit Permission Management records.
### Wireframe
Please refer to the wireframe on the Figma.
### Business Rules
* + - * 1. If permission required has not been defined, click on the Permission Management icon in the Main Menu to bring up the summary list as illustrated in the section [Wireframe](#_Wireframe_19)
2. Click on the Add button ([Image Removed]) in the screen to bring up the edit form; clicking on the MoreOutLined icon (⋮) and then clicking on the Edit icon (!) also brings up the same edit form. The edit form for Permission Management is illustrated in the section [Wireframe](#_Wireframe_19).
3. Screen description
| | | | |
| --- | --- | --- | --- |
| **Index** | **Field** | **Description** | **Data type** |
| **Step 1\*: General information/Thông tin Chung** | | | |
| | Role \*/Quyền | The unique identifier of the permission group. | ~~X(20)~~ X(10) |
| | Role Name\*/Tên nhóm quyền | Text describing the Permission Group Name, for user reference | X(100) |
| | Permission Type \*/Loại quyền | Drop down to select the following permission type: *Particular User* *User Group* | Drop-down Select one |
| | User/Người dùng | Condition field Drop-down list to select one or more users who can be accessed on all functions of this role. This field is only active and required when "Particular User" is selected in the previous step. | Drop-down Multiple select |
| | User group/ Nhóm người dung | Condition field Drop-down list to select only one group and all users under this group can be accessed on all functions of this role. This field is only active and required when this role is applicable to the user group type. | Drop-down Select one |
| | Description/ Mô tả | Text describing the Role, for user reference | X(200) |
| **Step 2**\*: **Permission Management** /Quản lí quyền | | | |
| | **Select Modules** A hierarchy of modules contains the list of functions available. Top-level module: The modules group Second level module: The specific module for each group. Allow the user to search the modules by entering the module name | | |
| | Select All/Chọn tất cả | Check/Uncheck to drag/drop all modules in the system into the permission part to configure the specific permission of the role. | Check box |
| | “Module Name” | Check/Uncheck to drag/drop this module permission part to configure the specific permission of the role. Checked/Unchecked on top level then all second level modules will be applicable as well. | Check box |
| | Search /Tìm kiếm | Users input their search keyword(s) into a designated search bar to find the module they're looking for. | Search feature |
| | **Permission /Quyền** **A list contains all selected modules in the previous step and the permission list applicable for each module.** **Note that: N/A =**Not Applicable will be defined in the master data and the user can’t check/uncheck to allow/disallow the permission if this permission is not applicable. **The system allows the user to quickly add/delete one permission to all modules per each module group.** **Besides the system allows** to allow/disallow all available permissions for all modules that appeared in the “Permission” part | | |
| | Selected all/Chọn tất cả | Check/Uncheck to allow/disallow all available permissions for all modules that appeared in the “Permission” part. | Check box |
| | “Top-level module name” E.g: Customer Management | The name of the top-level selected module. Check/uncheck to allow/disallow all available permission for all second-level modules belonging to this module | Check box |
| | “Second level Module name” E.g: Card | The name of the second level selected module. Check/uncheck to allow/disallow all available permissions for the chosen module. | Check box |
| | “Second level Module name” E.g: Card | Click on the second level module to bring up the popup to define the permission of each field on the each screen. See more on “Acccess Right Fields” | Hyperlink |
| | View /Xem | This column contains one checkbox in each row corresponding to a function to which the View action is applicable. If checked, users in this role can view the data available in this function | Check box |
| | Create/Thêm mới | This column contains one checkbox in each row corresponding to a function to which the Create action is applicable. If checked, users in this role can create data in this function. If user have created permisson then user will have "Save as draft" role also | Check box |
| | Edit /Sửa | This column contains one checkbox in each row corresponding to a function to which the Edit action is applicable. If checked, users in this role can do "update" action in this function. | Check box |
| | Delete/Xóa | This column contains one checkbox in each row corresponding to a function to which the Delete action is applicable. If checked, users in this role can do "delete" action in this function. | Check box |
| | Copy /Sao chép | This column contains one checkbox in each row corresponding to a function to which the Copy action is applicable. If checked, users in this Role can coppy available data in this function | Check box |
| | Approve /Phê duyệt | This column contains one checkbox in each row corresponding to a function to which the Approve/Reject action are applicable. If checked, users in this role can do " approve/reject" action in this function | Check box |
| | History/Xem lịch sử | This column contains one checkbox in each row corresponding to a function to which the History action (i.e. to view earlier versions of the data in the activity log) is applicable. If checked, users in this role can view data history in this function. | Check box |
| | Template/Tạo biểu mẫu | This column contains one checkbox in each row corresponding to a function to which the "Save As Tempalte"action is applicable. If checked, users in this role can save record as a template and able to access to "template" tab in listing page | Check box |
| **Access rights field /Phần quyền chi tiết trường thông tin** | | | |
| | Access permission | The list available fields of chosen module | Display |
| | View/Xem | This column contains one checkbox in the each row corresponding to a function to which the “view” action is applicable. If checked, user in this role can view the field in the screen. | Check box |
| | Editable/Cho phép chỉnh sửa | This column contains one checkbox in the each row corresponding to a function to which the “Editable” action is applicable. If checked, user in this role can modify the value of this field in the screen. | Checkbox |
* When viewing any record, the system displays only the available permissions for this group.
### Post-Conditions
Record is automation approval.
Based on the permission the system will check and display available module/function of each user as following:
A = Set of Permission of role which are assigned directly to user
B= Set of Permission of Role which are assigned to permission group and user are in these permission group.
**Therefore: C= User permission = Combination of A and B.**
### Exception Flow
1. Input data are not passed all validations and then user choose cancel the action then use case ends in failure.
## User Profile
### Business requirement
The user profile defines user attributes and sets the date and time for allowing user access to system functions. User profile created will be used for login, and users, upon logging in, will be able to view a list of functions with specific operations set in the permission management section and will be associated with users through this function screen.
### Process Flow
N/A
### Trigger
* + 1. New account need to be defined.
2. Need to update information of any existing account in the system.
### Post-codition
1. Users have to have the access right on this screen in order to access this screen.
2. Depending on user’s access rights, they can view/add/edit User Profile records.
### Wireframe
Please refer to the wireframe in the Figma.
### Business Rules
* + - * 1. If the permission required has not been defined, click on the User Profile icon in the Main Menu to bring up the summary list as illustrated in the section [Wireframe](#_Wireframe_20).
2. Click on the Add button ([Image Removed]) in the screen to bring up the edit form; clicking on the MoreOutLined icon (⋮) and then clicking on the Edit icon (!) also brings up the same edit form. The edit form for the User Profile is illustrated in the section [Wireframe](#_Wireframe_20).
3. Screen description
| | | | |
| --- | --- | --- | --- |
| **Index** | **Field** | **Description** | **Data type** |
| **General information** | | | |
| | User ID\*/ ID người dùng | Unique user identifier, assigned by the user | X(10) |
| | User Name\*/Tên người dùng | Name of the user associated with the User ID | X(50) |
| | Password/Mật khẩu | Condition field This field is only active and required when creating a new user. The password must be strong enough. | X(50) |
| | Re-enter password/Nhập lại mật khẩu | Condition filed This field is only active and required when viewing any record. The re-enter password must be matched with the password. | X(50) |
| | Reset Password | Condition field This field is only active and required when updating the user profile record. Click to reset the password in case the user forgot the password. See more on “ Reset password” | Hyperlink |
| | Email \*/Email | User’s email address. A password reset link can be sent to this address if the system is configured to do so. User can use this email to log in in the system instead. The email must be unique value | X(100) |
| | Default Language\* /Ngôn ngữ mặc định | Determines the language in which the screen labels are displayed. | Drop-down Select one |
| **Access Detail** | | | |
| | Access Day \*/Ngày truy cập | Seven checkboxes, each of which indicates the day of week on which the user has (checked) or has no (unchecked) access to the system. | Check box Allow to check more than one value |
| | Access time \*/Thời gian truy cập | On days when user has access, the Access Time is the time on and after which user has access to the system – i.e. is able to log in to the system | Time |
| | User Profile Effective From Date \*/Tài khoản có hiệu lực từ ngày | Date on and after which this User Profile is effective and the user can log in to the system | Date |
| | User Profile Effective End Date\*/Tài khoản hết hạn sau ngày | Date on and before which this User Profile is effective and the user can log in to the system After this day user can no longer log in to the system | Date |
| | User Group\*/Nhóm người dùng | A drop-down listing the available User groups. The selected group determines the functions to which the user that this user profile is defined for has access. | Drop-down Select one |
| | Report Access Right/ Quyền truy cập báo cáo | Drop-down listing the Report Access Rights groups. The selected Report Access Rights group determines which report(s) the user has access to. | Drop-down Select one |
| | User Status\*/Trạng thái người dùng | Drop-down to select following user status: Active Blocked If account is blocked then user can no longer login into the system. | Drop-down Select one |
| **Reset Password** A pop-up will be appeared when user click to Reset password | | | |
| | New Password\*/ Mật khẩu mới | Enter new password Password must be strong enough. | X(50) |
| | Re-enter Password\*/Nhập lại mật khẩu | Enters their new password again to confirm | X(50) |
| | Save /Lưu | Click to accept the change | Button |
| | Cancel /Hủy | Click to cancel the change | Button |
| **User Permission / Quyền người dùng** **Display for any active User Profile records** **The list contains all permission which applicable for the chosen user** | | | |
| | “Top level module name” E.g: Customer Management | The name of top-level module. | Display |
| | “Second level Module name” E.g: Card | The name of the seconde level selected module. | Display |
| | “Second level Module name” E.g: Card | Click on the second level module to bring up the popup show the access rights fields of chosen module. | Hyperlink |
| | View /Xem | Checked if allow Unchecked if disallow N/A if not applicable this action to that module | Display |
| | Create/Thêm mới | Display |
| | Edit /Sửa | Display |
| | Delete/Xóa | Display |
| | Copy /Sao chép | Display |
| | Approve /Phê duyệt | Display |
| | History/Xem lịch sử | Display |
| | Template/Tạo biểu mẫu | Display |
### Post-Conditions
When create new record then the new user account is successfully created in the system.
The new user receives an email notification with login instructions and temporary password.
When password is resetted then an email notification will send into user’s email with new password to user can login into the system again.
### Exception Flow

186
docs/specs/archive/oneadmin.md
View File

@@ -1,186 +0,0 @@
---
title: "OneAdmin™"
type: OpenSpec
status: Draft
---
# OneAdmin™
## Overview
1. OneAdmin™ is a browser-based application framework based on which all OLS administration screen functions are implemented.
2. This section describes the admin screen functions in general.
3. OneAdmin™ provides the screen functions such as the following for users to administer OLS:
| | |
| --- | --- |
| * 1. Application parameters and campaign management | * 1. Creating and reviewing customer information through menus |
| * 1. Viewing and Posting of transactions for award, redeems and adjusts | * 1. Requesting for generation and viewing of reports. |
| * 1. Creating and reviewing catalogue information. | * 1. Generic Ledger management |
| * 1. Creating and reviewing merchant information | * 1. Posting of transaction testing for award, redeem and adjusts. |
1. Maintenance actions supported include:
1. “**Add**”, to add a new record in the module or function. See section 3.6 for an illustration of the [Add](#_Add_Form) form for adding a record.
2. “**Edit**”, to modify an existing record on the module or function. See section [Edit](#_Edit_Form) for an illustration of the Edit form for editing a record.
3. “**Copy**”, where user can add a new record with the contents of a currently selected record: user will be prompted to change key values which are not allowed to be replicated across records. See section [Record Copy](#_Record_Copy) for an illustration of the record copy screen.
4. “**History**” tab brings up a display of previous versions of this record. See section [History](#_Record_History) for an illustration of the History screen.
5. “**Save**” will save the record displayed in the edit form to the database (whether it’s a new record or changes made to an existing record).
6. “**Cancel**” will cancel the action.
7. “**Approve**”, to accept the change of the record in the module or function.
8. “**Reject**”, to reject the change of the record in the modue or function.
9. “**Save as Draft**”, to temporary save the record in the module or function without publishing it.
10. “**Save as Template**”, to save the record displayed in the form to re-use in the furture as a template.
2. When first “saved”, the record is stored with its Status set to “Pending”.
3. It has to be selected (by click on the “Pending” tab to locate records with Status = “Pending”), then clicking on the record to view and/or approve it.
4. Upon approval, the record status is set to “Active”.
5. See section [Approve](#_Approve_Pending_Record) for the process to “**Approve**” pending records.
6. “**Delete**” marks the record being displayed as deleted or “inactive”.
7. The record will be copied into a new record with its status set to “Pending”, and the original record will be left intact.
8. A user with the necessary “Approval” rights must approve the deletion for the record to be deleted and blocked from further use.
9. All updates posted through OneAdmin™ are reflected in the database immediately on approval.
## Types of Screen Layouts
1. OLS admin screen functions are generally made up of 3 types of screen layouts, each corresponding to the screen function
2. The first is the **Home Page** – there is only one of this. This screen is displayed after a successful log in.
3. The second is the **Listing** **Page**:
1. This class of screens is displayed when module in the navigation panel (Menu) is clicked.
2. It generally displays a default list of records that can be accessed through the module.
4. The third type of screens is the “**Details Page**” layout:
1. This is the page displayed after a record in the Summary Listing page has been selected.
2. It shows the details of the selected record at the field level
3. In some cases, access to child records of the record on display is provided as tabs in the screen.
5. The general features of each type of screen layout are described in the following sub-sections.
## Home Page
1. The following figure illustrates the Home Page screen:
Main Menu
1. The left panel (navigation panel) lists the module and functions to which user has access. The actual functions available in the navigation panel vary depending on the access rights of the user id that is used to log into the system. Only the functions to which the user has access will be displayed.
2. The main display area shows charts of key statistics, pre-configured at time of deployment.
3. Each of the listed modules in the navigation panel expands when clicked to show the functions available under that module.
[Image Removed]
Figure: The “Campaign Managemetn” module in illustrates this expanded view.
This module has 07 functions – “Campaign Insight”, “Campaign”, “Campaign Rule”, “Pool Definition”, “Pool Conversion Rate”, “Counter Definition”, and “Account Type Group”.
The total number of pending records on each module is displayed on the right side of the module name.
1. Clicking on a function will bring up the summary listing page for that function: see section 3.4.
## Summary Listing Screens
1. When a function in the navigation menu is clicked, the main display area will typically show the summary listing page for that function.
2. The typical layout is illustrated in the following:
[Image Removed]
Sample Summary Listing Screen Layout
1. In the following table, the row numbers correspond to the display areas enclosed in red boxes with the same number:
| Box | Description |
| --- | --- |
| | The name and the path of the function are displayed at the top left corner of the main display area, in this case “Campaign Management > Pool List” – i.e. the function for maintaining “Pool Definition” records. |
| | The top right conner of the screen displays the language, with an icon of the language and language name. To change the display language, click on the icon to choose another language. |
| | The top right corner of the screen displays the user id and an icon of the user, with a description of the user’s access rights, i.e. the actions to which the user has access. To leave this screen simply click on the destination module and function in the navigation menu. |
| | The module name |
| | The area labelled in red displays the quick search form. It contains input boxes for filtering the records to be displayed. There are two modes of search – the **Quick search** mode and **Filter** mode: * The **Quick Search** mode search involves searching by key word: + Provides users with a fast and efficient way to access search functionality without navigating through multiple pages with the selection record status in the area 7. + Entering keyword on the text box. + By click on the icon or press “Enter” key to get result. The system will display the list of records where the keyword is found in any column on the listing page except date time data type coulmn, in the area labeled as box number 9. + The search uses the "Contains" operator in a case-insensitive manner to find the matching record |
| | The area labelled 4 in red displays the link to the advanced filter form where multiple fields can be set up as part of the search/filter criteria. * The advanced mode involves clicking on the “**Filter**” link. * When click on the “Filter” button the advanced filter form that appears is illustrated as following: [Image Removed] Figure 1 – Example of the Advanced Filter Form * When click to “Add” button the form that appears as illustrated in red box in area 2 as following: [Image Removed] Figure 2 – Example of the Advanced Filter when add any filter In the red box, which represents the Advance Filter form (area 2): * + Three purple boxes appear in the adjacent areas: area 4, area 5, and area 6. + In the area 4, there is the “Search Field” drop-down a data field name by which to search. The system list all available **field in the listing page by the default, except “Action” and “Status” field.** * Some specific modules will need include custom filter field, that are not displayed on the listing page such as: “Customer Profile” and “Transacion History” screen. See more on its section. * Users can choose from the available data fields to narrow down their search. + In the area 5, there is the “Search Operator”. For each data type‘s search filed then the system provides a set of “Operator” options that users can apply. These operator allow the user to specific how the field should be applied to the selected filter field. All available operator according on each data type’s search field are described on the following table: | | | | | --- | --- | --- | | **Index** | **Data Type** | **Operator** | | | Character | A drop dow to select following values: * Equal * Not Equal * Empty * Not Empty * Contains * Not Contains * In * Not In | | | Number | A drop dow to select following values: * Equal * Not Equal * Greater Than * Less Than * Greater than Or Equal to * Less than or Equal to * Between | | | Boolean | A drop dow to select following values: * Equal | | | Datetime | A drop down to select following values: * Equal * Not Equal * Greather Than or Equal To * Less than or Equal to * Between | * + In the area 6, there is the “Value Field”. This field can be of two types: Text box or Drop-Down. The type of value fields (text box or drop-down) displayed to users depends on the selected operator and searched field as following: * “Empty” and “Not Empty” operator should not require a value input field. * “Between” operator of Date/Time search field should require 2 value input fields with date/ time picker to allow the users to specific the range of date /time to be used in the filter query. * “Between” operator of number search field should require 2 text boxes with number format to allow user to specific the range of number to be used in the filter query. * “In” /”Not In” operator of character search field may present a drop-down list when search field is a lookup value field on that screen, meaning it is a field that fetches data from other tables in the system . The drop-donw list all active records of the search field and allow user select multiple value to be used in the filter query. * “In”/”Not In” operator of character search field may present a text box when search field is not a lookup value field on that screen. This text box should allow the user to enter multiple values, separated by input tag. * “Contain”/”Not Contain” operator of character search field shoud present a text box. This text box should allow the user to enter multiple values, separated by input tag. They system uses “\*” to match zero or more occurrences of the preceding subexpression. * All remaining operators may present a text box input filed to allow the users to enter a filter value. The system should validate the user-entered value based on the data type of the search field. * There is no sensitive case for character search fields. * All selected fields are used in an “AND” search. * On clicking the “Adanced Search” button, the list of records found to have the matching value would be displayed in area in box number 9. * Searching by “Filter” and “Status” be done together as an AND condition. * On clicking the “Reset” button, the system delete all filter field and return all records by the slection status. |
| | This are contains three distinct tabs, each representing a different record status: Active, Pending and Rejected. On the “Pending” tab the system show the total number of pending records next to the tab label. |
| | This area contains the pagination control links – to page forward, backward or to navigate directly to a numbered page with the number of records displayed and the number of record in total. |
| | This is the main display area listing the first N records within the function selected, where N defaults to a system parameter. N can be changed in drop-down box in area 8. The top row contains the column headings, with up to N numbered rows below it. The right-most column in are 10, inclues the actions for viewing, editing, deleting and approval the record in each row. |
| | This area shows the number of records displayed and the number of record in total. |
| | This is the Add button which when clicked brings up the edit form described in section 3.6, for adding a new record in the system. |
## Detail View
1. When the View icon for a row is clicked in the Summary List page as described in section 3.4, the details of the record in that row is displayed as illustrated in the following:
[Image Removed]
Figure 3 – Sample Record View Screen with Labelled Areas
[Image Removed]
Figure 4 – Sample Record History
| | |
| --- | --- |
| Box | Description (Refer to figure 3 and figure 4) |
| | * This area display the name of the module with the record status and record primary key. |
| | * Clicking on the “Copy” button brings up the view described in section 3.10. This feature provides a convenient means by which to create new records by changing existing records. The “Copy” feature is provided only for selected functions where a “Copy” action is practical. * Clicking on the “Edit” button, the fields are displayed with details of the record in that row, awaiting user input to amend the details. * Clicking on the “Delete” button brings up the pop-up to user confirm the deleted action. |
| | * The function accessed is displayed as a tab. * If the function has data which can be categorised separately in a logical way, each category is displayed as a different tab. * This area shows the tabs available and clicking on the tab brings up the display for that category of data. |
| | * This area shows the details of the record. |
| | * The panel on the right/bottom displays supplementary data relating to the record in the main display area (area 5). The details in the right panel vary depending on the function. |
| 7 | * Clicking on the “Back” button brings the view back to the Summary Listing page. |
| 8 | This area shows when the record was last changed, and by whom. * Every time a record is updated or approved, the user id that last made the change and the user id that last approved a change are logged with the record, together with the date and time of the action. * This information is always shown at the bottom of the record details screen display. * Only records with Status = “A” for Active are taken into account during transaction processing: if a record status is not active it will not be taken into account for any transaction processing. * The “Last Updated By” field shows the user id of the user who last updated this record. If the record is updated by a batch process, this field will contain the Batch Id. * The “Last Updated Date” field shows the date and time when the record was last updated. * The “Last Approved By” field shows the user id of the user who last approved this record. For updates by programs (batch processes and online transactions), this field is empty. * The “Last Approved Date” field shows the date and time when the record was last Approved. For updates by programs (batch processes and online transactions), this field is empty. |
| 9 | This area shows when the action records may can be changed * Clicking on the “History” records will bring up the display described as in area 4. * By choose the 2 version and clicking the “Compare” button will bring up the display described in section 3.8: Record History. Feature allows for easy browsing of the changes made to the record |
## Add/ Edit Screen
1. When the Edit /add for a row is clicked in the Summary List page, the details of the record in that row is displayed in the edit form for editing, as illustrated in the following:
[Image Removed]
Figure 3 – Sample Record Edit Form with Labelled Areas
1. Each row in the following describes the correspondingly numbered area in Figure 3:
| | |
| --- | --- |
| Box | Description (Refer to Figure 3) |
| | This area shows the function for which the edit form is being displayed. |
| | This is the main edit form. * Mandatory input fields have a coloured border on the left. * If the edit form is displayed as a result of the “Add” button being clicked in the previous screen, the fields will be displayed empty, awaiting user input * If the edit form is displayed as a result of the “Edit” button being clicked in the previous screen, the fields are displayed with details of the record in that row, awaiting user input to amend the details. |
| | * The “Create”/”Update” button will save the changes or in the case of the “Add” action, the input data, in the database as a new record with record Status = “Pending”. Note that the record being changed (“original record”) will remain unchanged. |
| | * The Cancel button causes any input or change made to be discarded and the display will return to the previous summary listing page. |
## Approve Pending Record
1. When a new record is first added, or when an existing record is “Changed” or “Deleted”, the new or modified record is inserted in the database with a Status set to “Pending”.
2. The original record remains active.
3. The “Pending” records must first be “Approved” by a user who has the rights to the “Approve” action for that function before the change becomes effective.
4. To “Approve” a record, the record must first be located by clicking for records with the “Pending ” tab as illustrated here:
[Image Removed]
Figure 4 – Search for Pending Records
[Image Removed]
Figure 5– Pending Record Listing
1. In change mode, the record values with and without the change are both displayed for comparison.The previous value (before change) and the modified value,that pending approval are displayed side by side, with modified fields displayed in a font of a different color, as illustrated:
* Red text highlights changes of the active record, ~~Red text~~ highlight with strikethrough effect for the deteled data.
* Green text highlights changes of the pending record.
* **Black text** denotes unchanged information in both record versions.
[Image Removed]
Figure 6 – Pending Record Displayed Side-by-side with Currently “Active” Record
1. At this point, it is possible to click on the Modify button to edit the record and save it back into the Pending list. The user who edits the record will not be able to “Approve” the change.
2. Click on the “Approve” button to put the record into active use.
3. Click on the “Reject” button to return the record to the Reject list for follow-up and correction.
4. Users can “Approve/Reject” record from detail view mode or by clicking on the “Approve/Reject” button from listing page.
## Record History
1. The “History” feature is for scanning through historical versions of a record.
2. When in the Record Detail view, clicking on the “History” Tab will bring up the all version of the record.
3. When the “Compare” button is clicked, the display will show details of two chosen version as following:
[Image Removed]
Figure 7 – Sample Display of a Record’s History
| | |
| --- | --- |
| Box | Description (Figure 7) |
| | Drop-down lisitng all history version inclues currently version. Users can change version to compare by select the verion to compare. |
| | Details displayed in the change history of two selected versions by the version in the drop-down list in area 1. * Red text highlights changes of the record in the red drop-down in the area 1. * Green text highlights changes of the redcoed in the green drop-down in the area 1. * **Black text** denotes unchanged information in both record versions. |

55
docs/specs/archive/reference.md
View File

@@ -1,55 +0,0 @@
---
title: "Reference"
type: OpenSpec
status: Draft
---
# Reference
| Ref# | Description / File Name |
| --- | --- |
| R01 | |
| R02 | |
| R03 | |
| R04 | |
| | |
Change History
| **Version** | **Change Description** | **Date** | **Updated by** |
| --- | --- | --- | --- |
| | The first version including: Customer Management Campaign Management Draft OMR module | 14/12/2023 | Trangdth Maivt |
| | 1. Customer 360: Add more detail for Account/Card information 2 Section 5.1 Add filter, Add/update some fields in the screen Section 5.5 Card: Update description and logical Section 5.9 and 5.10: Update label | 18/12/2023 | Trangdth |
| | 1. Update the Pool Conversion Rate module 2. Update data type DD/MM/YYYY into "Date" to respect the date time configuration format 3. Update the Card logically: Add more detail when updating the card 4. **Update customer Management module section 5: an update based on Sang's requirement (Customer/Account/dashboard/transaction history/attribute/counter)** Update Vietnamese fields and some cosmetic issues | 20/12/2023 | Trangdth |
| | 1. Update customer block data type from X(20) into X(10) 2. Section 5.4 update the card activation date from mandatory to optional 3. Section 5.2.6: Update the logic of most items 4. Section 4.7- Pool Conversion Rate: update field name and logic for pool conversion rate 5. Section 4.12 Campaign Rule Criteria: Correction some typos and add more detail for txncat criteria 6. Pool Definition: remove the item code field (move to Rule setup). Add some validations(red line) 7. Add CEP rule type | 27/12/2023 | Trangdth |
| | 1. Add REP Rule 2. Update Pool Definition Screen: screen and logical 3. Update Counter Defintion to match with PMS and add more detail. | 02/01/2024 | Trangdth |
| | 1. Update API information for REP rule 2. Update API information for CEP Rule 3. Add document for Formula (UI+ Logical) | 10/01/2024 | Trangdth |
| | 1. Add Section 5.15 Awward Transaction Entry Screen 2. Update Section 4.8 Counter Definition: Add Late txn posting option. Update logical on post-condition 3. Update Pool Defintion: add more detail for ATG field 4. CEP/REP: Update API for run schedule | 16/01/2024 | Trangdth |
| | 1. Counter definition: Update: Active "First start date is fixed" for "Days from COD" period unit 2. Pool conversion rate: Update code from X(03) into X(05) 3. Card - Update data type and logic for Old Card number - Update the relationship of Account type and Account number 4. Add Campaign : Add description for CP module | 24/01/2024 | Trangdth |
| | 1. Add section 4.12 Campaign Rule logical for Award/redem/Adjust rule type 2. Add section 4.9 Transaction Category module | 25/01/2024 | Trangdth |
| | 1. Campaign: change data type and add alidation for Campaign type 2. CEP: Update data type for Run schedule and change the sequence order in Layout 3. REP: Update data type for Run schedule and change the sequence order in Layout | 30/01/2024 | Trangdth |
| | Section 4.17 : CEP : Update API information of following fields: - Account with blocked Card - Post Transactions under PA Account selected based on | 19/02/2024 | Trangdth |
| | Section 4.12.6 : Campaign Rule/Business Rule : Update validation of "Apply after Cap value " field | 21/02/2024 | Trangdth |
| | 1. Correction typo 2. Section 4.13: Rule criteria: Update more detail and req 3. Section 5.11 Adjustment : Add field and update logical of quick view | 05/03/2024 | Trangdth |
| | 1. Correction typo 2. Section 5.11 Adjustment: Update Vietnamese label and correction logical 3. Section 5.12 Transfer Balance: Add fields, Update logical, Add User Stories and Accepted Criterions 4. Section 5.13 Re-instatement : Add fields, Update logical , Add User Stories and Accepted Criterions | 07/03/2024 | Trangdth |
| | 1. 5.2.6.3: Account/Card information: Update logical and data entities 2. 5.11 Adjust: Add US and AC 3. 5.12 Award Transaction: Add fields, Update logical , Add User Stories and Accepted Criterions 4 5.5 Pool Balance Detail: Correction and Add User Stories and Accepted Criterions | 11/03/2024 | Trangdth |
| | 1. Section 4.15 contributor setting: Update data type of "Contributor Percentage" field 2. Section 4.14 Campaign Rule formula: Remove validation of F5/Multiplier | 12/03/2024 | Trangdth |
| | 1. Section 7: Added OneCatelogue module, including: Item master/ Catalogue/Category/Voucher management 2. Section 4.12 Campaign Rule: Added Post-condition for Amount to Use feature (Transaction Processing with Amount to use). 3. Secttion 4.6 Pool Definition: Remove CP Rule name and change data for "List Of Campaign" listing page. | 20/03/2024 | Trangdth |
| | 1. Add section 7.5: Item Price 2. Update section 5.14 Item redemption to match onecatalogue logical 3. Update quick view of Adjust/transfer balance/Re-instatement/Award. Take note that I just remove redundant information and update the description to be more clearly. The logical is not changed. | 25/03/2024 | Trangdth |
| | 1. Added section 2 (2.1/ 2.2/2.3/2.4) OneAccess module, including Overview, User Group, Permission Management and User Profile 2. 4.6 Pool Definition: Correction typo 3. 4.13 Rule Criteria: Correct index of operator on each data type 4. 4.14 Campaign Formula : Update Formula logical on TP sides | 03/04/2024 | Trangdth |
| | 1. Correction typo 2. Section 4.13 Rule Criteria: Update logical of String data type (TP sides only) (change in red text) | 12/04/2024 | Trangdth |
| | 1. Section 5.6 Transaction History: Update sketch, Update US and AC, update Business rule 2. Section 5.11 Adjustment: Update sketch. Update US and AC, update business rule 3. Section 5.15 Award : Update US and AC | 15/04/2024 | Trangdth |
| | 1. Section 4.18 Added Item Redemption Rule Type | 16/04/2024 | Trangdth |
| | 1. Section 7: OneCatalogue: Typ0 correction and update section 7.6 Voucher Code module 2. Section 4.12.7 CP rule : Add Award limit use case in FSD | 19/04/2024 | Trangdth |
| | 1. Section 5.6 Transaction History: Added "Pool Unit Amount" on Award quick view. 2. Section 5.15 Item Redemption: update business req/ Flow and post condition 3. Section 7.5 Item Price Update flow/ post condition / add effective date | 26/04/2024 | Trangdth |
| | 1. Section 4.6 Pool Definition : Add validation for Card entity level field 2. Section 4.13 Campaign Rule Criteria : Correction description of filter value of Number data type 3. Section 5.14 Item Redemption : Correction Wireframe and update business rule 4. Section 7.3 Item master: Add Face value and correction typo | 02/05/2024 | Trangdth |
| | 1. Addded description to clear "Balance detail" quick view of Award and Adjustment Transaction Screen (in red text). 2. Section 5.14 Item redemption : Added User Stories and Acceptance criteria | 06/05/2024 | Trangdth |
| | 1. Section 4.13 Campaign Rule Criteria: Update String data type: Use Input tag instead of delimiter in case there are many filter value if input type as "value" | 09/05/2024 | Trangdth |
| | 1. Section 4.13 Campaign Rule Criteria: Add more description for Date Data type. 2. Section 4.12 Campaign Rule: Add new fields/validation to handle Evoucher Pool and Adjust Rule Type. ( Change in red) | 20/05/2024 | Trangdth |
| | 1. Section 4.6: Pool Definition: Add validation for Precision of Pool 2. Section 7.6: Voucher code: Change field name from Voucher type into Promotion Type 3. Section OneAdmin Overview: Update and correction section 3.1/3.2/3.3 4. Section 7.5 Item price: Add item code to avoid confuse 5. Customer Profile: Add "Address Type: field 6. Section 5.6 Item redemption Entry: Remove redudant field and add validation (Change in red text) | 24/05/2024 | Trangdth |
| | 1. Counter Definition: Add validation for "Bucket period Unit" 2. Campaign rule: Remove API of master data filed Remove Voucher code Add item code | 30/05/2024 | Trangdth |
| | 1. Section 5.9/5.10: Attribute/Counter: Correction and update more detail 2. Section 5.6: Transaction History: Remove Deleted field, correction typo and update detail for quick view 3. Section 5.11/5.12: Adjustment /Transfer balance: Correction process flow and business 4, Section 5.15: Award transaction: Update process flow on TP side 5. Other section: Update and correct to match with the system | 17/06/2024 | Trangdth |
| | All sections: Add more description for number field if needed | 19/06/2024 | Trangdth |
| | 1. Campaign formula /Business rule : Update validation for "Amount " field (F4/F6) 2. Section 5.2.6.2: Customer’s rewards statistic : Remove total spending, Update logical for Points/Cash back All change in red text | 24/06/2024 | Trangdth |
| | 1. Add section 3: Oneadmin: Overview about the OLS system : Search/Filter/Add/View/Edit/Approve/History 2. Add Section 4: Application Parameter 3. Update section 6.2.6: Customer 360=>Business Rule: Correct typo. Add more detail for pool balance information and most redeemed item | 12/07/2024 | Trangdth |
| | Correction typos | 11/11/2024 | Trangdth |

46
docs/specs/customer_management/account.md
View File

@@ -1,46 +0,0 @@
---
title: "Account"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Account
## Requirement Definition
Manages customer account information, which is either sent from an external system to OLS or added by users manually via the OLS system.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Account" module.
- An account type must exist in OLS before an account of that type can be added.
- The user must select a customer to access the Account tab.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| CIF Number | CIF number of selected customer. | String | Required. Read-only on creation. |
| Product Account Level (PAL) | Product Account Level. | Enum (Lookup) | Required. |
| Product Account Type (PAT) | Product Account Type. | Enum (Lookup) | Required. PAL + PAT = Account Type. |
| Account Number | Product Account Number. | String (20) | Required. Combination of Account No + Account Type must be unique. |
| Account Open Date | Open date of the account. | Date | Required. |
| Account Indicator | Personal [P] or Corporate [C]. | Enum (Lookup) | Required. |
| Account Block Code | Used to block transactions. | String (10) | Optional. |
| Block Code Reason | Reason for blocking. | String (100) | Optional. |
| Block Code Last Update Date | Date block was applied. | Date | Optional. |
| Cycle | Statement cycle date. | Integer (2) | > 0 if provided. |
| Account Status | Status of the account. | Enum (Lookup) | Required. |
### Execution
- Each account belongs to one Customer. The CIF number cannot be changed via this screen (requires CIF Merge batch).
- Records managed by OLSACCT batch cannot typically be changed from the admin screen.
- On Add: Rejected if Account No + Account Type already exists. Else, record added to PRODUCT_ACCOUNT and LOYALTY_ACCOUNT_PRODUCT created.
- On Update: Must exist in OLS. Original record moved to history.
- On Delete: Rejected if linked to an active Card record. Else, logical delete applied (moved to history).
## Exception Flow
- Input validation failures stop the action.

53
docs/specs/customer_management/adjustment.md
View File

@@ -1,53 +0,0 @@
---
title: "Adjustment"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Adjustment
## Requirement Definition
Allows manual posting of adjustment transactions to correct balance discrepancies.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Adjustment Entry" module.
- Records require Maker-Checker approval.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Posted Transaction By | Card, Account, or CIF. | Enum | Required. |
| Card / Account / CIF | Identifier based on above selection. | String | Required. |
| Adjustment Quantity Sign | Positive or Negative adjustment. | Enum | Required. |
| Store | Store of transaction. | Enum (Lookup) | Required. |
| Pool Id | Pool to be adjusted. | Enum (Lookup) | Required. Must respect entity level logic. |
| Transaction Date | Transaction date time. | Date | Required. |
| Expiry Date (Positive) | Expiry date of the new bucket. | Date | Required if Positive Adjustment. Defaults to pool policy. |
| Bucket Expiry Date (Negative)| Specific bucket to deduct from. | Enum (Lookup) | Optional. If empty, uses FIFO Redemption approach. |
| Adjustment Quantity | Amount to adjust. | Decimal | Required. Must be > 0. |
| Reason Code | Reason for adjustment. | Enum (Lookup) | Required. |
| Transaction Code | OLS transaction code. | Enum (Lookup) | Required. |
| Remarks | Additional notes. | String (100) | Optional. |
### Execution
- **Pending/Approve Flow**: New adjustments go to a Pending state. Authorized user must approve.
- **Positive Adjustments**:
- Offsets any negative balance buckets first.
- Remaining points added to a new bucket with specified Expiry Date.
- **Negative Adjustments**:
- If a specific Bucket Expiry Date is chosen, deduction happens there.
- Otherwise, points are deducted based on FIFO.
- OLS validates status, permissions, and block codes for the entity.
## Post-Conditions
- Pool balance buckets updated.
- Transaction logged in history.
## Exception Flow
- Validation failures or insufficient permissions.

51
docs/specs/customer_management/attribute.md
View File

@@ -1,51 +0,0 @@
---
title: "Attribute"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Attribute
## Requirement Definition
Provides a consolidated view of all attributes assigned to a customer, account, or card, populated by batch processes or Campaign Rules.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Attribute" module.
## Business Rules
### Data Schema
#### Attribute Value Detail
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Attribute Group | Group of attribute. | String | Read-only. |
| Attribute ID | Attribute ID. | String | Read-only. |
| Attribute Name | Attribute Name. | String | Read-only. |
| Entity | Client, Product_Account, or Card. | Enum | Read-only. |
| Entity ID | CIF Number, PA Number, or Card Number based on Entity. | String | Read-only. |
| Account Type | Required for Account attribute. | String | Read-only. |
| Attribute Value | Value of the attribute. | String/Number | Read-only. |
| Effective Date From | Start date. | Date | Read-only. |
| Effective Date To | End date. | Date | Read-only. |
#### Linked Campaign Details
Lists Campaign Rules referencing this attribute.
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Campaign ID | Campaign ID. | String | Read-only. |
| Campaign Name | Name of Campaign. | String | Read-only. |
| Campaign Rule | Campaign Rules ID. | String | Read-only. |
| Campaign Rule Name | Name of Campaign Rule. | String | Read-only. |
| Effect Date | Effective from and to dates. | Date | Read-only. |
### Execution
- **View-only screen.**
- Data from `ATTRIBUTE_VALUE` table.
- Filterable by Entity level and effective dates. Only effective records listed by default.
## Exception Flow
- N/A

52
docs/specs/customer_management/award_transaction.md
View File

@@ -1,52 +0,0 @@
---
title: "Award Transaction"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Award Transaction
## Requirement Definition
Allows users to review, verify, and manually create Award Transactions to grant points/rewards to a customer's account.
## Process Flow
### Pre-Conditions
- Users must have access rights in both the "Customer Profile" and "Award Transaction" modules.
- The user must select a customer on the customer profile listing page.
- Dependent on access rights, users can view, add, edit, or approve manual Award Transaction records.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Posted Transaction By | Card, Account, or CIF. | Enum | Required. |
| Card / Account / CIF | Identifier based on above selection. | String | Required. |
| Store | Store of transaction. | Enum (Lookup) | Required. |
| Transaction Date | Transaction date time. | Date | Required. |
| Reason Code | Reason for the award. | Enum (Lookup) | Required. |
| Transaction Code | OLS transaction code. | Enum (Lookup) | Required. |
| Remarks | Additional notes. | String (100) | Optional. |
#### Award Details
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Pool Id | Pool to be awarded. | Enum (Lookup) | Required. Must respect entity level logic. |
| Award Quantity | Points to award. | Decimal | Required. Must be > 0. |
| Expiry Date | Expiry date of the awarded points bucket. | Date | Required. Defaults based on pool's expiry policy. |
### Execution
- **Pending/Approve Flow**: New award transactions go to a Pending state. An authorized user must approve them.
- Manual awards act similarly to positive Adjustments but follow the Award business logic path (potentially triggering Campaign Rules if configured).
- Points are added to a new bucket with the specified Expiry Date.
## Post-Conditions
- Pool balance buckets are updated.
- Transaction is logged in history.
## Exception Flow
- Validation failures or insufficient permissions.

47
docs/specs/customer_management/card.md
View File

@@ -1,47 +0,0 @@
---
title: "Card"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Card
## Requirement Definition
Manages customer card information. Generally updated in the external system and loaded into OLS, thus often view-only, though manual additions/replacements are supported with strict rules.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Card" module.
- The parent account must exist in OLS before adding a card.
- User must select a customer.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| CIF Number | CIF Number of the card. | String | Required. Defaults to selected customer but can change for Supplement Cards. |
| Account Type | Product Account Level + Type. | Enum (Lookup) | Required. |
| Account Number | Parent Product Account Number. | Enum (Lookup) | Required. |
| Card Number | The card number. | String (20) | Required. Must be globally unique. |
| Masked Card Number | Masked version. | String (20) | Optional. |
| Cardholder Name | Name on card. | String (50) | Required. |
| Card Indicator | Supplement [S], Principal [P], Corporate [K]. | Enum (Lookup) | Required. If Principal, Card CIF must equal Account CIF. |
| Card Status | Card status. | Enum (Lookup) | Required. |
| Card Block Code | Block code for transactions. | String (10) | Optional. |
| Card Activation Date | Date activated. | Date | Optional. |
| Card Creation Date | Date created. | Date | Required. |
| Card Expiry Date | Expiry date. | Date | Required. |
| Old Card Number | For replacements only. | Enum (Lookup) | Required only if adding a replacement card for an existing one. |
### Execution
- Each Card belongs to one Account and one Customer. Changes to CIF/Account require CIF Merge batch.
- On Add: Rejected if Card Number already exists, or if Account/CIF does not exist. Adds to CARD and CARD_PRODUCT_ACCOUNT_REL.
- On Delete: Logical delete (moved to history).
- Replacement Flow: When replacing an old card, the new card gets the same PSN (Plastic Serial Number). The old card remains active until its status/block code is updated. All attributes, counters, and pool buckets linked to the old card are automatically linked to the new card.
## Exception Flow
- Validation failures.

51
docs/specs/customer_management/counter.md
View File

@@ -1,51 +0,0 @@
---
title: "Counter"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Counter
## Requirement Definition
Displays all counter buckets for a chosen customer, including Customer-level, Account-level, and Card-level counters, which are updated by Campaign Rules or manually.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Counter" module.
## Business Rules
### Data Schema
#### Counter Value Detail
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Counter | Counter identifier. | String | Read-only. |
| Entity | Cust [CU], Account [PA], Card [CA]. | Enum | Read-only. |
| Entity ID | CIF Number, Account Number, or Card Number. | String | Read-only. |
| What to count | The data entity tracked. | String | Read-only. |
| Counter Value | Counter value. | Decimal | Read-only. |
| Bucket Start Date | Start date. | Date | Read-only. |
| Bucket End Date | End date. | Date | Read-only. |
| Counter State | A: Awarded, C: New. | Enum | Read-only. |
#### Counter Statistic (History)
Lists transactions that updated this counter bucket.
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Reference No | OLS Transaction Reference Number. | String | Read-only. |
| Post Date | Post date of the transaction. | Date | Read-only. |
| Counter Value | Value updated on this transaction. | Decimal | Read-only. |
| Bucket Number | Bucket number of selected counter. | Integer | Read-only. |
| Update Date | System date when updated. | Date | Read-only. |
| Updated By | Batch/User who posted transaction. | String | Read-only. |
### Execution
- **View-only screen.**
- Values retrieved from `Campaign_Counter` table.
- Filterable by Entity level and bucket periods. Effective records listed by default.
## Exception Flow
- N/A

56
docs/specs/customer_management/customer_360.md
View File

@@ -1,56 +0,0 @@
---
title: "Customer 360"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Customer 360
## Requirement Definition
A centralized dashboard providing key information about a customer, giving a real-time view of customer behavior, balances, cards, and transaction statistics.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Customer Profile" module and select a customer to view the dashboard.
## Business Rules
### Dashboard Components
#### 1. Customer Information
- Summarized view of the customer's profile (name, CIF, status, etc.). Allows edit/delete actions from a pop-up.
#### 2. Customer's Rewards Statistic
- **Points**: Total available points.
- **Cash back**: Total available cash back.
- (Uses system date to determine balance bucket periods).
#### 3. Account / Card Information
- Lists all of the customer's accounts and cards.
- If there are no cards, it shows just the accounts.
- Columns include: Account Type, Account No, Card No, CIF, Card Status, Indicator, Expiry, Account Block Code, Account Status, Open Date.
#### 4. Transaction Statistic
- **Line Chart**: Shows fluctuation in balance (Earned/Redeemed/Adjusted) for a selected pool over a specified period (This month, Last month, Last 3/6 months). Data from TRANSACTION table.
- **Combo Chart**: Illustrates relationship between total number of transactions (line) and total transacted merchants (bar) over a specified period.
#### 5. Customer Activities
- Logs loyalty program actions (enroll, earn, redeem, transfer), feedback/reviews, email engagement, and account management events.
- Filterable by timeframe.
#### 6. Customer Segmentation
- Shows the demographic (Gender, Age, Marital Status, Income) and behavioral (Frequency, Membership class, Purchase channel, Hobby) segments the customer belongs to.
#### 7. Most Redeemed Items
- Displays the top N (configurable, default 10) redeemed items of the customer.
- Shows Item Code, Name, Category, Quantity, Points used, Cash amount used.
- Data from CAT_CATALOGUE_TRANS_DETAIL ordered by quantity descending.
#### 8. Balance Information
- Summary of all Pool balances for the customer.
- Shows Pool ID, Pool Name, Balance (sum of all buckets), Redeemable Balance (non-expired/available), Earliest Expiring Balance and Date.
## Post-Conditions
- Strategy guide for personalized experiences.

62
docs/specs/customer_management/customer_profile.md
View File

@@ -1,62 +0,0 @@
---
title: "Customer Profile"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Customer Profile
## Requirement Definition
Provides view-only access to Customer details within the OLS administration screens. Customer records are primarily updated from source systems via batch processes.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Customer Profile" module.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| CIF Number | Unique CIF Number assigned to each customer. | String (30) | Required. |
| First Name | Customer First Name. | String (50) | Required. |
| Last Name | Customer Last Name. (First Name + Last Name = Customer Name) | String (50) | Required. |
| Date of Birth | Customer birth date. | Date | Required. |
| Registration Date | Date customer opened an account. | Date | Optional. |
| Gender | Customer Gender. | Enum (Lookup) | Optional. |
| Customer Status | Customer status. | Enum (Lookup) | Required. |
| Customer Block Code | Customer block code. | String (10) | Optional. |
| Marital Status | Customer marital status. | Enum (Lookup) | Optional. |
| ID Type | ID Type of cardholder ID. | Enum (Lookup) | Optional. |
| Cardholder ID | Cardholder ID. | String (30) | Required if ID Type is selected. |
| Country Origin | Customer country origin. | Enum (Lookup) | Optional. |
| Customer Income | Customer income. | Decimal (14,2) | >= 0 if provided. |
| Profile Picture | Uploaded image file. | Image / URL | Optional. |
#### Contact Detail
Each customer can have more than one contact detail (e.g., customer contact, guardian contact). At least one must be provided.
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Address Type | Home/Business/Shipping/Billing. | Enum | Required. Unique per customer. |
| Phone Number | Phone number. | String (30) | Required. |
| Email Address | Email address. | String (50) | Required. Must be valid email format. |
| Address 1 | Main address. | String (100) | Optional. |
| Address 2 | Other address. | String (100) | Optional. |
| State | State code. | Enum (Lookup) | Optional. |
| City | City code. | Enum (Lookup) | Optional. |
| Zip Code | Postal code. | Enum (Lookup) | Optional. |
### Execution
- When a new customer is added in OLS, it is added to Client tables, and the corresponding LOYALTY_ACCOUNT is created.
- A request to add a customer whose CIF already exists with an Active status is rejected.
- A request to update/delete a CIF that does not exist or is inactive is rejected.
- Deletion of a CIF linked to an active Account is rejected. Logical delete is used (moving to History).
- Admin screen changes are generally restricted for records managed by the OLSCUST batch.
## Exception Flow
- N/A

59
docs/specs/customer_management/item_redemption.md
View File

@@ -1,59 +0,0 @@
---
title: "Item Redemption"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Item Redemption
## Requirement Definition
Allows users (e.g., call center staff) to manually redeem items for customers in real-time, exchanging points (and optionally cash) for catalog items.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Item Redemption Entry" module.
- Real-time catalog configuration and customer balances must be available.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Posted Transaction By | Card, Account, or CIF. | Enum | Required. |
| Card / Account / CIF | Identifier. | String | Required. |
| Redemption Channel | Channel of redemption. | Enum (Lookup) | Required. |
| Redemption Date | Transaction date. | Date | Required. |
| Store | Active store in OLS. | Enum (Lookup) | Required. |
| Applicable Fee | Apply item fee if configured. | Boolean | Default False. |
#### Item Details
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Catalogue Code | Catalog to redeem from. | Enum (Lookup) | Required. |
| Item | Item code. | Enum (Lookup) | Required. Item must have a matched price. |
| Redemption Mode | Fixed Points or Fixed Partial (Cash + Points).| Enum | Required based on price configuration. |
| Unit Price (Points) | Point cost per item. | Decimal | Required. Fixed for Fixed Points; editable but >= minimum for Fixed Partial. |
| Unit Cash Amount | Cash cost per item. | Decimal | Required for Fixed Partial. Calculated: (Full Price - Unit Price) * Price in Cash. |
| Unit Face Value | Face value of item. | Decimal | Read-only. Base face value or price config face value. |
| Quantity on Hand | Available inventory. | Integer | Read-only. Displayed if tracked by quantity. |
| Redemption Quantity | Amount to redeem. | Integer | Required. Must be > 0 and <= Quantity on Hand. |
| Total Price (Points) | Total points required. | Decimal | Read-only. Unit Price * Redemption Quantity. |
| Total Cash Amount | Total cash required. | Decimal | Read-only. Unit Cash Amount * Redemption Quantity. |
| Delivery Address | Delivery details for Physical/Evoucher. | String | Auto-populated from profile, editable. |
### Execution
- Transactions cannot be modified after posting.
- Validates block codes and permissions.
- Net transaction value is sum of tax, total fee, and total cash required.
- At EOD, approved items are output to a file for partners to fulfill.
## Post-Conditions
- Balances and inventory updated.
- Transaction viewable in history.
## Exception Flow
- Insufficient balance or TP validation failure blocks transaction.

51
docs/specs/customer_management/no_hit_cp_transaction.md
View File

@@ -1,51 +0,0 @@
---
title: "No-Hit CP Transaction"
type: OpenSpec
status: Draft
domain: Customer Management
---
# No-Hit CP Transaction
## Requirement Definition
Tracks all incoming transactions that trigger a campaign rule but are not eligible (do not meet criteria) OR transactions that have no linked campaign rule. Helps in troubleshooting why a customer did not receive an expected reward.
## Process Flow
### Pre-Conditions
- Incoming transactions trigger campaigns but do not hit the rule criteria.
- Users must have access rights in the "No hit CP- Transaction" module.
## Business Rules
### Data Schema
#### Transaction Detail (Incoming request data)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| CIF Number | CIF Number. | String | Read-only. |
| Product Account No | Product Account No. | String | Read-only. |
| Card Number | Card Number. | String | Read-only. |
| Invoice No | Generated unique incoming transaction ID. | String | Read-only. |
| Transaction Type | AWD / RED / ADJ. | Enum | Read-only. |
| OLS Transaction Code | Used to locate CP rule. | String | Read-only. |
| Transaction Amount | Gross amount or adjust point. | Decimal | Read-only. |
| Various | Store, Terminal, MCC, Currency, etc. | Various | Sourced from incoming transaction. |
#### CP Rule Listing (Error Details)
Displays details for each Campaign Rule the transaction triggered but failed to hit.
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Campaign ID | Campaign ID. | String | Read-only. |
| Campaign Rule | Campaign Rule ID. | String | Read-only. |
| Pool ID | Reward pool. | String | Read-only. |
| Error Code | Error response code from OLS. | String | Read-only. |
| Error Descriptions | Detailed description of why criteria failed. | String | Read-only. |
### Execution
- **View-only screen.**
- Data is sourced from `OLS_ORPHAN_TXN_NO_HIT`.
- The error description should specify exactly which criteria failed (e.g., MCC didn't match, Minimum amount not met).
## Exception Flow
- N/A

54
docs/specs/customer_management/pool_balance_detail.md
View File

@@ -1,54 +0,0 @@
---
title: "Pool Balance Detail"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Pool Balance Detail
## Requirement Definition
Provides a summary and detailed breakdown of all reward pools and their balance buckets for a selected customer.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Balance Enquiry" module.
## Business Rules
### Data Schema
#### Pool Balance Summary
Displays a row for each pool the customer interacts with.
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Pool ID | Pool ID. | String | Read-only. |
| Pool Name | Pool Name. | String | Read-only. |
| Pool Type | Pool Type. | String | Read-only. |
| Pool Entity Level | Customer, Account, or Card level. | String | Read-only. |
| Balance | Sum of all balance buckets. | Decimal | Read-only. |
| Redeemable Balance | Sum of non-expired, available buckets. | Decimal | Read-only. |
| Next Expiring Balance | The earliest non-expired balance bucket amount. | Decimal | Read-only. |
#### Pool Balance Detail (Bucket Breakdown)
Displays the individual expiry buckets for a selected pool.
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Account Type | Account Type. | String | Read-only. |
| Account No | Account Number. | String | Read-only. |
| Card Number | Card Number (only if Card pool entity level). | String | Read-only. |
| Pool ID | Selected Pool ID. | String | Read-only. |
| Balance | Non-zero balance of the bucket. | Decimal | Read-only. |
| Expiry Date | Expiring date of the bucket. | Date | Read-only. |
### Execution
- **View-only screen.** No modifications allowed directly.
- Grouping/Visibility is dependent on the Pool Entity Level:
- Customer level: Shows buckets grouped under accounts, even though earned at customer level.
- Account level: Shows buckets earned by the specific Account.
- Card level: Shows buckets earned by the specific Card.
- Expired buckets that have not yet forfeited are shown.
## Exception Flow
- N/A

46
docs/specs/customer_management/re_instatement.md
View File

@@ -1,46 +0,0 @@
---
title: "Re-Instatement"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Re-Instatement
## Requirement Definition
Allows manual re-instatement of expired balance buckets that have not yet been forfeited.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Re-Instatement" module.
- The customer must have expired pool buckets that are within the grace period (not yet forfeited).
- Requires Maker-Checker approval.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Posted Transaction By | Card, Account, or CIF. | Enum | Required. |
| Card / Account / CIF | Identifier based on above selection. | String | Required. |
| Store | Store of transaction. | Enum (Lookup) | Required. |
| Pool Id | Pool of the bucket to re-instate. | Enum (Lookup) | Required. Lists pools with non-forfeited expired balances. |
| Bucket to Re-instate | Specific expired bucket to reinstate. | Enum (Lookup) | Required. |
| Expiry Date | New expiry date of the reinstated points. | Date | Required. |
| Reason Code | Reason for re-instatement. | Enum (Lookup) | Required. |
| Remarks | Additional notes. | String (100) | Optional. |
### Execution
- **Pending/Approve Flow**: New requests go to a pending list. Authorised user approves.
- Re-instatement is posted as an Adjustment.
- The expired bucket balance is set to 0.
- If a bucket with the new Expiry Date already exists, the amount is added to it.
- Otherwise, a new bucket is created with the new Expiry Date.
## Post-Conditions
- Balances updated and logged as adjustments.
## Exception Flow
- Rejected by TP validation or block code.

52
docs/specs/customer_management/statement.md
View File

@@ -1,52 +0,0 @@
---
title: "Statement"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Statement
## Requirement Definition
Provides a list of all transactions for an account/customer over a set period (usually monthly). Includes earned, redeemed, adjusted points, beginning/ending balances, and expired points.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Statement Enquiry" module.
## Business Rules
### Data Schema
#### Statement Summary
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Loyalty Account Number | Identifier. | String | Read-only. |
| Product Account Number | Identifier. | String | Read-only. |
| Pool ID | Statement Pool. | String | Read-only. |
| Cycle Start Date | Previous statement cycle start. | Date | Read-only. |
| Statement Opening Balance | Previous points balance. | Decimal | Read-only. |
| Total Award | Earned points in cycle. | Decimal | Read-only. |
| Total Redeem | Redeemed points in cycle. | Decimal | Read-only. |
| Total Adjust | Adjusted points in cycle. | Decimal | Read-only. |
| Statement Closing Balance | Accumulated points at cycle end. | Decimal | Read-only. |
| Expired Points | Balance in expired but not forfeited buckets. | Decimal | Read-only. |
| Cycle Statement Date | Generation date. | Date | Read-only. |
#### Transaction Detail
Lists transactions within the cycle.
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Reference Number | OLS Reference Number. | String | Read-only. |
| Transaction Type | Award, Redeem, Adjust. | Enum | Read-only. |
| Unit | Earned/Redeemed/Adjusted points. | Decimal | Read-only. |
| Post Date | Post Date. | Date | Read-only. |
| Transaction Date | Transaction Date Time. | Date | Read-only. |
### Execution
- **View-only screen.** Records are updated by OLS batch jobs.
- Output supports Customer and Account level, but stored under Account level.
## Exception Flow
- N/A

72
docs/specs/customer_management/transaction_history.md
View File

@@ -1,72 +0,0 @@
---
title: "Transaction History"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Transaction History
## Requirement Definition
Provides a running record of all transactions logged in OLS for a customer, including cancellations, over a configurable period (normally the last 12 months).
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Transaction History" module.
## Business Rules
### Data Schema
#### Transaction Detail
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Invoice No | Internal invoice No generated by OLS. | String | Read-only. |
| Reference No | OLS Transaction Reference Number. | String | Read-only. |
| Source Reference Number | Reference number from source system. | String | Read-only. |
| OLS Transaction Code | OLS Transaction Code. | String | Read-only. |
| Gross Amount | Gross transaction amount. | Decimal | Read-only. |
| Nett Amount | Nett transaction amount. | Decimal | Read-only. |
| Redeem Points | Total redeem points. | Decimal | Read-only. |
| Points Redeemed Amount | Total redeem points amount. | Decimal | Read-only. |
| Adjust Points | Total adjustment points. | Decimal | Read-only. |
| Points Adjustment Amount | Total adjust point amount. | Decimal | Read-only. |
| Award Points | Total award points. | Decimal | Read-only. |
| Points Awarded Amount | Total award point amount. | Decimal | Read-only. |
| Transaction Date | Transaction Date Time. | Date | Read-only. |
| Post Date | Post Date. | Date | Read-only. |
| Settlement Date | Settlement Date. | Date | Read-only. |
| Cancellation Indicator | Cancellation Indicator. | Boolean | Read-only. |
| MCC | Transaction MCC Code. | String | Read-only. |
| Store | Transaction Store ID. | String | Read-only. |
| Terminal | Transaction Terminal ID. | String | Read-only. |
| Transaction Description | Transaction Description. | String | Read-only. |
#### Quick View Details (Right Panel)
Provides a breakdown of the transaction into its component effects.
**Reward Details** (Award/Redeem/Adjust)
- Campaign Rule triggered.
- Transaction Type.
- OLS Transaction Code.
- Reward Pool.
- Pool Unit / Amount.
**Counter Transaction Detail**
- Campaign Rule triggered.
- Counter updated.
- Entity level.
- Counter Value.
- Bucket Number, Start Date, End Date.
**Item Redemption Detail**
- Item, Description.
- Redeemed Quantity, Redeemed Points, Cash Amount Used.
### Execution
- **View-only screen.**
- Represents all successful transaction impacts on balances, counters, and redemptions.
## Exception Flow
- N/A

48
docs/specs/customer_management/transfer_balance.md
View File

@@ -1,48 +0,0 @@
---
title: "Transfer Balance"
type: OpenSpec
status: Draft
domain: Customer Management
---
# Transfer Balance
## Requirement Definition
Allows manual transfer of points from a customer/account to another customer/account (External) or between the customer's own accounts (Internal).
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Transfer Balance" module.
- Requires Maker-Checker approval.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Transfer Mode | Internal (self) or External (to another). | Enum | Required. |
| Transfer Type | Entity type to transfer from (Card, Account, Client). | Enum | Required. |
| From | Card/Account/CIF Number to transfer from. | String | Required. |
| To | Card/Account/CIF Number to transfer to. | String | Required. |
| Pool ID | The pool from which to transfer. | Enum (Lookup) | Required. Must respect "From" entity level. |
| Store | The store where transaction is logged. | Enum (Lookup) | Required. |
| Amount to Transfer | Amount. | Decimal | Required. > 0. Defaults to whole pool balance. |
| Expiry Date | Expiry date of transferred points. | Date | Required. Defaults to source expiry date. |
| Transaction Code | OLS transaction code. | Enum (Lookup) | Required. |
| Reason Code | Pre-defined reason for transfer. | Enum (Lookup) | Required. Determines GL posting accounts. |
| Remarks | Additional remarks. | String (100) | Optional. |
### Execution
- **Pending/Approve Flow**: Goes to a pending list. Authorised user approves.
- OLS validates status, block codes, and permissions for both "From" and "To".
- Rejected if "From" pool balance is insufficient.
- Execution transfers all linked pools directly from "From" to "To".
- Logged as a negative Adjustment on "From" and positive Adjustment on "To".
## Post-Conditions
- Pool balances updated.
## Exception Flow
- Insufficient balance, TP validation failures, or input errors block the action.

42
docs/specs/introduction/terminology.md
View File

@@ -1,42 +0,0 @@
---
title: "Terminology"
type: OpenSpec
status: Draft
domain: Introduction
---
# Terminology
This document defines the terms used across the OLS (One Loyalty System) modules.
## Term Definitions
| Term | Definition |
|---|---|
| Amount vs Quantity | - **Amount**: Used in connection with monetary amounts (e.g., Dollars). For example, "Transaction Amount".<br>- **Quantity**: Refers to the number of units of an entity, not monetary value. For example, "Award Quantity" or "Redeem Quantity". |
| Pool Balance Bucket (Bucket) | Used in the context of a Reward Pool Bucket. A bucket is determined based on the pool entity level and expiration date. |
| Bucket Expiry Date | - If used in the context of a Counter, refers to the Counter Expiry.<br>- If used in the context of a Reward Pool Bucket, refers to the Pool Expiry. |
| Campaign Rule (Rule) | A business rule defining the conditions under which a reward will be given, including the type and quantity of the reward. It includes **Rule Criteria** and **Rule Formula**. |
| CEP | **Counter Extract & Process**. A module for setting up job requests to extract a specified counter based on criteria and using the counter value as a transaction amount to process against Campaign Rules. Includes batch processes to execute requests. |
| Contributor | Identifies an entity which funds the rewards given under a specific Rule. One or more Contributors can be set up. **Rule Contributor Settings** define the percentage billed to each Contributor (totaling 100%). Default is the transacting business entity if only one exists. Used in end-of-day settlement reports. |
| Counter | Used to track a customer's transaction statistics (e.g., spend frequency, spend total for specific criteria like MCC). Periodic counts (e.g., monthly) are tracked in separate **Counter Buckets** with a specific **Counter Bucket Date**. |
| Effective Period | Defines a Start Date and End Date range during which a parameter is effective. Generally starts at 00:00:00 and ends at 23:59:59. Time is considered a discrete quantity in seconds. |
| Expiry Policy | Defines how rewards expire. New policies based on Card Types will be supported. |
| Formula | Defines the calculation formula used for calculating the reward quantity. Comprises:<br>- **Formula Header**: General parameters (e.g., max reward amount, rounding rules, Gross vs Nett amount).<br>- **Formula Detail**: Specific calculations, each with an Execution Sequence number (executed in descending order). |
| Gross Amount | The payment amount before any reward deduction. |
| Pool (Reward Pool) | Tracks each type of reward (e.g., points, coupons). Associated with a **Pool Expiry Policy**. Rewards expiring on a given date are tracked in a **Pool Bucket** with a **Bucket Expiry Date**. |
| REP | **Redeem, Extract and Process**. A module for setting up requests to redeem a specified Pool based on criteria, and to output the redemption transaction details. |
| Rule Criteria | Defines the conditions to be met for a rule to apply. |
| Rule Pool | A Reward Pool which is updated with the results of a Rule Formula. Each Rule is associated with one Rule Pool. |
| Transaction Amount | Mandatory column in OLS for award processing. Used as the principal quantity for reward calculations. For payment transactions:<br>- **Gross Amount**: Total payment amount.<br>- **Nett Amount**: Amount remaining after offsetting with redeemed rewards. (Logged in OLS as Gross Amount). |
| OLS Transaction Code (TC) | The key used to locate applicable Rules for a transaction record. If no Rule is linked to a TC, no reward calculation occurs. Must be defined in the TC look-up table. |
## Document Structure Reference
The standard modules defined across the system include:
1. Introduction
2. OneAccess
3. Customer Management
4. Campaign Management
5. OneCatalogue
6. OneMarketing
7. OneTargeting

65
docs/specs/oneaccess/permission_management.md
View File

@@ -1,65 +0,0 @@
---
title: "Permission Management"
type: OpenSpec
status: Draft
domain: OneAccess
---
# Permission Management
## Requirement Definition
The Permission Management module is used to maintain Access Rights Groups. It defines:
1. Which modules and functions can be accessed by users in a group.
2. Which applicable actions (Add, Change, View, Delete, Approve/Reject, Copy, View History, Save as Template) can be performed by users in each function within each module.
## Process Flow
### Trigger
- A new user group is defined, requiring permission assignment.
### Pre-Conditions
- Users must have access rights to the Permission Management module to view, add, or edit permission records.
## Business Rules
- The system checks and displays available modules/functions for each user based on:
- **A**: Permissions assigned directly to the user.
- **B**: Permissions assigned to the user's permission group.
- **Total User Permission (C)** = Combination of A and B.
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Role | The unique identifier of the permission group. | String (10) | Required. |
| Role Name | Text describing the Permission Group Name. | String (100) | Required. |
| Permission Type | The type of permission assignment. | Enum | Required. Values: Particular User, User Group. |
| User | Select one or more users for this role. | Array of User IDs | Required if Permission Type is "Particular User". |
| User Group | Select one group for this role. | String (User Group ID) | Required if Permission Type is "User Group". |
| Description | Text describing the Role. | String (200) | Optional. |
#### Module Permissions
*A hierarchy of modules containing the list of available functions (Top-level and Second-level modules).*
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| View | Allows viewing data available in the function. | Boolean | |
| Create | Allows creating data in the function. (Includes "Save as draft" implicitly). | Boolean | |
| Edit | Allows updating data in the function. | Boolean | |
| Delete | Allows deleting data in the function. | Boolean | |
| Copy | Allows copying available data in the function. | Boolean | |
| Approve | Allows approving/rejecting data in the function. | Boolean | |
| History | Allows viewing data history (activity log). | Boolean | |
| Template | Allows saving records as a template. | Boolean | |
#### Access Rights Fields (Field-Level Permissions)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| View | Allows viewing the specific field on the screen. | Boolean | |
| Editable | Allows modifying the value of the specific field. | Boolean | |
## Post-Conditions
- Records are automated for approval upon creation/modification.
## Exception Flow
- If input data fails validation, the action is canceled, and the operation fails.

47
docs/specs/oneaccess/user_group.md
View File

@@ -1,47 +0,0 @@
---
title: "User Group"
type: OpenSpec
status: Draft
domain: OneAccess
---
# User Group
## Requirement Definition
The User Group module is utilized to categorize users who share identical permissions within OLS. It defines the group to be assigned to a particular user or group of users.
## Process Flow
### Trigger
- A new user group needs to be defined.
- An existing user group needs to be modified, or a user needs to review the existing group.
### Pre-Conditions
- Users must have access rights to the User Group module to view, add, or edit user group records.
## Business Rules
- The user group ID must be a unique value.
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| User Group ID | The identity of the user group. | String (10) | Required. Must be unique. |
| User Group Name | The name of the user group. | String (100) | Required. |
| Description | Description for the user group. | String (200) | Optional. |
#### Group Users (View Only)
*Lists all active User Profile records assigned to this group.*
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| User ID | The identity of the user belonging to the chosen group. | String | Read-only |
| User Name | The name of the user. | String | Read-only |
| Email | Email address of the user. | String | Read-only |
## Post-Conditions
- The data is updated in the database and related screens.
## Exception Flow
- If input data fails validation, the action is canceled, and the operation fails.

61
docs/specs/oneaccess/user_profile.md
View File

@@ -1,61 +0,0 @@
---
title: "User Profile"
type: OpenSpec
status: Draft
domain: OneAccess
---
# User Profile
## Requirement Definition
The User Profile defines user attributes and sets the date and time allowing user access to system functions. It is used for login. Upon logging in, users can view a list of functions with specific operations set in the permission management section.
## Process Flow
### Trigger
- A new account needs to be defined.
- Information of an existing account needs to be updated.
### Pre-Conditions
- Users must have access rights to the User Profile module to view, add, or edit User Profile records.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| User ID | Unique user identifier. | String (10) | Required. Must be unique. |
| User Name | Name of the user associated with the User ID. | String (50) | Required. |
| Password | User password. | String (50) | Required for new users. Must meet strong password policies. |
| Re-enter Password | Confirmation of the password. | String (50) | Must match Password. |
| Email | User's email address. Can be used for login and password resets. | String (100) | Required. Must be unique. |
| Default Language | Determines the language for screen labels. | Enum | Required. |
#### Access Detail
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Access Day | Indicates the days of the week the user has access to the system. | Array of Enums | Required. (e.g., Monday-Sunday) |
| Access Time | The time on and after which the user has access to the system on allowed days. | Time | Required. |
| User Profile Effective From Date | Date on and after which the User Profile is effective. | Date | Required. |
| User Profile Effective End Date | Date on and before which the User Profile is effective. | Date | Required. |
| User Group | The selected group determining the functions the user can access. | String (User Group ID) | Required. |
| Report Access Right | Determines which report(s) the user has access to. | String (Report Group ID) | Optional. |
| User Status | Status of the user account. | Enum | Required. Values: Active, Blocked. |
#### User Permission (View Only)
*Displays all permissions applicable for the chosen user across top-level and second-level modules.*
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Module Name | The name of the module. | String | Read-only |
| Permissions | Available actions (View, Create, Edit, Delete, Copy, Approve, History, Template). | Boolean per action | Read-only |
## Post-Conditions
- When creating a new record, the user account is successfully created.
- The new user receives an email notification with login instructions and a temporary password.
- When the password is reset, an email notification is sent to the user's email with the new password.
## Exception Flow
- No specific exception flow defined.

50
docs/specs/oneadmin/framework_behavior.md
View File

@@ -1,50 +0,0 @@
---
title: "OneAdmin Framework Behavior"
type: OpenSpec
status: Draft
domain: OneAdmin
---
# OneAdmin Framework Behavior
## Requirement Definition
OneAdmin is the application framework upon which all OLS administration functions are built. It defines the standard behavior for data maintenance, record lifecycle states, search capabilities, and audit trailing across all modules (e.g., Campaign Management, Customer Management, Catalogue).
## Business Rules
### Maintenance Actions
The framework supports the following standard maintenance actions across modules:
- **Add**: Creates a new record in a Pending state.
- **Edit**: Modifies an existing record. The modifications are saved as a new version in a Pending state, leaving the original active record unchanged until approval.
- **Copy**: Duplicates an existing record, prompting the user to update unique key values.
- **Delete**: Marks a record for deletion (Inactive). The deletion request creates a Pending state version.
- **Approve**: Transitions a Pending record to Active state. The approving user must have appropriate approval rights and cannot be the user who submitted the change.
- **Reject**: Transitions a Pending record to a Rejected state for follow-up.
- **Save as Draft**: Temporarily saves the record without publishing it to a Pending state.
- **Save as Template**: Saves the record details to be reused as a template.
- **History**: Retrieves previous versions of a record.
### Record State Transitions
1. **Pending**: When a new record is added, edited, or deleted, the action results in a Pending state.
2. **Active**: Upon approval, a Pending record becomes Active. Only Active records are considered during transaction processing.
3. **Rejected**: If an approver rejects a Pending record, its state becomes Rejected.
4. **Inactive**: An approved deletion sets the record to Inactive, blocking it from further use.
### Search and Filtering Capabilities
- **Quick Search**: Keyword-based search applied to all character columns using a case-insensitive "Contains" operator.
- **Advanced Filter**: Allows compound criteria using AND logic. Supported operators vary by data type:
- **Character**: Equal, Not Equal, Empty, Not Empty, Contains, Not Contains, In, Not In.
- **Number**: Equal, Not Equal, Greater Than, Less Than, Greater Than Or Equal To, Less Than Or Equal To, Between.
- **Boolean**: Equal.
- **DateTime**: Equal, Not Equal, Greater Than Or Equal To, Less Than Or Equal To, Between.
### Audit Logging
Every record update or approval is logged. The following audit fields are maintained for all records:
- **Last Updated By**: User ID (or Batch ID) that last updated the record.
- **Last Updated Date**: Date and time of the last update.
- **Last Approved By**: User ID that last approved the record.
- **Last Approved Date**: Date and time of the last approval.
## Post-Conditions
- All updates are reflected in the database immediately upon approval.
- Concurrent edits and approvals are strictly logged and version-controlled.

44
docs/specs/onecatalogue/catalogue.md
View File

@@ -1,44 +0,0 @@
---
title: "Catalogue"
type: OpenSpec
status: Draft
domain: OneCatalogue
---
# Catalogue
## Requirement Definition
A Catalogue groups items for online redemptions (e.g., Cash-back rebates, frequent flyer miles, merchant vouchers). All items included in the Catalogue must be tagged with a specific Catalogue Code. The system supports multiple concurrent catalogues, each with its own Item Master records.
## Process Flow
### Pre-Conditions
- Users must have access rights to the "Catalogue" screen under the "OneCatalogue" module.
- Depending on access rights, users can view, add, edit, or approve catalogue records.
## Business Rules
- Each Catalogue operates within a Start / End date range.
- Items are only presented to customers if the current date falls within the Catalogue's effective date range.
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Catalogue Code | User-specified code identifying the catalogue. Used by front-end systems. | String (10) | Required. |
| Description | A description of this catalogue. | String (50) | Required. Default description if no specific language is chosen. |
| Effective From Date | Date from which the catalogue is effective. | Date | Required. |
| Effective To Date | Date until which the catalogue is effective. | Date | Required. |
| Icon | Icon of the catalogue. | Image | Optional. |
#### Content Configuration
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Language | Selected language for specific description setup. | String (Lookup) | Required. |
| Description | Description of the catalogue in the chosen language. | String (100) | Required. |
## Post-Conditions
- The Catalogue information is returned to the front-end during Item Enquiry responses for searching.
## Exception Flow
- None specified.

40
docs/specs/onecatalogue/category.md
View File

@@ -1,40 +0,0 @@
---
title: "Category"
type: OpenSpec
status: Draft
domain: OneCatalogue
---
# Category
## Requirement Definition
A Category is a logical group within a catalog that organizes items. Multiple Categories can be linked to form a hierarchy, which is utilized on the Member site.
## Process Flow
### Pre-Conditions
- Users must have access rights to the "Category" screen under the "OneCatalogue" module.
- Depending on access rights, users can view, add, edit, or approve category records.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Category Code | User-specified code identifying the category. | String (10) | Required. |
| Description | Default description of this category. | String (100) | Required. |
| Effective From Date | Date from which the category is effective. | Date | Optional. If empty, non-expiring. |
| Effective To Date | Date until which the category is effective. | Date | Optional. |
| Parent Category | Identifies the parent category to form a hierarchy. | String (Lookup) | Optional. |
| Display Ordering | Ordering sequence on the Member Site. | Integer | Optional. |
| Icon | Icon of the category. | Image | Optional. |
| Image Group | Selected image group. | String (Lookup) | Optional. |
| Image | Selected image from Image Stock. | String (Lookup) | Required if Image Group is selected. |
#### Content Configuration
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Language | Selected language for specific description setup. | String (Lookup) | Required. |
| Description | Description of the category in the chosen language. | String (100) | Required. |

65
docs/specs/onecatalogue/item_master.md
View File

@@ -1,65 +0,0 @@
---
title: "Item Master"
type: OpenSpec
status: Draft
domain: OneCatalogue
---
# Item Master
## Requirement Definition
Item Master defines details about a particular item, such as prices, quantities, availability dates, terms, and conditions.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Item Master" screen under the "OneCatalogue" module.
- Depending on access rights, users can view, add, edit, or approve Item Master records.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Catalogue Code | The Catalogue for which this item is configured. | String (Lookup) | Required. |
| Category | Category under which this item is tagged. | Array of Strings (Lookup) | Optional. |
| Item Code | Identifier for the item to be added. | String (10) | Required. |
| Item Name | Short description used by customer-facing application. | String (50) | Required. |
| Redemption From Date | Date from which the item is available for redemption. | Date | Required. Must fall within Catalogue/Category date range. |
| Redemption To Date | Date until which the item is available. | Date | Required. Must fall within Catalogue/Category date range. |
| Redemption Store | Supplier/merchant of this item. | String (Lookup) | Optional. |
| Redemption Transaction Code | OLS TC used for redemption processing. | String (Lookup) | Required. |
| Award Transaction Code | OLS TC used to locate award campaign rules upon redemption. | String (Lookup) | Optional. |
| Item Type | Type of item. | Enum | Required. Values: Miles, Physical, eVoucher, Donation, Cash rebate, Other. |
| Voucher Code | Selected voucher code. | String (Lookup) | Required if Item Type is eVoucher. |
| Face Value | Value of the cash rebate/voucher/miles that customer receives. | Decimal (14,2) | Required for Cash rebate/eVoucher/Miles. Must be positive. |
| Display on Member Site | Determines if the item is displayed on the member site. | Boolean | Default: True. |
| Hot Item | Indicates if this is a hot item. | Boolean | Active only if Display on Member Site is True. Default: False. |
| Display Ordering | Ordering sequence to display on member site. | Integer | Must be > 0. Active only if Display on Member Site is True. |
| Track Quantity on Hand | Enables inventory control. | Boolean | Default: False. Forced to True if item is a Voucher Code. |
| Initialize Quantity of Stocks | Initial stock quantity. | Integer | Required if Track Quantity on Hand is True. Read-only if item has been redeemed. |
#### Item Detail (Localization)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Language | Selected language. | String (Lookup) | Required. |
| Item Name | Specific item name in the chosen language. | String (50) | Required. |
| Item Description | Specific item description. | String (100) | Optional. |
| Item Content | Detailed content/information. | String (2000) | Optional. |
| How to use | Instructions on how to use the item. | String (2000) | Optional. |
| Term and Condition | Free text for Terms and Conditions. | String (2000) | Optional. |
#### Contact and Address Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| City | City where the item can be used. | String (Lookup) | Required. |
| Address | Detailed address. | String (200) | Optional. |
| Email | Contact email. | String (100) | Optional. |
| Phone | Contact phone number. | String (20) | Optional. |
## Post-Conditions
- The newly created item should have all required fields populated with valid data.
- System adds/updates items in the database.
- Other screens looking up the item screen can use the new item.

54
docs/specs/onecatalogue/item_price.md
View File

@@ -1,54 +0,0 @@
---
title: "Item Price"
type: OpenSpec
status: Draft
domain: OneCatalogue
---
# Item Price
## Requirement Definition
Item Price specifies the conversion rate between reward points and redemption quantity, defining pricing tiers based on account types, redemption channels, or specific criteria. It manages redemption options (points only vs. cash and points).
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Item Master" and "Item Price" screens under the "OneCatalogue" module.
- Depending on access rights, users can view, add, edit, or approve Item Price records.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Item Code | The item being configured. | String (Lookup) | Required. |
| Price Code | Identifier of the item price. | String (10) | Required. |
| Price Name | Default name of the price. | String (100) | Required. |
| Effective Start Date | Start date of the price validity. | Date | Required. |
| Effective End Date | End date of the price validity. | Date | Required. |
| Redemption Channel | Channel applicable for this price (e.g., Call Center, Mobile App). | String (Lookup) | Required. |
| Account Type Group | Account Type Group this price applies to. | Array of Strings (Lookup) | Optional. Mutually exclusive with Account Level/Type. |
| Product Account Level | Account Level this price applies to. | String (Lookup) | Optional. Mutually exclusive with Account Type Group. |
| Product Account Type | Account Type this price applies to. | Array of Strings (Lookup) | Optional. Mutually exclusive with Account Type Group. |
| Redemption Pool | Pool from which to deduct points. | String (Lookup) | Required. |
| Use Only Points from Selected PA Type | Restrict points usage to the selected Account Type/Group. | Boolean | Default: False. |
| Face Value | The value the customer receives upon redemption. | Decimal (12,2) | Must be > 0. |
| Price in Point | Price if paid fully in points. | Decimal (12,2) | Must be > 0. |
| Original Price | The original price of the item (for reference). | Decimal (12,2) | Must be > 0. |
| Partial Redemption Allowed | Allows a mix of points and cash for redemption. | Boolean | Default: False. |
| Minimum Partial Redeem Points | Minimum points customer must use for partial redemption. | Decimal (12,2) | Required if Partial Redemption is Allowed. Must be >= 0. |
| Cash per Point | Cash amount required to substitute one point during partial redemption. | Decimal (12,2) | Required if Partial Redemption is Allowed. Must be > 0. |
| Applicable Taxes | Tax rate applicable. | String (Lookup) | Optional. |
#### Price Detail (Localization)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Language | Selected language. | String (Lookup) | Required. |
| Item Price Name | Specific name of chosen language. | String (100) | Required. |
| Description | Description of the price. | String (500) | Optional. |
#### Item Criteria
- Utilizes the Query Builder logic. Criteria groups can be combined using logical OR/AND operators.
- Applicable criteria are tagged specifically for the "Item Price" module.

58
docs/specs/onecatalogue/voucher_code.md
View File

@@ -1,58 +0,0 @@
---
title: "Voucher Code"
type: OpenSpec
status: Draft
domain: OneCatalogue
---
# Voucher Code
## Requirement Definition
Voucher Codes manage external partner vouchers distributed to customers. Vouchers are imported or generated with specific codes, valid periods, and serial numbers.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Voucher Management" screen under the "OneCatalogue" module.
- Depending on access rights, users can view, add, edit, or approve Voucher records.
## Business Rules
- Voucher codes cannot be deleted if any associated voucher serial number has been redeemed.
### Data Schema
#### Voucher Statistic (View Only)
| Field Name | Description | Logic Type |
|---|---|---|
| Total Voucher | Total serial numbers under this voucher code. | Integer |
| Available Vouchers | Total valid, non-expired, ready-to-use vouchers. | Integer |
| Redeemed Vouchers | Total successfully redeemed vouchers. | Integer |
| Cancelled Vouchers | Total failed redemptions canceled by customers/system. | Integer |
| Expired Vouchers | Total expired vouchers not redeemed. | Integer |
#### Voucher Code Detail
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Voucher Code | Identifier of the voucher. | String (10) | Required. |
| Description | Description of the voucher. | String (100) | Optional. |
| Supplier | Partner issuing the voucher. | String (Lookup) | Optional. |
| Expiry Policy | Determines how the voucher expires. | Enum | Required. Values: Fixed Date, N days from Transaction Date, N days from Post Date, N Months from Transaction Date, N months from Post Date. |
| Expiry Date | The absolute expiry date. | Date | Required if Expiry Policy is "Fixed Date". |
| N Param | Parameter N for relative expiry policies. | Integer | Required if Expiry Policy requires N parameter. Must be >= 0. |
| Generate Voucher | Indicates if OLS generates the voucher (instead of partner upload). | Boolean | Default: False. Read-only if voucher is redeemed. |
| Quantity | Number of voucher codes to generate. | Integer | Required if Generate Voucher is True. Read-only if voucher is redeemed. |
| This is a promo code | Indicates if this is a promo code. | Boolean | Default: False. |
| Promotion Type | Type of discount. | Enum | Required if This is a promo code is True. Values: Fixed Percentage Discount, Fixed Monetary Value Discount, Cashback Voucher, Gift Voucher. |
| Value | The specific value of the discount. | Decimal (14,2) | Required if Promotion Type is Fixed Monetary Value or Fixed Percentage. Must be > 0. |
#### Voucher Detail (View Only)
*Displays specific serial numbers assigned to the Voucher Code.*
| Field Name | Description | Logic Type |
|---|---|---|
| Voucher Code | The associated voucher code. | String |
| Voucher No | The serial voucher number. | String |
| Redemption Date | Date when voucher is redeemed. | Date |
| Expiry Date | Expiry date of the serial number. | Date |
| Redemption Indicator | Yes or No. | Boolean |
| Fulfillment Status | New, Issued, Fulfilled, Cancelled, Rejected. | Enum |

51
docs/specs/onemarketing/ab_testing.md
View File

@@ -1,51 +0,0 @@
---
title: "A/Bn Testing"
type: OpenSpec
status: Draft
domain: OneMarketing
---
# A/Bn Testing
## Requirement Definition
Evaluates and optimizes marketing elements (content or target customers) to identify better performing campaigns. Supports A/Bn Content testing (same target, different messages) and A/Bn Target Customer testing (same message, different targets).
## Process Flow
### Pre-Conditions
- Third-party data/results must be available for OLS to collect and analyze.
- Users must have access rights in the "A/Bn Testing" module.
## Business Rules
### Data Schema (A/Bn Message Content Testing)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Campaign ID | Unique identifier. | String (20) | Required. No special characters. |
| Campaign Description | Description. | String (100) | Optional. |
| Effective Date From | Start date. | Date | Optional. |
| Effective End date | End date. | Date | Required. |
| Message Channel | SMS, Email, Push. | Enum | Required. |
| Target Customer | OMR Criteria setup for targeting. | Rule | Required. |
| Variant Content | Multiple variants (A, B, N) defining content based on channel. | Array of Messages | Required. Must be unique within the campaign. |
| Run Schedule | Schedule parameters. | Complex | Required. |
### Data Schema (A/Bn Target Customer Testing)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Campaign ID | Unique identifier. | String (20) | Required. No special characters. |
| Campaign Description | Description. | String (100) | Optional. |
| Effective Date From | Start date. | Date | Optional. |
| Effective End date | End date. | Date | Required. |
| Variant Target Customer | Multiple variants (A, B, N) defining OMR Criteria. | Array of Rules | Required. Must be unique within the campaign. |
| Run Schedule | Schedule parameters. | Complex | Required. |
### Execution
- ABn batch job triggers effective testing requests based on schedule.
- For content testing, sends variant messages to the same subset of targets. Tracks open rates, click-through rates.
- For target testing, evaluates which criteria setup reaches the most/best customers.
## Post-Conditions
- Results are reported back to the user to make data-driven decisions on campaign rollout.

36
docs/specs/onemarketing/blacklist.md
View File

@@ -1,36 +0,0 @@
---
title: "Blacklist"
type: OpenSpec
status: Draft
domain: OneMarketing
---
# Blacklist
## Requirement Definition
A list of customers excluded from marketing campaigns for strategic reasons (e.g., fraud).
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Black List" module.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| ID | Blacklist identifier. | String (10) | Required. |
| Name List | Name of the blacklist. | String (50) | Required. |
| Description | Description. | String (200) | Optional. |
| Input Type | Input from screen or Upload file. | Enum | Required. |
| Customer List | List of selected CIF numbers. | Array of Strings (Lookup) | Required if Input Type is "Input from screen". Requires >= 4 digits to search. |
| Upload File | Uploaded CSV/XLS file. | File | Required if Input Type is "Upload file". Max 50MB. |
### Execution
- Users can review or download the customer list.
- Blacklisted customers are strictly blocked from receiving notifications from OMR.
## Exception Flow
- Validation errors for file type/size during upload display an error message.

42
docs/specs/onemarketing/frequency_capping.md
View File

@@ -1,42 +0,0 @@
---
title: "Marketing Frequency Cap"
type: OpenSpec
status: Draft
domain: OneMarketing
---
# Marketing Frequency Cap
## Requirement Definition
Controls the frequency and volume of notifications delivered to customers to prevent overwhelming them. Caps can be set daily, weekly, or monthly per customer across different channels.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Frequency Capping" module.
## Business Rules
### Data Schema
#### Edit Mode Configuration
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Frequency Cap Id | Record identifier. | String (10) | Required. |
| Notification Channel | SMS, Email, or Push Notifications. | Enum | Required. |
| Effective Date From | Start date of the cap. | Date | Required. Only one effective cap per channel at any given time. |
| Effective Date To | End date of the cap. | Date | Required. |
| Capping Period | Daily, Weekly, or Monthly. | Enum | Required. Each period must have only one cap value. |
| Maximum number | Max messages per unique customer. | Integer (12) | Required. |
| Include Whitelist | Disallows/allows whitelist customers to receive more notifications. | Boolean | Default: False. |
| Customer list | Selected whitelist customers to ignore rules. | Array of Strings (Lookup) | Required if Include Whitelist is True. |
| Description | Description of the capping. | String (100) | Optional. |
### Execution
- Frequency Capping is applied to all marketing campaigns at the customer level.
- System automatically tracks notification counts per customer per channel and period unit.
- If the customer reaches the cap, further notifications are blocked.
- Whitelisted customers are excluded from the frequency cap unless explicitly included.
## Post-Conditions
- System enforces defined limits during OMR batch processing.

62
docs/specs/onemarketing/marketing_campaign.md
View File

@@ -1,62 +0,0 @@
---
title: "Marketing Campaign (OneMarketing Request)"
type: OpenSpec
status: Draft
domain: OneMarketing
---
# Marketing Campaign (OneMarketing Request)
## Requirement Definition
Filters target customers that satisfy specific marketing criteria. Triggers either notification messages or reward campaigns (via OLS Transaction Code) for the target customers.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Marketing Request" module.
- Depending on rights, users can view, add, edit, or approve requests.
- All OMR criteria must be defined as attributes.
## Business Rules
### OMR Criteria Logic
- Uses Query Builder for marketing criteria.
- Criteria can be dragged/dropped from the right panel.
- Supports AND/OR conditions between criteria groups.
- Introduces NOT toggle for exclusion criteria.
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Request ID | Unique identifier. | String (20) | Required. No special characters. |
| Description | Description. | String (100) | Required. |
| Effective Date From | Start date. | Date | Required. |
| Effective Date To | End date. | Date | Required. |
| Marketing Function | Notification [N] or Trigger Campaign Rule [TCR]. | Enum | Required. |
#### Run Schedule and Message Content
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Trigger Method | Schedule or Event trigger. | Enum | Required. |
| Run Schedule | Once Time [O], Daily [D], Weekly [W], Monthly [M], Annually [A]. | Enum | Required if Trigger Method is Schedule. |
| Schedule Details | Specific details (e.g., Repeat every, Fixed Date, Time of day). | Complex | Required based on Run Schedule. |
| Business Event | Specific event triggering the request. | Array of Strings (Lookup) | Required if Trigger Method is Event trigger. |
| Message Template | The marketing message to send. | String (Lookup) | Required if Marketing Function is Notification. |
| OLS Transaction Code | TC used to trigger campaign rule. | String (Lookup) | Required if Marketing Function is Trigger Campaign Rule. |
#### Targeting
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Trigger Method | OMR Criteria or Upload file. | Enum | Required. |
| Targeting Data | The selected OMR criteria setup or the uploaded file. | Rule / File | Required based on Trigger Method. |
### Batch Job Processing
- OMR job checks effective requests based on processing date.
- Finds valid jobs based on schedule.
- Creates notifications or extracts transactions based on criteria.
- Stops sending when frequency capping limits are reached.
## Post-Conditions
- Marketing content is sent to target customers, or target customers trigger a Campaign Rule.

69
docs/specs/onemarketing/marketing_message.md
View File

@@ -1,69 +0,0 @@
---
title: "Marketing Message"
type: OpenSpec
status: Draft
domain: OneMarketing
---
# Marketing Message
## Requirement Definition
Manages (CRUD) all message templates used in the system. A Message Template can be built for different channels (SMS, Push Notification, Email). The message can be based on pre-defined parameters or HTML files.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Marketing Message" module.
- Depending on rights, users can view, add, edit, or approve message templates manually.
- OMR criteria must be defined as attributes available in the right panel for drag-and-drop setup.
## Business Rules
### Data Schema (SMS Message)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Message ID | Unique identifier. | String (10) | Required. No special characters. |
| Message Description | Description. | String (100) | Required. |
| SMS Type | Promotion/Marketing or Transaction. | String (Lookup) | Required. |
| Effective Date From | Start date of the effective period. | Date | Required. |
| Effective End Date | End date of the effective period. | Date | Required. |
| SMS Brand Name | Select SMS Sender. | String (Lookup) | Required. |
| Message | Message content. Supports drag/drop parameters. | String (5000) | Required. Unicode (non-GSM). No images, subject, or attachments. |
### Data Schema (Email Message)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Message ID | Unique identifier. | String (10) | Required. No special characters. |
| Message Description | Description. | String (100) | Required. |
| Email Type | Promotion/Marketing or Transaction. | String (Lookup) | Required. |
| Effective Date From | Start date of the effective period. | Date | Required. |
| Effective End Date | End date of the effective period. | Date | Required. |
| Use Type | Use Message or Upload Template. | Enum | Required. |
| Sender Name | Name of sender. | String (100) | Required. |
| From Email | Configured email address. | String (100) | Required. |
| Subject | Subject of email. | String (100) | Required. |
| Preview Text | Preheader of Email. | String (100) | Optional. Defaults to first line of content if not provided. |
| Message / Upload File | HTML content or uploaded template file. | String / File | Required based on Use Type. |
### Data Schema (Push Notification)
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Message ID | Unique identifier. | String (10) | Required. No special characters. |
| Message Description | Description. | String (100) | Required. |
| Notification Type | Promotion/Marketing or Transaction. | String (Lookup) | Required. |
| Effective Date From | Start date of the effective period. | Date | Required. |
| Effective End Date | End date of the effective period. | Date | Required. |
| Message Title | Primary text at the top. | String (50) | Required. |
| Message | Main content. Supports drag/drop parameters. | String | Required. |
| Image Type | Single (No image), Richer (1 image), Carousel (>1 images). | Enum | Required. |
| Upload Image | Images for Richer or Carousel push. | Image / URL | Required if Image Type is not Single. |
| Link URL | URL to navigate to. | String (100) | Required. |
### Testing Message
- A "Send sample" function exists for all channel types to test the message rendering using a sample phone number, email, or CIF number.
## Post-Conditions
- All configured messages are available for use in Marketing Request, Campaign Rule, and Item Master.

36
docs/specs/onemarketing/whitelist.md
View File

@@ -1,36 +0,0 @@
---
title: "Whitelist"
type: OpenSpec
status: Draft
domain: OneMarketing
---
# Whitelist
## Requirement Definition
A list of customers who have given consent or shown strong interest and are excluded from standard frequency cap rules, ensuring they receive all communications without limit.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Whitelist" module.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| ID | Whitelist identifier. | String (10) | Required. |
| Name List | Name of the whitelist. | String (50) | Required. |
| Description | Description. | String (200) | Optional. |
| Input Type | Input from screen or Upload file. | Enum | Required. |
| Customer List | List of selected CIF numbers. | Array of Strings (Lookup) | Required if Input Type is "Input from screen". Requires >= 4 digits to search. |
| Upload File | Uploaded CSV/XLS file. | File | Required if Input Type is "Upload file". Max 50MB. |
### Execution
- Users can review or download the customer list.
- Whitelisted customers bypass frequency capping restrictions by default, unless a specific frequency cap explicitly opts to "Include Whitelist".
## Exception Flow
- Validation errors for file type/size during upload display an error message.

32
docs/specs/onetargeting/audience_upload.md
View File

@@ -1,32 +0,0 @@
---
title: "Audience Upload"
type: OpenSpec
status: Draft
domain: OneTargeting
---
# Audience Upload
## Requirement Definition
Provides a module for marketers to manage audience uploads, enabling them to upload customer data for targeted marketing campaigns via file uploads.
## Process Flow
### Pre-Conditions
- Users must have access rights in the "Audience Upload" module.
- Depending on access rights, users can view, add, edit, or manually approve.
## Business Rules
- Users can upload customer data for targeted marketing campaigns via file upload (CSV, Excel spreadsheets).
- The system allows users to map data from source files to required platform fields.
- The system validates the uploaded data to ensure all required fields are present and in the correct format.
### Data Schema
| Field Name | Description | Data Type | Constraints / Rules |
|---|---|---|---|
| Audience Name | The name of the audience | String (50) | Required. Must be unique in the system. |
| Description | Audience description | String (200) | Optional. |
| File ID | Audience identifier | String (10) | Required. Internal system reference. |
| File Size | The file size of the upload | Numeric | System generated. |
| Upload File | The uploaded file data | File/Binary | Required. Allowed extensions: CSV, XLS, XLSX. Max size: <= 50 MB. |

14
docs/specs/onetargeting/customer_audience.md
View File

@@ -1,14 +0,0 @@
---
title: "Customer Audience"
type: OpenSpec
status: Draft
domain: OneTargeting
---
# Customer Audience
## Requirement Definition
No requirements defined yet.
## Business Rules
No business rules defined yet.

64
docs/specs/onetargeting/segmentation.md
View File

@@ -1,64 +0,0 @@
---
title: "Segmentation"
type: OpenSpec
status: Draft
domain: OneTargeting
---
# Segmentation
## Requirement Definition
Segmentation is a process to divide a customer base into smaller groups, providing a way to narrow down the target audience based on the types of products or services the customers have previously purchased. This allows businesses to create more personalized and effective marketing strategies for each segment, rather than adopting a one-size-fits-all approach.
In the system, a segment is a combination of one or more criteria. The same criteria set may be reused multiple times, allowing an efficient way to set up targeted customers.
## Process Flow
### Trigger
- User accesses the OneTargeting Module to create or update a new segment.
### Pre-Conditions
- Users must have access rights in the Segmentation module.
- Depending on access rights, users can view, add, edit, or manually approve.
- All criteria are defined as attributes and are available for setup.
## Business Rules
- The OLS system uses Query Builder to build queries for segmentation.
- Business segments target customers using the following criteria combinations:
### Criteria Matrix
| Segment Group | Criteria Group | Combination by Following Criteria | Segment Example |
|---|---|---|---|
| Demographic Segmentation | Customer Profile | Age | Life Cycle segment: Children (0-14), Youth (15-24), Adults (24-64), Seniors (65+) |
| Demographic Segmentation | Customer Profile | Last Name | |
| Demographic Segmentation | Customer Profile | First Name | |
| Demographic Segmentation | Customer Profile | Income | Income segment: High-Income, Middle-Income, Low-Income |
| Demographic Segmentation | Customer Profile | Gender | Male, Female |
| Demographic Segmentation | Customer Profile | Marital Status | Single, Married |
| Demographic Segmentation | Customer Profile | DOB | Generation segment: Gen Z (1997-2012), Gen Y (1981-1996), Gen X (1965-1980), Gen W (1946-1964) |
| Demographic Segmentation | Customer Profile | Location (Country/State/City/Zip Code) | Geography segment: International, Urban, Suburban, Mountain |
| Demographic Segmentation | Customer Profile | Customer's Tenure | Customer Tenure Segment (based on Registration): New (<1 yr), Early-tenured (1-2 yrs), Mid-Tenured (2-5 yrs), Long-tenured (>5 yrs) |
| Demographic Segmentation | Customer Profile | Account's Tenure | Account Tenure Segment (based on AOD): New (<1 yr), Early-tenured (1-2 yrs), Mid-Tenured (2-5 yrs), Long-tenured (>5 yrs) |
| Demographic Segmentation | Customer Profile | Account's Status | |
| Demographic Segmentation | Customer Profile | Next AOD | |
| Demographic Segmentation | Customer Profile | Customer's status | |
| Behavior Segmentation | Transaction | Last transaction / Integration | Churned customer: Last transaction > 6 months ago and status is active |
| Behavior Segmentation | Transaction | Transaction Frequency | Total number of transactions or Average transaction frequency in a specific period (day/week/month/quarter/year). Segment: High-Value, Medium-Value, Low-Value |
| Behavior Segmentation | Transaction | Customer Recency | When was the last transaction/integration |
| Behavior Segmentation | Transaction | Total spending value | Total net transaction amount |
| Behavior Segmentation | Transaction | Transaction Date | Peak-Time customer (special day, weekend, midnight). Consistent-Time Customers (first day of month). Flexible-Time Customers (specific day) |
| Behavior Segmentation | Transaction | Transaction Time | |
| Behavior Segmentation | Transaction | Merchant (Corporation/Chain/Store/MCC) | Used with another criteria or alone to create specific segments |
| Behavior Segmentation | Transaction | Merchant Group | |
| Behavior Segmentation | Transaction | Transaction Description | |
| Behavior Segmentation | Transaction | Transaction Category | |
| Behavior Segmentation | Transaction | Transaction Gross Amount | |
| Behavior Segmentation | Transaction | Transaction Nett Amount | |
| Flexible Segment | Attribute | Attribute Criteria | |
| Psychographic Segmentation | Item | Favorite Category | Life Style segment, Interest segment, Opinion segment |
| Psychographic Segmentation | Item | Favorite Item | |
Note: Psychographic segmentation data will be collected from surveys upon OneDisplay implementation.
## Post-Conditions
- Each segment is used to define the targeting customer in the marketing module.

46
docs/specs/reference/change_history.md
View File

@@ -1,46 +0,0 @@
---
title: "Change History"
type: OpenSpec
status: Draft
domain: Reference
---
# Change History
| Version | Date | Updated By | Change Description |
|---|---|---|---|
| 1.0 | 14/12/2023 | Trangdth, Maivt | The first version including: Customer Management, Campaign Management, Draft OMR module |
| 1.1 | 18/12/2023 | Trangdth | Customer 360: Add more detail for Account/Card information.<br>Section 5.1: Add filter, Add/update some fields in the screen.<br>Section 5.5 Card: Update description and logical.<br>Section 5.9 and 5.10: Update label |
| 1.2 | 20/12/2023 | Trangdth | Update the Pool Conversion Rate module.<br>Update data type DD/MM/YYYY into "Date" to respect the date time configuration format.<br>Update the Card logically: Add more detail when updating the card.<br>Update customer Management module section 5: an update based on Sang's requirement (Customer/Account/dashboard/transaction history/attribute/counter).<br>Update Vietnamese fields and some cosmetic issues |
| 1.3 | 27/12/2023 | Trangdth | Update customer block data type from X(20) into X(10).<br>Section 5.4 update the card activation date from mandatory to optional.<br>Section 5.2.6: Update the logic of most items.<br>Section 4.7- Pool Conversion Rate: update field name and logic for pool conversion rate.<br>Section 4.12 Campaign Rule Criteria: Correction some typos and add more detail for txncat criteria.<br>Pool Definition: remove the item code field (move to Rule setup). Add some validations(red line).<br>Add CEP rule type |
| 1.4 | 02/01/2024 | Trangdth | Add REP Rule.<br>Update Pool Definition Screen: screen and logical.<br>Update Counter Defintion to match with PMS and add more detail. |
| 1.5 | 10/01/2024 | Trangdth | Update API information for REP rule.<br>Update API information for CEP Rule.<br>Add document for Formula (UI+ Logical) |
| 1.6 | 16/01/2024 | Trangdth | Add Section 5.15 Awward Transaction Entry Screen.<br>Update Section 4.8 Counter Definition: Add Late txn posting option. Update logical on post-condition.<br>Update Pool Defintion: add more detail for ATG field.<br>CEP/REP: Update API for run schedule |
| 1.7 | 24/01/2024 | Trangdth | Counter definition: Update: Active "First start date is fixed" for "Days from COD" period unit.<br>Pool conversion rate: Update code from X(03) into X(05).<br>Card - Update data type and logic for Old Card number. Update the relationship of Account type and Account number.<br>Add Campaign : Add description for CP module |
| 1.8 | 25/01/2024 | Trangdth | Add section 4.12 Campaign Rule logical for Award/redem/Adjust rule type.<br>Add section 4.9 Transaction Category module |
| 1.9 | 30/01/2024 | Trangdth | Campaign: change data type and add alidation for Campaign type.<br>CEP: Update data type for Run schedule and change the sequence order in Layout.<br>REP: Update data type for Run schedule and change the sequence order in Layout |
| 1.10 | 19/02/2024 | Trangdth | Section 4.17 : CEP : Update API information of following fields: - Account with blocked Card - Post Transactions under PA Account selected based on |
| 1.11 | 21/02/2024 | Trangdth | Section 4.12.6 : Campaign Rule/Business Rule : Update validation of "Apply after Cap value " field |
| 1.12 | 05/03/2024 | Trangdth | Correction typo.<br>Section 4.13: Rule criteria: Update more detail and req.<br>Section 5.11 Adjustment : Add field and update logical of quick view |
| 1.13 | 07/03/2024 | Trangdth | Correction typo.<br>Section 5.11 Adjustment: Update Vietnamese label and correction logical.<br>Section 5.12 Transfer Balance: Add fields, Update logical, Add User Stories and Accepted Criterions.<br>Section 5.13 Re-instatement : Add fields, Update logical , Add User Stories and Accepted Criterions |
| 1.14 | 11/03/2024 | Trangdth | 5.2.6.3: Account/Card information: Update logical and data entities.<br>5.11 Adjust: Add US and AC.<br>5.12 Award Transaction: Add fields, Update logical , Add User Stories and Accepted Criterions.<br>5.5 Pool Balance Detail: Correction and Add User Stories and Accepted Criterions |
| 1.15 | 12/03/2024 | Trangdth | Section 4.15 contributor setting: Update data type of "Contributor Percentage" field.<br>Section 4.14 Campaign Rule formula: Remove validation of F5/Multiplier |
| 1.16 | 20/03/2024 | Trangdth | Section 7: Added OneCatelogue module, including: Item master/ Catalogue/Category/Voucher management.<br>Section 4.12 Campaign Rule: Added Post-condition for Amount to Use feature (Transaction Processing with Amount to use).<br>Secttion 4.6 Pool Definition: Remove CP Rule name and change data for "List Of Campaign" listing page. |
| 1.17 | 25/03/2024 | Trangdth | Add section 7.5: Item Price.<br>Update section 5.14 Item redemption to match onecatalogue logical.<br>Update quick view of Adjust/transfer balance/Re-instatement/Award. Take note that I just remove redundant information and update the description to be more clearly. The logical is not changed. |
| 1.18 | 03/04/2024 | Trangdth | Added section 2 (2.1/ 2.2/2.3/2.4) OneAccess module, including Overview, User Group, Permission Management and User Profile.<br>4.6 Pool Definition: Correction typo.<br>4.13 Rule Criteria: Correct index of operator on each data type.<br>4.14 Campaign Formula : Update Formula logical on TP sides |
| 1.19 | 12/04/2024 | Trangdth | Correction typo.<br>Section 4.13 Rule Criteria: Update logical of String data type (TP sides only) |
| 1.20 | 15/04/2024 | Trangdth | Section 5.6 Transaction History: Update sketch, Update US and AC, update Business rule.<br>Section 5.11 Adjustment: Update sketch. Update US and AC, update business rule.<br>Section 5.15 Award : Update US and AC |
| 1.21 | 16/04/2024 | Trangdth | Section 4.18 Added Item Redemption Rule Type |
| 1.22 | 19/04/2024 | Trangdth | Section 7: OneCatalogue: Typ0 correction and update section 7.6 Voucher Code module.<br>Section 4.12.7 CP rule : Add Award limit use case in FSD |
| 1.23 | 26/04/2024 | Trangdth | Section 5.6 Transaction History: Added "Pool Unit Amount" on Award quick view.<br>Section 5.15 Item Redemption: update business req/ Flow and post condition.<br>Section 7.5 Item Price Update flow/ post condition / add effective date |
| 1.24 | 02/05/2024 | Trangdth | Section 4.6 Pool Definition : Add validation for Card entity level field.<br>Section 4.13 Campaign Rule Criteria : Correction description of filter value of Number data type.<br>Section 5.14 Item Redemption : Correction Wireframe and update business rule.<br>Section 7.3 Item master: Add Face value and correction typo |
| 1.25 | 06/05/2024 | Trangdth | Addded description to clear "Balance detail" quick view of Award and Adjustment Transaction Screen.<br>Section 5.14 Item redemption : Added User Stories and Acceptance criteria |
| 1.26 | 09/05/2024 | Trangdth | Section 4.13 Campaign Rule Criteria: Update String data type: Use Input tag instead of delimiter in case there are many filter value if input type as "value" |
| 1.27 | 20/05/2024 | Trangdth | Section 4.13 Campaign Rule Criteria: Add more description for Date Data type.<br>Section 4.12 Campaign Rule: Add new fields/validation to handle Evoucher Pool and Adjust Rule Type. |
| 1.28 | 24/05/2024 | Trangdth | Section 4.6: Pool Definition: Add validation for Precision of Pool.<br>Section 7.6: Voucher code: Change field name from Voucher type into Promotion Type.<br>Section OneAdmin Overview: Update and correction section 3.1/3.2/3.3.<br>Section 7.5 Item price: Add item code to avoid confuse.<br>Customer Profile: Add "Address Type: field.<br>Section 5.6 Item redemption Entry: Remove redudant field and add validation |
| 1.29 | 30/05/2024 | Trangdth | Counter Definition: Add validation for "Bucket period Unit".<br>Campaign rule: Remove API of master data filed Remove Voucher code Add item code |
| 1.30 | 17/06/2024 | Trangdth | Section 5.9/5.10: Attribute/Counter: Correction and update more detail.<br>Section 5.6: Transaction History: Remove Deleted field, correction typo and update detail for quick view.<br>Section 5.11/5.12: Adjustment /Transfer balance: Correction process flow and business.<br>Section 5.15: Award transaction: Update process flow on TP side.<br>Other section: Update and correct to match with the system |
| 1.31 | 19/06/2024 | Trangdth | All sections: Add more description for number field if needed |
| 1.32 | 24/06/2024 | Trangdth | Campaign formula /Business rule : Update validation for "Amount " field (F4/F6).<br>Section 5.2.6.2: Customer's rewards statistic : Remove total spending, Update logical for Points/Cash back |
| 1.33 | 12/07/2024 | Trangdth | Add section 3: Oneadmin: Overview about the OLS system : Search/Filter/Add/View/Edit/Approve/History.<br>Add Section 4: Application Parameter.<br>Update section 6.2.6: Customer 360=>Business Rule: Correct typo. Add more detail for pool balance information and most redeemed item |
| 1.34 | 11/11/2024 | Trangdth | Correction typos |

15
docs/specs/reference/document_references.md
View File

@@ -1,15 +0,0 @@
---
title: "Document References"
type: OpenSpec
status: Draft
domain: Reference
---
# Document References
| Ref# | Description / File Name |
|---|---|
| R01 | |
| R02 | |
| R03 | |
| R04 | |

42
docs/specs/reward_campaign/account_type_group.md
View File

@@ -1,42 +0,0 @@
---
title: "Account Type Group"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Account Type Group (ATG)
## Requirement Definition
Groups Account Types (Product Account Level + Type) and orders them in priority sequence. ATGs are assigned to Reward Pools to restrict which accounts can earn into the pool, and to define the priority sequence for deducting points during redemptions at Customer-level pools.
## Process Flow
### Pre-Conditions
- Users must have access rights.
- Account Types must exist in OLS.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Account Type Group Id | Identifier. | String (10) | Required. Unique. |
| Description | Description. | String (100) | Required. |
#### Account Type Sequence
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Product Account Level | PAL. | Enum (Lookup) | Required. |
| Product Account Type | PAT. | Enum (Lookup) | Required. |
| Sequence No | Priority sequence (lowest is highest priority). | Integer | Required. |
### Execution
- **Redemption Priority**: When redeeming from a Customer pool, buckets with the same expiry date are deducted in ascending order of the Account Type's Sequence No in the pool's ATG. Account types NOT in the ATG have highest priority.
- **Posting Priority**: If a transaction arrives with only a CIF Number (no Account Number), the system uses the ATG to find eligible accounts for that CIF. If multiple exist, the one with the lowest Sequence No in the ATG is selected for the transaction.
- **Validation**: Incoming transactions must map to an Account Type that is within the Pool's ATG. If the intersection of Customer's Accounts and the Pool's ATG is null, the transaction is rejected.
## Exception Flow
- TP validation failures reject the transaction.

38
docs/specs/reward_campaign/campaign_insight.md
View File

@@ -1,38 +0,0 @@
---
title: "Campaign Insight"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Campaign Insight
## Requirement Definition
Combines data from across multiple data sources into charts to track and display customer and campaign activities, providing a high-level performance overview.
## Process Flow
### Pre-Conditions
- Users must have access rights to the Campaign Insight module.
## Business Rules
### Data Schema
#### Key Metrics Displayed
- Total Redeemed Points.
- Total Members (Active vs Inactive).
- Total Partners.
- Total Active Reward Campaigns.
#### Charts & Visualizations
- **Campaign Performance**: Displays the Top N Campaigns by awarded points, comparing "Target Avg Transaction Value" vs actual awards.
- **Top Channels**: Breakdown of transactions by entry channel (e.g., EDC, Web, Call Center).
- **Points Awarded vs Redeemed**: Time-series comparison of point inflows vs outflows over a period.
### Execution
- **View-only dashboard.**
- Real-time or near-real-time aggregation depending on batch job configuration for analytics.
## Exception Flow
- N/A

35
docs/specs/reward_campaign/campaign_rule_contributor.md
View File

@@ -1,35 +0,0 @@
---
title: "Campaign Rule - Contributor Settings"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Campaign Rule - Contributor Settings
## Requirement Definition
Configures funding contributors for a reward. If a reward is funded by entities other than the transacting merchant (or split between them), Contributors define the split percentage.
## Process Flow
### Pre-Conditions
- Rule must be created.
- Contributing merchants (Chains) must exist in OLS.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Contributor | The Chain funding the reward. | Enum (Lookup) | Required. Unique per rule. |
| Contributor Percentage | Percentage of cost to fund. | Decimal | Required. > 0. |
| Absorb Remainder | Absorbs rounding remainders. | Boolean | Required. Exactly one must be true. |
### Execution
- Total contribution must equal 100%.
- Transaction processing splits the awarded value across Contributors based on percentages.
- If no contributors are configured, the transacting Merchant (Chain) absorbs 100% of the cost.
## Exception Flow
- Validation failures block saving.

40
docs/specs/reward_campaign/campaign_rule_criteria.md
View File

@@ -1,40 +0,0 @@
---
title: "Campaign Rule Criteria"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Campaign Rule Criteria
## Requirement Definition
Defines the conditions a transaction must meet to trigger a Campaign Rule. Built using a drag-and-drop Query Builder interface.
## Process Flow
### Pre-Conditions
- Rule must be created.
## Business Rules
### Data Schema
Criteria are categorized into: Customer, Account, Transaction, Attribute, Counter, Merchant.
#### Operators
| Data Type | Operators | Logic Type / Details |
|---|---|---|
| String / Lookup | Is in, Is not in, Contains, Equal to, Not equal to, Starts with, Ends with, Is null, Is not null. | Validates against provided text or list of values. |
| Number | Equal, Not equal, Less than, Less/equal, Greater, Greater/equal, Between, Null, Not null. | Standard numerical comparison. |
| Date | On or before, On or after, Fixed date, Between date range, Between period from N. | Complex date logic (e.g. comparing Day/Month regardless of year, comparing "3 months ago"). |
| Day of week | Is the day of week. | Monday-Sunday. |
| Time | Is between. | Time-of-day comparison (00:00 - 23:59). |
| Boolean | Is. | True / False. |
### Execution
- Supports AND and OR logic grouping.
- A single rule can have multiple groups, but inter-group logic must be consistent (all ANDs or all ORs).
- NOT toggles support exclusion.
- All criteria defined in the rule must evaluate to true (for AND) or at least one (for OR) to trigger the Formula execution.
## Exception Flow
- Validation failure means the rule is not triggered (proceeds to next rule in Execution Sequence).

27
docs/specs/reward_campaign/campaign_rule_formula.md
View File

@@ -1,27 +0,0 @@
---
title: "Campaign Rule Formula"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Campaign Rule Formula
## Requirement Definition
Configures the mathematical formula used to calculate the reward, redemption value, or counter increment for a given Rule.
## Process Flow
### Pre-Conditions
- Rule must be created.
## Business Rules
### Execution
- Formulas act on the "Amount to Use (A)" defined in the Rule Header.
- Support mathematical operations (e.g., A * 0.05, A + 10).
- Formulas can be assigned to different tiers based on criteria.
- Formulas can be used to update Pool Balances, or simply update a Counter / Attribute without impacting a Pool.
## Exception Flow
- N/A

40
docs/specs/reward_campaign/campaign_structure.md
View File

@@ -1,40 +0,0 @@
---
title: "Campaign Structure"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Campaign Structure
## Requirement Definition
Defines the conceptual structure and mechanics of how reward campaigns operate in OLS, managing the issuance and redemption of various reward types (Points, Cash Rebates, eCoupons, Lucky Draw chances).
## Process Flow
### Pre-Conditions
- N/A (Core concepts)
## Business Rules
### Types of Campaign Mechanics
1. **Award on Every Transaction**: Rewards are determined and given at the time the transaction is processed (real-time or batch).
2. **Accumulate Then Award**: Rewards depend on cumulative criteria (e.g., total spend over a month). Transactions update Counters, and at the end of the period, a separate process extracts the Counter value to determine the award.
3. **Auto-redemption Campaigns**: Awarded quantities (e.g., Cash Rebates) are immediately "redeemed" and sent to an external system (like a Core Banking system) to credit the customer's account.
### Reward Pool Structure & Deduction
- Earnings are tracked in "Pools" by reward type.
- Pools belong to Loyalty Accounts (or specific Accounts/Cards).
- Stored value is tracked in Buckets segregated by Expiry Date and Account Type.
- **Redemption Sequence**:
- Deducted in ascending Expiry Date (earliest expiring first).
- If identical expiry dates, sorted by a pre-configured Account Type priority sequence.
### Counters
- A Counter tracks a quantity (e.g., spend amount, transaction frequency) over a defined time period (Bucket).
- Entities tracked: Customer, Account, Card, Store, Chain, etc.
- Quantities tracked: Gross Amount, Nett Amount, Points, Transaction Count, Custom Quantities.
- Counter Periods: Days, Weeks, Months, Quarters, Years, Fixed Date, No Expiry, Days/Months/Quarters from Account Open Date.
## Exception Flow
- N/A

41
docs/specs/reward_campaign/cep_rule.md
View File

@@ -1,41 +0,0 @@
---
title: "Counter Extract & Process (CEP) Rule"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Counter Extract & Process (CEP) Rule
## Requirement Definition
Extracts values accumulated in a Counter at the end of a defined period and generates a transaction to trigger an Award/Redeem rule based on that accumulated total.
## Process Flow
### Pre-Conditions
- Users must have access rights.
- A Counter tracking the required metric must exist.
## Business Rules
### Data Schema
#### General & Extraction Settings
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Rule Type | CEP. | Enum | Required. |
| Counter to Extract | Counter containing the value. | Enum (Lookup) | Required. |
| Bucket to Extract | Current, Previous, Period Before Last. | Enum | Required. |
| Rule type to process | Rule type of the destination rule. | Enum (Lookup) | Required. |
| Transaction Code | TC used to post the extracted transaction. | Enum (Lookup) | Required. |
| -ve Bal. Adjust. TC | TC for negative extracted values. | Enum (Lookup) | Optional. |
| Account with blocked Card | Include or Exclude blocked cards. | Boolean | Conditional (if Acct/Card entity). |
| Run schedule | Day, Month, Annual, N days AOD, Stmt Cycle. | Enum (Lookup) | Required. Defines execution frequency. |
### Execution
- Evaluated by the CEP Batch scheduled at end-of-day.
- The extracted Counter Bucket value becomes the `Amount A` for the destination Rule.
- State of Counter Buckets is updated based on Counter Definition (e.g., closed after extraction) to prevent double-processing.
## Exception Flow
- N/A

45
docs/specs/reward_campaign/counter_definition.md
View File

@@ -1,45 +0,0 @@
---
title: "Counter Definition"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Counter Definition
## Requirement Definition
Defines conceptual entities that track quantities (spend amount, transactions, points) over defined periods of time.
## Process Flow
### Pre-Conditions
- Users must have access rights.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Counter Id | Unique identifier. | String (10) | Required. |
| Counter Name | Descriptive name. | String (50) | Required. |
| Effective From Date | Start date of counter effectiveness. | Date | Required. |
| Effective To Date | End date of counter effectiveness. | Date | Required. |
| Entity | Level of tracking (Cust, Acct, Card, Store, etc).| Enum (Lookup) | Required. |
| Bucket Period Unit | Time period for buckets (Day, Month, etc). | Enum (Lookup) | Required. |
| Bucket End Date | Used if Unit is Fixed Date. | Date | Conditional. |
| Bucket Period Duration(N)| Length of the period unit. | Integer | Conditional. |
| What to count | Entity to track (Gross Amt, Txns, Points, etc). | Enum (Lookup) | Required. |
| Reset type | Reset to 0, or keep remainder. | Enum (Lookup) | Required. |
| Reset Value | Threshold at which counter resets and new bucket starts. | Decimal | Required. Default 999999999. |
| First Start Date Is Fixed| Boolean flag. | Boolean | Conditional. |
| First Start Date | Starting date for the first bucket. | Date | Conditional. |
| Update State When | When to close bucket (On extract, On award). | Enum (Lookup) | Required. |
| Late Posting Option | Update late value vs Current bucket. | Enum | Required. |
### Execution
- If counter ID has existing values in `counter_stock`, definition cannot be changed (except Name/Desc/End Date).
- Late Posting determines how transactions with backdated post dates update counters (update the "Late Counter Value" or force update into the currently active time bucket).
## Exception Flow
- N/A

33
docs/specs/reward_campaign/external_transaction_code.md
View File

@@ -1,33 +0,0 @@
---
title: "External Transaction Code"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# External Transaction Code
## Requirement Definition
Maps incoming transaction codes from external systems (e.g., Card System) to OLS Transaction Codes.
## Process Flow
### Pre-Conditions
- Users must have access rights in the module.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| External Transaction Code | Source System Transaction Code. | String (10) | Required. |
| Description | Description for reference. | String (30) | Required. |
### Execution
- An External System TC is the first key used to locate the corresponding OLS TC for processing.
- Each External TC must be mapped to an OLS TC.
- Supports Maker-Checker approval workflow (Pending -> Active).
## Exception Flow
- N/A

36
docs/specs/reward_campaign/item_redemption_rule.md
View File

@@ -1,36 +0,0 @@
---
title: "Item Redemption Rule"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Item Redemption Rule
## Requirement Definition
Evaluates item redemption transactions (e.g. redeeming an eVoucher or physical item from a catalog).
## Process Flow
### Pre-Conditions
- Users must have access rights.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Rule Type | Item Redemption (ITRD). | Enum | Required. |
| Message Template ID | SMS/Email template if rule hit. | Enum (Lookup) | Optional. |
| Transaction Code | TC used to post the redemption. | Enum (Lookup) | Required. |
### Execution
- Same criteria evaluation approach as Award rules.
- There is NO reward pool, formula, or contributor attached to this rule type.
- The redemption pool to deduct from is configured separately in the Item Price configuration.
- To post an item redemption, the transaction must pass the validation criteria of the Item Redemption Rule linked to the redemption TC.
## Exception Flow
- Criteria failure blocks the item redemption transaction.

34
docs/specs/reward_campaign/ols_transaction_code.md
View File

@@ -1,34 +0,0 @@
---
title: "OLS Transaction Code"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# OLS Transaction Code
## Requirement Definition
Every transaction processed against Campaign Rules must have an OLS Transaction Code (TC). It acts as the primary key to locate relevant Campaign Rules.
## Process Flow
### Pre-Conditions
- Users must have access rights in the module.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| OLS Transaction Code | The internal transaction code. | String (10) | Required. |
| Description | Description of the code. | String (30) | Required. |
| External Transaction Code | The mapped external TCs. | List of Strings | Optional. Many External TCs can map to one OLS TC. |
| Reversal Indicator | Indicates if this is a reversal. | Boolean | Default False. |
### Execution
- Supports internal transactions (e.g., CEP Batch generated) that do not have an External TC.
- Supports Maker-Checker approval workflow (Pending -> Active).
## Exception Flow
- N/A

68
docs/specs/reward_campaign/pool_definition.md
View File

@@ -1,68 +0,0 @@
---
title: "Pool Definition"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Pool Definition
## Requirement Definition
Defines Reward Pools which track stored values (Points, Cash Rebates, Lucky Draw chances, eVouchers). Pools dictate expiry policies, entity tracking levels (Customer, Account, Card), and velocity controls.
## Process Flow
### Pre-Conditions
- Users must have access rights.
- Pool Conversion Rate must be active.
- Account Type Groups (if applicable) must be active.
## Business Rules
### Data Schema
#### General Information
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Pool Id | System-generated identifier. | String (10) | Required. |
| Pool Name | Name of the pool. | String (30) | Required. |
| Pool Type | Points, Cash Rebate, Lucky Draw, eVoucher. | Enum | Required. |
| Expiry Policy | Method to calculate expiry date. | Enum (Lookup) | Required (except eVoucher). |
| Policy Parameter N | Numeric parameter for Expiry Policy. | Integer | Conditional based on policy. |
| Expiry Date | Fixed expiry date. | Date | Conditional (if policy is Fixed Date). |
| Ripening Period | Days before reward is redeemable. | Integer | Conditional. Default 0. |
| Conversion Rate Code | Currency representing a unit of reward. | Enum (Lookup) | Conditional. |
| Allow Negative Balance | Allow pool to go negative on adjust/cancel. | Boolean | Conditional. Default False. |
| Precision | Number of decimal places. | Enum (Lookup) | Conditional. Default 2. |
| Account Type Group | Restricts earning to specific accounts. | Enum (Lookup) | Optional. |
| Grace Period | Months to keep expired buckets before forfeit. | Integer | Optional. |
| Entity Level | Tracks balance at Customer, Account, Card. | Enum | Required. |
#### Product Specific Policy
Overrides general expiry policy for specific Account Types.
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Product Account Level | PAL. | Enum (Lookup) | Required. |
| Product Account Type | PAT. | Enum (Lookup) | Required. Unique per row. |
| Expiry Policy | Specific expiry policy. | Enum (Lookup) | Required. |
#### Velocity Control
Defines thresholds for sending alerts (Exception Alert Reports).
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Maximum | Threshold limit. | Decimal | Required. |
| Transaction Type | Award, Redeem, Adjust. | Enum | Required. |
| Units | Per Pool Units or Per Transaction. | Enum | Required. |
| Per Entity 1 | Customer, Account, Card. | Enum | Optional (System-wide if null). |
| Per Entity 2 | Corporation, Chain, Store, Terminal. | Enum | Optional. |
| Per Period | Quarter, Month, Week, Day. | Enum | Required. |
| Alert Template | Message template for alert. | Enum | Required. |
| Alert Group | Recipient group (SMS/Email). | Enum | Required. |
### Execution
- Precision cannot be reduced after transactions are posted.
- Entity Level cannot be moved downwards (e.g., Customer to Card) after transactions are posted.
- Evoucher pools have No Expiry, no Precision, and no Negative Balances.
## Exception Flow
- N/A

39
docs/specs/reward_campaign/rep_rule.md
View File

@@ -1,39 +0,0 @@
---
title: "Redemption Extract & Process (REP) Rule"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Redemption Extract & Process (REP) Rule
## Requirement Definition
Extracts reward pool balances to automatically output them as Cash Rebates or Partner Points to an external destination system (like a Core Banking system or Airline Partner).
## Process Flow
### Pre-Conditions
- Users must have access rights.
## Business Rules
### Data Schema
#### Extraction Settings
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Rule Type | REP. | Enum | Required. |
| Pool to Extract | Pool containing the balance. | Enum (Lookup) | Required. |
| Minimum Pool Balance | Threshold before extraction. | Decimal | Optional. |
| Trigger Campaign rule | Validates criteria before extraction. | Boolean | Default False. |
| Redeem TC | TC used to post the redemption. | Enum (Lookup) | Required. |
| Output Redemption As | Format/System of output (e.g. Cash Rebate file).| Enum (Lookup) | Required. |
| Run schedule | Day, Month, Annual, Stmt Cycle, N days AOD. | Enum (Lookup) | Required. Defines execution frequency. |
### Execution
- Evaluated by the REP Batch scheduled at end-of-day.
- The full eligible amount of the Pool balance is deducted and output to a file (e.g., `OLSCRTXN`).
- If `Trigger Campaign rule` is true, an intermediate Redeem rule evaluates criteria, and the extracted amount is the minimum of (Available Balance, Formula Result).
## Exception Flow
- N/A

37
docs/specs/reward_campaign/reward_campaign.md
View File

@@ -1,37 +0,0 @@
---
title: "Reward Campaign"
type: OpenSpec
status: Draft
domain: Reward Campaign Management
---
# Reward Campaign
## Requirement Definition
Acts as the parent container for Business Rules (Campaign Rules) controlling rewards and redemptions. Campaigns can be "Base" (core product) or "Tactical" (short-term objectives).
## Process Flow
### Pre-Conditions
- Users must have access rights.
## Business Rules
### Data Schema
| Field Name | Description | Logic Type | Constraints / Rules |
|---|---|---|---|
| Campaign ID | Identifier. | String (10) | Required. |
| Campaign Name | Name of the campaign. | String (50) | Required. >= 10 chars. |
| Campaign Owner | Owner reference. | String (50) | Optional. |
| Campaign Description | Description. | String (500) | Optional. |
| Campaign Type | Base or Tactical. | Enum (Lookup) | Required. |
| Target Active Customer Count | Expected participant count. | Integer | Optional. Insight metric. |
| Target Avg Transaction Value | Expected spend value. | Decimal | Optional. Insight metric. |
| Campaign Period | Earliest Rule start to latest Rule end. | Date Range | Read-only based on Rules. |
### Execution
- Campaigns simply group Rules logically. The actual execution logic is defined in the child Campaign Rules.
## Exception Flow
- N/A

Some files were not shown because too many files have changed in this diff Show More