chore: initial commit
This commit is contained in:
hailin
236
AGENTS.md
Normal file
236
AGENTS.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Agent Guidelines for Data Index Report App
|
||||
|
||||
## Project Overview
|
||||
This is a React + TypeScript + Vite application for generating data analysis reports with PDF export functionality. The app includes data visualization components (ECharts), Excel import/export, and PDF generation.
|
||||
|
||||
## Build, Lint, and Test Commands
|
||||
|
||||
### Development
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run preview # Preview production build
|
||||
```
|
||||
|
||||
### Build
|
||||
```bash
|
||||
npm run build # Build for production (runs TypeScript compilation + Vite build)
|
||||
```
|
||||
|
||||
### Linting
|
||||
```bash
|
||||
npm run lint # Run ESLint on all files
|
||||
```
|
||||
|
||||
### Type Checking
|
||||
```bash
|
||||
npx tsc --noEmit # Type check without emitting files
|
||||
```
|
||||
|
||||
### Single File Operations
|
||||
```bash
|
||||
# Lint specific file
|
||||
npx eslint src/components/ComponentName.tsx
|
||||
|
||||
# Type check specific file
|
||||
npx tsc --noEmit src/components/ComponentName.tsx
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### Imports Order
|
||||
1. React and external library imports
|
||||
2. Internal component imports
|
||||
3. Type imports
|
||||
4. Utility/helper imports
|
||||
5. Style/constant imports
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
import { useRef, useState } from 'react';
|
||||
import html2pdf from 'html2pdf.js';
|
||||
import { Download, Upload } from 'lucide-react';
|
||||
import { CoverPage } from './components/CoverPage';
|
||||
import { defaultReportData } from './data/defaultData';
|
||||
import { parseExcelReportData } from './utils/excelUtils';
|
||||
import type { ReportData } from './types/data';
|
||||
```
|
||||
|
||||
### TypeScript Configuration
|
||||
- Strict mode enabled (`"strict": true`)
|
||||
- No unused locals/parameters enforced
|
||||
- Use explicit type annotations for function parameters and return types
|
||||
- Prefer `interface` over `type` for object shapes
|
||||
- Use `type` imports for type-only imports
|
||||
|
||||
### Naming Conventions
|
||||
- **Components**: PascalCase (e.g., `Page02Industry`, `ChinaMap`)
|
||||
- **Files**: PascalCase for components, camelCase for utilities
|
||||
- **Variables/Functions**: camelCase
|
||||
- **Constants**: UPPER_SNAKE_CASE for true constants, camelCase for exported constants
|
||||
- **Types/Interfaces**: PascalCase with `I` prefix optional (not used in this codebase)
|
||||
- **Props Interfaces**: `ComponentNameProps` pattern
|
||||
|
||||
### Component Structure
|
||||
1. Import statements
|
||||
2. Interface/type definitions
|
||||
3. Component function with typed props
|
||||
4. Internal helper functions
|
||||
5. JSX return with proper className organization
|
||||
|
||||
Example component pattern:
|
||||
```typescript
|
||||
interface ComponentProps {
|
||||
data: SomeType[];
|
||||
onAction?: () => void;
|
||||
}
|
||||
|
||||
export const Component = ({ data, onAction }: ComponentProps) => {
|
||||
// State and hooks
|
||||
const [state, setState] = useState<StateType>(initialValue);
|
||||
|
||||
// Helper functions
|
||||
const processData = () => {
|
||||
// Implementation
|
||||
};
|
||||
|
||||
return (
|
||||
<div className="container-class">
|
||||
{/* JSX content */}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
- Use try/catch for async operations
|
||||
- Provide user feedback for errors (status messages, UI indicators)
|
||||
- Log errors to console for debugging
|
||||
- Use TypeScript's strict null checking
|
||||
|
||||
### Styling (Tailwind CSS)
|
||||
- Use Tailwind utility classes exclusively
|
||||
- Organize classes logically: layout → typography → colors → effects
|
||||
- Use responsive prefixes (sm:, md:, lg:) when needed
|
||||
- Custom colors defined in `tailwind.config.js`
|
||||
- Use `@apply` sparingly in CSS files only
|
||||
|
||||
Example class organization:
|
||||
```jsx
|
||||
<div className="
|
||||
flex flex-col /* Layout */
|
||||
p-4 space-y-4 /* Spacing */
|
||||
bg-white rounded-lg /* Appearance */
|
||||
shadow-md /* Effects */
|
||||
hover:shadow-lg /* Interactive */
|
||||
">
|
||||
```
|
||||
|
||||
### File Organization
|
||||
- `src/components/` - React components
|
||||
- `src/types/` - TypeScript type definitions
|
||||
- `src/utils/` - Utility functions
|
||||
- `src/data/` - Default data and constants
|
||||
- `src/constants.ts` - Application constants
|
||||
- `public/` - Static assets
|
||||
|
||||
### React Patterns
|
||||
- Use functional components with hooks
|
||||
- Prefer explicit prop typing over `any`
|
||||
- Use `useState` for local state
|
||||
- Use `useRef` for DOM references
|
||||
- Extract complex logic into custom hooks when reusable
|
||||
- Use `React.memo` for performance optimization when needed
|
||||
|
||||
### ECharts Integration
|
||||
- Chart components should accept typed data props
|
||||
- Use responsive chart configurations
|
||||
- Include proper error handling for missing data
|
||||
- Export charts as reusable components
|
||||
|
||||
### PDF Generation
|
||||
- Use `html2pdf.js` for PDF export
|
||||
- Handle width locking during PDF generation
|
||||
- Provide proper error feedback
|
||||
- Use `@ts-expect-error` for library type issues when necessary
|
||||
|
||||
### Excel Integration
|
||||
- Use `xlsx` library for Excel operations
|
||||
- Provide template generation functions
|
||||
- Validate imported data structure
|
||||
- Handle file upload errors gracefully
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Adding New Components
|
||||
1. Create component file in `src/components/`
|
||||
2. Define TypeScript interfaces for props
|
||||
3. Implement component with Tailwind styling
|
||||
4. Export component as named export
|
||||
5. Add to appropriate parent component
|
||||
|
||||
### Adding New Types
|
||||
1. Add to existing interface in `src/types/data.ts` or create new file
|
||||
2. Use descriptive property names
|
||||
3. Include JSDoc comments for complex types
|
||||
4. Export types for reuse
|
||||
|
||||
### Adding Utilities
|
||||
1. Create file in `src/utils/`
|
||||
2. Write pure functions with typed parameters
|
||||
3. Include error handling
|
||||
4. Export functions as named exports
|
||||
|
||||
### Testing Changes
|
||||
1. Run `npm run lint` to check code style
|
||||
2. Run `npx tsc --noEmit` for type checking
|
||||
3. Test component in development server
|
||||
4. Verify PDF generation still works
|
||||
5. Test Excel import/export functionality
|
||||
|
||||
## Common Patterns in Codebase
|
||||
|
||||
### Data Processing
|
||||
```typescript
|
||||
// Map data aggregation pattern
|
||||
const aggregatedData = data.reduce((acc, item) => {
|
||||
const key = item.name;
|
||||
acc[key] = (acc[key] || 0) + item.value;
|
||||
return acc;
|
||||
}, {} as Record<string, number>);
|
||||
```
|
||||
|
||||
### Component Props
|
||||
```typescript
|
||||
// Optional props with defaults
|
||||
interface Props {
|
||||
data: DataType[];
|
||||
title?: string;
|
||||
className?: string;
|
||||
}
|
||||
|
||||
const Component = ({
|
||||
data,
|
||||
title = 'Default Title',
|
||||
className = ''
|
||||
}: Props) => {
|
||||
// Implementation
|
||||
};
|
||||
```
|
||||
|
||||
### State Management
|
||||
```typescript
|
||||
// Status state pattern
|
||||
const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
|
||||
|
||||
// Data state with default
|
||||
const [reportData, setReportData] = useState<ReportData>(defaultReportData);
|
||||
```
|
||||
|
||||
## Notes for Agents
|
||||
- This is a Chinese-language application (UI text in Chinese)
|
||||
- Focus on data visualization and report generation
|
||||
- Maintain print-friendly styling for PDF export
|
||||
- Ensure all interactive elements have `no-print` class when needed
|
||||
- Follow existing patterns for consistency
|
||||
- Test PDF generation after UI changes
|
||||
- Verify Excel template compatibility after data structure changes
|
||||
Reference in New Issue
Block a user