Skip to content

F
finwise-miniapp-fe
Commit 28aefb92 authored by ThinhNC's avatar ThinhNC
Browse files
Options

Merge branch 'docs/update-comprehensive-readme' into 'develop' 

docs(fe): update comprehensive README with Claymorphism UI, modules, and Zalo deploy guide

See merge request !29
parents 34d1e1c2 4d439196
Hide whitespace changes
Inline Side-by-side
Showing with 226 additions and 34 deletions
README.md
View file @ 28aefb92
# Zalo Mini App
# FinWise Frontend - Zalo Mini App Client
## Development
<p align="center">
<img src="./src/static/icons/app-icon.png" alt="FinWise Logo" width="96" height="96" onerror="this.style.display='none'"/>
</p>
### Using Zalo Mini App Extension
<p align="center">
<b>FinWise</b> — Ứng dụng Quản lý Chi tiêu, Lập Kế hoạch Tài chính & Trợ lý Thông minh trên nền tảng <b>Zalo Mini App</b>.
</p>
1. Install [Visual Studio Code](https://code.visualstudio.com/download) and [Zalo Mini App Extension](https://mini.zalo.me/docs/dev-tools).
1. In the **Home** tab, process **Config App ID** and **Install Dependencies**.
1. Navigate to the **Run** tab, select the suitable launcher, and click **Start**.
<p align="center">
<img src="https://img.shields.io/badge/React-18.3-61DAFB?logo=react&logoColor=black" alt="React 18" />
<img src="https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
<img src="https://img.shields.io/badge/Zalo_Mini_App-ZaUI-0068FF?logo=zalo&logoColor=white" alt="ZMP SDK" />
<img src="https://img.shields.io/badge/Vite-5.2-646CFF?logo=vite&logoColor=white" alt="Vite" />
<img src="https://img.shields.io/badge/TailwindCSS-3.4-38B2AC?logo=tailwind-css&logoColor=white" alt="TailwindCSS" />
<img src="https://img.shields.io/badge/TanStack_Query-v5-FF4154?logo=react-query&logoColor=white" alt="TanStack Query" />
<img src="https://img.shields.io/badge/Design_System-Claymorphism-F59E0B" alt="Claymorphism" />
</p>
### Using Zalo Mini App CLI
---
1. [Install Node JS](https://nodejs.org/en/download/).
1. [Install Zalo Mini App CLI](https://mini.zalo.me/docs/dev-tools/cli/intro/).
1. **Install dependencies**:
```bash
npm install
```
1. **Start** the dev server:
```bash
npm run start
## 📑 Mục lục
1. [Giới thiệu](#-giới-thiệu)
2. [Đặc điểm nổi bật & Giao diện Claymorphism](#-đặc-điểm-nổi-bật--giao-diện-claymorphism)
3. [Danh sách tính năng & Màn hình](#-danh-sách-tính-năng--màn-hình)
4. [Công nghệ sử dụng](#-công-nghệ-sử-dụng)
5. [Cấu trúc thư mục](#-cấu-trúc-thư-mục)
6. [Yêu cầu hệ thống & Môi trường](#-yêu-cầu-hệ-thống--môi-trường)
7. [Hướng dẫn cài đặt & Chạy ứng dụng](#-hướng-dẫn-cài-đặt--chạy-ứng-dụng)
8. [Cấu hình biến môi trường (.env)](#-cấu-hình-biến-môi-trường-env)
9. [Hệ thống Phân quyền (RBAC) & Bảo mật](#-hệ-thống-phân-quyền-rbac--bảo-mật)
10. [Đa ngôn ngữ (i18n) & Giao diện sáng/tối](#-đa-ngôn-ngữ-i18n--giao-diện-sángtối)
11. [Quy trình đóng gói & Triển khai lên Zalo](#-quy-trình-đóng-gói--triển-khai-lên-zalo)
---
## 🌟 Giới thiệu
**FinWise Mini App** là ứng dụng cá nhân hóa tài chính thế hệ mới được tối ưu hóa riêng cho người dùng Zalo tại Việt Nam. Không chỉ dừng lại ở sổ thu chi đơn thuần, FinWise tích hợp các mô hình toán học dự báo tài chính tất định (*Deterministic Forecasting*), phân tích bất thường bằng thống kê (*MAD Z-score*), phát hiện gói thuê bao định kỳ (*Subscription Discovery*), truy vấn tự nhiên (*Natural Language DSL Query*) và trung tâm quản trị toàn diện (*Admin Control Center P0/P2*).
Giao diện được thiết kế theo phong cách **Claymorphism** cao cấp, mềm mại với đổ bóng đa lớp, bo góc lớn, phối màu tương phản tinh tế, đem lại trải nghiệm mượt mà và trực quan trên mọi kích thước màn hình điện thoại.
---
## 🎨 Đặc điểm nổi bật & Giao diện Claymorphism
- **Claymorphism Design System**: Các thẻ (*Cards*), nút bấm (*Buttons*), thanh tiến trình (*Progress Bars*), hộp thoại (*Modals*) đều được đúc nổi 3D với hiệu ứng ánh sáng bề mặt (inner-shadow) và đổ bóng nổi (outer-shadow).
- **Bộ màu Semantic Tài chính**: Phân biệt trực quan dòng tiền Thu (*Emerald Green*), Chi (*Rose Pink/Red*), Chuyển tiền (*Indigo/Blue*), Cảnh báo (*Amber/Orange*).
- **Phản hồi trạng thái toàn diện**: Đầy đủ Skeleton Loading bo tròn phong cách đất sét, Empty State có minh họa, và Error Boundary / Retry state.
- **Tối ưu Mobile First & Zalo WebView**: Tương thích hoàn hảo với thanh điều hướng (*Header Bar*), vùng an toàn (*Safe Area Insets*), và cơ chế điều hướng trang `ZMPRouter` + `AnimationRoutes`.
---
## 📱 Danh sách tính năng & Màn hình
### 1. Quản lý Tài chính Cốt lõi
| Màn hình | Đường dẫn | Chức năng chính |
| :--- | :--- | :--- |
| **Tổng quan** | `/` | Dashboard dòng tiền, biểu đồ tóm tắt, danh sách giao dịch gần đây, lối tắt nhanh |
| **Ví tiền** | `/wallets`, `/wallets/:id` | Quản lý ví đa tiền tệ (Tiền mặt, Ngân hàng, Thẻ tín dụng, Crypto), xem lịch sử biến động số dư |
| **Danh mục** | `/categories` | Danh mục thu/chi phân cấp Cha - Con đa tầng, chọn icon & màu sắc tùy biến |
| **Giao dịch** | `/transactions` | Ghi chép thu/chi, gắn danh mục, đính kèm hóa đơn hình ảnh/PDF (hỗ trợ Cloudflare R2), lọc & tìm kiếm |
| **Chuyển khoản** | `/transfers` | Chuyển tiền giữa các ví nội bộ, ghi nhận biến động số dư nguyên tử |
| **Ngân sách** | `/budgets`, `/budgets/:id` | Thiết lập hạn mức chi tiêu theo danh mục/tổng thể, cảnh báo thời gian thực khi chạm ngưỡng |
| **Mục tiêu tiết kiệm** | `/saving-goals`, `/saving-goals/:id` | Lập mục tiêu tài chính, theo dõi tiến độ %, nạp tiền trực tiếp vào mục tiêu |
| **Báo cáo & Phân tích** | `/reports` | Biểu đồ trực quan hóa cơ cấu chi tiêu, xu hướng thu nhập vs chi phí theo tuần/tháng/năm |
### 2. Bộ công cụ Thông minh & Phân tích Nâng cao
| Tính năng | Đường dẫn | Mô tả chi tiết |
| :--- | :--- | :--- |
| **Dự báo Dòng tiền** | `/forecast` | Dự báo Runway tài chính, ước tính ngày cạn kiệt ngân sách (*Depletion Date*) bằng thuật toán làm mượt hàm mũ |
| **Mô phỏng Sandbox** | `/simulations` | Mô phỏng kịch bản tài chính giả định (*What-If*), đánh giá va chạm mục tiêu (*Goal Collision Analysis*) |
| **Phát hiện Bất thường** | `/anomalies` | Phát hiện chi tiêu đột biến, lặp lại bất thường thời gian thực bằng thuật toán thống kê phi tham số Modified Z-score (MAD) |
| **Phát hiện Gói thuê bao** | `/subscriptions` | Tự động nhận diện định kỳ dịch vụ (Netflix, Spotify, Cloud...), chuyển đổi 1-chạm sang Lịch nhắc nhở |
| **Giao dịch Định kỳ** | `/recurring-transactions` | Lên lịch tạo giao dịch tự động theo Ngày/Tuần/Tháng/Năm, xem trước lịch chạy, tạm dừng/kích hoạt |
| **Truy vấn Ngôn ngữ Tự nhiên** | `/query` | Đặt câu hỏi chi tiêu bằng tiếng Việt/Anh, biên dịch sang AST DSL tất định 0% bịa đặt (*Zero Hallucination*) |
| **Trợ lý Tài chính AI** | `/ai-assistant` | Chatbot tư vấn kế hoạch chi tiêu, phân tích thói quen, gợi ý tiết kiệm dựa trên dữ liệu thực |
| **Thông báo & Nhắc nhở** | `/notifications` | Hệ thống thông báo đẩy trong ứng dụng, nhắc hạn thanh toán hóa đơn |
### 3. Trung tâm Quản trị (Admin Control Center P0 / P2)
| Màn hình Admin | Đường dẫn | Phân quyền yêu cầu | Mô tả |
| :--- | :--- | :--- | :--- |
| **Admin Dashboard** | `/admin` | `USER_READ` | Thống kê số lượng người dùng, biểu đồ tăng trưởng, phiên hoạt động |
| **Quản lý Người dùng** | `/admin/users`, `/admin/users/:id` | `USER_READ`, `USER_UPDATE` | Danh sách người dùng, kích hoạt/khóa tài khoản, gán vai trò Role |
| **Ma trận Phân quyền** | `/admin/roles`, `/roles` | `ROLE_READ`, `ROLE_UPDATE` | Quản lý Role động, gán ma trận Permission chi tiết theo từng chức năng |
| **Nhật ký Kiểm toán** | `/admin/audit-logs` | `AUDIT_LOG_READ` | Xem lịch sử thao tác hệ thống bất biến, so sánh diff dữ liệu trước/sau |
| **Cấu hình Hệ thống** | `/admin/settings` | `SYSTEM_CONFIG_READ` | Bật/tắt chế độ bảo trì (Maintenance Mode), cấu hình tham số toàn cục |
| **Quản trị Thông báo** | `/admin/notifications` | `NOTIFICATION_ADMIN_READ` | Quản lý mẫu thông báo, gửi thông báo diện rộng tới người dùng |
| **Quản trị Trí tuệ Nhân tạo** | `/admin/ai` | `AI_ADMIN_READ` | Giám sát hạn mức Token AI, cấu hình Model Gemini, Prompt Templates |
| **Tích hợp API & Webhooks** | `/admin/integrations` | `API_KEY_READ`, `WEBHOOK_READ` | Quản lý API Key cho bên thứ 3 và cấu hình Webhook endpoints |
---
## 🛠 Công nghệ sử dụng
| Công nghệ | Phiên bản | Vai trò |
| :--- | :--- | :--- |
| **React** | `18.3.1` | Thư viện xây dựng giao diện người dùng |
| **TypeScript** | `5.7.2` | Ngôn ngữ phát triển với hệ thống kiểu tĩnh an toàn |
| **Zalo Mini App SDK (`zmp-sdk`)** | `latest` | Tương tác với native API của Zalo (User Info, Auth, Device, Routing) |
| **ZaUI (`zmp-ui`)** | `latest` | Bộ UI Component nền tảng của Zalo Mini App |
| **Vite** | `5.2.13` | Build tool và Development Server siêu tốc |
| **TailwindCSS** | `3.4.3` | Utility-first CSS framework kết hợp biến thể Claymorphism tùy biến |
| **TanStack React Query** | `5.101.4` | Quản lý Server State, Caching, Polling và Revalidation |
| **Zustand & Jotai** | `5.0.14` / `2.12.1` | Quản lý Global Client State (Auth Store, Theme Store, Chat Store) |
| **React Hook Form & Zod** | `7.84.0` / `4.4.3` | Quản lý Form và xác thực dữ liệu đầu vào |
| **Axios** | `1.19.0` | HTTP Client tương tác với RESTful API Backend |
| **Sass / PostCSS** | `1.76.0` / `8.4.38` | Tiền xử lý CSS mở rộng |
---
## 📁 Cấu trúc thư mục
```text
finwise-miniapp-fe/
├── app-config.json # Cấu hình Zalo Mini App (Header, Status bar, Routing)
├── index.html # HTML entry template
├── package.json # Danh sách thư viện và scripts
├── tailwind.config.js # Cấu hình Design System, Claymorphism shadow, theme colors
├── tsconfig.json # Cấu hình TypeScript compiler & alias (@/*)
├── vite.config.mts # Cấu hình Vite bundler & plugin ZMP
├── zmp-cli.json # Cấu hình Zalo Mini App CLI (App ID)
│
└── src/
├── app.ts # Điểm khởi tạo ứng dụng và mount DOM React
├── common/ # Constants & Enums dùng chung (Permissions, System Roles)
├── components/
│ ├── layout.tsx # Cấu hình ZMPRouter, AnimationRoutes, Theme & Auth Guard
│ ├── language-switcher/# Nút chuyển đổi ngôn ngữ Việt / Anh
│ ├── shared/ # AuthGuard, PermissionGate, AccessDenied, ThemeControl, Artwork...
│ └── ui/ # Claymorphism Base Components (Button, Card, Input, Modal, Badge...)
├── constants/ # Các hằng số ứng dụng
├── css/
│ ├── app.scss # Style ứng dụng & Claymorphism custom mixins
│ └── tailwind.scss # Import Tailwind directives
├── hooks/ # Custom React Hooks & TanStack Query Hooks
├── i18n/ # Đa ngôn ngữ (I18nProvider, từ điển vi / en)
├── lib/ # axios client, query client cấu hình
├── pages/ # Các trang màn hình (xem danh sách tính năng)
├── services/ # Lớp giao tiếp API với Backend (Auth, Wallet, AI, Admin...)
├── static/ # Hình ảnh, icons tĩnh
├── stores/ # Zustand Global Stores (auth-store, theme-store, ai-chat-store)
└── types/ # Định nghĩa TypeScript Types & Interfaces
```
---
## 💻 Yêu cầu hệ thống & Môi trường
- **Node.js**: Phiên bản `18.x` hoặc `20.x` LTS trở lên.
- **Package Manager**: Khuyến nghị dùng `pnpm` (hoặc `npm` / `yarn`).
- **Trình duyệt**: Chrome / Edge / Brave phiên bản mới nhất để chạy giả lập Zalo Simulator.
- **VS Code Extension (Tùy chọn)**: [Zalo Mini App Extension](https://mini.zalo.me/docs/dev-tools).
---
## 🚀 Hướng dẫn cài đặt & Chạy ứng dụng
### 1. Cài đặt Dependencies
Tại thư mục `finwise-miniapp-fe`:
```bash
pnpm install
# hoặc npm install
```
### 2. Thiết lập Biến Môi trường
Tạo file `.env` tại thư mục gốc của frontend:
```env
APP_ID=4159485577959643080
VITE_API_URL=http://localhost:7777/api/v1
```
### 3. Khởi động Development Server
```bash
pnpm start
# hoặc npm run start
```
Sau khi khởi động thành công:
- **Zalo Mini App Simulator (Web UI)**: Mở trình duyệt tại [`http://localhost:13580`](http://localhost:13580)
- **Mini App Webview Content**: Chạy tại `http://localhost:13579`
> 💡 **Mẹo phát triển**: Bạn có thể truy cập trang phong cách giao diện mẫu tại đường dẫn `/style-guide` để xem toàn bộ danh mục Claymorphism UI components.
---
## 🔐 Hệ thống Phân quyền (RBAC) & Bảo mật
Ứng dụng Frontend triển khai cơ chế kiểm soát truy cập phân tán chi tiết dựa trên quyền hạn (*Permission-Based Access Control*):
1. **`AuthGuard`**: Bảo vệ các route riêng tư, tự động kiểm tra phiên đăng nhập qua cookie HTTP-Only hoặc Access Token, chuyển hướng về `/login` nếu chưa xác thực.
2. **`PermissionGate`**: Kiểm soát hiển thị component hoặc chặn truy cập route dựa trên danh sách Permission của người dùng:
```tsx
<PermissionGate permission={PERMISSIONS.WALLET_CREATE} fallback={<p>Không có quyền tạo ví</p>}>
<CreateWalletButton />
</PermissionGate>
```
1. **Open** `localhost:13580` in your browser. The Mini App content runs at `localhost:13579`.
3. **`usePermission` Hook**: Cung cấp hàm kiểm tra quyền tiện lợi trong mã logic (`hasPermission`, `hasAnyPermission`, `hasAllPermissions`).
---
## 🌐 Đa ngôn ngữ (i18n) & Giao diện sáng/tối
- **Đa ngôn ngữ**: Hệ thống hỗ trợ hoàn chỉnh 2 ngôn ngữ: **Tiếng Việt (`vi`)** và **Tiếng Anh (`en`)**. Được quản lý qua `I18nProvider` và lưu trạng thái vào `localStorage`.
- **Giao diện Chủ đề (Theme)**: Hỗ trợ 3 chế độ: `Light` (Sáng), `Dark` (Tối) và `System` (Theo hệ thống thiết bị), áp dụng chuẩn màu Claymorphism trên cả 2 nền sáng và tối.
---
## Deployment
## 📦 Quy trình đóng gói & Triển khai lên Zalo
1. **Create** a mini program. For instructions on how to create a mini program, please refer to the [Coffee Shop Tutorial](https://mini.zalo.me/tutorial/coffee-shop/step-1/)
### 1. Đăng nhập Zalo Mini App CLI
1. **Deploy** your mini program to Zalo using the mini app ID created.
```bash
pnpm run login
# hoặc: npx zmp-cli login
```
*Quét mã QR hiển thị trên màn hình bằng ứng dụng Zalo trên điện thoại để xác thực tài khoản lập trình viên.*
- **Using Zalo Mini App Extension**: navigate to the **Deploy** panel > **Login** > **Deploy**.
- **Using Zalo Mini App CLI**:
```bash
zmp login
zmp deploy
```
### 2. Build ứng dụng
1. Open the mini app in Zalo by scanning the QR code.
```bash
pnpm run build
```
*Vite sẽ tối ưu hóa và xuất mã nguồn bundle vào thư mục `www/`.*
## Resources
### 3. Triển khai (Deploy)
- [Zalo Mini App Official Website](https://mini.zalo.me/)
- [ZaUI Documentation](https://mini.zalo.me/documents/zaui/)
- [ZMP SDK Documentation](https://mini.zalo.me/documents/api/)
- [DevTools Documentation](https://mini.zalo.me/docs/dev-tools/)
- [Ready-made Mini App Templates](https://mini.zalo.me/zaui-templates)
- [Community Support](https://mini.zalo.me/community)
```bash
pnpm run deploy
# hoặc: npx zmp-cli deploy
```
*Sau khi deploy thành công, Zalo DevTools sẽ trả về mã QR phiên bản thử nghiệm để quét mở trực tiếp trên ứng dụng Zalo.*
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment