Fix bug pull request #28
@@ -0,0 +1,304 @@
|
||||
# AGENTS GUIDE
|
||||
|
||||
## 1) Kiến trúc project
|
||||
|
||||
Dự án sử dụng **Next.js App Router** với cấu trúc chính:
|
||||
|
||||
### `app/` - Routes & Pages
|
||||
Chứa route/page/layout theo Next.js App Router.
|
||||
- **`layout.tsx`** - Root layout toàn app (Header + Providers + Footer wrapper)
|
||||
- **`providers.tsx`** - Client component gắn 3 providers: AuthProvider, MenuProvider, CartProvider
|
||||
- **`globals.css`** - Global styles + CSS variables + Tailwind imports
|
||||
- **Route groups:**
|
||||
- **`(main)/`** - Main shopping interface (duyệt menu, đăng nhập, đăng ký, thanh toán)
|
||||
- **`(feed)/`** - Feed/discovery page (khám phá quán)
|
||||
- **`(manager)/`** - Manager dashboard (quản lý sản phẩm, đơn hàng) - **[ĐANG PHÁT TRIỂN]**
|
||||
- **Tài liệu:** `app/APP.md` - Chi tiết routes, pages, CSS tokens
|
||||
|
||||
### `components/` - Reusable UI Components
|
||||
Chứa các UI component tái sử dụng:
|
||||
- **`CartProduct.tsx`** - Product card (image, name, price, buy button)
|
||||
- **`Navbar.tsx`** - Left sidebar với category filter (collapsible 64px/240px)
|
||||
- **`CartFab.tsx`** - Floating action button hiển thị số item giỏ + tooltip giá
|
||||
- **`ReviewModal.tsx`** - Modal đánh giá 5 sao + textarea
|
||||
- **Tài liệu:** `components/COMPONENTS.md` - Props, behavior, styling của từng component
|
||||
|
||||
### `layouts/` - Layout Components
|
||||
Chứa layout dùng chung:
|
||||
- **`header.tsx`** - Sticky top bar với brand (logo + shop name) + auth status
|
||||
- **`footer.tsx`** - Footer với 3 sections: brand info, social links, WiFi card
|
||||
- **Tài liệu:** `layouts/LAYOUTS.md` - Responsive design, CSS variables, responsive patterns
|
||||
|
||||
### `lib/` - Shared Logic & Data
|
||||
Chứa logic dùng chung, context, constants, types:
|
||||
- **`types.ts`** - TypeScript interfaces: User, Product, MenuCategory, Shop, ShopInfo
|
||||
- **`constants.ts`** - Mock data: MOCK_PRODUCTS (18 items), MOCK_SHOPS (5), MOCK_USERS, MENU_CATEGORIES (8), SHOP_INFO, SOCIAL_LINKS
|
||||
- **`auth-context.tsx`** - AuthProvider + useAuth() hook (login, logout, register)
|
||||
- **`cart-context.tsx`** - CartProvider + useCart() hook (add, remove, quantity operations)
|
||||
- **`menu-context.tsx`** - MenuProvider + useMenu() hook (category state)
|
||||
- **Tài liệu:** `lib/LIB.md` - Chi tiết types, constants, contexts, integration guide
|
||||
|
||||
### `public/` - Static Assets
|
||||
Chứa static assets:
|
||||
- **`favicon/`** - Favicon files
|
||||
- **`imgs/`** - Logo, product images (organized in `products/` subfolder)
|
||||
|
||||
### `scripts/` - Internal Scripts
|
||||
Chứa script nội bộ:
|
||||
- **`release.ts`** - Semantic release script
|
||||
|
||||
### `types/` - Global Types
|
||||
Chứa type dùng chung cấp project:
|
||||
- **`css.d.ts`** - TypeScript declarations cho CSS modules
|
||||
|
||||
### Root Config Files
|
||||
- **`package.json`** - Dependencies (Next.js 16.1.7, React 19.2.3, Tailwind 4.2.2, TypeScript)
|
||||
- **`pnpm-lock.yaml`, `package-lock.json`** - Lock files
|
||||
- **`tsconfig.json`** - TypeScript config
|
||||
- **`next.config.ts`** - Next.js config
|
||||
- **`tailwind.config.ts`** - Tailwind CSS config (v4)
|
||||
- **`postcss.config.mjs`** - PostCSS config
|
||||
- **`eslint.config.ts`** - ESLint rules
|
||||
- **`.prettierrc`** - Prettier formatting
|
||||
- **`release.config.ts`** - Semantic release config
|
||||
- **`.gitignore`** - Git ignored files
|
||||
- **`.blackboxrules`** - Custom rules for blackbox AI
|
||||
|
||||
## 2) Code convention (Naming, format, style guide)
|
||||
|
||||
### Naming & File Organization
|
||||
- **React components:** `PascalCase` (e.g., `CartProduct.tsx`, `Navbar.tsx`)
|
||||
- **Context/util files:** `kebab-case` (e.g., `auth-context.tsx`, `menu-context.tsx`)
|
||||
- **Variables/functions:** `camelCase`
|
||||
- **Types/Interfaces:** `PascalCase`
|
||||
- **Routes:** Follow folder structure in `app/` (URL = folder path)
|
||||
- **Imports:** Use absolute paths with `@/` alias (e.g., `import { useAuth } from "@/lib/auth-context"`)
|
||||
|
||||
### Format & Linting
|
||||
- **Language:** TypeScript (.ts, .tsx) for all files
|
||||
- **Formatter:** Prettier (config: `.prettierrc`)
|
||||
- Import sorting: `@trivago/prettier-plugin-sort-imports`
|
||||
- Tailwind class sorting: `prettier-plugin-tailwindcss`
|
||||
- **Linter:** ESLint (config: `eslint.config.ts`, extends `next` rules)
|
||||
- **Code style:**
|
||||
- Clear, self-documenting code
|
||||
- Separate concerns by module/file
|
||||
- Avoid code duplication
|
||||
- Keep imports clean (no dead code)
|
||||
- Use `"use client"` directive only where needed (interactive components)
|
||||
|
||||
### Styling & UI
|
||||
- **Framework:** Tailwind CSS v4.2.2
|
||||
- **CSS Variables:** Defined in `globals.css` at `:root`
|
||||
- Colors: `--color-primary`, `--color-primary-dark`, `--color-accent`, `--color-bg-*`, `--color-text-*`, `--color-border-*`, `--color-shadow-*`
|
||||
- Spacing: `--spacing-header-height` (72px)
|
||||
- Use in Tailwind: `bg-[color:var(--color-primary)]`, `text-[color:var(--color-text-primary)]`
|
||||
- **Icons:** FontAwesome (free CDN icons via `<i class="fa-solid fa-...">`)
|
||||
- **Images:** Next.js `Image` component from `next/image`
|
||||
- **Dark mode:** CSS variables support dark mode (can override `:root` values in `@media (prefers-color-scheme: dark)`)
|
||||
|
||||
### Responsive Design
|
||||
- **Breakpoints (Tailwind):** sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px)
|
||||
- **Every new UI feature must be responsive:**
|
||||
- Mobile (<640px): Single column, stacked layout, collapsed sidebar
|
||||
- Tablet (640px-1024px): 2-column layout, adjusted grid
|
||||
- Desktop (1024px+): Multi-column, expanded sidebar, comfortable spacing
|
||||
- **Mobile-first approach:** Write base styles for mobile, then add `sm:`, `md:`, `lg:`, `xl:` prefixes for larger screens
|
||||
- **Example:** `className="w-full sm:w-1/2 md:w-1/3 lg:w-1/4"`
|
||||
|
||||
## 3) Quy tắc quan trọng
|
||||
|
||||
### Markdown Documentation Updates
|
||||
**Luôn update các file markdown trong folder liên quan khi hoàn thành task:**
|
||||
|
||||
| Folder Modified | Update File | Content to Add/Update |
|
||||
|---|---|---|
|
||||
| `app/` | `app/APP.md` | Routes, pages, layouts, CSS tokens, responsive behavior |
|
||||
| `components/` | `components/COMPONENTS.md` | Component props, behavior, styling, dependencies, usage examples |
|
||||
| `layouts/` | `layouts/LAYOUTS.md` | Layout structure, responsive patterns, CSS variables, integration |
|
||||
| `lib/` | `lib/LIB.md` | New types, constants, contexts, integration guide, best practices |
|
||||
|
||||
**Quy trình:**
|
||||
1. Hoàn thành task/feature
|
||||
2. Update file `.md` tương ứng trong folder
|
||||
3. Commit code + markdown updates cùng lúc
|
||||
4. Push to branch
|
||||
|
||||
### Type Safety & Data Flow
|
||||
- **Always use TypeScript** - no plain `any` types
|
||||
- **Mock data first** - Use `lib/constants.ts` for development, replace with API later
|
||||
- **Contexts for state sharing:**
|
||||
- `AuthContext` (lib/auth-context.tsx) - User state + auth operations
|
||||
- `CartContext` (lib/cart-context.tsx) - Shopping cart + operations
|
||||
- `MenuContext` (lib/menu-context.tsx) - Active category state
|
||||
- **localStorage keys:** `coffee-shop-user`, `coffee-shop-cart` (defined in contexts)
|
||||
|
||||
### Component Development
|
||||
- **Client vs Server Components:**
|
||||
- Use `"use client"` only for interactive components (forms, state, event handlers)
|
||||
- Server components by default (layouts, static content)
|
||||
- **Props pattern:** Always define prop interfaces, no unnamed parameters
|
||||
- **Reusable components:** Place in `components/`, not scattered in `app/`
|
||||
- **Styling:** Use Tailwind + CSS variables, not inline styles or CSS files
|
||||
|
||||
### Testing & Quality
|
||||
- **Responsive testing:** Test on mobile (< 640px), tablet (768px), desktop (1024px+)
|
||||
- **Accessibility:** Images have alt text, buttons have semantic HTML, sufficient contrast
|
||||
- **Performance:** Use Next.js Image component, optimize imports, lazy-load where needed
|
||||
- **Error handling:** Validate user input at system boundaries, not internally trusted code
|
||||
|
||||
### Git & Commits
|
||||
- **Commit message:** Follow conventional commits (`feat:`, `fix:`, `docs:`, `style:`, `refactor:`)
|
||||
- **Before pushing:** Ensure `npm run lint` and `npm run format` pass locally
|
||||
- **Markdown updates:** Include in same commit as code changes
|
||||
- **Branch naming:** Feature branches = `feature_<name>` (e.g., `feature_manager_page`)
|
||||
|
||||
---
|
||||
|
||||
## 4) Quick Reference Guide for AI
|
||||
|
||||
### Creating a New Component
|
||||
1. Create file in `components/ComponentName.tsx` (PascalCase)
|
||||
2. Use TypeScript with proper prop interfaces
|
||||
3. Export default component
|
||||
4. Add section to `components/COMPONENTS.md`
|
||||
|
||||
### Creating a New Page
|
||||
1. Create folder: `app/(group-name)/page-name/page.tsx`
|
||||
2. Add `"use client"` if interactive
|
||||
3. Use context hooks as needed: `useAuth()`, `useCart()`, `useMenu()`
|
||||
4. Document in `app/APP.md`
|
||||
|
||||
### Adding a New Route Group
|
||||
1. Create folder: `app/(group-name)/`
|
||||
2. Create `layout.tsx` if custom layout needed
|
||||
3. Add pages under this group
|
||||
4. Update `app/APP.md`
|
||||
|
||||
### Adding Product Categories
|
||||
1. Update `MENU_CATEGORIES` in `lib/constants.ts`
|
||||
2. Update `Product.category` references
|
||||
3. Update `MOCK_PRODUCTS` with new category items
|
||||
4. Document in `lib/LIB.md`
|
||||
|
||||
### Adding Mock Products
|
||||
1. Add to `MOCK_PRODUCTS` array in `lib/constants.ts`
|
||||
2. Ensure `Product` interface fields are filled
|
||||
3. Place images in `public/imgs/products/`
|
||||
4. Test filtering in main page
|
||||
|
||||
### Using Contexts
|
||||
```tsx
|
||||
// In client component with "use client"
|
||||
import { useAuth } from "@/lib/auth-context";
|
||||
import { useCart } from "@/lib/cart-context";
|
||||
import { useMenu } from "@/lib/menu-context";
|
||||
|
||||
export default function MyComponent() {
|
||||
const { user, login, logout } = useAuth();
|
||||
const { items, addToCart, removeFromCart } = useCart();
|
||||
const { activeCategory, setActiveCategory } = useMenu();
|
||||
// ... component logic
|
||||
}
|
||||
```
|
||||
|
||||
### Common File Locations
|
||||
- **Page layouts:** `app/(group-name)/layout.tsx`
|
||||
- **Page content:** `app/(group-name)/page-name/page.tsx`
|
||||
- **Shared UI components:** `components/ComponentName.tsx`
|
||||
- **Layout wrappers:** `layouts/header.tsx`, `layouts/footer.tsx`
|
||||
- **Business logic:** `lib/auth-context.tsx`, `lib/cart-context.tsx`, etc.
|
||||
- **Data/constants:** `lib/constants.ts`
|
||||
- **Type definitions:** `lib/types.ts`
|
||||
- **Styling:** `app/globals.css` (CSS variables), Tailwind classes in components
|
||||
|
||||
### CSS Variables (from `globals.css`)
|
||||
```css
|
||||
/* Colors */
|
||||
--color-primary: main brand color
|
||||
--color-primary-dark: darker shade
|
||||
--color-accent: secondary color
|
||||
--color-bg-main: main background
|
||||
--color-bg-card: card background
|
||||
--color-bg-sidebar: sidebar background
|
||||
--color-text-primary: main text color
|
||||
--color-text-secondary: secondary text
|
||||
--color-text-muted: gray/muted text
|
||||
--color-border: border color
|
||||
--color-border-light: light border
|
||||
--color-shadow-sm: small shadow
|
||||
--color-shadow-md: medium shadow
|
||||
|
||||
/* Spacing */
|
||||
--spacing-header-height: 72px
|
||||
```
|
||||
|
||||
### Useful Commands
|
||||
```bash
|
||||
# Development
|
||||
npm run dev # Start dev server
|
||||
|
||||
# Code quality
|
||||
npm run lint # Run ESLint
|
||||
npm run format # Format code with Prettier
|
||||
|
||||
# Build & Deploy
|
||||
npm run build # Build for production
|
||||
npm start # Start production server
|
||||
|
||||
# Release
|
||||
npm run release # Semantic release (auto-version + changelog)
|
||||
```
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**Filtering products by category:**
|
||||
```tsx
|
||||
const filtered = MOCK_PRODUCTS.filter(p =>
|
||||
activeCategory === "all" || p.category === activeCategory
|
||||
);
|
||||
```
|
||||
|
||||
**Adding to cart:**
|
||||
```tsx
|
||||
const { addToCart } = useCart();
|
||||
<button onClick={() => addToCart(product)}>Add to Cart</button>
|
||||
```
|
||||
|
||||
**Conditional rendering for user roles:**
|
||||
```tsx
|
||||
const { user } = useAuth();
|
||||
{user?.role === "customer" && <CustomerOnlyFeature />}
|
||||
{user?.role === "manager" && <ManagerDashboard />}
|
||||
```
|
||||
|
||||
**Responsive classes:**
|
||||
```tsx
|
||||
// Mobile-first: base style applies to all, sm:/md:/lg: apply at breakpoints
|
||||
className="w-full sm:w-1/2 md:w-1/3 p-4 md:p-6 hidden md:block"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5) Project Status
|
||||
|
||||
### ✅ Completed Features
|
||||
- User authentication (login, register, logout)
|
||||
- Product grid display with category filtering
|
||||
- Shopping cart with add/remove/update operations
|
||||
- Payment page with review modal
|
||||
- Shop discovery (feed page)
|
||||
- Responsive design (mobile, tablet, desktop)
|
||||
- Header + Footer with navigation
|
||||
- Sidebar category filter
|
||||
|
||||
### 🚀 In Progress
|
||||
- Manager dashboard (quản lý sản phẩm) - `app/(manager)/` route group
|
||||
|
||||
### 📋 Planned Features
|
||||
- Order history and tracking
|
||||
- User profile page
|
||||
- Real backend API integration (replace MOCK_PRODUCTS, MOCK_SHOPS)
|
||||
- Dark mode toggle
|
||||
- Search functionality enhancement
|
||||
- Admin order management page
|
||||
Reference in New Issue
Block a user