Cấu hình thuế suất linh hoạt theo country + service category. VN: VAT 10% (mặc định), 8% (giảm tạm thời), 5% (một số ngành). US: Sales Tax theo bang. SG: GST 9%.
Currency Conversion Rate
Tỷ giá quy đổi giữa các currency. Lưu lịch sử theo ngày để báo cáo nhất quán. Source: ngân hàng trung ương hoặc API như exchangerate-api.com.
Money Type
Struct { amount: BIGINT, currency_code: CHAR(3) }. Không bao giờ lưu money như FLOAT (sai số). Amount lưu dạng minor units (cents/đồng, không decimal).
Multi-tenant
Một codebase phục vụ nhiều "tenants" (quốc gia/khách lớn) độc lập. Có thể chia logical (cùng DB, partition by tenant_id) hoặc physical (mỗi tenant 1 DB cluster).
i18n Dictionary (Open Dictionary)
Thay vì hardcode chuỗi tiếng Việt trong code, lưu vào i18n_translations table với key. Frontend lookup theo (key, locale). Vd: key order.status.in_progress, locale vi-VN → "Đang thực hiện", en-US → "In progress".
Locale Fallback
Nếu thiếu translation, fallback theo chain: requested locale → language only → default (en-US). Vd thiếu zh-HK → thử zh → fallback en-US.
Hệ thống không hardcode business rules vào Go code. Thay vào đó, dùng file YAML + library antonmedv/expr để eval expressions runtime. Cho phép update policy không cần deploy lại.
Thuật ngữ
Định nghĩa
Rules Engine
Component đọc rules từ file YAML, eval expressions với context input, return decision. Implementation: thư viện Go antonmedv/expr (lightweight, ~20kb).
Rule
1 quy tắc nghiệp vụ. Gồm id, when (predicate), then (action/value), priority, enabled. Vd rule "dispatch round timeout = 60s nếu country=VN, 90s nếu country=US".
Expression
Biểu thức logic/toán học. Cú pháp antonmedv/expr tương tự JavaScript. Vd: order.country == 'VN' && agent.rating >= 4.5.
Predicate
Expression trả về boolean. Dùng trong field when. Nếu predicate eval = true → rule active.
Context
Input data cho engine khi eval rule. Là 1 map/struct chứa các biến rule có thể reference. Vd { order, agent, customer, now }.
Action / Value
Output của rule. Có thể là 1 số (multiplier, fee), 1 string (status), hoặc 1 object (config).
Rule Priority
Nếu nhiều rule match cùng lúc, rule có priority cao hơn thắng. Default = 100. Rules đặc biệt set priority 1-10 hoặc 200+.
Hot Reload
Khả năng update rules trong production mà không restart service. Cơ chế: file watcher monitor ConfigMap mount path, reload vào memory khi file changes.
ConfigMap
Kubernetes resource lưu config (key-value hoặc whole files). Mount vào pod như volume. Update ConfigMap → file ở pod tự update sau ~30s.
Config-as-Code
Pattern: config + rules được version control trong Git, review qua PR, deploy qua CD. Không edit live trong UI admin (tránh sai sót, dễ rollback).
antonmedv/expr
Thư viện Go open source eval expression. Type-safe, sandbox (không exec arbitrary Go code), benchmark ~1µs/eval. Repo: https://github.com/expr-lang/expr
Decision Table
Cách biểu diễn rules dưới dạng bảng (input columns → output column). Tools như GoRules Zen có hỗ trợ. Hiện SMP chưa dùng — chỉ dùng YAML rules list.
Kiến trúc hiện tại (v3.x) chủ yếu request-response sync. v4.0 chuyển sang event-driven với Kafka cho dispatch + pricing, CDC cho reporting.
Thuật ngữ
Định nghĩa
Event
1 fact đã xảy ra trong hệ thống. Immutable. Vd OrderCreated, AgentAccepted, PaymentSucceeded. Format JSON với schema versioning.
Event Schema
Cấu trúc cố định của 1 event type. Có schema_version để backward-compatible khi evolve. Lưu trong Schema Registry (Confluent).
Producer
Service phát ra events. Vd order-svc produces OrderCreated.
Consumer
Service subscribe events. Vd dispatch-engine, notification-svc cùng consume OrderCreated.
Topic
Logical stream của Kafka. Group các events cùng loại. Vd topic orders.events, payments.events, agents.events.
Partition
Sub-stream trong 1 topic. Cho phép parallel processing. Số partition = parallelism tối đa. Khuyến nghị: 6-12 partitions/topic.
Partition Key
Field dùng để route event vào partition cụ thể. Cùng key → cùng partition → preserve order. SMP dùng order_id làm key cho orders.events.
Consumer Group
Group các consumer instance share workload. 1 partition chỉ assign cho 1 consumer trong group. Vd dispatch-engine có 3 replicas → cùng consumer group dispatch-engine-cg.
Offset
Position của consumer trong partition. Commit offset = "đã xử lý xong tới đây". Restart vẫn tiếp tục từ offset.
At-least-once delivery
Mặc định Kafka. Event có thể delivered nhiều lần nếu consumer crash trước commit. Consumer phải idempotent.
Exactly-once semantics (EOS)
Kafka transaction guarantee. Setup phức tạp + slower. SMP chọn at-least-once + idempotency cho đơn giản.
Dead Letter Queue (DLQ)
Topic riêng lưu events fail xử lý nhiều lần. Cho phép review thủ công sau. Naming: <topic>.dlq.
CQRS (Command Query Responsibility Segregation)
Pattern tách Write (Commands → MySQL) và Read (Queries → Elasticsearch/ClickHouse). Cho phép optimize 2 luồng riêng biệt.
Write Model
Schema optimized cho transaction (normalized, MySQL). Chỉ phục vụ ghi và validate.
Read Model
Schema optimized cho query (denormalized, Elasticsearch). Phục vụ dashboard, search, report. Sync từ Write Model qua CDC.
CDC (Change Data Capture)
Capture mọi INSERT/UPDATE/DELETE từ DB primary, publish sang Kafka. Tool chuẩn: Debezium (free, open source).
Debezium
Open source CDC connector cho MySQL/Postgres/Mongo. Đọc binlog → publish Kafka events. Production-grade, used by Uber/Netflix.
Eventual Consistency
Read Model "catch up" với Write Model sau 1-5 giây. Khi user đặt đơn xong → ngay UI confirm (Write OK) nhưng dashboard analytics sẽ update sau vài giây.
Saga Pattern
Quản lý long-running transaction qua nhiều services bằng sequence of events + compensation. Vd: nếu PaymentFailed sau OrderCreated → emit OrderCancelled (compensating action).
Outbox Pattern
Để đảm bảo "ghi DB + publish event" atomic, dùng outbox table. App ghi event vào outbox trong cùng transaction với business data. Debezium CDC pickup outbox → publish Kafka.
Idempotency Key
Header Idempotency-Key ở API request. Server cache result 24h theo key. Cùng key gọi lại → return cached response. Required cho payment, order create.
Khi scale global, các luật bảo vệ dữ liệu khác nhau giữa quốc gia. SMP phải design system tuân thủ được PDPA (VN), CPRA (US), PIPL (China), GDPR (EU).
Thuật ngữ
Định nghĩa
PII (Personally Identifiable Information)
Dữ liệu định danh cá nhân: tên, số điện thoại, email, địa chỉ, CCCD, STK ngân hàng. Bắt buộc bảo vệ ở mọi layer.
Dynamic Data Masking
Che dữ liệu PII khi return từ API tùy theo scope của user gọi. Vd CSKH thấy 0912****890, Finance Admin thấy full 0912345890. Implement tại API Gateway middleware.
Masking Rule
Cấu hình che dữ liệu cho 1 field. Format: {field: 'phone', pattern: 'first_3_last_3', required_scope: 'pii.unmask.phone'}.
Tokenization
Thay PII bằng token random, lưu mapping trong vault riêng. Mạnh hơn masking. Dùng cho card number (PCI-DSS).
Data Sovereignty
Yêu cầu pháp lý: dữ liệu công dân nước X phải lưu trên server đặt tại nước X. Ví dụ: PIPL (TQ) yêu cầu data citizen TQ lưu tại TQ; GDPR (EU) cho phép xuyên biên giới với điều kiện.
Data Residency
Concept tương tự sovereignty nhưng nhẹ hơn, do contract chứ không phải luật.
Sharding by Country
Strategy chia DB physical theo quốc gia. Vd: cluster smp-vn ở Singapore (gần VN), cluster smp-cn ở Beijing, cluster smp-us ở Virginia. Routing theo country_code của user.
Logical Sharding
Chia trong cùng 1 DB cluster bằng partition theo column. Nhẹ hơn physical sharding. Vd partition orders table by (country_code, created_at).
Right to Erasure
Quyền "bị quên" của user. Tất cả PII của họ phải xóa khỏi system trong X ngày sau khi yêu cầu. PDPA VN: 30 ngày. GDPR: 30 ngày. CPRA: 45 ngày.
Right to Data Portability
User có quyền yêu cầu export toàn bộ data của họ dạng máy đọc được (JSON/CSV). Trả trong 7 ngày (PDPA), 30 ngày (GDPR).
Consent Management
Hệ thống lưu trữ và verify user đã đồng ý cụ thể với từng mục đích xử lý data (vd: marketing, analytics, sharing với partner). Audit-able.
PDPA (Vietnam)
Personal Data Protection Act. Nghị định 13/2023/NĐ-CP. Hiệu lực 1/7/2023. Yêu cầu: consent, breach notification 72h, DPO appointment.
CPRA (California, US)
California Privacy Rights Act. Mở rộng từ CCPA. Yêu cầu opt-out of sale, sensitive PII categories, breach response.
PIPL (China)
Personal Information Protection Law. Hiệu lực 1/11/2021. Strict nhất: data localization mandatory, cross-border transfer cần security assessment của CAC.
GDPR (EU)
General Data Protection Regulation. Hiệu lực 2018. Phạt max 4% revenue toàn cầu.
DPO (Data Protection Officer)
Vai trò bắt buộc theo PDPA/GDPR. Responsible cho compliance, breach response, user requests.
Reconciliation (Đối soát)
Quy trình kiểm tra khớp 2 bộ data từ 2 sources khác nhau. Vd đối soát partner wallet (SMP DB) vs payment gateway transactions. Daily job.
Automated Reconciliation
Job tự động chạy hàng ngày, phát hiện mismatch (vd wallet SMP báo -10M nhưng gateway báo -10.1M), alert tới Finance.
Fraud Detection Rules
Rules engine pattern matching trên transaction stream để flag suspicious: top up từ nhiều IP, multiple wallets cùng device, abnormal velocity.
Breach Notification
Khi data breach xảy ra, phải báo cáo authority + users bị ảnh hưởng trong 72h (PDPA/GDPR), 60 days (CPRA).