# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Vue 3 + TypeScript + Vite mobile H5 application for a music/digital classroom system (音乐数字课堂). It's built with Naive UI component library and uses Pinia for state management. The app is a PWA (Progressive Web App) with offline capabilities.

## Commands

```bash
# Development server (port 5005)
npm run dev
npm start

# Production build (includes type check)
npm run build

# Development build (no type check)
npm run build:dev

# Preview production build
npm run serve

# Lint and fix files
npm run lint

# Generate component/page templates via plop
npm run generate
```

## Architecture

### Router

- Uses `createWebHashHistory` with base path `/classroom`
- Query parameters are AES encrypted/decrypted in `src/router/index.ts`
- Route guards in `src/router/router-guards.ts` handle auth, title updates, and cache clearing
- Admin preview mode supported via `getAuthForAdmin()` token handling

### State Management (Pinia)

Located in `src/store/modules/`:
- `users.ts` - User authentication, token, profile info
- `prepareLessons.ts` - Lesson preparation state
- `catchData.ts` - Cached data
- `designSetting.ts` - UI settings

### API Layer

- HTTP client: `umi-request` (configured in `src/utils/request.ts`)
- Automatic auth header injection and schoolId header
- 401/403 auto logout and redirect to login
- Global message loading/error display

### Path Aliases

Defined in `vite.config.ts` and `tsconfig.json`:
- `@` → `src/`
- `@common` → `src/common/`
- `@components` → `src/components/`
- `@store` → `src/store/`
- `@views` → `src/views/`

### Core Views

- `/attend-class` - Main classroom teaching interface with tools (whiteboard, pen, metronome, timer, roll call)
- `/prepare-lessons` - Lesson preparation with courseware, resources, training presets
- `/notation` - Music score editor
- `/xiaoku-*` - Music library, AI practice features
- `/content-*` - Content information (instruments, musicians, music theory)
- `/natural-resources` - Resource library
- `/data-module` - Data/statistics view

### Component Structure

- `src/components/layout/` - Main layout with sidebar navigation (TSX components)
- `src/components/card-type/` - Various card types (video player, etc.)
- Custom form components in `src/components/` (CSelect, CDatePicker, CBreadcrumb)

### Mobile Adaptation

- Uses `postcss-px2rem` with `remUnit: 16`
- `lib-flexible` for responsive font sizing
- Reference viewport adaptation approach from postcss-px-to-viewport

### PWA Configuration

- `vite-plugin-pwa` configured with `registerType: 'prompt'`
- Service worker update handling in `App.tsx`
- Manifest defines app as "酷乐秀-音乐数字课堂"

### Styling

- Less preprocessor
- Global styles in `src/styles/index.less`
- Component styles use `.module.less` pattern

## Important Files

- `src/main.ts` - App bootstrap, mounts Naive UI, Pinia, Router
- `src/plugins/naive.ts` - Naive UI setup with global `$message`, `$loadingBar` injection
- `src/utils/rem.ts` - Mobile responsive base sizing
- `src/utils/storage.ts` - Local storage wrapper with expiration support
- `src/utils/cipher.ts` - AES encryption utilities

## Notes

- Chrome-only app (browser check in router guards)
- Right-click and F12 developer tools disabled in production
- Build includes timestamp hashes for cache busting