Merge branch 'fix/zmp-black-screen' into 'develop'

fix(frontend): resolve ZMP black screen

See merge request !2

.agents/memory.md

@@ -12,12 +12,16 @@ File này lưu trữ các quyết định thiết kế dài hạn và trạng th
 - **Phong cách Icon**: Tự thiết kế các inline SVG dạng blob dày, tròn trịa, nhiều màu sắc pastel thay vì dùng icon nét mảnh phẳng thông thường.
 - **Quản lý Routing**: Sử dụng cấu hình router của ZMP UI / React Router tích hợp bên trong template để dẫn hướng giữa các màn hình nghiệp vụ và `/style-guide`.
 - **Cấu hình API**: Base URL mặc định là `http://localhost:7777/api/v1` (tương tác trực tiếp với port 7777 của Backend).
+- **Vite/ZMP entry**: Giữ `index.html` tại root repository và không cấu hình Vite `root: "./src"`. ZMP CLI khởi chạy dev server với project root; cấu hình khác sẽ khiến iframe app trả 404. Build output chuẩn là `www/` tại root.
+- **Luồng xác thực**: Khi app mount, `AuthInitializer` gọi `/auth/me`; `AuthGuard` chỉ render private route sau khi khởi tạo xong và chuyển người dùng chưa đăng nhập tới `/login`. Cookie HTTP-only là cơ chế xác thực ưu tiên.
 
 ## Trạng thái đã biết
 
-- Đã sao chép khung boilerplate từ Zalo Mini App blank template (React + Vite + TypeScript).
-- Đã cài đặt và cấu hình `zmp-sdk` và `zmp-ui` làm thư viện nền tảng cơ bản.
-- Đang bắt đầu quá trình triển khai cấu hình Tailwind, import Fonts, viết các base components phong cách Claymorphism, và dựng trang Style Guide để kiểm thử trực quan.
+- Đã cấu hình React 18, Vite 5, ZMP SDK/UI, Tailwind và bộ base components Claymorphism.
+- Đã có các màn hình đăng nhập, đăng ký, quên mật khẩu, đặt lại mật khẩu, trang chủ, hồ sơ và Style Guide.
+- Đã kết nối frontend với API xác thực, React Query và Zustand auth store.
+- Dev server đã được sửa để nội dung app tại cổng 2999 trả 200 và render đúng thay vì màn hình đen do sai Vite root.
+- Các module tài chính chính (ví, giao dịch, ngân sách, tiết kiệm, báo cáo, AI Assistant) chưa được triển khai trong frontend hiện tại.
 
 ## Khi cập nhật file này
 

.agents/project.md

@@ -14,36 +14,32 @@
 - **State Management**: Zustand cho state toàn cục (auth, ui settings).
 - **Form Validation**: Zod + React Hook Form.
 
-## Cấu trúc thư mục (Feature-based)
+## Cấu trúc thư mục hiện tại
 
 ```text
-src/
-├── app.ts                  # Điểm vào chính của ứng dụng
-├── components/
-│   ├── ui/                 # Base components Claymorphism (Button, Card, Input, v.v.)
-│   └── shared/             # Components nghiệp vụ dùng chung (TransactionItem, WalletCard)
-├── pages/                  # Thư mục chứa các trang nghiệp vụ
-│   ├── home/               # Trang chủ
-│   ├── wallet/             # Quản lý ví
-│   ├── transaction/        # Giao dịch
-│   ├── budget/             # Ngân sách
-│   ├── saving-goal/        # Mục tiêu tiết kiệm
-│   ├── report/             # Báo cáo tài chính
-│   ├── ai-assistant/       # Trợ lý AI tài chính
-│   └── style-guide/        # Trang thử nghiệm & tài liệu Design System
-├── css/
-│   ├── tailwind.scss       # Import directives của Tailwind
-│   └── app.scss            # CSS tùy chỉnh và các lớp phong cách bổ sung
-├── hooks/                  # Custom hooks dùng chung
-├── services/               # Module gọi API (auth.service.ts, wallet.service.ts)
-├── lib/
-│   ├── api-client.ts       # Axios instance có đính kèm Bearer Token & Interceptor tự refresh
-│   └── query-client.ts     # Cấu hình TanStack Query Client
-├── stores/                 # Zustand stores (ví dụ: auth-store.ts)
-├── types/                  # Kiểu dữ liệu TypeScript khớp với BE
-└── utils/                  # Hàm tiện ích (định dạng tiền tệ, ngày tháng)
+├── index.html              # HTML entry ở root; ZMP CLI yêu cầu vị trí này khi chạy dev
+├── app-config.json         # Cấu hình khung hiển thị Zalo Mini App
+├── vite.config.mts         # Vite config; không đổi root sang ./src
+├── www/                    # Build output được sinh bởi `npm run build`
+└── src/
+    ├── app.ts              # React entry, mount vào #app
+    ├── components/
+    │   ├── ui/             # Base components Claymorphism
+    │   └── shared/         # AuthGuard và component nghiệp vụ dùng chung
+    ├── pages/
+    │   ├── auth/           # Đăng nhập, đăng ký, quên/đặt lại mật khẩu
+    │   ├── profile/        # Trang hồ sơ người dùng
+    │   ├── index.tsx       # Trang chủ sau đăng nhập
+    │   └── style-guide.tsx # Trang kiểm thử Design System
+    ├── css/                # Tailwind directives và style bổ sung
+    ├── lib/                # Axios client và React Query client
+    ├── services/           # Module gọi API, hiện có auth.service.ts
+    ├── stores/             # Zustand stores, hiện có auth-store.ts
+    └── types/              # Kiểu dữ liệu dùng chung với backend
 ```
 
