Bỏ qua

SMP · System Functional Overview

Audience: All roles (BA, Dev, QC, DevOps, Security, Stakeholder) · Reading time: 30–45 min

Doc này là executive summary mô tả toàn bộ chức năng hệ thống SMP. Đọc trước khi đi sâu vào các docs kỹ thuật khác.

📚 Current state: Outbox-first event pattern · Finance Ledger spec (Pattern 2 double-entry) · Legal policy pack (3 policies aligned với PDPL VN, NĐ 70/2025)

Mục lục

  1. SMP là gì
  2. Personas · Ai dùng hệ thống
  3. Module Map · 10 microservices
  4. Core Domain Concepts
  5. Feature Catalog · 6 epics
  6. End-to-end Flows · 5 luồng chính
  7. Module ↔ Feature Matrix
  8. Key Business Rules · Tóm tắt
  9. KPIs · Đo lường thành công
  10. Integration với hệ thống ngoài
  11. Roadmap · v3.1 → v3.3 → tương lai
  12. Quick links · Đào sâu

1. SMP là gì

SMP (Service Marketplace Platform) là nền tảng SaaS 3-sided marketplace chuyên cho dịch vụ kỹ thuật tận nơi (sửa điều hòa, máy giặt, điện nước, vệ sinh, lắp đặt thiết bị...) tại thị trường Việt Nam.

3 bên tham gia

 ┌─────────────┐
 │ CUSTOMER │ Khách hàng cuối · đặt đơn qua mobile app
 │ (B2C) │
 └──────┬──────┘
 │
 ▼
 ┌─────────────┐ ┌─────────────┐
 │ SMP CORE │ ◄─────► │ PARTNER │ Đối tác B2B (cty
 │ (3-sided) │ │ (B2B2C) │ bảo trì, chuỗi shop...)
 └──────┬──────┘ └─────────────┘
 │
 ▼
 ┌─────────────┐
 │ TECHNICIAN │ Thợ kỹ thuật (freelance hoặc thuộc partner)
 │ (Agent) │
 └─────────────┘

Giá trị cốt lõi

  • Với customer: đặt thợ trong 2 phút, biết giá trước, theo dõi real-time, bảo hành rõ ràng
  • Với technician: nhận đơn gần nhà, thanh toán nhanh, không lo lừa đảo
  • Với partner: outsource toàn bộ field operation, có dashboard quản lý, white-label được
  • Với SMP: thu commission per order + subscription fee từ partner

Tech stack tóm tắt

Layer Technology (v3.x) Bổ sung v4.0
Backend Go 1.22 · microservices polyrepo + antonmedv/expr (rules engine)
Primary DB MySQL 8.0 (transactional) + multi-currency schema, UTC, sharding
Cache + Queue Redis 7 + Redis Streams (light pub/sub)
Event Bus (none, sync HTTP) Apache Kafka (production), Debezium CDC
Read Model (query MySQL) Elasticsearch (dashboard, search, KPI)
Event store + audit MongoDB 6 (giữ nguyên)
Config env files + ConfigMap (rules_engine.yaml hot-reload)
Frontend Web Vanilla HTML/CSS/JS (admin) + i18n dictionary
Frontend Mobile PWA (customer + technician + partner) + locale switcher, currency formatter
Infrastructure Kubernetes · GitHub Actions · ArgoCD + region-based clusters (sovereignty)
Integration Webhooks + REST · với inside + wms + Kafka cross-region replication

Note: v3.4 (current) = docs phase, chưa code v4.0. Schema/architecture đang được design để forward-compatible.

2. Personas · Ai dùng hệ thống

Persona Channel Mô tả Quyền chính
👤 Customer Mobile PWA Khách hàng cuối · đặt dịch vụ tại nhà Tạo order, duyệt báo giá, rating, thanh toán
🔧 Technician (Agent) Mobile PWA Thợ kỹ thuật · có thể là Survey (SUR) / Execution (EXC) / Dual Nhận đơn, báo giá, upload photo proof, nhận tiền
🏢 Partner Owner Admin Web Chủ công ty đối tác B2B Đặt đơn cho khách cuối, quản lý wallet, xem báo cáo
💼 Partner Manager Admin Web Quản lý cấp giữa của partner Quản lý đội thợ partner, xem báo cáo team
📊 Partner Finance Admin Web Kế toán partner Topup wallet, xem invoice, export CSV
📞 Partner Dispatcher Admin Web Điều phối viên partner Tắt/bật agent, manual dispatch
👥 Partner End-user Mobile PWA Khách cuối của partner (đôi khi partner đặt giúp họ) Tracking + rating (limited)
🛠️ Ops Admin Admin Web Nhân viên vận hành SMP Approve KYC, manual dispatch, dispute, quản lý catalog
🎯 Ops Manager Admin Web Quản lý vận hành SMP Dashboard, surge config, partner approval
💰 Finance Admin Admin Web Tài chính SMP Payout thợ, reconcile, refund
👑 Super Admin Admin Web Root cấp cao nhất Full quyền + audit log access

