Task: Hoàn thiện dispatcher/worker, thu phí theo lô và bổ sung UPoint/LaoTV

1. Mục tiêu và phạm vi

Triển khai một task chung cho action theo kiến trúc v2: phục hồi chuỗi A → B → C, giảm số lần gọi LaoCredit bằng thu phí theo lô, lưu được lịch sử phí từng action và bổ sung UPoint/LaoTV còn thiếu.

Điều kiện tích hợp: API LaoCredit hiện mô tả transfer đơn, orderId và tra giao dịch, chưa xác nhận hợp đồng gom phí. Task bao gồm chốt cách transfer tổng/mô tả/đối soát với LaoCredit, đặc biệt phí dịch vụ có số điện thoại. Chỉ bật gom nhiều command cho loại phí được xác nhận; loại chưa được phép dùng chế độ thu riêng, tức lô một command trong cùng pipeline. Không tự suy đoán quyền gom chỉ vì API nhận amount.

2. Sơ đồ tổng thể

[Diagram]

Bộ xử lý phí là nhóm consumer/service riêng trong campaign-dispatcher, dùng model/service chung trong common; không cần thêm microservice. Nhận lệnh chờ phí và lập lô độc lập với consumer quản lý tiến độ, không chặn toàn bộ dispatcher trong lúc chờ HTTP.

3. Luồng triển khai

Dispatcher

  1. Nhận event hoặc người nhận từ campaign run; dùng mã ổn định để tạo/lấy execution, không tạo lại khi Kafka redelivery.
  2. Trong transaction Mongo, tạo command đủ điều kiện, gắn activeCommandId và ghi outbox. Command có phí đi topic chờ phí; command không phí đi topic worker tương ứng.
  3. A thành công thì trong một transaction tạo B, chuyển execution và ghi outbox. Result A trùng không tạo/chuyển B lần hai.

Bộ xử lý phí

  1. Nhận command chờ phí, giải tham số, kiểm tra dữ liệu action/provider và chốt giá/request trước khi thu. Lưu trạng thái chờ bền vững trước khi xác nhận message; không chỉ giữ danh sách trong RAM.
  2. Đọc command đến hạn theo index, nhóm tương thích, lập lô và giữ ngân sách.
  3. Lưu danh sách, phí từng command, tổng tiền, request và orderId cố định. Chốt lô trước khi gọi transfer.
  4. Chuyển lô từ SEALED sang SENDING bằng cập nhật có điều kiện; chỉ tiến trình thắng được gọi transfer, ngoài transaction Mongo.
  5. Transfer xác nhận thành công: transaction cập nhật lô/transfer, tiêu thụ reservation, tăng cost đúng một lần và ghi outbox gửi các command được phép chạy cùng fact phí.
  6. Timeout/chưa rõ: lô UNKNOWN, giữ khoản liên quan, chưa phát command thực hiện; tra /api/order theo mã cũ.

Worker và kết quả

Worker đọc/claim command, kiểm tra phí đã xác nhận hoặc NOT_REQUIRED, kiểm tra pause/stop rồi ghi action SENDING trước khi gọi handler. Ghi kết quả + outbox trong transaction. Worker không gọi thu phí lần nữa.

Relay gửi có Kafka ACK, lỗi thì phát lại cùng mã. Dispatcher nhận result để chuyển tiến độ; analytics nhận fact để ghi lịch sử/thống kê. UNKNOWN/chờ không ép thành result thất bại cuối cùng.

4. Cách gom lô theo số dư và ngân sách

Điều kiện Quy tắc
Nhóm lô Cùng SP, campaign/run, ví gửi/nhận, đơn vị tiền và chính sách/mô tả phí được phép gom
Danh sách Chỉ command đã nhận và đủ điều kiện; B chưa có kết quả A thì chưa đưa vào lô
Tổng phí Tổng phí riêng đã chốt của các command; không ước đoán số event tương lai
Ngân sách Không vượt maxCost - cost - reservedCost khi campaign có maxCost
Số dư Dựa trên số dư ví được quan sát và khoản địa phương đã phân bổ chưa giải quyết; số dư cache không phải tiền được LaoCredit giữ
Đóng lô Đạt số command, tổng tiền tối đa hoặc hết thời gian chờ; cấu hình từng giới hạn
Không đủ tiền Chọn nhóm nhỏ hơn nếu phù hợp, command còn lại chờ/pause theo nghiệp vụ; không drop
Lô đã chốt Không thêm/bớt command, thay tổng tiền/request hoặc đổi orderId

