EN
SaaS
Đang vận hành

S Finance — SaaS quản lý chi tiêu & công nợ

Nền tảng SaaS đa tenant quản lý chi tiêu, khoản vay, thấu chi và cho vay đối tác: nhập sao kê ngân hàng bằng LLM, dashboard tuỳ biến, trợ lý AI và MCP server 29 tool để agent đọc/ghi dữ liệu tài chính — mỗi tenant một subdomain, cô lập bằng PostgreSQL Row-Level Security.

Thiết kế & phát triển (backend, frontend, hạ tầng)

finance.devbyspark.com
S Finance — SaaS quản lý chi tiêu & công nợ

29

Tool MCP

3

Tenant đang chạy

33 mã

Ngân hàng hỗ trợ

300+

Test tự động

Bối cảnh

Chi tiêu cá nhân, khoản vay thế chấp, thấu chi và các khoản cho đối tác vay lại nằm rải rác ở sao kê nhiều ngân hàng và vài bảng tính. Mỗi tháng phải đối chiếu tay: tiền nào đã trả, lãi bao nhiêu, đối tác còn nợ bao nhiêu. SPARK Finance gom tất cả về một chỗ — rồi được tách thành SaaS đa tenant để người khác cũng dùng được trên cùng hệ thống.

Tính năng chính

  • Nhập sao kê bằng AI: nhận PDF, ảnh, CSV, XLSX. Trình duyệt tách trang PDF (pdf.js) / chuyển XLSX sang CSV, tải file thẳng lên Cloudflare R2 bằng presigned URL; LLM (qua 9Router) đọc từng trang (~6 giây/trang) và tạo bản nháp — không ghi gì vào sổ cho tới khi người dùng bấm Nhập. Chống nhập trùng bằng sha256, kiểm tra số dư liên tục giữa các kỳ, nhập theo lô.
  • Giao dịch & phân loại: danh mục, quy tắc tự phân loại (xem trước rồi áp dụng), xu hướng theo danh mục, dòng tiền theo tháng, nguồn thu và chi phí cố định.
  • Khoản vay & thấu chi: dư nợ, lãi ước tính, theo dõi rút/trả thấu chi và đối chiếu dòng tiền.
  • Cho vay đối tác: lãi tính theo ngày dư nợ × lãi suất/365 × số ngày, nhiều giai đoạn lãi suất, điều chỉnh tay, dựng lại từ giao dịch. Đối tác đăng nhập bằng mã 6 số, tự báo đã trả qua VietQR; chủ khoản vay xác nhận qua Telegram bot.
  • Liên kết tenant: bên cho vay mời bên vay; bên vay xem được khoản vay của mình, hai bên đối chiếu khoản vay và chuyển khoản tự động (lệch ±3 ngày).
  • Dashboard kéo thả: 9 loại widget, cộng widget biểu đồ do trợ lý AI dựng từ một câu lệnh.
  • Trợ lý AI: chat SSE qua SPARK AI Gateway (agent finance-assistant); Gateway gọi ngược tool nội bộ của Finance bằng request ký HMAC. Agent chỉ được gọi tool đọc, mọi thao tác ghi đi qua thẻ xác nhận.

SaaS đa tenant

  • Mỗi tenant một subdomain <tenant>.finance.devbyspark.com; tenant chỉ được xác định từ subdomain, khoá API đã xác thực hoặc session do server ký — không bao giờ từ header, query hay body.
  • Cô lập 4 lớp: kiểu tenant.ID riêng, pool kết nối từ chối truy vấn thiếu tenant, giá trị mặc định + WITH CHECK của PostgreSQL Row-Level Security, và điều kiện USING của RLS. Tenant đi theo context.Context nên các hàm repository không phải đổi chữ ký; khoá ngoại chuyển sang khoá ghép (tenant_id, …).
  • Cấp tenant tự động: superadmin tạo tenant, backend commit Ingress của subdomain vào repo GitOps qua GitHub API, ArgoCD đồng bộ và cert-manager cấp TLS.
  • Phân quyền: superadmin, quản trị tenant (mã 6 số) và đối tác (mã truy cập riêng); bật/tắt AI và hạn mức tin nhắn AI theo từng tenant.

MCP cho agent bên ngoài

  • Endpoint https://<tenant>.finance.devbyspark.com/api/mcp — Streamable HTTP, JSON-RPC 2.0, có session. Có thêm cầu nối stdio cho client chỉ hỗ trợ stdio.
  • 29 tool đọc và ghi: tra giao dịch, dòng tiền, danh mục, khoản vay, thấu chi, đối tác, bản nháp import… — cùng một registry dùng cho REST, MCP và trợ lý AI.
  • Khoá API spk_live_… chỉ lưu SHA-256, chọn quyền theo từng tool và hạn dùng, chỉ chạy trên đúng subdomain của tenant, có giới hạn tần suất.
  • Thao tác nhạy cảm (sửa dư nợ, ghi kỳ cho vay) bắt buộc confirm=true; ghi có idempotency_key; mọi phiên và lời gọi lưu log 90 ngày. Màn hình "Kết nối MCP" sinh sẵn lệnh/prompt kết nối cho Claude Code, Claude Desktop, Cursor, OpenClaw.

Công nghệ sử dụng

Backend

