# Agent Instructions for Trace Frontend

## Build & Development Commands

### Development
```bash
pnpm dev                # Start dev server at http://localhost:5173
```

### Build
```bash
pnpm build              # Build for production (outputs to dist/)
pnpm preview            # Preview production build
```

### Testing & Linting
No test or lint commands are currently configured. When adding tests, use Vitest or Jest.

## Project Overview

This is a React 19 + TypeScript frontend for the Zhejiang Beifan Trace Management Platform (溯源管理平台). It provides:
- Public query interface for serial number verification
- Admin dashboard for QR code generation and company management
- User authentication and profile management

**Tech Stack**: React 19, TypeScript, Vite 7, Ant Design 6, React Router v7, Axios

## Code Style Guidelines

### File Organization
```
src/
├── components/        # Reusable UI components (AdminLayout, etc.)
├── pages/            # Page components (Login, Dashboard, etc.)
├── services/         # API service layer (api.ts with domain-specific APIs)
├── types/            # TypeScript type definitions (index.ts)
├── hooks/            # Custom React hooks
├── utils/            # Utility functions
├── styles/           # Global CSS files
├── assets/           # Static assets (images, etc.)
├── App.tsx           # Main app with routes
└── main.tsx          # Application entry point
```

### Imports
- Use `@/` alias for src directory (configured in vite.config.ts and tsconfig.json)
- Group imports: React/hooks first, then third-party libraries, then internal imports
- Example:
  ```tsx
  import { useState } from 'react';
  import { Form, Input, Button } from 'antd';
  import { UserOutlined } from '@ant-design/icons';
  import { useNavigate } from 'react-router-dom';
  import { authApi } from '@/services/api';
  import type { User } from '@/types';
  ```

### Naming Conventions
- **Components**: PascalCase (e.g., `LoginPage`, `AdminLayout`)
- **Functions/Methods**: camelCase (e.g., `handleLogin`, `loadStats`)
- **Constants**: UPPER_SNAKE_CASE (e.g., `API_BASE_URL`)
- **Types/Interfaces**: PascalCase (e.g., `User`, `Company`, `ApiResponse<T>`)
- **Files**: PascalCase for components/pages, lowercase for services/utils

### TypeScript
- All new code must be TypeScript
- Use `interface` for object shapes, `type` for unions/aliases
- Explicit return types for API functions and handlers
- Use `any` only as last resort - prefer `unknown` with type guards
- Strict mode enabled: no unused locals, no unused parameters

### Component Patterns
- Use functional components with hooks
- For pages: use `function PageName()` (not arrow functions)
- For layout/reusable components: use `function ComponentName()`
- Export with `export default ComponentName;`
- Use Ant Design components via destructuring: `const { Button, Form } = antd;`

### Error Handling
- Use try-catch blocks for async operations
- Display errors with Ant Design `message.error()`
- API services throw errors with descriptive messages
- Global axios interceptor handles 401 (auth) and 404 (not found) automatically

### API Services
- API calls organized by domain in `src/services/api.ts`:
  - `authApi` - Authentication (login, logout, profile)
  - `serialApi` - Serial number management
  - `companyApi` - Company management
  - `dashboardApi` - Dashboard statistics
- Auth token automatically added via axios interceptor
- All API calls return typed responses based on `src/types/index.ts`

### Routing
- Use React Router v7 with `<Routes>` and `<Route>` components
- Protected routes wrapped with `<PrivateRoute>` component
- Admin pages wrapped with `<AdminRoutes>` layout component
- Use `useNavigate()` for programmatic navigation
- Use `useLocation()` to get current path

### State Management
- Use React hooks (`useState`, `useEffect`) for local component state
- Authentication state persisted in localStorage via authApi
- No global state management library currently used

### Styling
- Global styles in `src/styles/global.css`
- Component-specific CSS in co-located styles directory (e.g., `pages/styles/Login.css`)
- Import component styles with relative path: `import './styles/PageName.css';`
- Use Ant Design components for primary UI, custom CSS for layout specifics

### Locale & Internationalization
- Chinese (zh_CN) locale configured globally via `ConfigProvider` in main.tsx
- All UI text should be in Chinese
- Ant Design components automatically use Chinese locale

## Key Patterns & Conventions

### Page Component Structure
```tsx
function PageName() {
  const [loading, setLoading] = useState(false);
  const [data, setData] = useState<DataType | null>(null);

  useEffect(() => {
    loadData();
  }, []);

  const loadData = async () => {
    setLoading(true);
    try {
      const result = await apiMethod();
      setData(result);
    } catch (error: any) {
      message.error(error.message || '加载数据失败');
    } finally {
      setLoading(false);
    }
  };

  if (loading) {
    return <Spin size="large" />;
  }

  return <div>{/* JSX content */}</div>;
}

export default PageName;
```

### Route Guards
- `<PrivateRoute />` - Redirects to /login if not authenticated
- `<PublicRoute children={...} />` - Redirects to /admin/dashboard if authenticated
- Use `<Outlet />` for nested routes

### Environment Variables
- Use Vite's `import.meta.env.VITE_*` pattern
- Example: `const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api';`
- Define in `.env` file (not committed to git)

## Notes for Agents

1. **No tests configured**: When adding test frameworks, update AGENTS.md accordingly
2. **No linter configured**: Consider adding ESLint and Prettier
3. **Authentication flow**: Tokens stored in localStorage, added to requests via interceptor
4. **API proxy**: /api requests proxied to http://localhost:3000 during dev (see vite.config.ts)
5. **QR Code generation**: Uses `qrcode` library for generating QR codes for serial numbers
6. **Admin Layout**: Uses Ant Design Layout with Sider navigation and Header
7. **Type safety**: Always add types for new props, state, and API responses

## Common Tasks

### Add a new API endpoint
1. Add interface to `src/types/index.ts`
2. Add method to appropriate API object in `src/services/api.ts`
3. Handle errors appropriately with descriptive messages

### Add a new page
1. Create component in `src/pages/PageName.tsx`
2. Add CSS file in `src/pages/styles/PageName.css`
3. Add route in `src/App.tsx`
4. If admin page, wrap in `<AdminRoutes />` and add menu item in `AdminLayout.tsx`

### Add a new component
1. Create in `src/components/ComponentName.tsx`
2. Add styles in `src/components/styles/ComponentName.css` if needed
3. Import using `@/components/ComponentName`