diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..61d3928 --- /dev/null +++ b/AGENTS.md @@ -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 ``) +- **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_` (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(); + +``` + +**Conditional rendering for user roles:** +```tsx +const { user } = useAuth(); +{user?.role === "customer" && } +{user?.role === "manager" && } +``` + +**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