# Tài liệu Thiết kế Tổng quan (High-Level Design - HLD)
## Hệ thống Event-Driven Loyalty & Rewards

### 1. Tổng quan Hệ thống (System Overview)
**Mục tiêu:** Xây dựng một nền tảng Loyalty linh hoạt, hiệu năng cao, dựa trên kiến trúc hướng sự kiện (Event-Driven). Hệ thống có khả năng xử lý song song các giao dịch tài chính (cộng/trừ điểm) an toàn tuyệt đối và theo dõi hành vi người dùng (tracking) ở tần suất cao mà không gây nghẽn luồng xử lý giao dịch cốt lõi.

**Đối tượng và Hệ thống liên quan:**
- **Actors (Người dùng):** Khách hàng (Member) sử dụng ứng dụng di động/web; Nhân viên đối tác (Merchant) sử dụng ứng dụng quét mã.
- **External Systems (Hệ thống ngoài):** Hệ thống phát hành thẻ (Card Issuance), Hệ thống gửi tin (SMS/Email/Firebase).

### 2. Sơ đồ Kiến trúc Tổng quan (Architecture Topology)
Hệ thống được chia thành các phân lớp (layers) rõ ràng nhằm đảm bảo tính độc lập, dễ bảo trì và dễ dàng mở rộng.

- **Client Layer:** Các ứng dụng tương tác trực tiếp với người dùng cuối (Member App, Merchant App).
- **Event Gateway Layer:** `event-processor-service` đóng vai trò là "Smart Router", chịu trách nhiệm tiếp nhận, validate và phân loại sự kiện (Direct, Tracking, Notification) để định tuyến vào đúng Kafka Topic.
- **Core Service Layer:** 
  - `transaction-service`: Core Engine đảm bảo tính ACID, xử lý giao dịch điểm/voucher và thực thi Rule logic.
  - `attribute-service`: Quản lý thuộc tính động (EAV) và các bộ đếm (Counter), tích lũy sự kiện để tránh dội tải cho Core Engine.
  - `notification-service`: Chuyên biệt cho việc gửi thông báo đa kênh.
  - `marketing-service`: Chạy cronjob, scheduler cho các chiến dịch và tập khách hàng.
  - `customer-service`: Quản lý hồ sơ người dùng.
- **Message Broker Layer:** Sử dụng Apache Kafka làm xương sống giao tiếp bất đồng bộ, chia thành các topic chuyên biệt (`events-topic`, `tracking-topic`, `noti-topic`).
- **Data & Caching Layer:** CSDL quan hệ (PostgreSQL) độc lập cho từng service, Cache (Redis) hỗ trợ truy xuất nhanh.

```mermaid
graph TD
    subgraph Client Layer
        MA[Member App]
        MRA[Merchant App]
    end

    subgraph Event Gateway Layer
        EP[event-processor-service<br/>Smart Router]
    end

    subgraph Message Broker Layer
        K_ET[Kafka: events-topic]
        K_TT[Kafka: tracking-topic]
        K_NT[Kafka: noti-topic]
    end

    subgraph Core Service Layer
        TP[transaction-service<br/>Core Rule & Ledger]
        ATTR[attribute-service<br/>Tracking & Counter]
        NS[notification-service<br/>Push/SMS]
        MKT[marketing-service<br/>Scheduler]
    end

    subgraph Data & Caching Layer
        DB_TP[(PostgreSQL<br/>Transaction)]
        DB_ATTR[(PostgreSQL<br/>EAV/Attribute)]
        REDIS[(Redis<br/>Cache)]
    end

    MA -->|Events: Login, View, Redeem| EP
    MRA -.->|Sync API: Scan Voucher| TP
    
    EP -->|Direct Events| K_ET
    EP -->|Tracking Events| K_TT
    EP -->|Noti Events| K_NT

    K_ET --> TP
    K_TT --> ATTR
    K_NT --> NS
    
    MKT -->|Cron: Scheduled Events| EP
    ATTR -->|Threshold Reached Trigger| K_ET
    TP -->|Reward Result| K_NT
    
    TP --- DB_TP
    ATTR --- DB_ATTR
    ATTR -.-> REDIS
```

### 3. Luồng dữ liệu & Tương tác chính (Key Workflows & Sequence)

#### 3.1. Luồng "Accumulate & Trigger" - Tracking & Thưởng (Ví dụ: View Item)
**Mô tả:** Nhằm tránh làm nghẽn Core Engine bởi các sự kiện có tần suất cao, hệ thống sử dụng Attribute Service để đếm (Counter). Chỉ khi đạt ngưỡng quy định (Threshold), một sự kiện trả thưởng mới được sinh ra và đẩy cho Core Engine xử lý.

