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.
spCode của LaoCRM, giữ handler SMS/mail/WhatsApp v2. Không khôi phục worker_log.Đ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.
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.
/api/order theo mã cũ.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.
| Đ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.
| 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í |
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.
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.
| 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.
| 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.
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.
/api/order theo orderId cũ; 404, lỗi server hoặc mã đã tồn tại chưa tự chứng minh kết quả. Đối chiếu ví/tổng tiền/mô tả.AddUpointData đã có; VcgwRewardProvider chưa thực hiện. Thêm handler/client Unipay trong subscriber-action-worker, route qua RewardActionExecutor, không tạo worker mới.PriceQuoteCommonService; phí riêng = số điểm × đơn giá.TelecomActionExecutor → UniserviceClient. Mobile giữ phone/description/period từ action/event và sub-service cấu hình.renew_percentage từ event, nhân 100 và kiểm tra 0–100 như v1 (0.5 → 50). Thiếu giá trị thì dùng mặc định cấu hình; client không ghi đè percent từ event.Đâ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.