webUI/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 **小智AI (Xiaozhi AI)** voice assistant front-end application built with **uni-app (Vue 3)** targeting multiple platforms (H5, WeChat Mini Program, and other mini-program platforms). The app provides AI conversation, voice interaction, script management, voice cloning, and IoT device configuration capabilities.

**Core Technologies:**
- uni-app 3.x with Vue 3 Composition API
- Vite 5.2.8 for build tooling
- Pinia 2.1.7 for state management
- vue-i18n 9.1.9 for internationalization

**Backend Integration:**
- Java Spring Boot backend at `http://localhost:8091` (configurable in `src/utils/api.js`)
- Alibaba Cloud voice services for TTS/ASR/voice cloning
- WeChat OAuth 2.0 for user authentication

## Development Commands

```bash
# Install dependencies
npm install

# H5 development (web browser)
npm run dev:h5

# WeChat Mini Program development
npm run dev:mp-weixin

# Build for H5 production
npm run build:h5

# Build for WeChat Mini Program
npm run build:mp-weixin

# Other platforms (Alipay, Baidu, etc.)
npm run dev:mp-[platform]    # development
npm run build:mp-[platform]   # production
```

Build outputs go to `dist/build/h5/` or `dist/build/mp-weixin/` respectively.

## Architecture & Code Structure

### Entry Points
- **`src/main.js`**: Application bootstrap, creates SSR app and registers Pinia
- **`src/App.vue`**: Root component with global lifecycle hooks
- **`src/pages.json`**: Page routing, tabBar configuration, and navigation styles (all pages use custom navigation)
- **`src/manifest.json`**: Platform-specific configurations (WeChat AppID: `wxff56c34ef9aceb62`)

### State Management (Pinia)
- **`src/stores/user.js`**: User authentication state
  - Manages `token`, `nickName`, `avatarUrl`, `openid`, `isLoggedIn`, `hasAgreedToTerms`, `hasVisitedMinePage`
  - Provides `login()`, `logout()`, `setUserInfo()`, `clearFakeLoginData()` methods
  - Persists state to uni-app local storage (`userInfo`, `custom_token`, `user_token`)
  - **Important**: Token is checked from multiple sources (store, `custom_token`, `user_token`, `userInfo.token`)

### API Layer (`src/utils/api.js`)
- **Request interceptor**: Automatically adds `Authorization: Bearer <token>` header from multiple token sources
- **Response handling**: Smart extraction of backend responses from various nested structures
- **Text cleaning**: `cleanText()` function strips HTML/Markdown and keeps only text and punctuation

**API Modules:**
- **`chatAPI`**:
  - `syncChat()` - Synchronous chat with fallback for anonymous users
  - `asyncChat()` - Asynchronous chat (if needed)
  - `getChatHistory()`, `createConversation()` - Conversation management
  - **Note**: When user is not logged in, returns `isAnonymous: true` to trigger local simulation
- **`voiceAPI`**:
  - `textToSpeech()` - TTS (Text-to-Speech)
  - `chatWithTTS()` - AI chat + voice synthesis
  - `voiceChat()` - Complete voice interaction (uploads AAC, backend converts to WAV)
  - `uploadVoiceChat()` - Audio file upload for voice chat
  - **Important**: Frontend sends AAC format, backend must convert to WAV for processing
  - Response parsing handles complex nested structures: `data.llmResult.response`, `data.sttResult.text`, `data.ttsResult.audioPath`
- **`rechargeAPI`**: `getUserBalance()`, `createRechargeOrder()`, `getOrderStatus()`, `getRechargeHistory()`
- **`roleAPI`**: `getRoles()`, `getRoleById()` - AI character management
- **`configAPI`**: `getAllConfigs()`, `getModels()`, `getSTTConfigs()`, `getTemplates()`, `getTTSConfigs()`

### Page Structure
Pages are organized by feature under `src/pages/`:

**Core Pages:**
- `splash/splash` - Launch screen with agreement flow
- `index/index` - Homepage with drama characters and AI voices (has tabBar)
- `mine/mine` - User profile and settings (has tabBar)
- `chat/chat` - AI conversation with text and voice input
- `create/create` - Script creation entry
- `script/editor` - Script editing interface
- `drama/index` - Drama character details
- `voice/clone` - Voice cloning feature
- `agreement/agreement` - User agreement display
- `recharge/recharge` - Recharge/payment
- `recharge/history` - Recharge history (with pull-down refresh enabled)

All pages use `navigationStyle: "custom"` for custom navigation bars.

### Global Styles
- **`src/uni.scss`**: Global SCSS variables and mixins
- **`src/styles/`**: Common stylesheets
- **`src/static/`**: Static assets (images, icons, etc.)

### Components
- **`src/components/UserAgreement.vue`**: User agreement component
- **`src/components/UserAuth.vue`**: User authentication component