```mermaid
sequenceDiagram
    participant MA as Member App
    participant EP as Event Processor
    participant K_TT as Kafka (tracking-topic)
    participant ATTR as Attribute Service
    participant K_ET as Kafka (events-topic)
    participant TP as Transaction Service

    MA->>EP: Gửi Event (VD: ViewItem)
    EP->>EP: Phân loại: Tracking Event
    EP->>K_TT: Đẩy vào tracking-topic
    K_TT->>ATTR: Consume Event
    
    ATTR->>ATTR: 1. Cập nhật Counter (weekly_view_count++)<br/>2. Cập nhật Cache (recently_viewed)
    
    alt Counter >= Threshold (VD: 10)
        ATTR->>K_ET: Bắn Event Trả Thưởng (View_10_Items_Reward)
        ATTR->>ATTR: Reset Counter
        K_ET->>TP: Consume Reward Event
        TP->>TP: Cộng điểm (Transaction ACID)
    end
```

#### 3.2. Luồng Xử lý Giao dịch Tài chính Trực tiếp (Ví dụ: Redeem Item / Transfer)
**Mô tả:** Các giao dịch mang tính tài chính trực tiếp (chuyển điểm, đổi quà) được gọi trực tiếp qua API tới Transaction Service để xử lý đồng bộ (Synchronous), giúp đảm bảo tốc độ phản hồi ngay lập tức cho người dùng và tính toàn vẹn dữ liệu.

```mermaid
sequenceDiagram
    participant MA as Member App
    participant TP as Transaction Service
    participant K_NT as Kafka (noti-topic)
    participant NS as Notification Service

    MA->>TP: Gọi API trực tiếp (Redeem_Item / Transfer)
    
    TP->>TP: BEGIN DB TRANSACTION
    TP->>TP: Validate Số dư & Điều kiện
    TP->>TP: Debit (-) Điểm & Cập nhật State/Inventory
    TP->>TP: COMMIT TRANSACTION
    
    TP-->>MA: Trả kết quả thành công (200 OK)
    
    TP->>K_NT: Bắn Event Giao dịch Thành công
    K_NT->>NS: Consume Event
    NS->>MA: Đẩy Noti (Firebase Push/SMS)
```

### 4. Lựa chọn Công nghệ & Hạ tầng (Technology Stack & Infrastructure)
- **Backend (Microservices):** Sử dụng Java / Spring Boot. Lý do: Hệ sinh thái phong phú, độ ổn định cực cao (Enterprise-grade) chuyên trị các hệ thống tài chính/giao dịch khắt khe.
- **Message Broker:** Apache Kafka. Lý do: Khả năng xử lý thông lượng khổng lồ (high-throughput), độ trễ cực thấp, hỗ trợ cơ chế lưu trữ bền vững (persistence) và phân chia luồng qua Consumer Groups.
- **Database Chính:** PostgreSQL. Lý do: Khả năng hỗ trợ ACID mạnh mẽ cho Transaction Service, đồng thời hỗ trợ kiểu dữ liệu JSONB tối ưu cho mô hình EAV (Entity-Attribute-Value) của Attribute Service.
- **Caching:** Redis. Lý do: Tốc độ Read/Write in-memory cực nhanh, phù hợp cho việc lưu trữ cache dữ liệu có tần suất đọc cao phi tài chính (ví dụ: recently viewed items).
- **Data Warehouse:** Doris. Lý do: Phục vụ bóc tách dữ liệu báo cáo, phân tích (BI) và phân tập khách hàng (Segmentation) mà không làm suy giảm hiệu năng của hệ thống CSDL tác nghiệp (OLTP).

### 5. Giải pháp Đảm bảo Chất lượng (Non-Functional Highlights)
- **Hiệu năng & Mở rộng (Performance & Scalability):**
  - **Tách bạch luồng dữ liệu (Isolation):** Việc tách riêng luồng giao dịch cốt lõi (Direct) và luồng theo dõi hành vi (Tracking) giúp Core Engine tập trung 100% công suất cho dòng tiền/điểm.
  - **Event-Driven & Async processing:** Các luồng không yêu cầu phản hồi ngay được đẩy qua Kafka, cho phép các service tự điều chỉnh tốc độ tiêu thụ (throttle) và dễ dàng mở rộng ngang (horizontal scaling) thông qua việc tăng partition của Kafka.
- **Bảo mật & Tính toàn vẹn (Security & Data Integrity):**
  - **Idempotency (Tính luỹ đẳng):** Transaction Service đảm bảo mọi giao dịch cộng/trừ điểm hoặc cấp thẻ/voucher đều kiểm tra khóa Idempotent, chống duplicate event sinh ra từ mạng chập chờn.
  - **ACID Transaction:** Mọi biến động điểm số hay trạng thái kho (voucher) đều được thực thi và khóa chặt trong 1 Database Transaction nguyên tử.
- **Tính khả dụng & Giám sát (Availability & Monitoring):**
  - **Smart Routing & Fallback:** Event Processor kiểm tra định dạng Schema của từng sự kiện đầu vào. Các sự kiện lỗi định dạng sẽ bị reject hoặc đẩy vào Dead Letter Queue (DLQ) để điều tra và phục hồi sau, đảm bảo không làm sập các service thụ hưởng phía sau.