Chi tiết RBAC scopes: xem Doc 08 · Auth Spec.

3. Module Map · 10 microservices

Hệ thống SMP chia thành 10 microservices, mỗi service own 1 database, communicate qua REST + Event bus (Kafka).

 ┌──────────────────────┐
 │ api-gateway │ Routing, auth, rate limit
 │ (Public entry) │
 └──────────┬───────────┘
 │
 ┌──────────────────────┼──────────────────────┐
 │ │ │
┌───────▼───────┐ ┌─────────▼────────┐ ┌─────────▼────────┐
│ order-svc │ │ dispatch-engine │ │ catalog-svc │
│ (đơn hàng) │◄──►│ (match đơn↔thợ) │ │ (service, BOM) │
└───────┬───────┘ └─────────┬────────┘ └──────────────────┘
 │ │
 │ ┌───────▼────────┐ ┌──────────────────┐
 │ │ agent-svc │ │ partner-svc │
 │ │ (quản lý thợ)│ │ (Partner B2B) │
 │ └────────────────┘ └──────────────────┘
 │
┌───────▼───────┐ ┌──────────────────┐ ┌──────────────────┐
│ finance-svc │ │ quality-svc │ │ integration-svc │
│ (ví, payout) │ │ (rating, photo) │ │ (inside, wms) │
└───────────────┘ └──────────────────┘ └──────────────────┘
 │
 ┌────────▼─────────┐
 │ notification-svc │
 │ (SMS, push, mail)│
 └──────────────────┘

Chi tiết từng module

🟦 1. api-gateway

Vai trò: Cổng vào duy nhất từ public internet Chức năng: - Routing request đến các services nội bộ - Authenticate JWT + verify scope - Rate limiting (per IP, per user, per tier) - Request logging + tracing header injection - CORS, security headers

Database: không own DB · stateless

🟦 2. order-svc

Vai trò: Quản lý toàn bộ vòng đời đơn hàng Chức năng: - Tạo order (customer direct, partner private, partner open) - 10-stage lifecycle: created → searching → quoted → approved → in_progress → completed → ... - Stage transitions với validation - Quote management (báo giá Survey) - Material consumption tracking (Execution) - Multi-agent step assignment : mỗi step có thể có lead + helpers + specialists với split ratio riêng. Xem Doc 02 §7.7, Doc 15 Section Q, Doc 16 §3.5. - Cancel/reschedule logic

Database: smp_order (MySQL) · core tables: orders, order_steps, order_step_agents , order_step_materials, order_stage_log

🟦 3. dispatch-engine

Vai trò: Tim agent phù hợp gửi đơn Chức năng: - Round-based dispatch (60s/round, max 5 rounds) - Filter qualified agents (skill, location, online, KYC, rating) - Send concurrent invitations (max 3-5 per round) - Surge multiplier calculation - Private dispatch (chỉ thợ partner) - Open dispatch with partner preference - Manual override cho Ops

Database: smp_dispatch (Redis cho queue, MySQL cho audit) · queue dispatch:queue:<round_id>

🟦 4. catalog-svc

Vai trò: Quản lý dữ liệu master Chức năng: - Service templates + steps + skills - Material types + variants + BOMs - Pricing rules per service/material - Coverage zones (geo)

Database: smp_catalog (MySQL) · 7 tables (skills, steps, services, service_steps, material_types, material_variants, step_boms)

🟦 5. agent-svc

Vai trò: Quản lý đời sống agent Chức năng: - Agent registration + KYC (basic, advanced, premium) - Skill assignment - Warehouse assignment (cho material stock) - Online/offline tracking (Redis) - Performance metrics (rating, completion rate) - Suspend/terminate flow

Database: smp_agent (MySQL) · agents, agent_skills, agent_warehouses, agent_kyc_docs

🟦 6. partner-svc

Vai trò: Quản lý Partner B2B (3-sided marketplace) Chức năng: - Partner onboarding (Type A/B/AB) - Partner admin users + RBAC (Owner/Manager/Finance/Dispatcher) - Wallet management (topup + auto-debit) - Invoice generation - Payout calculation (cho thợ thuộc partner) - Partner-specific pricing override

Database: smp_partner (MySQL) · partners, partner_admin_users, partner_wallet_transactions, partner_invoices, partner_payouts

🟦 7. finance-svc

Vai trò: Tiền bạc của SMP Chức năng: - Customer payment (qua inside) - Agent payout (T+7 schedule) - Refund processing - Commission calculation - Tax/VAT handling

