docs: comprehensive AGENTS guide for AI development
Update AGENTS.md with detailed project architecture, code conventions, and quick reference guide to help AI understand the codebase structure and development workflow more efficiently. Key additions: - Complete folder structure with descriptions (app/, components/, layouts/, lib/) - File organization and naming conventions - Code style (TypeScript, Prettier, ESLint, Tailwind) - Responsive design guidelines - Markdown documentation update rules - Type safety and data flow patterns - Quick reference guide for common tasks - CSS variables reference - Useful npm commands - Common code patterns - Project status (completed, in progress, planned features) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Thanh Quy - wolf
@@ -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