Ví dụ: ví quan sát còn 1.000.000, campaign còn 300.000, command đủ điều kiện có tổng phí 120.000 → thu lô 120.000, không thu toàn bộ 300.000 hay số dư ví.

Không gọi /api/information từng command. Refresh số dư khi bắt đầu, theo thời hạn và sau tín hiệu thiếu tiền/đối soát; ghi thời điểm snapshot. Khi refresh phải đối chiếu các transfer đang SENDING/UNKNOWN và đã xác nhận để không trừ cùng khoản hai lần trong tính toán địa phương. Nếu chưa xác định được snapshot đã phản ánh giao dịch nào, giữ phân bổ theo hướng thận trọng hoặc chờ đối soát; không coi số dư mới là khoản tiền tự do hoàn toàn.

Trong LaoAds, điều phối một lượt lập/gửi lô theo mỗi ví gửi để các instance không cùng dùng một snapshot; giữ phần đã phân bổ bằng trạng thái Mongo có cập nhật có điều kiện. Ví UNKNOWN chưa đủ thông tin phải được kiểm soát trước khi cấp lô mới. Điều phối này không ngăn hệ thống bên ngoài dùng ví SP; LaoCredit vẫn là nơi quyết định transfer có thành công hay không.

Giữ công thức và danh sách phí v1: TOP_UP, ADD_MONEY, ADD_DATA, ADD_PROMOTION, ADD_SMS, ADD_CALL_MINUTES, NOTIFICATION_SMS, NOTIFICATION_MAIL, ADD_UPOINT. Chốt giá/đơn vị theo command; không tự thêm phí LaoTV/WhatsApp/Push hoặc gom các loại mô tả chưa được phép.

5. Bảng, lịch sử và sự kiện cần thêm/sửa

Bảng Thay đổi cần làm
campaign_action_execution — Mongo, có Execution key unique theo SP; quản lý chuỗi, nextActionIndex và activeCommandId; chuyển A → B nguyên tử
worker_command_state — Mongo, mới command/effect identity, execution/SP/campaign, tham số/giá/phí riêng, batchId, trạng thái phí/action, provider reference, attempt/lease, revision và đối soát
billing_batch — Mongo, mới batchId, SP/campaign/run, ví gửi/nhận, đơn vị, danh sách command có giới hạn và digest, tổng phí, orderId, SEALED/SENDING/SUCCESS/FAILED/UNKNOWN, attempt, thời điểm và kết quả đối soát
budget_reservation — Mongo, mới Một khoản giữ/command, batchId, campaign/SP, phí riêng và HELD/CONSUMED/RELEASED; ngân sách giữ cho lô bằng tổng các khoản
laocredit_transfer_record — Mongo, có Một giao dịch/lô: batchId/orderId, ví, tổng tiền, request/response tối thiểu, trạng thái và audit; không tạo một giao dịch ngoài cho từng command nữa
campaign — Mongo, có reservedCost, cập nhật ngân sách/cost nguyên tử và tiền chính xác; xử lý dữ liệu Double hiện có
event_outbox — Mongo, mới eventId/revision, topic/key, payload nhỏ/ref, lease/retryAt/publishedAt; lệnh chờ phí, lệnh được phép chạy và kết quả
campaign_action_event — ClickHouse, mới Kết quả từng action: command/source/batch identity, SP/campaign, status/revision/thời gian/provider
campaign_fee_event — ClickHouse, mới Phân bổ phí từng command: batchId/orderId/commandId, số tiền/đơn vị, status/revision; liên kết giao dịch tổng để đối chiếu
Price quote model/API — có Thêm giá UPoint và mapping tính phí

