[Open Source] #178 - Piglet: Hệ thống quản trị tài chính gia đình thông minh với kiến trúc API-First, FastAPI, Flask và cơ chế điều phối Celery/Redis
Trong kỷ nguyên số, việc quản lý chi tiêu chung trong gia đình hoặc nhóm bạn thường gặp khó khăn do dữ liệu bị phân tán hoặc phụ thuộc vào các ứng dụng cloud không đảm bảo quyền riêng tư. Piglet ra đời như một giải pháp tự lưu trữ (self-hosted) mạnh mẽ, cung cấp một hệ sinh thái quản lý ngân sách đa người dùng, hỗ trợ từ theo dõi chi tiêu hàng ngày đến các biểu đồ phân tích nợ nần và lập lịch chi tiêu tự động.
Dưới góc độ kỹ thuật, Piglet là một minh chứng xuất sắc về việc ứng dụng kiến trúc API-First, kết hợp giữa tốc độ của FastAPI và tính linh hoạt của Flask thông qua một hệ thống điều phối tác vụ nền bền bỉ.
Github: https://github.com/v8u7/piglet
🛠️ 1. Nền tảng công nghệ: Sự phối hợp giữa High-performance API và Flexible WebUI
Piglet sử dụng một ngăn xếp công nghệ Python hiện đại, chia tách rõ ràng giữa lớp xử lý dữ liệu và lớp hiển thị:
- Backend Core (FastAPI): Đóng vai trò là "trái tim" của hệ thống, quản lý toàn bộ logic nghiệp vụ, tính toán báo cáo tài chính và cung cấp hệ thống API RESTful bảo mật qua JWT.
- Frontend Orchestrator (Flask & Jinja2): Sử dụng Flask làm lớp WebUI điều phối. Cách tiếp cận này cho phép hệ thống render trang cực nhanh và tách biệt hoàn toàn trạng thái phiên làm việc (Session) khỏi API chính.
- Task Management (Celery & Redis): Sử dụng Celery làm bộ máy thực thi tác vụ không đồng bộ (Async Tasks), kết hợp với Redis làm Message Broker. Đây là hạ tầng quan trọng để xử lý các chi tiêu định kỳ và gửi thông báo email mà không làm chậm trải nghiệm người dùng.
- Infrastructure (Docker & Supervisor): Đóng gói toàn bộ hệ sinh thái (MariaDB, Redis, API, WebUI) vào Docker. Sử dụng Supervisor để quản lý vòng đời của nhiều tiến trình Python bên trong một container duy nhất, tối ưu hóa tài nguyên cho các máy chủ gia đình hoặc NAS.
🏗️ 2. Trụ cột kiến trúc: API-First và Multi-tenant Budgeting
Kiến trúc của Piglet được thiết kế để phục vụ bài toán cộng tác tài chính quy mô nhóm:
- API-First Design Philosophy: Toàn bộ tính năng của Piglet (từ CRUD chi tiêu đến phân tích đồ thị) đều được phơi bày qua API của FastAPI. Tư duy này giúp Piglet sẵn sàng cho việc mở rộng sang ứng dụng di động hoặc tích hợp với các bộ cảm biến IoT tài chính trong tương lai.
- Shared Budget Model: Trái tim của cơ sở dữ liệu là thực thể
Budget. Piglet cho phép một ngân sách có nhiều thành viên tham gia với các cấp độ quyền hạn khác nhau, hỗ trợ cơ chế mời qua Email/Token và tự động tính toán số dư/nợ chéo giữa các thành viên. - Stateless API & Stateful WebUI: Trong khi API hoạt động hoàn toàn không trạng thái (stateless) qua JWT, lớp WebUI sử dụng Redis để lưu trữ Session người dùng, mang lại sự cân bằng hoàn hảo giữa bảo mật và trải nghiệm mượt mà.
🔄 3. Workflow: Từ Chi tiêu hàng ngày đến Biểu đồ phân tích (Sequence Diagram)
Sơ đồ mô tả quy trình hệ thống xử lý một giao dịch mới và cập nhật báo cáo cho toàn bộ thành viên:
⚡ 4. Các kỹ thuật "Pro-level" trong mã nguồn
- Recurring Order Engine: Piglet tích hợp một bộ máy lập lịch tinh vi trong bảng
pig_schedules. Celery Worker định kỳ quét và tự động sinh ra các chi tiêu (ví dụ: Tiền nhà, Netflix) dựa trên tần suất người dùng đã cài đặt, đảm bảo sổ thu chi luôn chính xác mà không cần nhập thủ công. - Auto-detection CSV Import: Khi người dùng chuyển đổi từ Excel/Google Sheets sang Piglet, hệ thống cung cấp bộ máy nhập liệu thông minh có khả năng tự động nhận diện dấu phân cách (Comma/Semicolon) và ánh xạ cột dữ liệu một cách linh hoạt.
- Security Hardening: Sử dụng kỹ thuật Salted SHA256 để băm mật khẩu và cơ chế JWT với thời gian hết hạn ngắn. Toàn bộ thông tin nhạy cảm trong cấu hình được quản lý qua biến môi trường Docker.
- Schema Evolution Manager: Thay vì dùng các công cụ Migration nặng nề, dự án tự xây dựng bộ quản lý phiên bản SQL (
config/dbschema/update), tự động nâng cấp cấu trúc bảng ngay khi người dùng kéo phiên bản Docker mới về.
⚖️ 5. So sánh chiến lược
| Tiêu chí | Piglet | Firefly III | Money Lover (SaaS) |
|---|---|---|---|
| Kiến trúc | API-First (Python) | Monolith (PHP/Laravel) | Proprietary Cloud |
| Tính cộng tác | Rất cao (Shared Budgets) | Trung bình | Có (Trả phí) |
| Độ nhẹ (Resource) | Thấp (Tối ưu cho NAS) | Cao | N/A |
| Tính riêng tư | Tuyệt đối (Self-host) | Tuyệt đối | Thấp |
| Độ khó sử dụng | Thấp (UI đơn giản) | Cao (Chuyên sâu kế toán) | Rất thấp |
✅ Kết luận: Tại sao Piglet là lựa chọn vàng cho gia đình?
Piglet chứng minh rằng một ứng dụng quản lý tài chính không cần phải quá phức tạp để đạt được hiệu quả cao. Bằng cách tập trung vào bài toán chia sẻ chi tiêu và xây dựng một kiến trúc API-First bền bỉ, dự án đã tạo ra một công cụ vừa an toàn cho dữ liệu gia đình, vừa linh hoạt cho các nhà phát triển muốn tùy biến sâu hơn.
Đối với các kỹ sư Backend, nghiên cứu Piglet giúp bạn hiểu sâu về:
- Kỹ thuật kết hợp FastAPI và Flask trong một dự án thực tế.
- Cách vận hành Distributed Tasks với Celery và Redis.
- Tư duy thiết kế Mô hình dữ liệu ngân sách nhóm (Group Budgeting).
All Rights Reserved
