Thiết kế Goal và ghi nhận chuyển đổi cho Campaign

1. Mục tiêu

Tính năng này trả lời được bốn câu hỏi:

Campaign muốn khách hàng thực hiện hành động gì sau khi nhận thông điệp?
Khách hàng nào đã đạt Goal?
Khách hàng đạt Goal sau lần gửi nào, thuộc Run và nhóm A/B nào?
Báo cáo cần tính số chuyển đổi và tỷ lệ chuyển đổi từ dữ liệu nào?

Hệ thống hỗ trợ đúng hai cách ghi nhận:

Chế độ	Cách hoạt động
`AUTO_OCS`	Hệ thống định kỳ đối chiếu target của Campaign với dữ liệu OCS.
`MANUAL_IMPORT`	Người dùng import danh sách khách đã phản hồi tại màn chi tiết Campaign.

Một Campaign chỉ được chọn một trong hai chế độ. Không cho phép vừa tự động vừa import thủ công để tránh một khách hàng được ghi nhận từ hai nguồn khác nhau.

Phạm vi hiện tại chỉ tính một khách hàng chuyển đổi một lần trong một Campaign. Không phát triển attribution nhiều chạm, doanh thu, nhiều Goal trên một Campaign hoặc tự động chọn biến thể A/B thắng.

2. Hiện trạng và phần còn thiếu

Luồng hiện tại đã có:

Campaign, CampaignRun và bản chụp cấu hình của từng Run.
campaign_target_member trong ClickHouse chứa đúng tập khách đã chốt cho từng Run.
campaign_delivery_event ghi SENT, FAILED và các kết quả gửi.
campaign_click_event, campaign_open_event ghi tương tác.
Dataset và field OCS được quản lý trong MongoDB.
Cấu trúc điều kiện truy vấn OCS của Segment đã có validation field, kiểu dữ liệu và operator.
JobRunr, Kafka, ClickHouse datasource và File Asset/MinIO đã có sẵn.

Phần còn thiếu:

Campaign chưa lưu định nghĩa Goal đúng nghĩa.
Chưa có tiến trình đối chiếu target với OCS sau khi gửi.
Chưa có nơi lưu kết quả chuyển đổi theo khách hàng.
Import thủ công chưa có job, file lỗi và trạng thái xử lý.
Báo cáo hiện tại chưa dùng conversion thật. Không được coi action gửi thành công là khách hàng đã chuyển đổi.

3. Quy tắc chung

3.1. Mốc bắt đầu tính chuyển đổi

Với target được gửi thông điệp:

Chỉ tính chuyển đổi nếu đã có ít nhất một campaign_delivery_event.event_type = SENT.
Khi khách xuất hiện trong nhiều Run, conversion được gắn với lần SENT gần nhất nhưng không sau thời điểm conversion được phát hiện.
campaignRunId, targetSnapshotId, variantCode, channel và actionIndex lấy từ lần gửi được gắn conversion.

Với target thuộc nhóm A/B CONTROL:

Nhóm này không nhận thông điệp nên không yêu cầu event SENT.
Mốc bắt đầu là campaign_target_snapshot.frozenAt.
Conversion của CONTROL vẫn được ghi nhận để so sánh tỷ lệ chuyển đổi tự nhiên với các nhóm được gửi.

Target gửi thất bại hoàn toàn và không thuộc CONTROL không được tính conversion.

3.2. Hạn chế của dữ liệu OCS hiện tại

Các trường như login_superapp, data_package, vas_service, g_volume phản ánh trạng thái hiện tại. Chúng không cung cấp chính xác thời điểm trạng thái thay đổi.

Vì vậy chế độ AUTO_OCS áp dụng quy tắc:

Trước khi gửi, Target Snapshot phải loại khách đã đạt Goal.
Sau khi gửi, job chỉ kiểm tra lại target đã SENT hoặc target CONTROL.
Khi OCS bắt đầu trả kết quả khớp, hệ thống ghi detectedAt là thời điểm phát hiện.

Như vậy hệ thống chứng minh được khách chưa đạt Goal ở thời điểm chốt target và đã đạt Goal ở lần kiểm tra sau khi gửi. Muốn có chính xác thời điểm nghiệp vụ, OCS phải bổ sung cột thời gian phát sinh sự kiện.

3.3. Chống ghi trùng

conversionId được tạo cố định:

SHA-256(companyId + ":" + campaignId + ":" + recipientKey)

Cùng một khách trong cùng Campaign luôn có cùng conversionId, kể cả khi:

JobRunr retry.
OCS trả lại cùng kết quả ở ngày tiếp theo.
Người dùng import lại cùng một file.
Khách xuất hiện trong nhiều Campaign Run.

Báo cáo luôn dùng uniqExact(conversion_id). Vì vậy bản ghi Kafka/ClickHouse bị phát lại không làm tăng số conversion.

3.4. Quy tắc kết hợp điều kiện

Để cấu hình dễ hiểu và không cần biểu thức lồng phức tạp:

Các điều kiện trong cùng một rule được nối bằng AND.
Nhiều rule được nối bằng OR.
Chỉ cần một rule khớp thì khách đạt Goal.

Quy tắc này đủ cho cả năm Campaign và tránh phải lưu thêm ruleMatchPolicy.

4. Cấu hình Goal trên giao diện

Tại bước thiết lập Campaign, FE thêm phần Ghi nhận chuyển đổi.

4.1. Tự động từ OCS

FE hiển thị:

Chọn Tự động từ OCS.
Chọn dataset.
Chọn field, operator và giá trị giống màn tạo Segment.
Có thể thêm nhiều điều kiện trong một rule.
Có thể thêm rule khác khi Goal nằm ở bảng khác hoặc cần điều kiện OR.

Payload tối thiểu:

{
  "conversionGoal": {
    "mode": "AUTO_OCS",
    "rules": [
      {
        "datasetCode": "ALL_REPORT_STL_NEW",
        "conditions": [
          {
            "fieldCode": "LOGIN_SUPERAPP",
            "operator": "GREATER_EQUAL_THAN",
            "valueSource": "FIXED",
            "value": 1
          }
        ]
      }
    ]
  }
}

Không yêu cầu FE gửi tên bảng, tên cột vật lý hoặc selectedFields. Backend tự resolve từ ocs_dataset_config và ocs_dataset_field_config.

4.2. Import thủ công

Khi tạo Campaign, FE chỉ gửi:

{
  "conversionGoal": {
    "mode": "MANUAL_IMPORT"
  }
}

Không upload file tại bước tạo Campaign.

Nút Import kết quả chuyển đổi chỉ xuất hiện tại màn chi tiết Campaign khi:

Goal là MANUAL_IMPORT.
Campaign có trạng thái IN_PROGRESS, PAUSED hoặc FINISHED.
Người dùng có quyền quản lý Campaign.