## Key Architectural Patterns

### Authentication Flow
1. User triggers login from UI
2. `useUserStore.login()` orchestrates:
   - Call `uni.getUserProfile()` for WeChat user info
   - Call `uni.login()` to get WeChat `code`
   - POST to `/app/login` with `code`
   - Save `token`, `nickName`, `avatarUrl`, `openid` to store and local storage
3. All subsequent API calls auto-inject token from store/storage via request interceptor

### Anonymous User Handling
- When not logged in, `chatAPI.syncChat()` returns `isAnonymous: true`
- UI layer should implement local simulation/fallback responses
- Voice APIs skip backend calls and use degradation handling

### Voice Interaction Flow
1. **Record**: User records voice (AAC format) using `uni.getRecorderManager()`
2. **Upload**: Frontend uploads AAC to backend via `voiceAPI.voiceChat()` or `uploadVoiceChat()`
3. **Backend Processing**:
   - Convert AAC to WAV
   - STT (Speech-to-Text) via Alibaba Cloud ASR
   - LLM processing for AI response
   - TTS (Text-to-Speech) via Alibaba Cloud TTS
4. **Response**: Backend returns structured response with `sttResult.text`, `llmResult.response`, `ttsResult.audioPath`
5. **Playback**: Frontend plays audio using `uni.createInnerAudioContext()`

### Response Data Extraction Pattern
The API layer uses a flexible extraction strategy to handle varying backend response structures:
- Try multiple field names: `response`, `message`, `content`, `reply`, `answer`, `text`
- Check nested paths: `data.data.response`, `data.response`, root-level `response`
- For voice APIs, specifically look for: `data.llmResult.response`, `data.sttResult.text`, `data.ttsResult.audioPath`
- Always clean responses with `cleanText()` to remove markup

## Important Configuration Files

### `src/pages.json`
Defines all pages, tabBar, and global styles. Key settings:
- All pages have `navigationStyle: "custom"` (custom nav bars)
- TabBar: Homepage (`pages/index/index`) and Mine (`pages/mine/mine`)
- `lazyCodeLoading: "requiredComponents"` for performance
- Splash and agreement pages have `disableScroll: true` and `popGesture: "none"` (prevent back gesture)

### `src/manifest.json`
Platform-specific configurations:
- WeChat Mini Program AppID: `wxff56c34ef9aceb62`
- App permissions and capabilities
- Platform-specific optimizations

### `vite.config.js`
Minimal Vite config using `@dcloudio/vite-plugin-uni` plugin.

## Documentation References

Refer to these files for detailed specifications:
- **`API接口文档.md`**: Complete backend API documentation with request/response examples
- **`产品设计需求文档.md`**: Product requirements, functional specifications, AI service integration details, IoT device configuration requirements
- **`前端交接文档.md`**: Project handoff document with module descriptions and development notes

## Development Best Practices

### Working with uni-app
- Use `uni.*` APIs for cross-platform compatibility (e.g., `uni.request`, `uni.showToast`, `uni.navigateTo`)
- Test on both H5 and WeChat Mini Program to ensure compatibility
- WeChat Mini Program has stricter restrictions (e.g., requires HTTPS for production, domain whitelist)

### State Management
- Always use Pinia store for shared state
- Persist critical state (user info, tokens) to local storage via `uni.setStorageSync()`
- Initialize stores on app launch by calling store's `init()` method

### API Integration
- Never hardcode API endpoints; use `BASE_URL` in `src/utils/api.js`
- Handle both logged-in and anonymous states gracefully
- Always check for multiple possible response structures when parsing backend data
- Use `cleanText()` for AI-generated text to strip formatting

### Audio Handling
- Record audio using `uni.getRecorderManager()` with AAC format
- Play audio using `uni.createInnerAudioContext()`
- Always inform backend that AAC will be sent and needs WAV conversion
- Cache frequently used audio responses for better performance

### Error Handling
- Display user-friendly error messages using `uni.showToast()`
- Log errors to console for debugging
- Implement fallback mechanisms for non-critical features when backend is unavailable

### Performance
- Use `lazyCodeLoading: "requiredComponents"` (already configured)
- Optimize images and static assets
- Implement code splitting for large pages
- Cache API responses where appropriate (e.g., config data, role lists)

## Platform-Specific Notes

### WeChat Mini Program
- Requires domain whitelist configuration in WeChat Developer Console
- OAuth login flow uses `uni.login({ provider: 'weixin' })`
- Recording and playback permissions must be requested from user
- Payment integration uses WeChat Pay API

### H5 (Web)
- Can be deployed to any web server
- Use browser DevTools for debugging
- May need CORS configuration on backend for local development

## Git Workflow

Main branch: `master`
Current branch: `test`

When creating PRs, target the `master` branch.