loyalty-agent-service/docs/knowledge-cards/campaign/counter_definition.md

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