classroom-instruments/CLAUDE.md

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

# 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