liqupan/webUI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
webUI/CLAUDE.md
liqupan 17570c7821 feat: init
2025-11-07 20:54:09 +08:00

9.4 KiB
Raw Permalink Blame History

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

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

Reference in New Issue View Git Blame Copy Permalink