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.IDriêng, pool kết nối từ chối truy vấn thiếu tenant, giá trị mặc định +WITH CHECKcủa PostgreSQL Row-Level Security, và điều kiệnUSINGcủa RLS. Tenant đi theocontext.Contextnê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.22 | Toà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 ServeMux | Router 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 v5 | Driver 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ết | cmd/migrate: kiểm checksum với bảng schema_migrations, có -dry-run và -status. |
| x/crypto | bcrypt cho mật khẩu và mã truy cập. |
| Telegram Bot API | Mỗ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. |
| VietQR | Dự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 Security | Giá 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_trgm | Tìm giao dịch gần đúng theo nội dung chuyển khoản. |
| pgvector | Vector 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 |
|---|---|
| 9Router | OCR 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 Gateway | Dù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ết | Streamable 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 + TypeScript | SPA, điều hướng bằng react-router. |
| MUI 6 + MUI X | Giao diện (Minimal UI). DataGrid cho bảng giao dịch, Date Pickers, Tree View cho cây danh mục. |
| ApexCharts + react-grid-layout | Biểu đồ dòng tiền và xu hướng; dashboard kéo thả. |
| pdf.js + SheetJS | Xử 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 + zod | Form 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 test | Mỗ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 → ArgoCD | Build 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.comvà 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.
