data-index-report/AGENTS.md

# 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