Database: smp_finance (MySQL)

🟦 8. quality-svc

Vai trò: Chất lượng dịch vụ Chức năng: - Rating 1-5 sao (customer rate agent) - Photo proof storage + verification - Dispute management (auto trigger nếu rating <3) - KYC document review

Database: smp_quality_media (MongoDB) cho file paths + metadata

🟦 9. integration-svc

Vai trò: Đồng bộ với hệ thống ngoài Chức năng: - Sync customer từ inside (HRM/CRM nội bộ) - Sync payment status từ inside - Sync stock từ wms (warehouse management) - Circuit breaker pattern (nếu inside/wms down, không sập SMP) - Webhook outbound (gửi event ra cho partner)

Database: dùng MongoDB smp_events.event_log (TTL 90 ngày)

🟦 10. notification-svc

Vai trò: Gửi thông báo cho user Chức năng: - SMS OTP (qua Twilio/eSMS) - Push notification (FCM cho mobile) - Email (SendGrid) - Template management - Retry logic + dead letter queue

Database: dùng MongoDB cho log + Redis cho rate limit

Chi tiết kiến trúc + diagrams: xem Doc 01 · Architecture.

4. Core Domain Concepts

Các khái niệm cốt lõi cần hiểu trước khi đọc các docs khác:

Service Template & Step

Service = 1 gói dịch vụ end-to-end (vd "Sửa điều hòa tại nhà") Step = 1 công đoạn trong service (vd "Khảo sát" + "Sửa chữa") 1 service có 1-N steps. Mỗi step thuộc về 1 agent role.

Agent Role · 4 vai trò trong 1 order

Role Color Chức năng
SUR (Survey) 🟣 Violet Khảo sát, báo giá
EXC (Execution) 🟢 Teal Thực thi (sửa, lắp)
Dual Mixed Làm cả 2 (đơn nhỏ)
Pool Gray Standby, chưa assign

Order Lifecycle · 10 stages

01 created → 02 searching → 03 sur_assigned → 04 sur_arrived
→ 05 quoted → 06 approved → 07 exc_assigned → 08 exc_in_progress
→ 09 completed → 10 paid

[cancelled] có thể xảy ra ở bất kỳ stage nào ≤ 06

Skill

Kỹ năng cụ thể (vd "điện lạnh", "điện nước"). 1 step yêu cầu 1-N skills. Agent phải có skill matching mới qualified.

Material (BOM) · v3.2

  • Material Type: nhóm vật tư (vd "Ống đồng")
  • Material Variant: SKU cụ thể (vd "Ống đồng 6mm Daikin")
  • BOM: định mức vật tư cho 1 step (vd "Step lắp đặt cần 2m ống đồng + 1 quả cảm biến")

Dispatch · Round + Invitation

  • Round: 1 lượt gửi đơn (timeout 60s)
  • Invitation: 1 lời mời gửi đến 1 agent (max 3-5/round)
  • Escalate: hết round vẫn ko ai nhận → expand bán kính / surge

Partner Concepts · v3.3

  • Partner Type A: Đặt đơn giúp khách cuối (không có thợ riêng)
  • Partner Type B: Có thợ riêng, dùng SMP làm orchestration
  • Partner Type AB: Cả 2
  • Private Dispatch: chỉ gửi cho thợ thuộc partner
  • Open Dispatch: gửi cho pool SMP (có thể prefer partner)
  • Wallet: số dư trả trước cho partner để đặt đơn
  • Payout Mode: Direct (SMP trả thợ) / Via Partner (partner trả thợ)

Chi tiết: xem Doc 05 · Glossary (full bảng tra cứu A-M).

5. Feature Catalog · 6 epics

Toàn bộ chức năng hệ thống được tổ chức thành 6 epics, mỗi epic gồm nhiều user stories.

🎯 Epic 1 · Customer Order Journey

Mục đích: Khách đặt đơn nhanh, biết giá trước, theo dõi real-time

Story Mô tả Persona
US-1.1 Customer đặt đơn dịch vụ (chọn service, slot, voucher) Customer
US-1.2 Customer xem tracking 2 thợ (SUR + EXC) trên map Customer
US-1.3 Customer duyệt báo giá (approve/reject/negotiate) Customer

🔧 Epic 2 · Technician Work Flow

Mục đích: Thợ nhận đơn → khảo sát → báo giá → thực thi → photo proof

Story Mô tả Persona
US-2.1 Thợ nhận đơn từ dispatch (window 60s) Technician
US-2.2 Thợ Survey nhập báo giá với material picker (có stock check) Technician
US-2.3 Thợ Execution upload photo proof bắt buộc Technician

🏢 Epic 3 · Partner Platform

Mục đích: 3-sided marketplace · partner B2B dùng SMP làm orchestration