5.1. Quy ước trường

Các trường dưới đây là hợp đồng thiết kế cần triển khai. Mongo dùng camelCase, ClickHouse dùng snake_case. ID dùng String; số tiền dùng BigDecimal lưu Decimal128 ở Mongo và Decimal ở ClickHouse, không Double. Chốt precision/scale và làm tròn theo đơn vị LaoCredit trước khi viết migration; không tự chuyển point thành KIP.

Các bảng trạng thái mới có createdAt, updatedAt (thời điểm UTC), revision (Long, cập nhật có điều kiện). Trường dùng cho scanner như nextCheckAt, leaseUntil, retryAt phải là thời điểm có index. Trường provider, batch hoặc kết quả chưa xuất hiện được phép null theo trạng thái; trường định danh không được null khi bắt đầu bước liên quan. Không lưu token/password trong snapshot.

5.2. Mongo — bảng mới

worker_command_state: một bản ghi cho một action

Trường Kiểu Ý nghĩa
_id String commandId ổn định, khóa chính
effectKey String Khóa chống tạo lại cùng action, unique cùng spCode
executionId, spCode, campaignId, sourceEventId String Liên kết execution/phạm vi/đầu vào; sourceEventId dành cho đầu vào event
campaignRunId, targetSnapshotId, recipientKey String Liên kết lần chạy/người nhận; run/snapshot có thể null với event
groupIndex, actionIndex Integer Vị trí chuỗi và action
workerType, actionType String/enum Chọn worker/handler
resolvedParams Object Tham số action đã giải, đủ phục hồi; không bản sao toàn bộ event
priceSnapshot Object quoteId/version, unitPrice, timePrice, isTimePricePercentage, quantity, durationDays và amountUnit đã chốt
feeAmount, currency Decimal, String Phí riêng của command và đơn vị thanh toán
batchId String Lô đang có hiệu lực cho khoản phí; null trước gom hoặc không thu phí
feeStatus enum NOT_REQUIRED/READY/SEALED/SENDING/SUCCESS/FAILED/UNKNOWN
actionStatus enum READY/SENDING/SUCCESS/FAILED/UNKNOWN; READY chưa cho phép gọi nếu phí chưa được xác nhận
commandStatus enum WAITING_BILLING/WAITING_BUDGET/READY/PROCESSING/WAITING_RECONCILIATION/SUCCEEDED/FAILED/CANCELLED
providerRequestId, providerReference, providerRequest String, String, Object Mã/request cố định trước gọi và tham chiếu provider sau gọi
actionResult Object Kết quả tối thiểu để trả lại dispatcher và kiểm chứng; phân biệt lỗi xác định với UNKNOWN
attemptToken, leaseOwner, leaseUntil String, String, Date Quyền xử lý hiện tại; token của bước gọi, lease không cấp quyền retry HTTP
actionStartedAt, completedAt, nextCheckAt Date Mốc gọi/kết thúc và đối soát/phục hồi
lastErrorCode, lastErrorMessage, reconcileCheckCount String, String, Integer Lỗi gọn và số lần tra cứu, không phải số lần retry action

Index: unique (spCode,effectKey); (commandStatus,nextCheckAt), (batchId,feeStatus), (executionId,actionIndex) và lease expiry theo truy vấn scanner. _id tra command trực tiếp.

billing_batch: lô đã chốt để thu một lần

