From 284183098ee7068d37cd05522d9daabf3851d63c Mon Sep 17 00:00:00 2001 From: Thanh Quy - wolf <524H0124@student.tdtu.edu.vn> Date: Sun, 29 Mar 2026 20:17:55 +0700 Subject: [PATCH] docs: update and create comprehensive markdown documentation - Updated README.md with current features (Auth, Cart, Feed pages) - Updated COMPONENTS.md with CartFab and all context providers (Auth, Cart, Menu) - Created APP.md: detailed documentation of all routes and pages - Created LIB.md: documentation of types, constants, and contexts - Created LAYOUTS.md: header and footer component documentation - Updated TODO.md: reflects completed implementations and future work This provides agents with comprehensive documentation to understand the project structure and implementation details. Co-Authored-By: Claude Opus 4.6 --- README.md | 115 +++++++-- TODO.md | 137 ++++++++--- app/APP.md | 361 +++++++++++++++++++++++++++++ components/COMPONENTS.md | 151 ++++++++++++ layouts/LAYOUTS.md | 486 +++++++++++++++++++++++++++++++++++++++ lib/LIB.md | 461 +++++++++++++++++++++++++++++++++++++ 6 files changed, 1653 insertions(+), 58 deletions(-) create mode 100644 app/APP.md create mode 100644 layouts/LAYOUTS.md create mode 100644 lib/LIB.md diff --git a/README.md b/README.md index 019fe74..6c9b36f 100644 --- a/README.md +++ b/README.md @@ -8,17 +8,46 @@ Dự án Frontend cho hệ thống đặt món cà phê, xây dựng bằng Next Giao diện người dùng (frontend) cho hệ thống đặt và bán đồ uống trực tuyến. -### Trang Người Dùng (User Page - /) -Dành cho khách hàng: -- Duyệt thực đơn theo danh mục (sidebar collapsible) -- Tìm kiếm món theo tên / mô tả -- Xem card sản phẩm với giá và nút Mua -- Lọc tự động theo trạng thái available +### Tính Năng Hiện Tại -### Trang Quản Lý (Manager Page - chưa triển khai) -Dành cho chủ quán / nhân viên: -- Quản lý thực đơn (thêm, sửa, xóa món) -- Theo dõi và xử lý đơn hàng +#### 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 +- Lưu trữ thông tin người dùng trong localStorage +- 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) +- Danh sách các quán cà phê +- Tìm kiếm theo tên quán và địa chỉ +- Thẻ quán với ảnh, địa chỉ, nút "Xem menu" +- 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)) +Dành cho khách hàng: +- Sidebar collapsible (64px/240px) - danh mục sản phẩm +- Grid sản phẩm responsive (1-5 cột tuỳ thiết bị) +- Tìm kiếm món theo tên / mô tả +- Xem card sản phẩm với giá và nút "Mua" +- 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) +- 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) +- 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) +- Chia sẻ trạng thái category giữa Header mobile và Sidebar +- Tự động clear search khi thay đổi category --- @@ -56,23 +85,45 @@ pnpm lint ``` frondend/ +-- app/ # Next.js App Router -| +-- layout.tsx # Root layout -| +-- page.tsx # Trang chủ - sidebar + product grid +| +-- 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 -| +-- COMPONENTS.md # Tài liệu component +| +-- 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 -| +-- footer.tsx # Footer +| +-- 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 +| +-- 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 -+-- WORKFLOW.md # Tài liệu kiến trúc & quy trình +| +-- imgs/ +| | +-- logo.png +| | +-- 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 +-- next.config.ts +-- tsconfig.json +-- postcss.config.mjs @@ -100,9 +151,27 @@ frondend/ ## Ghi Chú Phát Triển -- Trang chủ (app/page.tsx) là điểm vào chính của User Page -- Design tokens định nghĩa trong app/globals.css dưới dạng CSS custom properties -- Mock data nằm trong lib/constants.ts - thay bằng API calls khi backend sẵn sàng -- Dark mode: biến CSS đã chuẩn bị sẵn trong globals.css nhưng chưa kích hoạt -- Ảnh sản phẩm: thêm ảnh thực vào public/imgs/products/ -- Xem WORKFLOW.md để hiểu kiến trúc tổng thể và quy trình mở rộng dự án +### Điểm Vào Chính +- **Trang Chủ (User):** `app/(main)/page.tsx` - Duyệt thực đơn +- **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` + +### Design & Styling +- Design tokens (CSS variables) định nghĩa trong `app/globals.css` +- Tailwind CSS v4 + custom properties cho consistent color/spacing +- Dark mode: biến CSS đã chuẩn bị sẵn nhưng chưa kích hoạt +- FontAwesome icons từ CDN + +### Data & Integration +- Mock data nằm trong `lib/constants.ts` +- Context providers trong `app/providers.tsx` - Sử dụng: AuthProvider, MenuProvider, CartProvider +- 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 +- **APP.md** - Chi tiết các routes, layouts, pages +- **COMPONENTS.md** - Tài liệu từng component + contexts +- **LAYOUTS.md** - Header, Footer, responsive behavior +- **LIB.md** - Constants, Types, Contexts diff --git a/TODO.md b/TODO.md index 39ec01b..8a286bf 100644 --- a/TODO.md +++ b/TODO.md @@ -1,52 +1,119 @@ # Coffee Shop Frontend - TODO -## Completed Optimizations +## Completed Features & Implementations -### A. Dead Code Removed -- [x] lib/constants.ts - Removed unused NAV_LINKS export -- [x] lib/types.ts - Removed unused NavLink interface -- [x] components/Navbar.tsx - Removed trivial handleClick wrapper; inlined onCategoryChange call -- [x] components/Navbar.tsx - Removed unused Link import +### A. Documentation +- [x] README.md - Updated with current features (Auth, Cart, Feed, etc.) +- [x] COMPONENTS.md - Added CartFab, AuthContext, CartContext, MenuContext sections +- [x] APP.md - New file: Detailed app routes, pages, layouts +- [x] LIB.md - New file: Types, Constants, Contexts documentation +- [x] LAYOUTS.md - New file: Header & Footer detailed documentation +- [x] WORKFLOW.md - Architecture and workflow documentation -### B. Bugs / Inaccuracies Fixed -- [x] layouts/header.tsx - Fixed JSDoc: 3-column -> 2-column layout (no center section exists) -- [x] app/page.tsx - Added available !== false filter to product list -- [x] app/page.tsx - Fixed setState-in-effect lint error: moved initial sidebar state to lazy useState initializer -- [x] next.config.ts - Added explanatory JSDoc comment +### B. Authentication System +- [x] lib/auth-context.tsx - Created Auth context with login/logout/register +- [x] lib/types.ts - User type with roles (manager, staff, customer) +- [x] app/(main)/login/page.tsx - Login page with form validation +- [x] app/(main)/register/page.tsx - Register page with OTP verification +- [x] localStorage integration - Persist user across sessions +- [x] Mock auth database - Pre-configured accounts for testing -### C. Documentation Updated -- [x] README.md - Fixed file structure tree, removed SCSS, fixed dark mode note, updated tech table -- [x] components/COMPONENTS.md - Fixed CartProduct styling (was outdated w-64/text-red-500/bg-blue-600); added Navbar, Header, Footer sections +### C. Shopping Cart System +- [x] lib/cart-context.tsx - Cart context with add/remove/update operations +- [x] Cart persistence - localStorage integration +- [x] CartItem interface - With id, name, description, price, quantity +- [x] Cart operations - addToCart, increaseQty, decreaseQty, removeFromCart, setQuantity +- [x] Computed totals - totalItems and totalPrice memoized -### D. New Documentation Created -- [x] WORKFLOW.md - Architecture, data flow, design token system, how-to guides, dev workflow +### D. Menu/Category System +- [x] lib/menu-context.tsx - MenuContext for shared category state +- [x] Shared state across components - Header mobile menu + Navbar sidebar sync +- [x] Category filtering - Products filtered by active category -### E. Mini-test Results -- [x] npm run lint - PASSED (0 errors, 0 warnings) -- [x] npm run build - PASSED (Compiled successfully, TypeScript clean, static pages generated) +### E. Product Pages +- [x] app/(main)/page.tsx - Main page with sidebar + product grid +- [x] Responsive product grid - 1-5 columns depending on sidebar & screen size +- [x] Product search - Search by name and description +- [x] Category filter - Sidebar collapsible navigation +- [x] Mobile category menu - Scrollable tabs on < md breakpoint +- [x] Empty states - Messaging when no products match filters +- [x] CartProduct component - Product card with image, price, buy button + +### F. Feed/Discovery Page +- [x] app/(feed)/feed/page.tsx - Shop discovery page +- [x] Shop grid - Responsive 1/2/3 column layout +- [x] Search by name and address - Sticky bottom filter bar +- [x] Shop cards - Image, name, address, view menu button +- [x] Empty state - Message when no shops match filters +- [x] MOCK_SHOPS constant - 5 sample coffee shops + +### G. Header & Footer +- [x] layouts/header.tsx - Sticky header with brand and auth demo +- [x] layouts/footer.tsx - Footer with shop info, social links, WiFi +- [x] Responsive layouts - Mobile/tablet/desktop optimized +- [x] Auth state display - Guest/Manager/Staff cycling demo + +### H. Code Quality & Optimization +- [x] Dead code removed - Unused imports and exports cleaned +- [x] Lint passed - 0 errors, 0 warnings +- [x] Build passed - TypeScript clean, all pages compile +- [x] Type safety - Full TypeScript coverage +- [x] React best practices - Hooks, memoization, context patterns --- ## Pending Features (Future Work) ### Cart & Ordering -- [ ] Implement add-to-cart logic (onBuy callback in CartProduct) -- [ ] Cart sidebar or modal with item list and total -- [ ] Order submission flow -- [ ] Payment page +- [ ] Implement cart checkout flow (app/(main)/cart or modal) +- [ ] Cart sidebar/modal with item list and total +- [ ] Order submission API integration +- [ ] Payment page implementation (app/(main)/payment) +- [ ] Order history/tracking page +- [ ] Toast notifications for cart actions + +### Authentication & User Management +- [ ] Real backend authentication (replace MOCK_AUTH_DB) +- [ ] Real OTP delivery service (SMS integration) +- [ ] User profile page with edit capability +- [ ] Password reset/recovery flow +- [ ] Session management and token refresh + +### Manager Features +- [ ] Manager dashboard page (app/(manager)/page.tsx) +- [ ] Product management (add/edit/delete) +- [ ] Category management +- [ ] Order management & tracking +- [ ] Sales analytics/dashboard +- [ ] Inventory management ### Backend Integration -- [ ] Replace MOCK_PRODUCTS with real API calls (lib/api.ts) -- [ ] Replace MOCK_USERS with real authentication -- [ ] Product images: replace placeholder with real images in public/imgs/products/ - -### Manager Page -- [ ] Create app/manager/page.tsx -- [ ] Menu management (add/edit/delete products) -- [ ] Order tracking dashboard +- [ ] Replace MOCK_PRODUCTS with API calls (GET /api/products) +- [ ] Replace MOCK_SHOPS with API calls (GET /api/shops) +- [ ] Replace MOCK_USERS with real authentication (POST /api/auth/login) +- [ ] Real product images (replace placeholder.jpg) +- [ ] Image upload for products ### UX Improvements -- [ ] Dark mode toggle (CSS variables already prepared in globals.css) -- [ ] Loading skeleton for product grid -- [ ] Toast notifications for cart actions -- [ ] Product detail modal/page +- [ ] Dark mode toggle (CSS variables prepared, toggle UI needed) +- [ ] Loading skeletons for product grid +- [ ] Product detail modal/page with full description +- [ ] Wishlist/favorites feature +- [ ] Sort products (price, rating, etc.) +- [ ] Filter by price range +- [ ] Quantity selector in product card +- [ ] Related products suggestions + +### Performance & SEO +- [ ] Dynamic route generation for products (app/(main)/product/[id]/page.tsx) +- [ ] Dynamic route generation for shops (app/(feed)/shop/[id]/page.tsx) +- [ ] Meta tags and Open Graph for SEO +- [ ] Image optimization and lazy loading +- [ ] Code splitting and dynamic imports + +### Accessibility & Testing +- [ ] Keyboard navigation testing +- [ ] ARIA labels audit +- [ ] Unit tests for contexts +- [ ] E2E tests for user flows +- [ ] Accessibility audit (WCAG 2.1 AA) diff --git a/app/APP.md b/app/APP.md new file mode 100644 index 0000000..e3a4ad3 --- /dev/null +++ b/app/APP.md @@ -0,0 +1,361 @@ +# App Routes & Pages Documentation + +> Tài liệu chi tiết về Next.js App Router structure, routes, và layouts + +--- + +## Route Structure Overview + +``` +app/ +├── layout.tsx # Root layout - Header + Footer wrapper +├── globals.css # CSS tokens + Tailwind imports +├── providers.tsx # Context providers (Auth, Menu, Cart) +├── (main)/ +│ ├── layout.tsx # Main layout for authenticated routes +│ ├── page.tsx # Main page - 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)/ + ├── layout.tsx # Feed layout + └── feed/ + └── page.tsx # Trang khám phá quán (/feed) +``` + +--- + +## Root Layout (app/layout.tsx) + +**Description:** Root layout wrapping entire application. Loads providers, fonts, and common layouts (header/footer). + +### Structure +- Imports providers (AuthProvider, MenuProvider, CartProvider) +- Renders Header component (sticky top) +- Renders page content via {children} +- Renders Footer component + +### Metadata +- Title: "Coffee Shop" +- Charset: UTF-8 +- Viewport: responsive + +### Key Features +- Global CSS variables loaded here +- Header remains sticky across all pages +- Footer always present + +--- + +## Providers (app/providers.tsx) + +**Description:** Client component that wraps all context providers for the application. + +### Providers Included +1. **AuthProvider** (lib/auth-context.tsx) + - Manages user authentication state + - Persists user in localStorage + - Enables login/logout/register flows + +2. **MenuProvider** (lib/menu-context.tsx) + - Shares active category state + - Syncs Header mobile menu and Navbar sidebar + +3. **CartProvider** (lib/cart-context.tsx) + - Manages shopping cart state + - Persists cart items in localStorage + - Provides add/remove/update operations + +### Usage in Root Layout +```tsx + +
+ {children} +