Ứng dụng Next.js hiện đại cho quản lý tài chính cá nhân với xử lý giao dịch bằng AI, ngân sách dựa trên hũ (jar), và quản lý ví toàn diện.

• Tính Năng
• Công Nghệ
• Yêu Cầu
• Cài Đặt
• Cấu Trúc Dự Án
• Tích Hợp API

• Tích hợp AWS Cognito cho xác thực bảo mật
• Đăng ký đa bước với xác minh OTP
• Luồng đặt lại và khôi phục mật khẩu
• Tạo và quản lý hồ sơ

• Hệ Thống Hũ: Ngân sách theo danh mục với các hũ tùy chỉnh
• Quản Lý Ví: Hỗ trợ đa ví với theo dõi giao dịch
• Lịch Sử Giao Dịch: Nhật ký giao dịch toàn diện với lọc và tìm kiếm
• Quét Hóa Đơn: Nhận diện và xử lý hóa đơn bằng OCR

• Nhập giao dịch bằng giọng nói chuyển văn bản
• Phân loại giao dịch hỗ trợ bởi AI
• Phân tích giao dịch thông minh từ hóa đơn
• Xử lý giao dịch bằng ngôn ngữ tự nhiên

• Next.js 16.0.1 - React framework với App Router
• React 19.2.0 - Thư viện UI
• TypeScript 5.x - An toàn kiểu dữ liệu

• AWS Cognito - Xác thực và ủy quyền người dùng
• Amazon Cognito Identity JS - Cognito SDK

• Zustand 5.0.8 - Quản lý state nhẹ
• Redux Toolkit 2.10.1 - Quản lý state phức tạp
• React Query (TanStack Query) 5.90.8 - Quản lý state server

• Tailwind CSS 3.4.18 - CSS framework utility-first
• shadcn/ui - Thư viện component tái sử dụng
• Radix UI - Component primitives accessible
• Framer Motion 12.23.24 - Thư viện animation
• Lucide React - Thư viện icon

• React Hook Form 7.66.0 - Quản lý form
• Zod 4.1.12 - Validation schema
• @hookform/resolvers - Resolvers validation form

• Axios 1.13.2 - HTTP client
• date-fns 4.1.0 - Xử lý ngày tháng
• class-variance-authority - Component variants
• clsx - Conditional classnames

• ESLint - Code linting
• Prettier - Code formatting
• Husky - Git hooks
• Commitlint - Commit message linting
• lint-staged - Chạy linters trên staged files

• Node.js: Phiên bản 24.10.1 trở lên
• npm/yarn/pnpm: Trình quản lý package
• AWS Account: Để cài đặt xác thực Cognito
• Backend API: Truy cập vào dịch vụ backend Vicobi

1. Clone repository

   git clone https://gitlab.com/vicobi/vicobi-frontend.git
   cd vicobi-frontend

2. Cài đặt dependencies

   npm install

3. Thiết lập biến môi trường

   Tạo file .env.local trong thư mục root:

   # Cấu hình AWS Cognito
   NEXT_PUBLIC_AWS_REGION=your-aws-region
   NEXT_PUBLIC_COGNITO_USER_POOL_ID=your-user-pool-id
   NEXT_PUBLIC_COGNITO_CLIENT_ID=your-client-id
   NEXT_PUBLIC_COGNITO_IDENTITY_POOL_ID=your-identity-pool-id
   
   # API Endpoints
   NEXT_PUBLIC_API_BASE_URL=https://api.vicobi.com
   NEXT_PUBLIC_AI_SERVICE_URL=https://ai-api.vicobi.com
   
   # Cài đặt ứng dụng
   NEXT_PUBLIC_APP_ENV=development

4. Chạy dự án

   npm run dev

5. Truy cập ứng dụng

   Mở trình duyệt: http://localhost:3000

6. Build cho Production

   npm run build
   npm start

Docker là cách nhanh nhất để chạy ứng dụng mà không cần cài đặt Node.js hay dependencies!

1. Cài đặt môi trường

   cp .env.example .env
   # Chỉnh sửa file .env với cấu hình của bạn

2. Khởi động ứng dụng

   # Dùng docker-compose trực tiếp
   docker-compose up -d

3. Truy cập ứng dụng

   Mở trình duyệt: http://localhost:3000

4. Các lệnh Docker hữu ích:

# Dừng ứng dụng
docker-compose down

# Xem logs
docker-compose logs -f

# Rebuild khi có thay đổi code
docker-compose up -d --build