Trường Kiểu Ý nghĩa
_id String batchId
spCode, campaignId, campaignRunId String Phạm vi lô; campaignRunId có thể null với event
fromWalletId, toWalletId, currency, transferType String Ví/đơn vị và loại phí, không gom khác nhóm
billingPolicyKey, description String Chính sách/format mô tả đã được LaoCredit xác nhận
commandIds, commandCount, membershipDigest Array<String>, Integer, String Danh sách có giới hạn, số command và dấu kiểm tra danh sách bất biến; phí riêng lưu ở command
totalAmount, orderId, transferRecordId Decimal, String, String Tổng phí và giao dịch ngoài liên quan
balanceSnapshot Object walletBalance, observedAt, localAllocatedAmountAtPlan và availableAmountAtPlan; chỉ bằng chứng lập lô, không hold thật
transferRequest Object fromWalletId/toWalletId/amount/description/orderId đã chốt, không chứa API key
status enum SEALED/SENDING/SUCCESS/FAILED/UNKNOWN/CANCELLED; CANCELLED chỉ trước gửi hoặc có xác minh nội bộ chắc chắn chưa gọi
sealedAt, sendingAt, confirmedAt, nextCheckAt Date Thời điểm chốt/gọi/xác nhận/tra cứu
attemptToken, leaseOwner, leaseUntil String, String, Date Claim phối hợp theo ví và bước gọi
allocationAppliedAt Date Transaction đã áp phí/reservation/command; chưa có thì chưa mở lô cho worker
replacesBatchId, failureCode, failureReason, reconcileCheckCount String, String, String, Integer Truy lô cũ đã xác nhận chưa thu và thông tin kiểm tra; UNKNOWN không được thay lô
reconciliation Object nguồn xác nhận, người thực hiện nếu thủ công, thời điểm, kết quả và bằng chứng/tham chiếu

Index: unique orderId; (spCode,campaignId,createdAt), (status,nextCheckAt). Trong phạm vi điều phối một lô chưa giải quyết/ ví gửi, dùng khóa/index partial unique theo fromWalletId cho SEALED/SENDING/UNKNOWN; giải phóng quyền chỉ sau kết quả xác định. Lease hết hạn của SENDING/UNKNOWN chỉ mở quyền đối soát, không tạo thêm lô thu tiền. Nếu backend/version không hỗ trợ cấu hình index đó phải chốt cơ chế claim tương đương trước triển khai.

budget_reservation: phần phí riêng được giữ

Trường Kiểu Ý nghĩa
_id, batchId, spCode, campaignId String _id=commandId, liên kết lô/campaign
amount, currency Decimal, String Phí giữ của command
status enum HELD/CONSUMED/RELEASED
transferRecordId, heldAt, consumedAt, releasedAt String, Date, Date, Date Chứng từ và mốc chuyển khoản giữ
releaseReason String Vì sao giải phóng; không release khi UNKNOWN

Index: _id unique command; (batchId,status), (campaignId,status). Chuyển lô sau từ chối xác định cập nhật version/batchId có điều kiện, giữ dấu lô cũ ở lịch sử lô; không tạo khoản giữ thứ hai cho cùng command.

event_outbox: thông báo cần gửi

Trường Kiểu Ý nghĩa
_id String eventId ổn định; dùng luôn làm mã message, không thêm một ID ngẫu nhiên khác
aggregateType, aggregateId, aggregateRevision, eventType String, String, Long, String Đối tượng và phiên bản thay đổi: execution/command/batch
spCode, campaignId, commandId, batchId String Phạm vi liên kết; các ID không áp dụng có thể null
topic, partitionKey, schemaVersion String, String, Integer Đích gửi và hợp đồng message
payload, payloadRef Object, Object Chọn một: nội dung gọn hoặc tham chiếu bền vững đủ dựng đúng message/revision đã chốt
status enum PENDING/PUBLISHING/PUBLISHED
publishAttempts, retryAt, publishedAt Integer, Date, Date Số lần gửi Kafka, lần gửi tới và broker ACK
leaseOwner, leaseUntil, lastErrorCode, lastErrorMessage String, Date, String, String Claim relay/lỗi gửi, không trạng thái action

Index: (status,retryAt), (status,leaseUntil); unique theo _id. Có thể thêm unique (aggregateType,aggregateId,aggregateRevision,eventType) nếu mỗi loại thông báo chỉ có một đích; khi một thay đổi có nhiều đích phải đưa đích vào khóa. Chỉ TTL bản PUBLISHED qua thời gian an toàn.

5.3. Mongo — bảng đang có cần sửa

Bảng Thêm / sửa trường cụ thể
campaign_action_execution Thêm spCode:String, sourceEventId:String, recipientKey:String, revision:Long, waitingReason:String, nextCheckAt:Date. Sửa cách dùng baseIdempotencyKey hiện có thành khóa ổn định và unique cùng SP; không thêm executionKey trùng chức năng. Giữ campaignId/campaignRunId/targetSnapshotId/requestId/groupIndex/chainCode/variantCode/actions/event/nextActionIndex/activeCommandId/status/failureReason. Status bổ sung trạng thái chờ phí, chờ ngân sách, chờ đối soát và dừng nếu cần; không đổi chờ thành FAILED. Tiến độ và command/outbox cập nhật cùng transaction
campaign Thêm reservedCost:Decimal mặc định 0. Đổi kiểu lưu/tính cost/maxCost/expectedCost từ Double sang Decimal, có migration và quy tắc làm tròn; maxCost null giữ nghĩa không giới hạn. currency, priceQuoteId, priceQuoteVersion, priceSnapshot đã có: dùng lại, không thêm trùng
laocredit_transfer_record Thêm batchId:String, currency:String, requestSnapshot:Object, attemptToken:String, sendingAt/confirmedAt/nextCheckAt:Date, allocationAppliedAt:Date, revision:Long, reconciliation:Object. Sửa status có SENDING/UNKNOWN ngoài trạng thái cũ; orderId unique và cố định theo lô. Giữ campaignId/spCode/fromWalletId/toWalletId/amount/description/transferType/response/errorMessage/createdAt/updatedAt; amount đã là BigDecimal, không khai báo là trường mới. requestId cũ có thể null cho giao dịch lô, không gán requestId của một action làm danh tính cả lô
price_quote Thêm addUPoint:PriceModel; cùng tên trong CreatePriceQuoteRequest/UpdatePriceQuoteRequest (PriceModelRequest) và PriceQuoteDto (PriceModel). PriceQuoteCommonService map ADD_UPOINT. Rà phép tính/kiểu unitPrice,timePrice hiện Double để chốt tiền chính xác, không đổi công thức v1

Index bổ sung: execution unique (spCode,baseIdempotencyKey) và đường scanner (status,nextCheckAt); transfer unique orderId, (batchId), (status,nextCheckAt). Kiểm tra dữ liệu trùng/cũ và backfill trước khi bật unique; không tạo index rồi bỏ qua lỗi.

RegisterRenewableNochargePackageRequest là DTO gọi API, không phải bảng: thêm percent:Double, lấy/validate theo mục LaoTV. Config bổ sung third-party-client.uniservice.renewable-nocharge.percent; không thêm trường DB riêng chỉ để lưu lại config. Percent đã giải được giữ trong resolvedParams/providerRequest của command.

5.4. ClickHouse — hai bảng mới

Bảng Trường cần có
campaign_action_event event_id:String, source_event_id:Nullable(String), command_id:String, execution_id:String, batch_id:Nullable(String), sp_code:String, campaign_id:String, campaign_run_id/target_snapshot_id:Nullable(String), recipient_key:String, group_index/action_index:UInt32, action_type/worker_type:String, action_status:String, source_revision:UInt64, provider_request_id/provider_reference/error_code/error_message:Nullable(String), event_time:DateTime64(3,'UTC'), completed_at:Nullable(DateTime64(3,'UTC')), ingested_at:DateTime64(3,'UTC')
campaign_fee_event event_id:String, command_id:String, batch_id:String, order_id:String, transfer_id:Nullable(String), sp_code/campaign_id:String, campaign_run_id:Nullable(String), action_type:String, fee_amount:Decimal, currency/fee_status:String, source_revision:UInt64, event_time:DateTime64(3,'UTC'), debited_at:Nullable(DateTime64(3,'UTC')), ingested_at:DateTime64(3,'UTC'). Mỗi dòng là phí phân bổ command, không thêm totalAmount của lô vào cùng dữ liệu để SUM