Story Mô tả Persona
US-3.1 Partner Owner đặt đơn cho khách cuối + wallet check Partner Owner
US-3.2 Partner Finance xem báo cáo + export CSV Partner Finance
US-3.3 Partner Dispatcher tắt agent tạm thời Partner Dispatcher
US-3.4 Ops admin onboard partner mới (approve KYC) Ops Admin

🧰 Epic 4 · Material BOM

Mục đích: Quản lý vật tư + định mức theo step

Story Mô tả Persona
US-4.1 Ops admin tạo Material Variant mới (auto-calc margin) Ops Admin
US-4.2 Ops verify free-form material (thợ nhập tay, ko trong catalog) Ops Admin

🔗 Epic 5 · Integration với inside/wms

Mục đích: Đồng bộ với hệ thống ngoài

Story Mô tả Persona
US-5.1 System sync customer data từ inside (với circuit breaker) System
US-5.2 Webhook payment.succeeded từ inside (HMAC verify) System

⭐ Epic 6 · Quality & Rating

Mục đích: Đảm bảo chất lượng dịch vụ

Story Mô tả Persona
US-6.1 Customer đánh giá thợ (1-5 sao, auto trigger dispute nếu <3) Customer

Chi tiết Gherkin + Acceptance Criteria: xem Doc 09 · User Stories.

6. End-to-end Flows · 5 luồng chính

Flow 1 · Customer Direct Order

[Customer mở app]
 ▼
[Chọn service + slot + địa chỉ]
 ▼
order-svc · POST /orders
 ▼ (event: OrderCreated)
dispatch-engine · tìm SUR agent
 ▼ (round 1, 60s)
[SUR agent nhận đơn] ──► agent-svc · update status
 ▼
[SUR đến tại nhà → khảo sát]
 ▼
[SUR nhập báo giá] ──► catalog-svc · query material price
 ▼
order-svc · POST /orders/:id/quote
 ▼ (notification gửi customer)
[Customer duyệt báo giá]
 ▼
order-svc · approve
 ▼ (event: QuoteApproved)
dispatch-engine · tìm EXC agent (có thể same SUR nếu Dual)
 ▼
[EXC thực thi → upload photo]
 ▼
order-svc · POST /orders/:id/complete
 ▼ (event: OrderCompleted)
finance-svc · trigger payment (qua inside)
 ▼
notification-svc · gửi receipt + rating prompt
 ▼
[Customer rating] ──► quality-svc · save rating
 ▼ (nếu <3: auto dispute)
[End]

Flow 2 · Partner Private Order

Tương tự Flow 1 nhưng: - Order tạo từ Partner admin với source=partner + partner_id=P001 - Trước khi tạo: check partner.wallet_balance >= estimated_cost - Dispatch chỉ gửi cho agents có partner_id=P001 (private dispatch) - Sau khi complete: auto-debit từ wallet (không cần payment từ customer) - Payout: tùy payout_mode của partner (Direct hoặc Via Partner)

Flow 3 · Material Check trong Quote

Khi SUR đang nhập báo giá: 

SUR app · search material "Ống đồng"
 ▼
catalog-svc · GET /materials?q=...
 ▼
integration-svc · check stock từ wms (parallel)
 ▼
[Nếu wms down: circuit breaker → fallback "stock unknown"]
 ▼
Return material list với stock indicator
 ▼
SUR chọn → nhập số lượng
 ▼
[Validate vs BOM: nếu vượt định mức cảnh báo]

Flow 4 · Dispatch Round với Surge

order-svc emit OrderCreated event
 ▼
dispatch-engine · pick up event
 ▼
Round 1 (radius 3km, base price)
 ├─ Filter qualified agents (skill, KYC, online, rating)
 ├─ Send 3 concurrent invitations
 └─ Wait 60s
 ▼
[Nếu có ai accept: assign, done]
[Nếu ko ai accept]
 ▼
Round 2 (radius 5km, surge 1.2x)
 ▼
Round 3 (radius 8km, surge 1.5x)
 ▼
Round 4 (radius 12km, surge 1.8x)
 ▼
Round 5 (radius unlimited, surge 2.0x)
 ▼
[Hết 5 rounds: escalate to Ops · manual dispatch]

Flow 5 · Partner Onboarding + KYC

Sales SMP đưa link onboarding cho partner
 ▼
Partner Owner đăng ký · partner-svc · POST /partners
 ▼ (status: pending_kyc)
Upload tài liệu (ĐKKD, MST, hợp đồng)
 ▼
Ops admin nhận task review · approve/reject
 ▼
[Nếu approve] partner-svc · update status=active
 ▼ (event: PartnerApproved)
Partner Owner tạo admin users (Manager, Finance, Dispatcher)
 ▼