Không cho import khi Campaign là DRAFT, SUBMITTED, REJECTED hoặc CANCELLED.

5. Cấu hình Goal cho năm Campaign

5.1. CAMP 1 - Chuyển đổi chéo BUs

Dataset: ALL_REPORT_STL_NEW
LOGIN_SUPERAPP >= 1

5.2. CAMP 2 - Onboarding khách Online

Dataset: ALL_REPORT_STL_NEW
LOGIN_SUPERAPP >= 1

5.3. CAMP 3 - Tải app chưa kích hoạt

Dataset: ALL_REPORT_STL_NEW
LOGIN_SUPERAPP >= 1

5.4. CAMP 4 - Upgrade gói Data 50K

Chỉ cần một trong hai rule khớp:

Rule 1
Dataset: ALL_REPORT_STL_NEW
DATA_PACKAGE = "50K"

OR

Rule 2
Dataset: F013_VAS_MONTH_STREAM
VAS_SERVICE = "50K"

Nếu nghiệp vụ cung cấp nhiều mã gói 50K, danh sách giá trị phải được quản lý trong cấu hình field/rule, không hard-code rải rác trong scheduler.

5.5. CAMP 5 - Phát triển thuê bao 4G

g_volume và num_usage_day_4g là số không âm, nên > 0 đồng thời loại null và 0.

Rule 1
Dataset: ALL_REPORT_STL_NEW
DATA_PACKAGE = "10K6S"
AND G_VOLUME > 0

OR

Rule 2
Dataset: ALL_REPORT_STL_NEW
DATA_PACKAGE = "10K6S"
AND NUM_USAGE_DAY_4G > 0

Các field sau cần được bổ sung vào cấu hình dataset ALL_REPORT_STL_NEW nếu chưa có:

LOGIN_SUPERAPP     STRING
G_VOLUME           NUMBER
NUM_USAGE_DAY_4G   NUMBER

6. Thiết kế dữ liệu

6.1. MongoDB `campaign`

Không tạo collection Goal riêng vì mỗi Campaign hiện chỉ có một Goal.

Bổ sung object nhúng:

conversionGoal.mode
conversionGoal.rules[]

Model đề xuất:

CampaignConversionGoalModel
  mode: AUTO_OCS | MANUAL_IMPORT
  rules: List<SegmentQueryDefinitionModel>

Backend nhận datasetCode + conditions, sau đó dùng validator OCS hiện có để resolve thành SegmentQueryDefinitionModel. Bản lưu phải chứa schema, table, column và kiểu dữ liệu đã resolve; không phụ thuộc vào label FE.

Không bổ sung các field sau trong giai đoạn này:

goalCode
countingMode
attributionWindowDays
ruleMatchPolicy

Các giá trị đó đã có quy tắc cố định trong phạm vi năm Campaign.

6.2. MongoDB `campaign_run`

Bổ sung conversionGoal vào CampaignRunDefinitionSnapshotModel.

Khi tạo Run, MapStruct copy Goal hiện tại của Campaign vào snapshot. Job conversion luôn đọc snapshot, không đọc cấu hình Campaign có thể đã bị thay đổi sau đó.

Sau khi Campaign đã có Run đầu tiên, không cho sửa conversionGoal. Muốn đổi Goal phải tạo Campaign mới để không làm báo cáo cũ thay đổi ý nghĩa.

6.3. MongoDB `campaign_conversion_scan_state`

Collection này chỉ lưu trạng thái kỹ thuật của job tự động, không lưu từng khách hàng.

Trường	Ý nghĩa
`companyId`, `campaignId`	Campaign đang được quét.
`cycleDate`	Ngày chạy hiện tại.
`status`	`IDLE`, `RUNNING`, `RETRY_WAIT`.
`cursorRecipientKey`	Điểm đã xử lý thành công gần nhất.
`scannedCount`, `matchedCount`	Số liệu theo dõi tiến độ.
`leaseOwner`, `leaseUntil`	Chống hai node xử lý cùng Campaign.
`nextScanAt`	Thời điểm được phép quét tiếp.
`lastSuccessAt`, `lastErrorCode`	Theo dõi vận hành.

Index:

UNIQUE(companyId, campaignId)
INDEX(status, nextScanAt)
INDEX(leaseUntil)

Cursor chỉ được cập nhật sau khi batch conversion đã ghi thành công xuống ClickHouse.

6.4. MongoDB `campaign_conversion_import_job`

Collection này phục vụ giao diện theo dõi import thủ công.

Trường	Ý nghĩa
`companyId`, `campaignId`	Phạm vi import.
`fileAssetId`	File nguồn đã upload lên MinIO.
`status`	`QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`.
`totalRows`, `successRows`, `invalidRows`, `duplicateRows`	Tiến độ xử lý.
`errorFileAssetId`	File lỗi để FE tải lại.
`createdBy`, `startedAt`, `completedAt`	Audit.
`lastErrorCode`	Mã lỗi tổng của job.

Index:

INDEX(companyId, campaignId, createdAt DESC)
INDEX(status, createdAt)

Không lưu từng dòng import trong MongoDB.

6.5. ClickHouse `campaign_conversion_event`

Đây là bảng kết quả chuyển đổi theo khách hàng và là nguồn chính cho báo cáo.