Partition đề xuất theo tháng event_time, order key phục vụ (sp_code,campaign_id,event_time,command_id). Chốt scale/precision Decimal và cách chuẩn hóa eventId/revision trước viết DDL; ClickHouse order key không bảo đảm unique. Tra cứu ngoài phạm vi thời gian/campaign cần đường tìm từ Mongo command/order, không mặc định quét cả lịch sử. Bảng tổng hợp dùng các trường này theo metric đã chốt, không là nguồn chứng từ mới.

5.5. Quan hệ và lịch sử

campaign_action_execution._id
    → worker_command_state.executionId
worker_command_state._id = budget_reservation._id = commandId
worker_command_state.batchId → billing_batch._id
billing_batch.transferRecordId → laocredit_transfer_record._id
billing_batch.orderId = laocredit_transfer_record.orderId

Lịch sử phải xem được cả hai cấp: một giao dịch tổng của lô và phí của từng action trong lô. Tổng phân bổ phải bằng tiền lô. Dữ liệu fee event từng command là phân bổ của cùng giao dịch, không cộng thêm tổng lô vào cùng metric để đếm tiền hai lần. Mongo giữ chứng từ, ClickHouse phục vụ tra cứu/thống kê; không suy phí từ quote hiện tại.

Transaction chốt lô phải claim command chưa có lô, tạo reservation/cập nhật reservedCost và ghi lô nguyên tử. Giới hạn số command để transaction/document không quá lớn. Ghi lô và command bền vững, không một file/document chứa cả triệu command. Nếu cần triển khai theo chunk, lô chỉ được mở cho worker khi phân bổ đã hoàn tất và có checkpoint phục hồi; không cho worker chạy từ cập nhật thành công một phần.

Unique execution/effect key theo SP, reservation theo command, transfer orderId, batch identity và outbox eventId. Command chỉ thuộc một lô có hiệu lực cho khoản phí đó. Lô cũ chỉ được giải phóng membership sau xác nhận không thu và audit; tuyệt đối không chuyển command khỏi lô UNKNOWN sang lô khác để thu lại. Scanner có index theo trạng thái/thời điểm/lease; lịch sử truy theo SP/campaign/batch/command/orderId.

Thêm topic logic campaign-billing-request cho command chờ phí; giữ topic command theo worker cho lệnh được phép thực hiện và campaign-action-result cho điều khiển chuỗi. Thêm fact campaign-action-event/campaign-fee-event; message có sourceEventId, executionId, commandId, batchId nếu có, eventId/revision. Topic/group lấy từ cấu hình theo quy ước repo.

6. Rule ngân sách, timeout và phục hồi

7. UPoint và LaoTV trong cùng task

UPoint — ADD_UPOINT

LaoTV — Mobile / FTTH

8. Phần triển khai và điều kiện hoàn thành

Đây là các phần của một task:

Module Phần phải hoàn thành
common Model/repository/index/message, billing batch/reservation/phân bổ, outbox, command state; price quote UPoint/DTO LaoTV; LaoCredit client pool và đối soát
campaign-dispatcher Transaction tiến độ, billing consumer/coordinator có giới hạn, số dư và gom lô, relay, scanner phục hồi/cảnh báo
Các worker v2 Nhận lệnh đã được phép, không thu phí lại; handler v2 và state/UNKNOWN; không drop khi rate limit hoặc dùng Redis key làm kết quả
subscriber-action-worker Hoàn thiện UPoint/Unipay và tham số LaoTV
API/analytics Giá UPoint; lịch sử lô/giao dịch và phân bổ từng action; fact/revision/chống đếm trùng, thống kê/dataAsOf

Hoàn thành khi:

Tham chiếu: v1 C:\Code\laoads-be; C:\Users\Lenovo\Documents\laoads\5.Laocredit_ APIs for LaoAds.pdf. Chốt với LaoCredit loại phí được gom, format mô tả lô, quota, phạm vi orderId trùng và ý nghĩa/độ trễ tra giao dịch. Không bật gom đa-command cho loại chưa xác nhận.