Partner Owner topup wallet (vd 10M VND)
 ▼ (event: PartnerWalletToppedUp)
[Partner ready để đặt đơn]

7. Module ↔ Feature Matrix

Bảng này map mỗi user story đến các modules tham gia:

Story api-gw order dispatch catalog agent partner finance quality integration notification
US-1.1 Đặt đơn ✅ ✅ · ✅ · · · · ✅ (customer sync) ✅
US-1.2 Tracking ✅ ✅ · · ✅ · · · · ✅
US-1.3 Duyệt báo giá ✅ ✅ · · · · · · · ✅
US-2.1 Nhận đơn ✅ ✅ ✅ · ✅ · · · · ✅
US-2.2 Báo giá + material ✅ ✅ · ✅ · · · · ✅ (wms stock) ·
US-2.3 Photo proof ✅ ✅ · · · · · ✅ · ·
US-3.1 Partner Owner đặt đơn ✅ ✅ ✅ · · ✅ · · · ✅
US-3.2 Finance báo cáo ✅ · · · · ✅ ✅ · · ·
US-3.3 Tắt agent ✅ · · · ✅ ✅ · · · ✅
US-3.4 KYC partner ✅ · · · · ✅ · ✅ · ✅
US-4.1 Tạo material ✅ · · ✅ · · · · · ·
US-4.2 Verify free-form ✅ ✅ · ✅ · · · ✅ · ·
US-5.1 Sync customer · · · · · · · · ✅ ·
US-5.2 Webhook payment · ✅ · · · · ✅ · ✅ ·
US-6.1 Rating ✅ ✅ · · ✅ · · ✅ · ✅

Đọc bảng: vd US-1.1 đụng đến 5 modules (api-gw, order, catalog, integration, notification). Khi sửa US-1.1, cần test cả 5 modules.

8. Key Business Rules · Tóm tắt

Hệ thống có ~80 business rules được code hóa thành ID BR-<CATEGORY>-<NUM>. Đây là 15 rule quan trọng nhất:

Dispatch

  • BR-DISP-001: Round timeout 60s (config được, đang là 60s)
  • BR-DISP-002: Max 5 rounds trước khi escalate
  • BR-DISP-005: Private dispatch — chỉ thợ thuộc partner_id
  • BR-DISP-007: Surge multiplier theo round (1.0 / 1.2 / 1.5 / 1.8 / 2.0)

Pricing

  • BR-PRICE-001: Labor price theo level thợ (Junior 0.8x, Mid 1.0x, Senior 1.3x)
  • BR-PRICE-005: Voucher discount áp dụng trước VAT
  • BR-PRICE-006: Surge chỉ apply lên labor, không apply material
  • BR-PRICE-008: VAT 10% mặc định, partner có thể override

Payment

  • BR-PAY-001: Customer thanh toán sau khi complete (qua inside)
  • BR-PAY-003: Partner wallet topup tối thiểu 1M VND
  • BR-PAY-004: Auto-debit wallet ngay khi order completed (partner private)

KYC

  • BR-KYC-001: 3 levels (basic, advanced, premium) với quyền tăng dần
  • BR-KYC-002: Progression: basic → advanced sau 10 đơn rating ≥4

Stages

  • BR-STAGE-001: Stage transitions một chiều, không skip
  • BR-STAGE-005: Cancel cho phép ≤ stage 06 (approved), sau đó cần dispute

Quality

  • BR-QUALITY-001: Rating <3 sao auto tạo dispute ticket
  • BR-QUALITY-003: Photo proof bắt buộc trước khi mark completed

Chi tiết 80+ rules + formula: xem Doc 15 · Business Rules.

9. KPIs · Đo lường thành công

Hệ thống track 5 nhóm metrics:

🎯 Business (cho PM, Founder)

  • GMV: tổng giá trị đơn hàng (mục tiêu Y1: 50 tỷ VND)
  • Take rate: SMP revenue / GMV (target 15%)
  • AOV: giá trị trung bình/đơn (target 800k VND)
  • Repeat customer rate: % khách quay lại (target 40% sau 6 tháng)

⚙️ Operational (cho Ops Manager)

  • Order completion rate: % đơn complete / đơn create (target ≥85%)
  • Dispatch SLA: % đơn được assign trong 5 phút (target ≥90%)
  • Stuck orders: đơn kẹt > 24h (alert nếu > 10/ngày)

🔧 Agent (cho Agent Squad)

  • Active agents (DAU): thợ online ≥4h/ngày (target 60% pool)
  • Agent rating avg: trung bình rating (target ≥4.5)
  • Acceptance rate: % invitation được accept (target ≥40%)
  • No-show rate: % đơn thợ ko đến (target ≤2%)

