add AGENTS.md
This commit is contained in:
187
AGENTS.md
Normal file
187
AGENTS.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user