CREATE TABLE campaign_conversion_event
(
    event_date Date,
    converted_at DateTime64(3),
    detected_at DateTime64(3),
    conversion_id String,
    company_id String,
    campaign_id String,
    campaign_run_id String,
    target_snapshot_id String,
    recipient_key String,
    variant_code String DEFAULT '',
    channel LowCardinality(String) DEFAULT '',
    action_index Int32 DEFAULT -1,
    attributed_sent_at Nullable(DateTime64(3)),
    source LowCardinality(String),
    time_source LowCardinality(String),
    matched_rule_no UInt16,
    source_dataset LowCardinality(String) DEFAULT '',
    source_reference String DEFAULT '',
    import_job_id String DEFAULT '',
    evidence String DEFAULT '{}',
    created_at DateTime64(3)
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(event_date)
ORDER BY (
    company_id,
    campaign_id,
    campaign_run_id,
    event_date,
    recipient_key
);

Giải thích các trường dễ nhầm:

Trường	Ý nghĩa
`converted_at`	Thời điểm conversion từ file hoặc thời điểm OCS được phát hiện.
`detected_at`	Thời điểm LaoAds ghi nhận được conversion.
`time_source`	`SOURCE_TIME`, `DETECTED_TIME` hoặc `IMPORT_TIME`.
`attributed_sent_at`	Lần gửi được gắn conversion; null với `CONTROL`.
`matched_rule_no`	Rule OCS đã khớp, bắt đầu từ 1.
`evidence`	JSON nhỏ chứa giá trị chứng minh rule khớp; không chứa số điện thoại gốc.

Không dùng MongoDB để lưu conversion theo từng người vì dữ liệu có thể rất lớn.

Không tạo bảng tổng hợp mới trong giai đoạn đầu. ClickHouse query trực tiếp bằng uniqExact(conversion_id) trên một Campaign. Chỉ bổ sung aggregate/Flink khi đo thực tế cho thấy API báo cáo không đạt ngưỡng yêu cầu.

7. Luồng tự động từ OCS

7.1. Chốt target trước khi gửi

[Diagram]

Không được coi UNKNOWN, NOT_FOUND hoặc lỗi OCS là “chưa đạt Goal”. Nếu không xác định được đầy đủ thì fail batch và retry để tránh gửi nhầm.

7.2. Quét conversion sau khi gửi

[Diagram]

Nếu process chết sau khi insert ClickHouse nhưng trước khi cập nhật cursor, batch được chạy lại. conversionId cố định và báo cáo dùng uniqExact, nên không tăng sai số liệu.

7.3. API OCS dùng cho Goal

Không gọi từng ISDN. Một request tối đa 1.000 ISDN:

POST /api/v1/internal/subscribers/match-goal
X-API-Key: <internal-api-key>

Request chứa:

{
  "requestId": "scan-id",
  "isdns": ["85620xxxxxxx"],
  "rules": [
    {
      "tableName": "all_report_stl_new",
      "identityColumn": "isdn",
      "conditions": [
        {
          "columnName": "login_superapp",
          "dataType": "STRING",
          "operator": "GREATER_EQUAL_THAN",
          "value": 1
        }
      ]
    }
  ]
}

API này chỉ nhận cấu hình đã resolve từ backend. FE không gọi trực tiếp. OCS service phải validate table/column/operator theo allow-list hiện có và bind giá trị bằng prepared statement.

Response phải trả kết quả cho toàn bộ ISDN đầu vào, gồm MATCHED, NOT_MATCHED, NOT_FOUND, UNKNOWN, INVALID. LaoAds chỉ ghi conversion cho MATCHED.

8. Luồng import thủ công

8.1. Định dạng file

Cột	Bắt buộc	Ý nghĩa
`phone`	Có	Số điện thoại khách hàng.
`converted_at`	Không	Thời điểm phản hồi; nếu trống dùng thời điểm import.
`reference`	Không	Mã giao dịch hoặc mã đối soát bên ngoài.

8.2. Luồng xử lý

[Diagram]

8.3. Lỗi theo từng dòng

INVALID_PHONE
DUPLICATE_IN_FILE
NOT_CAMPAIGN_TARGET
NO_SUCCESSFUL_SEND
CONVERTED_BEFORE_SEND
ALREADY_CONVERTED
INVALID_CONVERTED_AT

Với target CONTROL, thay NO_SUCCESSFUL_SEND bằng kiểm tra converted_at >= targetSnapshot.frozenAt.

Một file có dòng lỗi vẫn hoàn thành job với các dòng hợp lệ. Chỉ đánh FAILED khi không đọc được file, ClickHouse không ghi được hoặc lỗi hệ thống khiến job không thể tiếp tục.

9. Luồng báo cáo

Nguồn dữ liệu:

Chỉ số	Bảng
Target	`campaign_target_member`
Sent/Failed/Delivered	`campaign_delivery_event` hoặc `campaign_metric_1m`
Open/Read/Click	Bảng tracking hiện có hoặc `campaign_metric_1m`
Conversion	`campaign_conversion_event`

Quy tắc tính:

conversionCount = uniqExact(conversion_id)
conversionRate = conversionCount / distinctTargetCount * 100

Dùng target làm mẫu số để nhóm CONTROL vẫn so sánh được. Không dùng số action hoàn thành trong MongoDB làm conversion.

Các API cần bổ sung hoặc sửa:

Campaign summary trả conversionCount và conversionRate.
Time series có đường conversions theo converted_at.
A/B comparison group conversion theo variant_code.
Donut theo kênh dùng channel đã được gắn từ lần SENT.
Company conversion time series đọc ClickHouse thay cho CampaignActionExecutionModel.

Query báo cáo bắt buộc scope bằng company_id + campaign_id; khi xem một Run thì thêm campaign_run_id.

10. Các trường hợp phải xử lý

Trường hợp	Xử lý
Khách đạt Goal trước khi chốt target	Loại khỏi Target Snapshot, không ghi conversion cho Campaign.
OCS lỗi khi chốt target	Snapshot fail và retry; không mặc định cho khách đi tiếp.
OCS lỗi khi quét conversion	Không cập nhật cursor; retry cùng batch.
OCS trả thiếu một ISDN	Batch lỗi; không đánh ISDN thiếu là `NOT_MATCHED`.
Khách có nhiều dòng OCS	OCS tổng hợp theo ISDN; chỉ trả một kết quả cuối.
Khách khớp nhiều rule	Chỉ một conversion; lưu rule đầu tiên theo thứ tự cấu hình và evidence các rule khớp nếu cần.
Khách thuộc nhiều Run	Gắn lần `SENT` gần nhất trước khi phát hiện; chỉ tính một lần trong Campaign.
Khách chỉ có event FAILED	Không conversion, trừ khi thuộc `CONTROL`.
Job chết giữa batch	Chạy lại; `conversionId` chống tăng số liệu.
Hai node cùng chạy	Mongo lease chỉ cho một node giữ Campaign.
Import lặp cùng file	Dòng đã conversion được tính `ALREADY_CONVERTED`, không tăng báo cáo.
Import khi Campaign AUTO	Từ chối toàn bộ request.
Import khi Campaign FINISHED	Cho phép.
Import khi Campaign CANCELLED	Từ chối.
Campaign đã có Run rồi sửa Goal	Từ chối; tạo Campaign mới.
`converted_at` trống trong file	Dùng thời điểm import và `time_source=IMPORT_TIME`.
Target CONTROL chuyển đổi	Ghi conversion, `attributed_sent_at=null`, `channel=''`.
Campaign không có ngày kết thúc	AUTO tiếp tục quét khi Campaign còn hoạt động; khi FINISHED thực hiện một lượt quét cuối.

11. Log, bảo mật và hiệu suất

11.1. Log bắt buộc

Log theo batch, không log từng người:

requestId, scanId, importJobId
companyId, campaignId, campaignRunId
cursor, batchSize, matchedCount, invalidCount
durationMs, errorCode, retryCount

Không log số điện thoại gốc, nội dung file, credential OCS hoặc evidence đầy đủ.

11.2. Hiệu suất

Keyset pagination bằng recipient_key, không dùng OFFSET.
Batch OCS và ClickHouse tối đa 1.000 bản ghi.
Không query OCS từng số điện thoại.
Không load toàn bộ file import vào RAM.
Không ghi từng conversion vào MongoDB.
Cursor chỉ tiến sau khi batch ClickHouse thành công.
Report dùng partition theo tháng và filter company_id + campaign_id.
Chưa tạo thêm aggregate table khi chưa có số đo chứng minh cần thiết.

11.3. Error code đa ngôn ngữ

Các exception từ API phải chỉ dùng error code và message resource hiện có:

CAMPAIGN_GOAL0001  Goal mode không hợp lệ
CAMPAIGN_GOAL0002  AUTO_OCS phải có ít nhất một rule
CAMPAIGN_GOAL0003  MANUAL_IMPORT không được chứa rule
CAMPAIGN_GOAL0004  Dataset/field/operator Goal không hợp lệ
CAMPAIGN_GOAL0005  Không được sửa Goal sau khi Campaign đã có Run
CAMPAIGN_GOAL0006  Campaign không cho phép import conversion
CAMPAIGN_GOAL0007  File import không hợp lệ
CAMPAIGN_GOAL0008  Không tìm thấy Goal snapshot của Run
CAMPAIGN_GOAL0009  Không thể kiểm tra Goal từ OCS
CAMPAIGN_GOAL0010  Kết quả OCS không đầy đủ

Bổ sung message tương ứng vào đầy đủ file ngôn ngữ đang được LaoAds sử dụng. Không hard-code message tiếng Anh trong service.

12. Danh sách task triển khai

Phần việc được tách thành chín task. Mỗi task tạo thành một merge request độc lập, có đầu ra rõ ràng và không gom toàn bộ trách nhiệm của một nhánh vào một merge request lớn.

Task 01 - Khai báo Goal và validation dùng chung

Mục tiêu

Tạo contract thống nhất cho Goal để Campaign API, Run snapshot, OCS và import cùng sử dụng.

Phạm vi thay đổi

Tạo CampaignConversionModeEnum: AUTO_OCS, MANUAL_IMPORT.
Tạo request, response và model CampaignConversionGoal.
Tái sử dụng cấu trúc điều kiện và validator dataset/field/operator của Segment.
AUTO_OCS bắt buộc có ít nhất một rule; mỗi rule có dataset và ít nhất một condition.
MANUAL_IMPORT không được chứa rule.
Resolve datasetCode, fieldCode thành schema/table/column/data type ở Backend.
Bổ sung error code và message cho đầy đủ ngôn ngữ hiện có.
Dùng MapStruct cho các model/DTO có cấu trúc tương ứng; không tạo mapper thủ công.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

Dataset không tồn tại hoặc không hoạt động.
Field không thuộc dataset.
Operator không hỗ trợ kiểu dữ liệu.
Rule rỗng, condition rỗng hoặc giá trị không đúng kiểu.
FE cố gửi trực tiếp tên bảng/cột không nằm trong cấu hình.

Phụ thuộc

Không phụ thuộc task khác. Đây là một trong ba task có thể bắt đầu ngay.

Hoàn thành khi

Có một validator dùng chung, không sao chép SegmentValidationService sang Campaign.
Request sai trả đúng error code; request đúng trả Goal đã resolve.
Unit test bao phủ hai mode và validation dataset/field/operator.

Task 02 - Lưu Goal vào Campaign và Campaign Run snapshot

Mục tiêu

Lưu Goal khi tạo Campaign và cố định Goal theo từng Run để cấu hình về sau không làm sai báo cáo cũ.

Phạm vi thay đổi

Bổ sung conversionGoal vào CampaignModel, Campaign request/response và API chi tiết Campaign.
Bổ sung conversionGoal vào CampaignRunDefinitionSnapshotModel.
Cập nhật MapStruct mapper Campaign và Campaign Run.
Khi tạo Run, copy Goal đã resolve từ Campaign sang snapshot.
Không cho sửa Goal sau khi Campaign đã có Run đầu tiên.
Với dữ liệu Campaign cũ chưa có Goal, giữ tương thích đọc; không tự suy diễn thành conversion.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

Campaign cũ không có conversionGoal vẫn đọc được.
Campaign đã có Run thì request đổi mode/rule bị từ chối.
Dataset config bị sửa sau đó không làm thay đổi Goal trong Run đã tạo.
API detail trả cấu hình đủ để FE hiển thị lại nhưng không lộ credential OCS.

Phụ thuộc

Phụ thuộc Task 01.

Hoàn thành khi

Campaign và Run lưu đúng Goal.
Run chỉ đọc Goal trong snapshot khi xử lý conversion.
Không có builder thủ công cho các field MapStruct có thể map trực tiếp.

Task 03 - Tạo bảng ClickHouse và lớp lưu conversion dùng chung

Mục tiêu

Tạo một nơi duy nhất ghi conversion cho cả AUTO_OCS và MANUAL_IMPORT, đồng thời cung cấp các query nền tảng cho scheduler và report.

Phạm vi thay đổi

Tạo migration campaign_conversion_event theo schema tại mục 6.5.
Tạo DTO row và repository/service batch insert.
Tạo conversionId = SHA-256(companyId + ":" + campaignId + ":" + recipientKey) tại một hàm dùng chung.
Tạo query kiểm tra conversion đã tồn tại theo Campaign và recipient.
Tạo query tìm lần SENT gần nhất trước thời điểm conversion.
Tạo query đọc candidate theo keyset recipient_key; không dùng OFFSET.
Mọi query bắt buộc scope bằng company_id và campaign_id.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

Retry cùng batch không làm tăng số liệu báo cáo.
Target CONTROL không cần SENT, attributed_sent_at để null.
Target gửi thất bại hoàn toàn không được ghi conversion.
Không log recipient gốc hoặc evidence nhạy cảm.

Phụ thuộc

Không phụ thuộc task khác. Đây là một trong ba task có thể bắt đầu ngay.

Hoàn thành khi

Migration chạy được trên ClickHouse hiện tại.
Insert theo batch và query bằng keyset hoạt động.
Test chứng minh ghi lại cùng conversionId không làm tăng kết quả uniqExact.

Task 04 - API OCS kiểm tra Goal theo batch

Mục tiêu

Cho phép LaoAds kiểm tra tối đa 1.000 thuê bao theo một hoặc nhiều rule mà không gọi OCS từng số điện thoại.

Phạm vi thay đổi

Tạo API nội bộ POST /api/v1/internal/subscribers/match-goal.
Request nhận danh sách ISDN và rules đã resolve; không nhận biểu thức SQL tự do.
Xác thực API key và giới hạn tối đa 1.000 ISDN.
Validate table, identity column, condition column và operator bằng allow-list.
Dùng prepared statement cho giá trị; không nối giá trị vào SQL.
Nhiều condition trong rule là AND; nhiều rule là OR.
Response trả đúng một trạng thái cho mọi ISDN đầu vào: MATCHED, NOT_MATCHED, NOT_FOUND, UNKNOWN, INVALID.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

Request rỗng hoặc vượt 1.000 ISDN.
OCS/Hadoop timeout hoặc trả lỗi giữa các rule.
Một ISDN có nhiều dòng dữ liệu.
ISDN không tồn tại khác với lỗi không xác định.
Một rule lỗi thì không trả kết quả thành công một phần cho cả batch.

Phụ thuộc

Không phụ thuộc task khác. Đây là một trong ba task có thể bắt đầu ngay.

Hoàn thành khi

API trả đủ số phần tử bằng số ISDN đầu vào.
Không có SQL injection qua table, column, operator hoặc value.
Có log requestId, batch size, dataset, duration và error code; không log ISDN.

Task 05 - Scheduler quét Goal tự động và quản lý checkpoint

Mục tiêu

Định kỳ tìm khách đã đạt Goal, ghi conversion theo batch và tiếp tục đúng vị trí sau retry hoặc restart.

Phạm vi thay đổi

Tạo collection campaign_conversion_scan_state và các index tại mục 6.3.
Tạo atomic lease để hai node không xử lý cùng Campaign.
Tạo scheduler chọn Campaign AUTO_OCS đến hạn.
Đọc target đã SENT hoặc CONTROL, chưa có conversion, theo keyset.
Chia batch tối đa 1.000 và gọi API của Task 04.
Chỉ ghi MATCHED; không coi UNKNOWN, INVALID hoặc response thiếu là chưa đạt Goal.
Chỉ commit cursor sau khi batch conversion đã ghi thành công.
Khi Campaign kết thúc, chạy lượt cuối rồi ngừng lên lịch.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

Process chết trước hoặc sau khi insert ClickHouse.
Lease hết hạn khi batch đang chạy.
OCS timeout, response thiếu ISDN hoặc trả UNKNOWN.
Campaign bị pause, cancel hoặc finish trong khi scheduler đang chạy.
Không có candidate vẫn phải kết thúc cycle đúng trạng thái.

Phụ thuộc

Phụ thuộc Task 01, Task 03 và Task 04.

Hoàn thành khi

Retry không bỏ sót và không làm tăng conversion report.
Cursor không tiến khi OCS hoặc ClickHouse lỗi.
Hai instance chạy đồng thời chỉ một instance claim được Campaign.

Task 06 - Lọc Goal khi chốt Target Snapshot và dừng gửi lại

Mục tiêu

Không đưa vào Run mới những khách đã đạt Goal trước khi gửi hoặc đã được ghi conversion trong Campaign.

Phạm vi thay đổi

Tích hợp pre-check Goal vào luồng build Target Snapshot của Campaign AUTO_OCS.
Đọc SegmentVersion member theo batch tối đa 1.000.
Gọi API OCS để loại khách đã đạt Goal tại thời điểm chốt target.
Anti-join campaign_conversion_event để loại khách đã conversion ở Run trước.
Chỉ freeze Target Snapshot khi toàn bộ batch được xác định thành công.
Campaign MANUAL_IMPORT không gọi OCS ở bước này; vẫn loại conversion đã import trước đó nếu Campaign tạo Run tiếp.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

OCS lỗi hoặc trả thiếu: fail bước build, không freeze snapshot thiếu dữ liệu.
Target đã conversion ở Run trước.
Một khách xuất hiện lặp trong SegmentVersion.
Snapshot retry không tạo target trùng.
Campaign MANUAL_IMPORT không có rules OCS.

Phụ thuộc

Phụ thuộc Task 02, Task 03 và Task 04.

Hoàn thành khi

Khách đã đạt Goal không nhận tin ở Run mới.
OCS lỗi không bị hiểu thành chưa đạt Goal.
Snapshot chỉ chuyển READY khi mọi batch hoàn tất.

Task 07 - API và trạng thái job import conversion thủ công

Mục tiêu

Cho phép FE tạo và theo dõi một lần import mà chưa xử lý dữ liệu file trong request HTTP.

Phạm vi thay đổi

Tạo collection campaign_conversion_import_job và index tại mục 6.4.
Tạo API bắt đầu import từ fileAssetId đã upload bằng File Asset/MinIO hiện có.
Tạo API xem chi tiết job, danh sách job có phân trang và tải file lỗi.
Kiểm tra company, quyền, Campaign, mode và trạng thái trước khi tạo job.
Chỉ cho phép MANUAL_IMPORT khi Campaign IN_PROGRESS, PAUSED hoặc FINISHED.
Enqueue background job và trả importJobId ngay.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

File asset không tồn tại, không thuộc company hoặc sai loại file.
Campaign AUTO, DRAFT, SUBMITTED, REJECTED hoặc CANCELLED.
Người dùng gọi lặp request tạo job.
Job đã chạy không được sửa fileAssetId.

Phụ thuộc

Phụ thuộc Task 01. Có thể phát triển song song với Task 02 sau khi contract Task 01 được chốt.

Hoàn thành khi

API trả nhanh, không đọc file trong request thread.
Danh sách lịch sử import có phân trang.
FE đọc được trạng thái và file lỗi của từng job.

Task 08 - Xử lý file import và ghi conversion

Mục tiêu

Đọc file lớn an toàn, ghi các dòng hợp lệ và trả file lỗi mà không làm mất toàn bộ job vì một dòng sai.

Phạm vi thay đổi

Claim job QUEUED thành RUNNING theo cách atomic.
Đọc CSV/Excel dạng stream; không load toàn bộ file vào RAM.
Validate header phone, converted_at, reference.
Normalize phone, loại trùng trong file và chia batch tối đa 1.000.
Match với Campaign target và lần SENT gần nhất; xử lý riêng CONTROL.
Dùng conversion store của Task 03 để batch insert.
Cập nhật counters sau mỗi batch.
Sinh file lỗi lên MinIO và kết thúc COMPLETED; chỉ dùng FAILED cho lỗi hệ thống không thể tiếp tục.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

Header sai hoặc file không đọc được.
Phone sai, trùng trong file, không thuộc target hoặc chưa gửi thành công.
converted_at trước thời điểm gửi/freeze.
Conversion đã tồn tại do import cũ hoặc retry.
Process chết giữa file; retry phải an toàn và counters không được cộng sai.

Phụ thuộc

Phụ thuộc Task 03 và Task 07.

Hoàn thành khi

Dòng sai không chặn dòng đúng.
Import lại không làm tăng conversion report.
Bộ nhớ không tăng theo tổng số dòng trong file.
File lỗi ghi rõ số dòng và error code, không chứa dữ liệu ngoài file nguồn.

Task 09 - Bổ sung conversion vào API báo cáo

Mục tiêu

Đưa conversion thật vào báo cáo Campaign, Run, A/B, channel và báo cáo tổng hợp company.

Phạm vi thay đổi

Bổ sung conversionCount và conversionRate vào Campaign summary.
Bổ sung series conversion theo converted_at.
Bổ sung conversion theo campaign_run_id, variant_code và channel.
Sửa A/B comparison dùng conversion của cả nhóm action và CONTROL.
Sửa Company conversion time series đọc campaign_conversion_event.
Loại bỏ cách dùng CampaignActionExecutionModel làm nguồn conversion.
Dùng uniqExact(conversion_id) và mẫu số distinct target.
Mọi query bắt buộc có company_id; API Campaign phải thêm campaign_id.

Luồng xử lý

[Diagram]

Trường hợp phải xử lý

Campaign chưa cấu hình Goal hoặc chưa có conversion.
Chỉ có nhóm CONTROL hoặc channel rỗng.
Một conversion event bị phát lại nhiều lần.
Mẫu số target bằng 0.
Lọc theo Run phải không lẫn dữ liệu Run khác.

Phụ thuộc

Phụ thuộc Task 03 để chốt schema và query contract. Có thể làm song song với Task 05, Task 06 và Task 08.

Hoàn thành khi

Report trả đúng conversion theo Campaign/Run/A-B/channel.
Không còn endpoint nào tính conversion từ action thực thi trong MongoDB.
Query có scope company và đạt ngưỡng hiệu suất đã thống nhất trên dữ liệu thử.

13. Cách chia việc cho ba nhánh song song

Không cần chờ hoàn thành toàn bộ một nhánh mới bắt đầu nhánh khác. Thứ tự đề xuất:

Giai đoạn	Nhánh A	Nhánh B	Nhánh C
Bắt đầu	Task 01 - Goal contract	Task 03 - ClickHouse conversion store	Task 04 - OCS Goal API
Sau khi nền tảng ổn định	Task 02 - Campaign/Run snapshot	Task 07 - Import job API	Task 05 - AUTO scheduler
Ghép luồng	Task 06 - Target pre-check	Task 08 - Import processor	Task 09 - Report

Sơ đồ phụ thuộc:

[Diagram]

Ba task phải được chốt contract sớm nhất là Task 01, Task 03 và Task 04. Sau khi ba contract này được merge hoặc thống nhất trên cùng branch tích hợp, các task còn lại có thể phát triển song song mà không tự định nghĩa lại model, schema hoặc response.

14. Thứ tự tích hợp cuối

Mốc 1: Task 01 + Task 03 + Task 04
Mốc 2: Task 02 + Task 05 + Task 07 + Task 09
Mốc 3: Task 06 + Task 08
Mốc 4: kiểm tra xuyên suốt AUTO_OCS và MANUAL_IMPORT

Hai luồng bắt buộc chạy xuyên suốt trước khi đóng nhóm task:

AUTO_OCS:
create -> approve -> snapshot pre-check -> send -> daily scan -> conversion -> report

MANUAL_IMPORT:
create -> approve -> send -> upload file -> import job -> conversion -> report

15. Phần bổ sung sau Task 01-09

Task 01-09 đã hoàn thành nên phần dưới đây được triển khai bằng một task độc lập. Không mở lại hoặc thay đổi tiêu chí nghiệm thu của các task cũ.

Phần bổ sung này mở rộng Goal với hai nhóm cấu hình còn thiếu trên màn tạo Campaign:

Thời gian ghi nhận chuyển đổi kể từ khi Campaign gửi tới khách hàng.
Chính sách dừng gửi và cho phép khách hàng quay lại Campaign.

Các quy tắc trong phần này thay thế hai giả định cũ đối với Campaign được tạo hoặc cập nhật sau khi Task 10 được triển khai:

attributionWindowDays không còn là giá trị cố định nằm ngoài Goal definition.
Scheduler không kết thúc việc tìm conversion ngay khi Campaign ngừng gửi; nó tiếp tục tới attribution deadline cuối cùng.

15.1. Cấu hình bổ sung

Các field được lưu cùng conversionGoal và được snapshot vào CampaignRunDefinitionSnapshot. FE không tự suy diễn giá trị mặc định.

{
  "conversionGoal": {
    "mode": "AUTO_OCS",
    "rules": [],
    "attributionWindowDays": 7,
    "stopPolicy": {
      "stopOnGoalAchieved": true,
      "noResponse": {
        "enabled": true,
        "consecutiveSentCount": 3
      },
      "reentry": {
        "enabled": true,
        "afterDays": 30
      }
    }
  }
}

Quy tắc validate:

Field	Quy tắc
`attributionWindowDays`	Bắt buộc khi có Goal, từ 1 đến 90 ngày.
`stopOnGoalAchieved`	Mặc định `true`.
`noResponse.enabled`	Mặc định `false`.
`noResponse.consecutiveSentCount`	Bắt buộc khi bật, từ 1 đến 100.
`reentry.enabled`	Mặc định `false`; chỉ được bật khi `noResponse.enabled=true`.
`reentry.afterDays`	Bắt buộc khi bật, từ 1 đến 365 ngày.

Campaign cũ không có các field mới được đọc với giá trị tương thích:

attributionWindowDays = 7
stopOnGoalAchieved = true
noResponse.enabled = false
reentry.enabled = false

Sau khi Campaign đã có Run đầu tiên, không cho sửa Goal hoặc stop policy vì Run cũ phải giữ nguyên definition đã chạy.

15.2. Thời gian ghi nhận chuyển đổi

Mỗi recipient có attribution window riêng, không lấy một mốc chung cho toàn Campaign.

attributionAnchor = thời điểm SENT gần nhất có thể quy conversion về recipient
attributionDeadline = attributionAnchor + attributionWindowDays

Conversion được ghi nhận khi:

attributionAnchor <= convertedAt <= attributionDeadline

Quy tắc theo nhóm:

Nhóm có action: anchor là event_time của delivery event SENT gần nhất trước conversion.
Nhóm CONTROL: anchor là frozenAt của TargetSnapshot vì nhóm này không có delivery event.
FAILED, SUPPRESSED và event retry trùng không tạo anchor.
Nếu một recipient được gửi ở Run sau, lần SENT mới tạo deadline mới; conversion được quy về lần gửi gần nhất hợp lệ.
MANUAL_IMPORT dùng convertedAt trong file để kiểm tra window.
AUTO_OCS chỉ ghi nhận khi scheduler phát hiện Goal trong window. OCS là current state nên không được tự suy đoán rằng Goal đã đạt trước deadline nếu lần quét đầu tiên nhìn thấy nó sau deadline.

Khi Campaign đã dừng gửi, scheduler vẫn scan các Run còn attribution window mở. Campaign chỉ hoàn tất phần conversion khi không còn recipient nào có attributionDeadline > now.

15.3. Điều kiện dừng khi đạt Goal

Nếu stopOnGoalAchieved=true, TargetSnapshot Builder loại recipient đã có conversion của Campaign trước khi chốt snapshot tiếp theo.

Nếu stopOnGoalAchieved=false, recipient vẫn có thể nhận bước hoặc Run tiếp theo. Conversion vẫn chỉ được đếm một lần cho mỗi recipient trong một Campaign theo idempotency contract hiện tại.

Snapshot đã chốt không bị sửa ngược. Worker gửi vẫn áp dụng final check hiện có nếu action yêu cầu chống gửi sau conversion.

15.4. Điều kiện dừng khi không phản hồi

Trong Task 10, “phản hồi” được định nghĩa là đạt Goal, không phải open hoặc click. Open/click không đồng nhất giữa SMS, Mail, WhatsApp, Push và nhóm CONTROL, nên không dùng làm tín hiệu reset bộ đếm.

Một lần thông báo liên tiếp được tính khi có một delivery event SENT duy nhất:

Không tính FAILED, SUPPRESSED hoặc provider callback lặp.
Dùng stable delivery event ID hoặc idempotency key để chống đếm trùng.
Nhóm CONTROL không tăng bộ đếm vì không thực sự nhận thông báo.

Trước khi tạo TargetSnapshot mới, hệ thống đếm số lần SENT kể từ countingStartedAt. Nếu recipient chưa đạt Goal và số lần gửi đạt consecutiveSentCount, recipient bị loại khỏi snapshot đang build và các snapshot sau.

Để tránh hiểu sai trên FE, nội dung nên hiển thị là:

Khách hàng chưa đạt mục tiêu sau [N] lần gửi thành công liên tiếp

15.5. Cho phép quay lại Campaign

Trong phạm vi Task 10, re-entry chỉ áp dụng cho recipient bị dừng vì NO_RESPONSE.

eligibleAgainAt = suppressedAt + reentry.afterDays

Khi tới eligibleAgainAt, recipient chỉ được xem xét lại nếu vẫn thuộc Segment/SegmentVersion nguồn của Run mới. Khi quay lại:

Chuyển trạng thái suppression về active.
Đặt lại countingStartedAt bằng thời điểm quay lại.
Không tính các delivery event cũ vào chu kỳ mới.

Nếu không bật re-entry, suppression NO_RESPONSE có hiệu lực tới khi Campaign kết thúc.

Không hỗ trợ quay lại sau khi đã đạt Goal trong task này. Muốn một khách hàng đạt Goal nhiều lần trong cùng Campaign phải bổ sung participationId/entryId và thay đổi contract “một conversion cho mỗi recipient trong một Campaign”; đây là một phạm vi nghiệp vụ khác.

15.6. Trạng thái vận hành

Không tạo Segment phụ và không sửa member của Segment nguồn. Chỉ lưu recipient thực sự đã bị dừng hoặc đã quay lại trong MongoDB collection campaign_recipient_suppression_state:

{
  "companyId": "companyId",
  "campaignId": "campaignId",
  "recipientKey": "sha256-normalized-recipient",
  "status": "SUPPRESSED_NO_RESPONSE",
  "countingStartedAt": "...",
  "suppressedAt": "...",
  "eligibleAgainAt": "...",
  "lastEvaluatedAt": "...",
  "version": 3,
  "updatedAt": "..."
}

Index bắt buộc:

db.campaign_recipient_suppression_state.createIndex(
  { companyId: 1, campaignId: 1, recipientKey: 1 },
  { unique: true, name: "campaign_recipient_suppression_unique_idx" }
)

db.campaign_recipient_suppression_state.createIndex(
  { companyId: 1, campaignId: 1, status: 1, eligibleAgainAt: 1 },
  { name: "campaign_recipient_suppression_reentry_idx" }
)

Không lưu raw phone/email. Recipient chưa từng bị suppress không cần tạo document; countingStartedAt mặc định là thời điểm Campaign bắt đầu gửi.

Số lần gửi được batch query từ campaign_delivery_event hiện có thay vì duy trì thêm một counter theo từng callback. Cách này giữ delivery event là nguồn đúng, chống retry và không tạo thêm một pipeline đồng bộ.

15.7. Thứ tự kiểm tra khi build TargetSnapshot

[Diagram]

Mọi phép đọc/ghi dùng batch tối đa 1.000 recipient. Không query Mongo hoặc ClickHouse từng recipient. Upsert suppression phải dùng version hoặc điều kiện trạng thái để hai node không cùng reset/suppress sai.

16. Task 10 - Attribution Window, Stop Policy và Re-entry

Mục tiêu

Bổ sung phần cấu hình còn thiếu của Conversion Goal mà không thay đổi dữ liệu và luồng đã hoàn thành ở Task 01-09.

Phạm vi BE

Bổ sung attributionWindowDays và stopPolicy vào request/response, model và Run definition snapshot.
Validate giá trị, quan hệ giữa no-response và re-entry, và khóa chỉnh sửa sau Run đầu tiên.
Mở rộng conversion scheduler để scan tới attribution deadline cuối cùng.
Sửa AUTO_OCS và MANUAL_IMPORT chỉ ghi conversion nằm trong attribution window.
Sửa TargetSnapshot Builder để stopOnGoalAchieved là cấu hình thay vì luôn bật.
Batch đếm distinct delivery event SENT theo Campaign và recipient.
Tạo model/repository/index campaign_recipient_suppression_state.
Suppress nguyên tử khi đủ số lần gửi mà chưa đạt Goal.
Cho phép re-entry đúng ngày, reset chu kỳ đếm và đánh giá lại Segment nguồn.
Giữ nguyên idempotency một conversion cho mỗi recipient trong một Campaign.
Không tạo Segment A', Segment hiệu hoặc copy Segment member để biểu diễn trạng thái dừng.

Phạm vi FE

Bổ sung lựa chọn thời gian ghi nhận chuyển đổi.
Bổ sung ba control như thiết kế: dừng khi đạt Goal, dừng sau N lần gửi thành công chưa đạt Goal, cho phép quay lại sau N ngày.
Chỉ bật control re-entry khi đã bật điều kiện no-response.
Hiển thị validation message từ error code backend.
Màn chi tiết Campaign và Run hiển thị policy snapshot thực tế đã dùng.

Mã lỗi bổ sung

CAMPAIGN_GOAL0011  Thời gian ghi nhận chuyển đổi không hợp lệ
CAMPAIGN_GOAL0012  Chính sách dừng Campaign không hợp lệ
CAMPAIGN_GOAL0013  Số lần gửi liên tiếp không hợp lệ
CAMPAIGN_GOAL0014  Cấu hình cho phép quay lại Campaign không hợp lệ
CAMPAIGN_GOAL0015  Không thể sửa Goal hoặc chính sách dừng sau khi Campaign đã chạy

Trường hợp bắt buộc

Trường hợp	Kết quả
Conversion nằm đúng attribution deadline	Được ghi nhận.
Conversion sau deadline	Không ghi nhận cho Campaign.
Campaign ngừng gửi nhưng window vẫn mở	Scheduler tiếp tục scan.
Recipient đạt Goal và bật stop	Không vào snapshot sau.
Recipient đạt Goal nhưng tắt stop	Vẫn có thể vào snapshot sau; conversion không nhân đôi.
Ba delivery event `SENT` khác nhau, chưa đạt Goal	Suppress trước lần gửi kế tiếp khi ngưỡng là 3.
Kafka/provider retry cùng một delivery event	Chỉ tính một lần.
Delivery `FAILED` hoặc `SUPPRESSED`	Không tăng bộ đếm.
Recipient thuộc nhóm `CONTROL`	Không tăng bộ đếm no-response.
Chưa tới `eligibleAgainAt`	Không vào snapshot.
Đã tới `eligibleAgainAt` nhưng không còn trong Segment nguồn	Không quay lại.
Đã tới `eligibleAgainAt` và còn trong Segment nguồn	Quay lại với bộ đếm mới bằng 0.
Hai builder cùng xử lý recipient	Chỉ một state transition thành công.

Kiểm thử tối thiểu

Unit test validate default, min/max và quan hệ giữa các option.
Unit test tính anchor/deadline cho action và CONTROL.
Integration test batch query distinct SENT, bỏ retry và status không hợp lệ.
Integration test suppress, re-entry và reset countingStartedAt.
End-to-end test AUTO_OCS: send -> đạt Goal trong window -> stop ở Run sau.
End-to-end test no-response: gửi đủ N lần -> suppress -> hết N ngày -> re-entry.
Regression test Campaign cũ không có field mới vẫn chạy với default tương thích.

Phụ thuộc

Task 10 bắt đầu sau khi Task 01-09 đã hoàn thành và tái sử dụng trực tiếp:

Goal contract và Run snapshot của Task 01-02.
Conversion store của Task 03.
Scheduler và TargetSnapshot pre-check của Task 05-06.
Delivery/conversion report data hiện có; không thay đổi cách tính report trong Task 09.

Hoàn thành khi

FE lưu và đọc lại đúng toàn bộ cấu hình trong ảnh thiết kế.
Conversion ngoài attribution window không xuất hiện trong report.
Customer đạt Goal hoặc đủ ngưỡng no-response bị loại đúng từ snapshot tiếp theo.
Re-entry không làm tính lại delivery cũ và không đưa customer đã rời Segment nguồn quay lại.
Campaign cũ không bị thay đổi hành vi ngoài các default đã nêu.
Không phát sinh Segment phụ hoặc pipeline event mới chỉ để lưu trạng thái dừng.

17. Mốc tích hợp bổ sung

Mốc 5: Task 10 - Attribution Window, Stop Policy và Re-entry

Task 10 nên được merge bằng một thay đổi độc lập sau Task 01-09. Migration chỉ tạo collection/index mới; không backfill suppression state và không sửa các conversion event đã ghi.

Thiết kế Goal và ghi nhận chuyển đổi cho Campaign

1. Mục tiêu

2. Hiện trạng và phần còn thiếu

3. Quy tắc chung

3.1. Mốc bắt đầu tính chuyển đổi

3.2. Hạn chế của dữ liệu OCS hiện tại

3.3. Chống ghi trùng

3.4. Quy tắc kết hợp điều kiện

4. Cấu hình Goal trên giao diện

4.1. Tự động từ OCS

4.2. Import thủ công

5. Cấu hình Goal cho năm Campaign

5.1. CAMP 1 - Chuyển đổi chéo BUs

5.2. CAMP 2 - Onboarding khách Online

5.3. CAMP 3 - Tải app chưa kích hoạt

5.4. CAMP 4 - Upgrade gói Data 50K

5.5. CAMP 5 - Phát triển thuê bao 4G

6. Thiết kế dữ liệu

6.1. MongoDB campaign

6.2. MongoDB campaign_run

6.3. MongoDB campaign_conversion_scan_state

6.4. MongoDB campaign_conversion_import_job

6.5. ClickHouse campaign_conversion_event

7. Luồng tự động từ OCS

7.1. Chốt target trước khi gửi

7.2. Quét conversion sau khi gửi

7.3. API OCS dùng cho Goal

8. Luồng import thủ công

8.1. Định dạng file

8.2. Luồng xử lý

8.3. Lỗi theo từng dòng

9. Luồng báo cáo

10. Các trường hợp phải xử lý

11. Log, bảo mật và hiệu suất

11.1. Log bắt buộc

11.2. Hiệu suất

11.3. Error code đa ngôn ngữ

12. Danh sách task triển khai

Task 01 - Khai báo Goal và validation dùng chung

Mục tiêu

Phạm vi thay đổi

Luồng xử lý

Trường hợp phải xử lý

Phụ thuộc

Hoàn thành khi

Task 02 - Lưu Goal vào Campaign và Campaign Run snapshot

Mục tiêu

Phạm vi thay đổi

Luồng xử lý

Trường hợp phải xử lý

Phụ thuộc

Hoàn thành khi

Task 03 - Tạo bảng ClickHouse và lớp lưu conversion dùng chung

Mục tiêu

Phạm vi thay đổi

Luồng xử lý

Trường hợp phải xử lý

Phụ thuộc

Hoàn thành khi

Task 04 - API OCS kiểm tra Goal theo batch

Mục tiêu

Phạm vi thay đổi

Luồng xử lý

Trường hợp phải xử lý

Phụ thuộc

Hoàn thành khi

Task 05 - Scheduler quét Goal tự động và quản lý checkpoint

Mục tiêu

Phạm vi thay đổi

Luồng xử lý

Trường hợp phải xử lý

Phụ thuộc

Hoàn thành khi

Task 06 - Lọc Goal khi chốt Target Snapshot và dừng gửi lại

Mục tiêu

Phạm vi thay đổi

Luồng xử lý

Trường hợp phải xử lý

Phụ thuộc

Hoàn thành khi

6.1. MongoDB `campaign`

6.2. MongoDB `campaign_run`

6.3. MongoDB `campaign_conversion_scan_state`

6.4. MongoDB `campaign_conversion_import_job`

6.5. ClickHouse `campaign_conversion_event`