+Các module ví, giao dịch, ngân sách, mục tiêu tiết kiệm, báo cáo và AI Assistant là phạm vi sản phẩm dự kiến, chưa có page trong code hiện tại.
+
 ## Luồng API & Dữ liệu
 
 ```text
@@ -55,6 +51,8 @@ Component / Page
 ```
 
 - **Base URL (Development)**: `http://localhost:7777/api/v1` (Port 7777 khớp với Backend `.env`).
+- **Khởi tạo đăng nhập**: `AuthInitializer` gọi `GET /auth/me`; route riêng tư đi qua `AuthGuard` và chuyển về `/login` khi chưa xác thực.
+- **Token**: Ưu tiên cookie HTTP-only; Axios vẫn hỗ trợ Bearer token từ auth store cho luồng tương thích hiện có.
 - **Response Format**:
   ```json
   {
@@ -64,3 +62,9 @@ Component / Page
     "errors": [] | null
   }
   ```
+
+## Dev server và build
+
+- `npm run start` chạy ZMP CLI: khung mô phỏng ở `http://localhost:3000`, nội dung app ở `http://localhost:2999`.
+- `index.html` phải nằm ở root repository. Nếu đặt trong `src/`, iframe nội dung sẽ trả 404 và giao diện có thể chỉ hiện màn hình đen.
+- `npm run build` phải sinh output tại `www/` ở root repository, không phải `src/www/`.

.agents/rules/workflow.md

@@ -16,8 +16,10 @@
   ```
 - Khởi động môi trường dev cục bộ để kiểm tra giao diện trực quan:
   ```bash
-  zmp start
+  npm run start
   ```
+- Xác nhận khung mô phỏng `http://localhost:3000` và iframe app `http://localhost:2999` đều phản hồi. Cổng 2999 trả 404 thường có nghĩa `index.html` không còn ở root hoặc Vite `root` bị cấu hình sai.
+- Xác nhận build output nằm trong `www/` ở root repository; không chấp nhận output nhầm tại `src/www/`.
 - Kiểm tra độ tương thích responsive trên các kích thước màn hình thiết bị di động (tối thiểu là tỷ lệ màn hình 375x812 tiêu chuẩn).
 
 ## 4. Trước khi bàn giao

.gitignore

@@ -14,6 +14,8 @@ pids
 
 # Dependency directories
 node_modules/
+.chrome-cdp/
+.chrome-codex/
 
 # Optional npm cache directory
 .npm

src/index.html → index.html

@@ -23,6 +23,6 @@
     <div id="app"></div>
     <!-- built script files will be auto injected -->
 
-    <script type="module" src="/app.ts"></script>
+    <script type="module" src="/src/app.ts"></script>
   </body>
 </html>

vite.config.mts

@@ -6,7 +6,6 @@ import path from "path";
 // https://vitejs.dev/config/
 export default () => {
   return defineConfig({
-    root: "./src",
     base: "",
     plugins: [zaloMiniApp(), react()],
     build: {