HSK Chinese Test System

A comprehensive online HSK (Hànyǔ Shuǐpíng Kǎoshì) test platform built with Next.js, TypeScript, Tailwind CSS, and shadcn/ui. This system provides authentic Chinese language proficiency testing for all HSK levels (1-6).

🚀 Features

Main Testing System

• Multi-Level Support: Complete HSK tests for levels 1-6
• Authentic Test Format:
  • Levels 1-2: Listening + Reading sections
  • Levels 3-6: Listening + Reading + Writing sections
• Interactive Components:
  • Audio playback for listening comprehension (max 2 plays)
  • Multiple choice questions for listening/reading
  • Writing prompts with word count validation
• Real-time Timer: Automatic test submission when time expires
• Instant Results: Detailed scoring and performance analysis

Admin Management System

• Test Management: Create, edit, delete, and manage HSK tests
• Question Bank: CRUD operations for all question types
• Analytics Dashboard: Test statistics and performance metrics
• Level Configuration: Manage HSK level settings and requirements

Technical Features

• Responsive Design: Works on desktop, tablet, and mobile devices
• TypeScript: Full type safety and better development experience
• State Management: Zustand for efficient state handling
• Modern UI: shadcn/ui components with Tailwind CSS
• Vercel Ready: Optimized for deployment to Vercel

🛠️ Tech Stack

• Framework: Next.js 15 with App Router
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: shadcn/ui
• State Management: Zustand
• Icons: Lucide React
• Deployment: Vercel-ready

📋 HSK Test Structure

Level 1 & 2 (Elementary)

• Listening: 20 questions (20 minutes)
• Reading: 20 questions (40 minutes)
• Vocabulary: 150-300 words
• Passing Score: 60%

Level 3 & 4 (Intermediate)

• Listening: 40 questions (35-30 minutes)
• Reading: 30-20 questions (60-40 minutes)
• Writing: 10-15 questions (60-25 minutes)
• Vocabulary: 600-1200 words
• Passing Score: 60%

Level 5 & 6 (Advanced)

• Listening: 45-50 questions (30-35 minutes)
• Reading: 45-50 questions (45-50 minutes)
• Writing: 10 questions (40-45 minutes)
• Vocabulary: 2500-5000+ words
• Passing Score: 60%

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Clone the repository

   git clone <repository-url>
   cd hsk-exam

2. Install dependencies

   npm install

3. Run development server

   npm run dev

4. Open your browser Navigate to http://localhost:3000

Building for Production

npm run build
npm start

📁 Project Structure

src/
├── app/                    # Next.js app router
│   ├── admin/             # Admin dashboard
│   ├── test/[level]/      # Dynamic test routes
│   └── page.tsx           # Home page
├── components/
│   ├── admin/             # Admin components
│   ├── hsk/               # HSK test components
│   └── ui/                # shadcn/ui components
├── data/                  # Test data and configurations
├── hooks/                 # Custom React hooks
├── store/                 # Zustand stores
└── types/                 # TypeScript type definitions

🎯 Usage

Taking a Test

1. Visit the home page
2. Select your desired HSK level (1-6)
3. Review test information and click "Start Test"
4. Complete each section within the time limit
5. Submit and view your results

Admin Functions

1. Navigate to /admin
2. Use the dashboard to:
   • View test statistics
   • Manage test content
   • Add/edit questions
   • Monitor test performance

📊 Features Detail

Test Components

Listening Questions

• Audio player with play/pause controls
• Limited replay functionality (max 2 times)
• Multiple choice answers
• Progress tracking

Reading Questions

• Text passages for comprehension
• Vocabulary reference sections
• Multiple choice format
• Context-based questions

Writing Questions (HSK 3-6)

• Structured prompts
• Word count validation
• Required keyword integration
• Rubric-based scoring

Scoring System

• Automatic Scoring: Instant results for listening/reading
• Manual Review: Writing sections require admin evaluation
• Detailed Breakdown: Section-wise performance analysis
• Pass/Fail Status: Based on 60% threshold
• Recommendations: Personalized improvement suggestions

🔧 Configuration

Adding New Questions

1. Access admin dashboard at /admin
2. Navigate to "Questions" tab
3. Select HSK level
4. Click "Add Question"
5. Fill in question details and save

Modifying Test Structure

Update configurations in src/data/hsktests.ts:

• Test duration limits
• Question counts per section
• Passing score requirements
• Level configurations

🌐 Deployment

Vercel Deployment

1. Connect your repository to Vercel
2. Configure build settings:
   • Build Command: npm run build
   • Output Directory: .next
3. Deploy automatically on push to main branch

Environment Variables

No environment variables required for basic setup. Add as needed for:

• Database connections
• Authentication services
• External API integrations

🎨 Customization

Styling

• Modify Tailwind configuration in tailwind.config.js
• Update component styles in respective component files
• Customize color schemes in globals.css

Adding New HSK Levels

1. Update HSKLevel type in src/types/hsk.ts
2. Add configuration in HSK_LEVEL_CONFIGS
3. Create test data following existing patterns

📝 License

This project is open source and available under the MIT License.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📞 Support

For questions, issues, or contributions, please:

• Open an issue on GitHub
• Check existing documentation
• Review the code structure for implementation details

---

Note: This system includes sample test data for demonstration. For production use, replace with authentic HSK test content and implement proper audio file hosting.