From 7547260e9091a401ff5693ce32b4c66f76abd6e0 Mon Sep 17 00:00:00 2001 From: Thanh Quy - wolf <524H0124@student.tdtu.edu.vn> Date: Sun, 5 Apr 2026 16:56:34 +0700 Subject: [PATCH] update README.md --- README.md | 168 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 119 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 5d86cb9..209acc0 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Giao diện người dùng (frontend) cho hệ thống đặt và bán đồ u ### Tính Năng Hiện Tại -#### 1. **Trang Đăng Nhập & Đăng Ký** (app/(main)/login, app/(main)/register) +#### 1. **Trang Đăng Nhập & Đăng Ký** (`app/(main)/login`, `app/(main)/register`) - Form đăng nhập với validation (username, password) - Form đăng ký với xác thực OTP @@ -19,7 +19,7 @@ Giao diện người dùng (frontend) cho hệ thống đặt và bán đồ u - Hỗ trợ 3 loại tài khoản: Manager, Staff, Customer - Hiển thị thông tin shop trong form -#### 2. **Trang Khám Phá Quán Nước** (app/(feed)/feed) +#### 2. **Trang Khám Phá Quán Nước** (`app/(feed)/feed`) - Danh sách các quán cà phê - Tìm kiếm theo tên quán và địa chỉ @@ -27,7 +27,7 @@ Giao diện người dùng (frontend) cho hệ thống đặt và bán đồ u - Responsive layout (grid 1/2/3 cột) - Empty state khi không tìm thấy quán -#### 3. **Trang Chính - Duyệt Thực Đơn** (app/(main)) +#### 3. **Trang Chính - Duyệt Thực Đơn** (`app/(main)`) Dành cho khách hàng: @@ -38,25 +38,47 @@ Dành cho khách hàng: - Lọc tự động theo trạng thái available - Mobile menu: scrollable category tabs (< md) -#### 4. **Hệ Thống Giỏ Hàng** (lib/cart-context.tsx) +#### 4. **Trang Thanh Toán** (`app/(main)/payment`) + +- Bảng danh sách sản phẩm trong giỏ hàng với điều chỉnh số lượng +- Invoice aside sticky với tổng giá và nút thanh toán (Tiền mặt, QR) +- Modal đánh giá 5 sao dành riêng cho khách hàng (ReviewModal) + +#### 5. **Hệ Thống Giỏ Hàng** (`lib/cart-context.tsx`) - Lưu trữ trạng thái giỏ trong localStorage - Thêm/xóa/tăng/giảm số lượng sản phẩm - Tính tổng giá và số mặt hàng - Persist dữ liệu giữa các session -#### 5. **Hệ Thống Xác Thực** (lib/auth-context.tsx) +#### 6. **Hệ Thống Xác Thực** (`lib/auth-context.tsx`) - Quản lý trạng thái người dùng (login/logout/register) - Lưu thông tin user trong localStorage - Mock auth database với 3 loại tài khoản - Hỗ trợ hoàn tất đăng ký qua OTP -#### 6. **Hệ Thống Danh Mục** (lib/menu-context.tsx) +#### 7. **Hệ Thống Danh Mục** (`lib/menu-context.tsx`) - Chia sẻ trạng thái category giữa Header mobile và Sidebar - Tự động clear search khi thay đổi category +#### 8. **Manager Dashboard** (`app/(manager)/manager`) + +Dành cho quản lý: + +- Sidebar desktop: Brand, tab navigation (Thực đơn / Combo / Danh mục), link tới Analytics +- CRUD sản phẩm, combo, danh mục qua modals +- Auth guard: tự động redirect non-manager về `/` + +#### 9. **Trang Phân Tích Tài Chính** (`app/(manager)/manager/analytics`) + +- Summary cards: Doanh thu, đơn hàng, lợi nhuận, giá trị đơn trung bình (so sánh kỳ trước) +- Bộ chọn kỳ: Ngày / Tuần / Tháng / Năm +- Biểu đồ SVG thuần: Line, Bar, Pie — hover tooltips tương tác +- Bảng top 5 sản phẩm và bảng chi tiết có thể sắp xếp +- Lọc theo danh mục + --- ## Cách Chạy Dự Án @@ -86,10 +108,17 @@ Mở trình duyệt tại http://localhost:3000 pnpm build && pnpm start ``` -### Lint +### Lint & Format ```bash pnpm lint +pnpm format +``` + +### Release + +```bash +pnpm release ``` --- @@ -98,52 +127,69 @@ pnpm lint ``` frondend/ -+-- app/ # Next.js App Router -| +-- layout.tsx # Root layout + Header + Footer -| +-- globals.css # CSS design tokens + Tailwind import -| +-- providers.tsx # Context providers (Auth, Menu, Cart) -| +-- APP.md # Tài liệu chi tiết về routes -| +-- (main)/ # Main route group -| | +-- layout.tsx # Main layout -| | +-- page.tsx # Trang chính - duyệt thực đơn -| | +-- login/page.tsx # Trang đăng nhập -| | +-- register/page.tsx # Trang đăng ký -| | +-- payment/page.tsx # Trang thanh toán -| +-- (feed)/ # Feed route group -| +-- layout.tsx # Feed layout -| +-- feed/page.tsx # Trang khám phá quán nước -+-- components/ # Shared UI components -| +-- Navbar.tsx # Sidebar danh mục (collapsible) -| +-- CartProduct.tsx # Card sản phẩm -| +-- CartFab.tsx # FAB - nút giỏ hàng floating -| +-- COMPONENTS.md # Tài liệu chi tiết components & contexts -+-- layouts/ # Layout-level components -| +-- header.tsx # Sticky top header + auth demo -| +-- footer.tsx # Footer + shop info -| +-- LAYOUTS.md # Tài liệu chi tiết layouts -+-- lib/ # Shared logic & data -| +-- constants.ts # Mock data (products, shops, users, shop info) -| +-- types.ts # TypeScript interfaces -| +-- auth-context.tsx # Authentication context & provider -| +-- cart-context.tsx # Shopping cart context & provider -| +-- menu-context.tsx # Menu/Category context & provider -| +-- LIB.md # Tài liệu chi tiết về lib -+-- types/ # Global TypeScript declarations -| +-- css.d.ts # CSS module type shim -+-- public/ # Static assets ++-- app/ # Next.js App Router +| +-- layout.tsx # Root layout + Header + Footer +| +-- globals.css # CSS design tokens + Tailwind import +| +-- providers.tsx # Context providers (Auth, Menu, Cart) +| +-- APP.md # Tài liệu chi tiết về routes +| +-- (main)/ # Main route group +| | +-- layout.tsx # Main layout +| | +-- page.tsx # Trang chính - duyệt thực đơn (/) +| | +-- login/page.tsx # Trang đăng nhập (/login) +| | +-- register/page.tsx # Trang đăng ký (/register) +| | +-- payment/page.tsx # Trang thanh toán (/payment) +| +-- (feed)/ # Feed route group +| | +-- layout.tsx # Feed layout +| | +-- feed/page.tsx # Trang khám phá quán nước (/feed) +| +-- (manager)/ # Manager route group +| +-- layout.tsx # Manager layout - auth guard + ManagerProvider +| +-- manager/page.tsx # Manager Dashboard (/manager) +| +-- manager/analytics/page.tsx # Financial Analytics (/manager/analytics) ++-- components/ # Atomic Design UI components +| +-- atoms/ # Nguyên tử: Button, Input, Badge, Text... +| +-- molecules/ # Phân tử: ProductCard, ShopCard, SearchBar... +| +-- organisms/ # Tổ chức: CategorySidebar, CartFab, ProductGrid, +| | # ReviewModal, analytics charts, manager tabs... +| +-- templates/ # Bố cục trang: MainLayout, AuthLayout, +| | # FeedLayout, ManagerLayout +| +-- COMPONENTS.md # Tài liệu chi tiết components (Atomic Design) ++-- layouts/ # Layout-level components +| +-- header.tsx # Sticky top header + auth info +| +-- footer.tsx # Footer + shop info +| +-- LAYOUTS.md # Tài liệu chi tiết layouts ++-- lib/ # Shared logic & data +| +-- constants.ts # Mock data (products, shops, users, analytics, shop info) +| +-- types.ts # TypeScript interfaces +| +-- auth-context.tsx # Authentication context & provider +| +-- cart-context.tsx # Shopping cart context & provider +| +-- menu-context.tsx # Menu/Category context & provider +| +-- manager-context.tsx # Manager CRUD context & provider +| +-- analytics-utils.ts # Financial analytics helper utilities +| +-- LIB.md # Tài liệu chi tiết về lib ++-- types/ # Global TypeScript declarations +| +-- css.d.ts # CSS module type shim ++-- public/ # Static assets | +-- imgs/ | | +-- logo.png -| | +-- products/ # Ảnh sản phẩm +| | +-- products/ # Ảnh sản phẩm | +-- favicon/ -+-- WORKFLOW.md # Tài liệu kiến trúc tổng thể & quy trình -+-- README.md # (file này) - Mô tả dự án -+-- TODO.md # Danh sách tính năng hoàn thành & chưa làm ++-- scripts/ # Release & CI scripts +| +-- release.ts ++-- WORKFLOW.md # Tài liệu kiến trúc tổng thể & quy trình ++-- README.md # (file này) - Mô tả dự án ++-- TODO.md # Danh sách tính năng hoàn thành & chưa làm ++-- Atomic.md # Hướng dẫn cấu trúc Atomic Design ++-- AGENTS.md # Hướng dẫn cho AI agents +-- next.config.ts +-- tsconfig.json +-- postcss.config.mjs -+-- eslint.config.mjs ++-- eslint.config.ts ++-- release.config.ts +-- package.json ++-- pnpm-lock.yaml +-- pnpm-workspace.yaml ++-- dockerfile ++-- k8s.yaml ``` --- @@ -155,11 +201,13 @@ frondend/ | Next.js | 16.1.7 | React Framework (App Router) | | React | 19.2.3 | Thư viện UI | | TypeScript | ^5 | Kiểu dữ liệu tĩnh | -| Tailwind CSS | ^4 | Utility-first CSS framework | +| Tailwind CSS | ^4.2.2 | Utility-first CSS framework | | Geist Font | - | Font chữ (Google Fonts via next/font) | | FontAwesome | 6.7.2 | Icon library (CDN) | | pnpm | - | Package manager | | ESLint | ^9 | Linting | +| Prettier | ^3 | Code formatting | +| semantic-release | ^25 | Automated versioning & release | --- @@ -171,6 +219,17 @@ frondend/ - **Trang Khám Phá:** `app/(feed)/feed/page.tsx` - Khám phá quán - **Đăng Nhập:** `app/(main)/login/page.tsx` - **Đăng Ký:** `app/(main)/register/page.tsx` +- **Thanh Toán:** `app/(main)/payment/page.tsx` +- **Manager Dashboard:** `app/(manager)/manager/page.tsx` +- **Phân Tích Tài Chính:** `app/(manager)/manager/analytics/page.tsx` + +### Tài Khoản Demo + +| Loại tài khoản | Tên đăng nhập | Mật khẩu | +| -------------- | -------------- | -------------- | +| Manager | admin | admin | +| Staff | Nguyễn Văn An | Nguyễn Văn An | +| Customer | 0987654321 | user1 | ### Design & Styling @@ -179,18 +238,29 @@ frondend/ - Dark mode: biến CSS đã chuẩn bị sẵn nhưng chưa kích hoạt - FontAwesome icons từ CDN +### Kiến Trúc Component (Atomic Design) + +Dự án tuân theo **Atomic Design** pattern — chi tiết tại `Atomic.md`: + +- **Atoms** - Nguyên tố cơ bản: Button, Input, Badge, Text, Heading, Divider +- **Molecules** - Nhóm atoms: ProductCard, ShopCard, SearchBar, PaymentSummaryCard +- **Organisms** - Phần UI phức tạp: CategorySidebar, CartFab, ProductGrid, ShopGrid, ReviewModal, analytics charts, manager tabs/modals +- **Templates** - Bố cục trang: MainLayout, AuthLayout, FeedLayout, ManagerLayout + ### Data & Integration - Mock data nằm trong `lib/constants.ts` -- Context providers trong `app/providers.tsx` - Sử dụng: AuthProvider, - MenuProvider, CartProvider +- Context providers trong `app/providers.tsx`: AuthProvider, MenuProvider, CartProvider +- ManagerProvider được thêm bởi `app/(manager)/layout.tsx` - Thay bằng API calls khi backend sẵn sàng - Ảnh sản phẩm: thêm vào `public/imgs/products/` ### Tài Liệu Chi Tiết - **WORKFLOW.md** - Kiến trúc tổng thể, data flow, quy trình phát triển +- **Atomic.md** - Cấu trúc Atomic Design và quy ước component - **APP.md** - Chi tiết các routes, layouts, pages -- **COMPONENTS.md** - Tài liệu từng component + contexts +- **COMPONENTS.md** - Tài liệu từng component (Atomic Design) - **LAYOUTS.md** - Header, Footer, responsive behavior - **LIB.md** - Constants, Types, Contexts +- **AGENTS.md** - Hướng dẫn cho AI agents làm việc với codebase