🏢 Partner (cho Partner Squad)

  • Partner GMV: GMV từ partner orders (target 30% total Y2)
  • Wallet health: % partner có balance ≥ 5M (target ≥80%)

🛠️ Technical (cho Engineering)

  • API latency p95 < 500ms
  • Dispatch latency p95 < 2s
  • Uptime ≥99.9%
  • Error rate < 0.1%

Chi tiết formula + dashboard mapping: xem Doc 14 · KPI Metrics.

10. Integration với hệ thống ngoài

SMP không phải hệ thống isolated. Nó kết nối với:

inside · HRM/CRM nội bộ

  • Direction: Bidirectional
  • Data: Customer profiles, payment status, sales pipeline
  • Method: REST API + webhooks (HMAC SHA256)
  • Failover: Circuit breaker (5 fails → open 30s → half-open retry)

wms · Warehouse Management

  • Direction: SMP → wms (read stock) + wms → SMP (stock updates)
  • Data: Material stock per warehouse + reservation
  • Method: REST API
  • Use case: SUR app check stock khi nhập báo giá

Payment Gateways (qua inside)

  • VNPay, MoMo, ZaloPay
  • SMP không handle trực tiếp, route qua inside

SMS / Push / Email Providers

  • SMS: Twilio (backup eSMS Vietnam)
  • Push: Firebase Cloud Messaging
  • Email: SendGrid

Maps & Geocoding

  • Google Maps API (geocoding, distance matrix)
  • Mapbox (rendering ở mobile)

Chi tiết: xem Doc 01 · Architecture section 5 (Data flow) và Doc 03 · API Contract.

11. Roadmap · v3.1 → v3.3 → tương lai

v3.1 · 2-Agent Survey + Execution (đã release)

  • Tách Survey và Execution thành 2 agent roles
  • 10-stage order lifecycle
  • Geo coverage zones
  • 8-stage flow chính

v3.2 · Material BOM + inside/wms Integration (đã release)

  • Material types + variants + BOM
  • WMS stock check trong Survey
  • Customer sync từ inside
  • Payment integration

v3.3 · Partner Platform 3-sided (đã release · CURRENT)

  • Partner B2B với 4 roles
  • Private + Open dispatch
  • Wallet system
  • Partner pricing override
  • Mobile triple-mode (Customer + Tech + Partner)

v3.4 · Process Documentation + v4.0 Design (✅ COMPLETED · CURRENT)

  • ✅ 16 docs chuẩn hóa process cho team 10+
  • ✅ Doc 00 System Functional Overview
  • ✅ Doc tổng hợp + onboarding paths cho 6 roles
  • ✅ v4.0 architecture preview: Foundation terms, DB conventions, Rules Engine, Kafka, Masking, Compliance
  • ✅ (xem root repo)
  • 🔄 Deployed: GitHub Pages + Cloudflare (16 docs accessible)

v3.5 · DB foundations + Finance Ledger shadow (📅 planned · 8 weeks · EXPANDED)

  • ⏳ Refactor DB: multi-currency columns (amount + currency)
  • ⏳ Refactor DB: UTC timestamps (*_utc columns)
  • ⏳ Add country_code to user-tenant tables
  • ⏳ Create smp_global DB (countries, currencies, currency_rates, tax_configs, i18n_translations)
  • ⏳ Build Go packages: pkg/money, pkg/clock, pkg/timezone, pkg/i18n
  • ⏳ Linter rules forbid hardcoded VND + time.Now + hardcoded VAT
  • ⏳ NEW: Create smp_finance DB (6 tables: accounts, journal_entries, journal_lines, outbox, dead_letters, tax_configs)
  • ⏳ NEW: Seed Chart of Accounts (16 accounts)
  • ⏳ NEW: Build pkg/finance.PostJournal single-writer + TaxResolver + SplitBreakdown
  • ⏳ NEW: Outbox dispatcher goroutine + Redis dedup
  • ⏳ NEW: Dual-write shadow mode (legacy + ledger cùng cập nhật)
  • ⏳ NEW: Daily reconcile job (zero drift gate cho cutover)
  • 📖 Reference: Doc 02 section 2.5 + 7.6, Doc 04 section 1.15-1.15.2, Doc 16, Doc 18

v3.6 · Rules Engine YAML (📅 planned · 4 weeks)

  • ⏳ Build pkg/rules (antonmedv/expr + hot-reload via ConfigMap)
  • ⏳ Migrate 80+ rules từ Go code sang rules_engine.yaml
  • ⏳ Setup repo smp-rules-config riêng với BA-friendly PR workflow
  • ⏳ Rule ID convention mới: <country>.<category>.<num> (multi-country ready)
  • 📖 Reference: Doc 01 section 7.5, Doc 15 Appendix