Công nghệDùng để làm gì, dùng như thế nào
Go 1.22Toàn bộ API, chỉ dùng rất ít thư viện ngoài (pgx, minio-go, x/crypto, uuid). Image build trên golang-alpine, chạy trên distroless static.
net/http ServeMuxRouter của thư viện chuẩn (từ Go 1.22 có pattern method + path). Middleware tự viết cho tenant, session, khoá API, giới hạn tần suất.
pgx v5Driver PostgreSQL và pool kết nối. Pool có thêm một lớp từ chối truy vấn khi context.Context không mang tenant, và đặt tenant cho RLS trước mỗi truy vấn.
Migrator tự viếtcmd/migrate: kiểm checksum với bảng schema_migrations, có -dry-run và -status.
x/cryptobcrypt cho mật khẩu và mã truy cập.
Telegram Bot APIMỗi tenant một bot riêng: nhắc lịch, gửi thẻ xác nhận khi đối tác báo đã trả, chủ khoản vay bấm nút để xác nhận.
VietQRDựng ảnh QR chuyển khoản đúng số tiền và nội dung cho đối tác trả nợ, không cần API key.

Dữ liệu

Công nghệDùng để làm gì, dùng như thế nào
PostgreSQL + Row-Level SecurityGiá trị mặc định + WITH CHECK gán tenant khi ghi; USING lọc khi đọc. Khoá ngoại dùng khoá ghép (tenant_id, …) nên không thể trỏ chéo sang tenant khác.
pg_trgmTìm giao dịch gần đúng theo nội dung chuyển khoản.
pgvectorVector embedding cho trí nhớ ngữ nghĩa của trợ lý và cho tìm kiếm ngữ nghĩa.
Cloudflare R2 (minio-go)Bucket riêng tư, key đặt theo tenant. Backend ký URL PUT (kèm Content-Length và Content-Type) để trình duyệt tải sao kê thẳng lên R2, rồi đọc lại bằng URL GET ngắn hạn.

AI

Công nghệDùng để làm gì, dùng như thế nào
9RouterOCR sao kê và gợi ý phân loại: backend gọi thẳng API kiểu OpenAI của 9Router với model OCR riêng.
SPARK AI GatewayDùng cho embedding (Gemini embedding) và trợ lý chat. Gateway gọi ngược /internal/agent-tools bằng request ký HMAC cho từng tool.
MCP server tự viếtStreamable HTTP, JSON-RPC 2.0, có Mcp-Session-Id, log mỗi lời gọi. Dùng chung registry tool với REST và trợ lý. Có cầu nối stdio finance-mcp.

Frontend

Công nghệDùng để làm gì, dùng như thế nào
React 18 + Vite + TypeScriptSPA, điều hướng bằng react-router.
MUI 6 + MUI XGiao diện (Minimal UI). DataGrid cho bảng giao dịch, Date Pickers, Tree View cho cây danh mục.
ApexCharts + react-grid-layoutBiểu đồ dòng tiền và xu hướng; dashboard kéo thả.
pdf.js + SheetJSXử lý file ngay trên trình duyệt trước khi tải lên: tách PDF thành text hoặc ảnh từng trang (vì 9Router không nhận file PDF), chuyển XLSX sang CSV.
react-hook-form + zodForm và validate.

Kiểm thử và vận hành

Công nghệDùng để làm gì, dùng như thế nào
go testMỗi test chạy trong một schema PostgreSQL riêng. Có test tái hiện đủ các kỳ cho vay thật, và kịch bản end-to-end đa tenant qua HTTP với Host header của từng tenant.
GitHub Actions → Docker Hub → ArgoCDBuild image, cập nhật repo finance-gitops, ArgoCD rolling update không gián đoạn. Khi có tenant mới, backend commit Ingress vào repo gitops qua GitHub API.

Kết quả

  • Thay bảng tính bằng một sổ tài chính tự đối chiếu: số liệu cho vay khớp 12/12 kỳ với bảng tính gốc.
  • Đang chạy cho 3 tenant trên finance.devbyspark.com và các subdomain riêng.
  • Agent AI (Claude, OpenClaw…) đọc và ghi dữ liệu tài chính qua MCP với quyền theo từng tool và bước xác nhận an toàn.

Điểm nổi bật

  • Go (net/http, pgx): API viết bằng thư viện chuẩn, rất ít dependency. Pool kết nối từ chối mọi truy vấn không mang tenant.

  • PostgreSQL RLS + pgvector: SaaS đa tenant theo subdomain, dữ liệu cô lập ngay ở tầng database. pgvector làm trí nhớ ngữ nghĩa cho trợ lý AI.

  • React, TypeScript, MUI, Cloudflare R2, LLM OCR: trình duyệt tách PDF/Excel rồi tải thẳng lên R2 bằng presigned URL. LLM đọc từng trang thành bản nháp giao dịch, người dùng duyệt xong mới ghi.

  • MCP + Kubernetes: MCP server cho từng tenant, khoá phân quyền theo từng tool, bắt buộc xác nhận khi sửa dư nợ. Tenant mới được tự cấp Ingress qua GitOps.

Hình ảnh

Dashboard tuỳ biến: dòng tiền theo tháng, khoản vay & thấu chi (số tiền được ẩn)
S Finance — SaaS quản lý chi tiêu & công nợ — Dự án của Vũ Xuân Bình