Backend API cho **FinWise - Sổ tay Chi tiêu & Báo cáo Tài chính**, phục vụ Zalo Mini App.
---
## 📚 Tài liệu Kỹ thuật Chuyên sâu
Để tìm hiểu chi tiết về hệ thống, vui lòng xem các tài liệu chuyên sâu dưới đây:
## 📑 Mục lục
*[Kiến trúc Hệ thống & Sơ đồ ERD](./docs/architecture.md): Mô tả mô hình phân tầng, Mermaid ERD chi tiết của 14 bảng, và các cơ chế Cache, Lock, Rate Limiting, Logging.
*[Tài liệu API chi tiết](./docs/api.md): Mô tả định dạng request/response, xác thực qua token JWT, cookie HTTP-only và danh sách toàn bộ endpoints.
1.[Tổng quan & Kiến trúc Hệ thống](#-tổng-quan--kiến-trúc-hệ-thống)
*[Hướng dẫn Cài đặt & Triển khai](./docs/deployment.md): Hướng dẫn thiết lập môi trường development cục bộ, nạp seed data và vận hành container hoá bằng Docker Compose (healthcheck & non-root user) hoặc PM2 Cluster.
2.[Nguyên tắc Bất biến Tài chính & Kiến trúc (Invariants)](#-nguyên-tắc-bất-biến-tài-chính--kiến-trúc-invariants)
3.[Danh mục Tính năng & Các Module Nghiệp vụ](#-danh-mục-tính-năng--các-module-nghiệp-vụ)
4.[Tài liệu API chi tiết (Endpoints Reference)](#-tài-liệu-api-chi-tiết-endpoints-reference)
5.[Công nghệ sử dụng](#-công-nghệ-sử-dụng)
6.[Cấu trúc thư mục](#-cấu-trúc-thư-mục)
7.[Yêu cầu hệ thống](#-yêu-cầu-hệ-thống)
8.[Hướng dẫn Cài đặt & Khởi chạy](#-hướng-dẫn-cài-đặt--khởi-chạy)
9.[Cấu hình Biến Môi trường (.env)](#-cấu-hình-biến-môi-trường-env)
10.[Dữ liệu Khởi tạo & Tài khoản Seed](#-dữ-liệu-khởi-tạo--tài-khoản-seed)
11.[Kiểm thử Tự động (Automated Testing)](#-kiểm-thử-tự-động-automated-testing)
12.[Vận hành & Triển khai Production](#-vận-hành--triển-khai-production)
---
---
## Tính năng chính
## 🏗 Tổng quan & Kiến trúc Hệ thống
- Đăng ký, xác thực email, đăng nhập JWT và quản lý phiên đăng nhập.
FinWise Backend được xây dựng theo mô hình kiến trúc phân tầng chuẩn mực (*Layered Architecture*), đảm bảo tính module hóa cao, dễ bảo trì, dễ mở rộng và kiểm thử:
- Quản lý hồ sơ, mật khẩu và khôi phục mật khẩu qua email.
- Quản trị người dùng theo role.
- Quản lý ví, danh mục thu/chi và giao dịch theo ownership.
- Tự động cập nhật số dư ví khi tạo, sửa hoặc xóa giao dịch.
- Chuyển tiền giữa hai ví cùng tiền tệ và cập nhật hai số dư nguyên tử.
- Lưu hóa đơn giao dịch dạng JPEG, PNG, WebP hoặc PDF.
*[Kiến trúc Hệ thống & Sơ đồ ERD](./docs/architecture.md): Mô tả mô hình phân tầng, Mermaid ERD chi tiết, cơ chế Cache, Distributed Lock và Logging.
- Zod cho validation
*[Tài liệu API chi tiết](./docs/api.md): Mô tả chi tiết định dạng Request/Response, mã lỗi chuẩn `AppError` và JWT Auth flows.
- JWT, cookie và role-based access control
*[Hướng dẫn Cài đặt & Triển khai](./docs/deployment.md): Hướng dẫn thiết lập môi trường production với Docker Compose, PM2 Cluster và Cloudflare.
- Helmet, CORS và rate limiting
*[Hướng dẫn Upload trực tiếp Cloudflare R2](./docs/r2-direct-upload.md): Cơ chế Presigned URL bảo mật cao để upload chứng từ và hóa đơn.
- Nodemailer cho email xác thực và khôi phục mật khẩu
- pnpm 9
## Yêu cầu
---
- Node.js 18 trở lên
## ⚖️ Nguyên tắc Bất biến Tài chính & Kiến trúc (Invariants)
- pnpm 9 (`packageManager` của dự án là `pnpm@9.15.0`)
- PostgreSQL
1.**Bảo toàn Cân bằng Sổ cái (Balance Accounting Invariant)**:
- Docker và Docker Compose nếu muốn chạy database bằng container
- Giao dịch `INCOME` tăng số dư ví tương ứng một cách nguyên tử (*Atomic*).
- Giao dịch `EXPENSE` giảm số dư ví tương ứng một cách nguyên tử.
- Giao dịch `TRANSFER` chuyển tiền giữa hai ví trong cùng một `Serializable Database Transaction`, không được tính là Thu nhập hay Chi phí.
2.**Khả năng Hoàn tác Đột biến (Mutation Reversibility)**:
- Khi chỉnh sửa giao dịch, hệ thống tự động hoàn tác (*Rollback/Offset*) ảnh hưởng số dư cũ trước khi áp dụng số dư mới.
- Khi xóa giao dịch, số dư ví lập tức được hoàn nguyên.
3.**Phân quyền Đa người thuê (Multi-tenant Authorization)**:
- Tuyệt đối không tin tưởng `userId` truyền từ Client Request Body. `userId` luôn được trích xuất an toàn từ JWT Token đã được ký mật mã.
4.**Bất biến Múi giờ Kinh doanh (Timezone Invariance)**:
- Toàn bộ chu kỳ tài chính, ngày chốt sổ, báo cáo, và lịch chạy định kỳ được neo cố định theo múi giờ Việt Nam: `Asia/Ho_Chi_Minh` (UTC+7) thông qua module `business-time.ts`.
5.**AI Không Bịa đặt Số liệu (Zero Hallucination Policy)**:
- Không sử dụng LLM để tính toán số học trực tiếp.
- AI chỉ đóng vai trò phân tích ngôn ngữ tự nhiên thành Cây cú pháp trừu tượng (AST DSL). Việc tính toán tổng, trung bình, nhóm danh mục hoàn toàn do PostgreSQL/Prisma thực thi bằng thuật toán tất định.
## Cài đặt
---
### 1. Cài dependency
## 🧩 Danh mục Tính năng & Các Module Nghiệp vụ
Hệ thống bao gồm 24 modules nghiệp vụ hoàn chỉnh:
1.**Authentication & Session**: Đăng ký, kích hoạt email, đăng nhập JWT kép (Access + Refresh Token qua HTTP-Only Cookie), khôi phục mật khẩu qua SMTP.
2.**Dynamic RBAC & Permissions**: Hệ thống phân quyền động dựa trên Permission (gần 40 permissions chi tiết), bảo vệ chống khóa Admin cuối cùng (*Last-Admin Protection*).
3.**Audit Logging**: Ghi nhận toàn bộ thao tác thêm/sửa/xóa hệ thống với chi tiết diff trước/sau, không thể chỉnh sửa (*Immutable*).
4.**Wallets & Multi-Currency**: Quản lý nhiều loại ví (Tiền mặt, Ngân hàng, Thẻ tín dụng, Đầu tư), quản lý ví mặc định và archive an toàn.
5.**Categories**: Danh mục phân cấp cây Cha - Con không giới hạn tầng, icon SVG tùy biến, phân loại Thu / Chi.
6.**Transactions**: Ghi chép giao dịch, gắn nhãn, địa điểm, đính kèm hóa đơn ảnh/PDF.
7.**Transfers**: Chuyển tiền giữa các ví cùng loại tiền tệ với cam kết giao dịch nguyên tử ACID.
8.**Budgets**: Quản lý hạn mức chi tiêu theo tháng hoặc theo từng danh mục, tính toán tỷ lệ sử dụng theo thời gian thực.
9.**Saving Goals**: Mục tiêu tiết kiệm thông minh, nạp tiền/rút tiền mục tiêu, tự động tính toán thời gian hoàn thành.
10.**Financial Reports**: Báo cáo tài chính chuyên sâu, tỷ lệ tiết kiệm (*Savings Rate*), cơ cấu chi tiêu và xuất dữ liệu.
11.**Cash Flow Runway & Forecaster**: Dự báo dòng tiền tương lai 30/60/90 ngày bằng thuật toán làm mượt hàm mũ (Holt-Winters), tính ngày cạn ngân sách (*Depletion Date*).
12.**What-If Simulation Sandbox**: Mô phỏng kịch bản tài chính giả định (mua nhà, tăng lương, cắt giảm chi phí) và đánh giá va chạm mục tiêu.
13.**Multi-dimensional Anomaly Detection**: Phát hiện giao dịch bất thường trong thời gian thực bằng thuật toán thống kê Modified Z-score (MAD) và tần suất đột biến (*Velocity Bursts*).
14.**Auto Subscription Discovery**: Tự động nhận diện gói thuê bao định kỳ (Netflix, Spotify, Cloud...) dựa trên tính tuần hoàn chu kỳ và phương sai số tiền, hỗ trợ chuyển đổi 1-click sang Nhắc nhở.
15.**Natural Language Query Engine**: Truy vấn tài chính bằng câu hỏi tự nhiên tiếng Việt, chuyển dịch sang AST DSL và tính toán chính xác 100%.
16.**Automated Recurring Transactions**: Lên lịch tạo giao dịch tự động định kỳ, xử lý bù lịch (*Catch-up policy*) và chống trùng lặp bằng Distributed Lock.
17.**Notifications & Worker**: Quản lý thông báo in-app, tích hợp background worker quét định kỳ và gửi thông báo tài chính.
18.**Bill Reminders**: Nhắc nhở hạn nộp hóa đơn, trả nợ định kỳ.
19.**AI Financial Assistant**: Trợ lý AI phân tích thói quen tài chính cá nhân hóa, gợi ý danh mục và kế hoạch chi tiêu.
20.**System Settings & Maintenance Mode**: Bật/tắt chế độ bảo trì hệ thống toàn cục, cấu hình tham số hệ thống động.
21.**AI Administration**: Giám sát lượng Token tiêu thụ, cấu hình Model Gemini, rate-limiting cho tính năng AI.
22.**Developer API Keys**: Quản lý API Key cho bên thứ 3 tích hợp, phân quyền theo scope và rate limit độc lập.
23.**Webhooks Dispatcher**: Bắn sự kiện webhook thời gian thực (HMAC SHA-256 signature) khi có biến động giao dịch hoặc số dư.
24.**Cloudflare R2 Direct Upload**: Sinh Presigned Upload URL cho Client tải trực tiếp ảnh/PDF lên Cloudflare R2 bảo mật.
```bash
---
pnpm install
```
### 2. Tạo file môi trường
## 📡 Tài liệu API chi tiết (Endpoints Reference)
Sao chép `.env.example` thành `.env`, sau đó thay các placeholder bằng cấu hình local:
Tất cả các endpoint đều có tiền tố `/api/v1`.
```powershell
### 1. System & Health
Copy-Item .env.example .env
| Method | Endpoint | Quyền | Mô tả |
```
| :--- | :--- | :--- | :--- |
| `GET` | `/health` | Public | Kiểm tra trạng thái hoạt động (Liveness probe cho Load Balancer) |
| `GET` | `/health/detail` | `SYSTEM_CONFIG_READ` | Kiểm tra chi tiết kết nối Database, Redis, Uptime, Memory |
| `GET` | `/system/public-config` | Public | Lấy cấu hình công khai (Trạng thái bảo trì, thông tin hệ thống) |
### 2. Auth & Session
| Method | Endpoint | Quyền | Mô tả |
| :--- | :--- | :--- | :--- |
| `POST` | `/auth/register` | Public | Đăng ký tài khoản mới |
| `GET` | `/auth/verify-email` | Public | Xác thực email đăng ký |
| `POST` | `/auth/login` | Public | Đăng nhập hệ thống (trả về Access Token và Refresh Token) |
| `POST` | `/auth/refresh` | Public | Làm mới cặp token |
| `POST` | `/auth/logout` | Public | Đăng xuất và vô hiệu hóa phiên |
| `GET` | `/auth/me` | Bearer Token | Lấy thông tin tài khoản và danh sách Permissions hiện tại |
| `PUT` | `/auth/profile` | Bearer Token | Cập nhật thông tin cá nhân |
| `GEMINI_API_KEYS` | `...` | Danh sách API Keys Google Gemini (ngăn cách bằng dấu phẩy) |
| `GEMINI_MODEL` | `gemini-2.5-flash` | Model AI mặc định xử lý truy vấn & tư vấn |
Các endpoint được bảo vệ nhận access token qua header:
---
```http
## 👥 Dữ liệu Khởi tạo & Tài khoản Seed
Authorization: Bearer <accessToken>
```
Refresh token cũng được trả qua cookie HTTP-only ở luồng đăng nhập/refresh. Xem Swagger UI để biết request body và response schema chi tiết.
Khi chạy lệnh `pnpm run db:seed`, hệ thống sẽ tự động khởi tạo toàn bộ Permissions, các System Roles (`SUPER_ADMIN`, `ADMIN`, `MANAGER`, `USER`), danh mục tài chính mặc định và các tài khoản thử nghiệm sau:
> ⚠️ **Lưu ý bảo mật**: Các tài khoản trên chỉ phục vụ cho môi trường phát triển và kiểm thử cục bộ. Vui lòng đổi mật khẩu hoặc xóa bỏ khi triển khai lên môi trường Production.
| `GET` | `/transactions` | Danh sách giao dịch có filter, sort và pagination |
| `POST` | `/transactions` | Tạo giao dịch và cập nhật số dư ví |
| `GET` | `/transactions/:id` | Chi tiết giao dịch |
| `PUT` | `/transactions/:id` | Cập nhật giao dịch và cân chỉnh số dư ví |
| `DELETE` | `/transactions/:id` | Xóa giao dịch và hoàn tác ảnh hưởng lên số dư |
| `PUT` | `/transactions/:id/receipt` | Upload hoặc thay hóa đơn qua field multipart `receipt` |
| `GET` | `/transactions/:id/receipt` | Xem hoặc tải hóa đơn |
| `DELETE` | `/transactions/:id/receipt` | Xóa hóa đơn |
### Transfers
Toàn bộ nhóm này yêu cầu access token. Hai ví phải thuộc người dùng, đang hoạt động, khác nhau, cùng tiền tệ và ví nguồn phải đủ số dư. Bản ghi chuyển tiền cùng hai thay đổi số dư được commit nguyên tử.
| `GET` | `/transfers` | Lịch sử có tìm kiếm, lọc ví/ngày, sort và pagination |
| `POST` | `/transfers` | Chuyển tiền và cập nhật nguyên tử số dư của cả hai ví |
| `DELETE` | `/transfers/:id` | Xóa giao dịch chuyển tiền và hoàn tác cả hai thay đổi dư |
### Budgets
Toàn bộ nhóm này yêu cầu access token và chỉ thao tác trên ngân sách của chính người dùng. Dữ liệu sử dụng được tổng hợp từ giao dịch chi tiêu theo thời gian thực.
