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

npm run dev          # Start development server
npm run preview      # Preview production build

Build

npm run build        # Build for production (runs TypeScript compilation + Vite build)

Linting

npm run lint         # Run ESLint on all files

Type Checking

npx tsc --noEmit     # Type check without emitting files

Single File Operations

# 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:

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:

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:

<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

// 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

// Optional props with defaults
interface Props {
  data: DataType[];
  title?: string;
  className?: string;
}

const Component = ({ 
  data, 
  title = 'Default Title', 
  className = '' 
}: Props) => {
  // Implementation
};

State Management

// 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