v3.6.5 · Ledger cutover (📅 planned · 4 weeks · NEW · HIGH RISK)

  • ⏳ Pre-cutover gate: 30-day reconcile zero drift verified
  • ⏳ Switch read path: dashboards + APIs → subledger view
  • ⏳ Drop legacy tables: partner_wallet_transactions, etc.
  • ⏳ Remove dual-write code, simplify single-writer flow
  • 📖 Reference:

v3.7 · Event-driven + CQRS + CDC (📅 planned · 8 weeks · HIGH RISK)

  • 🔄 Prerequisite: Outbox stable từ v3.5. Phase này chỉ trigger khi đạt thresholds:
  • Order volume > 5,000/day
  • Consumer types > 10
  • Cần CDC → Elasticsearch
  • ⏳ Apache Kafka 3.7 KRaft cluster (3 brokers production)
  • ⏳ Migrate outbox → Kafka pipeline (Debezium binlog reader)
  • ⏳ 9 topics + DLQ
  • ⏳ Debezium MySQL → Kafka CDC pipeline
  • ⏳ Elasticsearch read model với ILM (hot 7d, warm 60d, cold 1y)
  • ⏳ Dashboard queries migrate sang ES (10x faster aggregations)
  • ⏳ Saga pattern cho long transactions
  • ⏳ Outbox pattern cho atomic write+publish
  • 📖 Reference: Doc 01 section 7.6, Doc 14 section 10.6, Doc 11 INC-006 to INC-009

v3.8 · Dynamic Data Masking + DSR (📅 planned · 6 weeks)

  • ⏳ API Gateway middleware auto-masks PII (default-deny)
  • ⏳ 9 PII unmask scopes (pii.unmask.phone, pii.unmask.bank_account...)
  • ⏳ Endpoint POST /pii/unmask cho sensitive fields với MFA-fresh
  • ⏳ Endpoint GET /pii/audit-trail cho DSR compliance
  • ⏳ Automated DSR export workflow (7-day SLA cho PDPA)
  • ⏳ Automated DSR deletion workflow (30-day grace + anonymize)
  • 📖 Reference: Doc 13 section 5.5, Doc 08 section 4.5, Doc 03 section 11.5

v4.0 GA · Multi-region Global Ready (📅 planned · Q4 2026 · 4 weeks final)

Quan trọng: v3.x = Vietnam-only. v4.0 = Global ready (Thailand, Indonesia, Philippines, US, China...).

4 nhóm cải tiến lớn (đã design đầy đủ trong v3.4 docs, sẽ implement Phase 1-4 above trước):

4.0.1 · Chuẩn hoá Quốc tế (Global Scaling)

  • Đa tiền tệ: Mọi cột tiền lưu kèm ISO 4217 currency code (VND, USD, CNY, THB...). Money type = { amount: BIGINT (minor units), currency_code: CHAR(3) }.
  • Thuế suất linh hoạt: Tax configuration per country + service category. VN VAT 10%, US Sales Tax theo bang, SG GST 9%.
  • Múi giờ UTC: Tất cả timestamp DB lưu UTC. Convert sang local timezone ở API Gateway/Frontend theo Asia/Ho_Chi_Minh, Asia/Bangkok...
  • Đa ngôn ngữ động: i18n_translations table (key, locale, value). Frontend lookup (key, locale) với fallback chain. Hỗ trợ Vietnamese, English, Thai, Indonesian, Chinese.

4.0.2 · Rules Engine Config-as-Code

  • Single file: rules_engine.yaml chứa 80+ business rules (dispatch, pricing, KYC, payment).
  • Storage: Kubernetes ConfigMap, mount vào pod, hot-reload khi update (no restart).
  • Library: antonmedv/expr (Go, ~20kb, sandbox eval expression).
  • Rule ID convention mới: <country>.<category>.<num> (vd vn.dispatch.001, us.pricing.005). Multi-country ready.
  • Hot Reload: file watcher monitor ConfigMap path, reload rules vào memory trong ~30s.

4.0.3 · Event-Driven Architecture (Kafka + CQRS + CDC)

  • Apache Kafka: replace HTTP sync calls cho dispatch + pricing. Topics: orders.events, payments.events, agents.events, partners.events.
  • Producers/Consumers: order-svc, dispatch-engine, finance-svc, notification-svc.
  • Partitioning: 12 partitions/topic, key = order_id để preserve order per entity.
  • CDC qua Debezium: capture MySQL binlog → publish Kafka → sink Elasticsearch/ClickHouse.
  • CQRS: Write side MySQL (transactional), Read side Elasticsearch (dashboard + search). Eventual consistency 1-5s.
  • Redis Streams: fallback nhẹ cho notification, GPS tracking (giảm tải MySQL).