# Xóa containers và volumes
docker-compose down -v

1. Tạo User Pool trong AWS Cognito
2. Cấu hình cài đặt app client
3. Thiết lập các thuộc tính bắt buộc (email, phone_number, v.v.)
4. Cấu hình MFA và chính sách mật khẩu
5. Cập nhật .env.local với thông tin Cognito của bạn

Ứng dụng kết nối đến hai dịch vụ chính:

• Backend API: REST API chính cho business logic
• AI Service: Tính năng và xử lý bằng AI

Cập nhật các URL API trong .env.local để phù hợp với môi trường của bạn.

vicobi-frontend/
├── app/                          # Next.js App Router
│   ├── (admin)/                  # Routes admin (được bảo vệ)
│   ├── (user)/                   # Routes user (được bảo vệ)
│   │   ├── page.tsx             # Dashboard người dùng
│   │   ├── (public)/            # Trang public
│   │   └── services/            # Dịch vụ người dùng
│   ├── auth/                    # Routes xác thực
│   │   ├── login/
│   │   ├── register/
│   │   ├── verify-otp/
│   │   ├── forgot-password/
│   │   └── reset-password/
│   ├── layout.tsx               # Layout gốc
│   └── globals.css              # Styles toàn cục
│
├── components/                   # React components
│   ├── ui/                      # UI components tái sử dụng (shadcn/ui)
│   │   ├── button.tsx
│   │   ├── input.tsx
│   │   ├── dialog.tsx
│   │   └── ...
│   ├── auth/                    # Components xác thực
│   ├── jars/                    # Components quản lý hũ
│   ├── wallet/                  # Components ví
│   ├── transactions/            # Components giao dịch
│   ├── transaction-ai/          # Xử lý giao dịch AI
│   ├── modal/                   # Modal dialogs
│   ├── sidebar/                 # Sidebar navigation
│   └── landing/                 # Components landing page
│
├── hooks/                       # Custom React hooks
│   ├── useAuth.tsx              # Hook xác thực
│   ├── useWallet.tsx            # Hook quản lý ví
│   ├── useJars.tsx              # Hook quản lý hũ
│   ├── useTransactions.tsx      # Hook giao dịch
│   └── useAIService.tsx         # Hook dịch vụ AI
│
├── lib/                         # Thư viện tiện ích
│   ├── api/                     # Tích hợp API
│   │   ├── core.ts             # API service class
│   │   └── services/           # Service endpoints
│   │       ├── authService.ts
│   │       ├── fetchWallet.ts
│   │       ├── fetchJars.ts
│   │       ├── fetchTransaction.ts
│   │       └── fetchAIService.ts
│   ├── store/                   # Quản lý state
│   │   ├── authStore.ts        # Auth state (Zustand)
│   │   └── apiStore.ts         # API state
│   ├── providers/               # Context providers
│   └── utils/                   # Utility functions
│
├── utils/                       # Helper utilities
│   ├── const/                   # Hằng số
│   ├── date/                    # Tiện ích ngày tháng
│   ├── email/                   # Tiện ích email
│   └── numbers/                 # Định dạng số
│
├── public/                      # Static assets
├── docs/                        # Tài liệu
│
├── next.config.mjs              # Cấu hình Next.js
├── tailwind.config.ts           # Cấu hình Tailwind CSS
├── tsconfig.json                # Cấu hình TypeScript
├── components.json              # Cấu hình shadcn/ui
├── commitlint.config.js         # Cấu hình Commitlint
└── package.json                 # Dependencies và scripts

Ứng dụng sử dụng class ApiService tùy chỉnh cho HTTP requests:

// lib/api/core.ts
import { ApiService } from '@/lib/api/core'

const api = new ApiService(baseURL, timeout, onAuthError)
api.setAuthToken(token)

• authService: Đăng nhập, đăng ký, xác minh OTP
• fetchWallet: Các thao tác CRUD ví
• fetchJars: Quản lý hũ và ngân sách
• fetchTransaction: Lịch sử và chi tiết giao dịch
• fetchAIService: Xử lý giao dịch bằng AI
• fetchUsers: Hồ sơ và cài đặt người dùng
• fetchNotification: Quản lý thông báo

React Query hooks cho việc fetch dữ liệu:

// Ví dụ sử dụng
import { useWallet } from '@/hooks/useWallet'

const { data, isLoading, error } = useWallet()

Được xây dựng với ❤️ bởi Vicobi Team

If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.