4.0.4 · Security & Compliance Layer

  • Dynamic Data Masking: API Gateway middleware tự che PII (phone, email, bank acc) dựa trên scope của caller. CSKH thấy 0912****890, Finance thấy full.
  • Data Sovereignty: Sharding by country. Cluster smp-vn (Singapore), smp-cn (Beijing), smp-us (Virginia). Routing theo country_code.
  • Automated Reconciliation: Daily job đối soát partner wallet vs payment gateway, detect mismatch >0.01%, auto-alert Finance.
  • Compliance: PDPA (VN), CPRA (US California), PIPL (China), GDPR (EU). Right to Erasure (30 ngày), Data Portability (7 ngày), Breach notification 72h.

Migration strategy: 6 phases tuần tự (v3.5 → v3.6 → v3.6.5 → v3.7 → v3.8 → v4.0 GA), ~34 weeks total (REVISED post Tech Lead review). Each phase ships independently with rollback path. Xem chi tiết full plan ở

Khi đọc xong overview này, đào sâu theo nhu cầu:

Bạn muốn biết... Đọc doc
Kiến trúc kỹ thuật + diagram chi tiết Doc 01 · Architecture
Database schema, DDL, ERD Doc 02 · Database Schema
API endpoints, request/response Doc 03 · API Contract
Code conventions + dev setup Doc 04 · Coding Standards
Thuật ngữ, định nghĩa Doc 05 · Glossary
Environment configs (dev/staging/prod) Doc 06 · Env Matrix
CI/CD pipeline Doc 07 · CI/CD
Auth + RBAC chi tiết Doc 08 · Auth Spec
User stories + Gherkin acceptance Doc 09 · User Stories
Test plan + cases + bug template Doc 10 · Test Plan
Incident playbook (top 5 sự cố) Doc 11 · Runbook
Audit log spec Doc 12 · Audit Log
Data classification + encryption Doc 13 · Data Class
KPI formulas + dashboard Doc 14 · KPI Metrics
Business rules chi tiết (80+ rules) Doc 15 · Business Rules
Finance ledger · double-entry · journal templates Doc 16 · Finance Ledger Spec (v3.5+ DRAFT)
Payment & settlement state machine Doc 17 · Settlement Lifecycle (v3.5+ DRAFT)
Events catalog (Outbox + DLQ) Doc 18 · Event Catalog (v3.5+ DRAFT)
Service guarantee policy (warranty) Doc 19 · Service Guarantee (legal DRAFT)
COD payment policy (legal) Doc 20 · COD Payment Policy (legal DRAFT)
PDPL VN data policy Doc 21 · PDPL Data Policy (legal DRAFT)

Reading order cho onboarding

Stakeholder (CEO, Investor, Partner mới)

Đọc duy nhất doc này + xem demo. Đủ 30-45 phút.

Dev mới

  1. Doc 00 (this) — 45 min
  2. Doc 05 (Glossary) — 30 min
  3. Doc 01 (Architecture) — 1h
  4. Doc 04 (Setup) — 2h (vừa đọc vừa setup máy)
  5. Doc 02 (Schema) — 1h
  6. Doc 03 (API) — 1h
  7. Doc 08 (Auth) — 30 min Total: ~6h, có thể onboard trong 1 ngày

BA mới

  1. Doc 00 (this) — 45 min
  2. Doc 05 (Glossary) — 30 min
  3. SPEC v3.x (3 file product spec) — 2h
  4. Doc 09 (User Stories) — 1h
  5. Doc 15 (Business Rules) — 2h
  6. Doc 14 (KPI) — 30 min Total: ~6h

QC mới

  1. Doc 00 (this) — 45 min
  2. Doc 05 (Glossary) — 30 min
  3. Doc 09 (User Stories) — 1h
  4. Doc 15 (Business Rules) — 2h
  5. Doc 10 (Test Plan) — 1h
  6. Doc 03 (API contract) — 1h (để hiểu endpoint test) Total: ~6h

DevOps mới

  1. Doc 00 (this) — 45 min
  2. Doc 01 (Architecture) — 1h
  3. Doc 06 (Env Matrix) — 30 min
  4. Doc 07 (CI/CD) — 1h
  5. Doc 11 (Runbook) — 1h
  6. Doc 13 (Encryption) — 30 min Total: ~5h

Security Reviewer

  1. Doc 00 (this) — 45 min
  2. Doc 08 (Auth Spec) — 1h
  3. Doc 12 (Audit Log) — 30 min
  4. Doc 13 (Data Class) — 1h
  5. Doc 11 (Runbook) — 30 min Total: ~4h

Changelog

Version Date Author Changes
1.0 2026-05-27 Docs team Initial · gom từ docs 01, 05, 09, 14, 15

Maintainers: BA team + Tech lead Review cycle: mỗi sprint (2 tuần) hoặc khi có release mới Slack: #engineering-docs