# CLAUDE.md

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

## Project Overview

QY LTY Backend is a comprehensive Django-based backend service that provides:
- User management and authentication system
- AI conversation capabilities (single/multi-turn chat with voice support)
- Card management system with batch generation and QR code functionality
- Device interaction via WebSocket real-time communication
- Achievement system
- Subscription management
- Multiple third-party integrations (Aliyun, Volcengine, Tencent, etc.)

## Development Commands

### Environment Setup
```bash
# Install dependencies
pip install -r requirements.txt

# Copy environment configuration
cp .env.bak .env

# Database migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser
```

### Running the Application
```bash
# Start development server (ASGI with WebSocket support)
./run.sh

# Or directly with daphne
daphne -b 0.0.0.0 -p 8000 qy_lty.asgi:application

# Traditional Django development server (HTTP only)
python manage.py runserver
```

### Database Management
```bash
# Create new migrations
python manage.py makemigrations
python manage.py makemigrations [app_name]

# Apply migrations
python manage.py migrate

# Database shell
python manage.py dbshell

# Django shell
python manage.py shell
```

### Internationalization (i18n)
```bash
# Generate message files
django-admin makemessages -l en
django-admin makemessages -l zh_HAns

# Compile translations
django-admin compilemessages
```

### Docker Deployment
```bash
# Build and start containers
docker-compose up -d --build

# Access application at http://localhost:12012
```

## Architecture Overview

### Core Django Apps Structure
- **userapp/**: Custom user model (ParadiseUser) with authentication, phone verification, and user management
- **aiapp/**: AI conversation system with Kimi integration, voice synthesis/recognition via multiple providers
- **card/**: Card management system with categories, batches, QR codes, and usage tracking
- **device_interaction/**: WebSocket-based real-time device communication with authentication
- **achievement_app/**: User achievement and progress tracking system
- **subscription_app/**: User subscription and billing management
- **ali_vi_app/**: Alibaba Cloud vision intelligence integration
- **workflow_app/**: Multi-tenant workflow management (in development)

### Key Technical Components

#### ASGI/WebSocket Configuration
- Uses Django Channels for WebSocket support
- Custom token-based WebSocket authentication (`device_interaction.auth.TokenAuthMiddleware`)
- Redis-backed channel layers for real-time messaging
- WebSocket routing: `ws://domain/ws/device/` and `ws://domain/ws/device/token/{token}/`

#### Authentication System
- Custom user model: `userapp.ParadiseUser` extending AbstractUser
- Token-based API authentication
- Phone verification with SMS (Aliyun SMS service)
- Social authentication (WeChat) via django-allauth

#### Database Configuration
- Primary: PostgreSQL (configurable via environment)
- Redis for caching and WebSocket channel layers
- Environment-based configuration using python-decouple

#### Audio/Voice Services
- Multi-provider audio support: Aliyun, Tencent, Volcengine (Huoshan)
- Provider configurable via `AUDIO_SERVICE_PROVIDER` setting
- Voice synthesis and recognition capabilities

## API Documentation

### Access Points
- Swagger UI: `http://localhost:8000/swagger/`
- ReDoc: `http://localhost:8000/redoc/`

### Main API Modules
- `/api/user/` - User authentication and management
- `/api/ai/` - AI conversation endpoints
- `/api/device/` - Device interaction and WebSocket messaging
- `/api/card/` - Card system management
- `/api/achievement/` - Achievement system
- `/api/v1/admin/` - Administrative functions

### WebSocket Message Types
```json
{
    "type": "message_type",
    "message": "content",
    "user_id": "user_id"
}
```

Supported types: `chat_message`, `weather`, `sing`, `dance`

## Environment Configuration

### Required Environment Variables (.env)
- `SECRET_KEY` - Django secret key
- `DEBUG` - Development mode flag
- Database: `POSTGRESQL_DATABASE_*` variables
- Redis: `REDIS_LOCATION`, `REDIS_PASSWORD`
- Kimi AI: `KIMI_API_KEY`, `KIMI_BASE_URL`
- Aliyun services: Various `ALIYUN_*` keys
- Audio services: Provider-specific configuration
- Volcengine: `VOLCENGINE_ACCESS_KEY`, `VOLCENGINE_SECRET_KEY`

## Key Dependencies

### Core Framework
- Django 4.2.13 with Django REST Framework
- Django Channels for WebSocket support
- Daphne ASGI server

### Third-party Integrations
- Aliyun: SMS, OSS, NLS (speech), Vision Intelligence
- Volcengine (ByteDance): RTC services
- Tencent: Audio services
- OpenAI-compatible API (Kimi)

### Development Tools
- django-debug-toolbar for development debugging
- django-simpleui for enhanced admin interface
- drf-yasg for API documentation generation

## Code Patterns and Conventions

### Model Structure
- Custom user model with extensive profile fields (gender, MBTI, interests, etc.)
- Card system uses batch-based generation with category classification
- Achievement system with rarity levels and progress tracking

### API Response Format
- Standardized responses via `common.middleware.StandardResponseMiddleware`
- Custom pagination: `common.pagination.CustomPageNumberPagination`

### Logging
- Aliyun Log Service integration for production logging
- Application-specific loggers for aiapp, userapp, common modules

### File Storage
- OSS (Aliyun Object Storage) for audio and media files
- Local storage for development with configurable paths

## Development Notes

### WebSocket Development
- Device connections require token-based authentication
- Channel layer uses Redis for message passing
- Custom consumers in `device_interaction.consumers`

### Audio Service Integration
- Provider-agnostic interface via `aiapp.audio.AudioService`
- Speech-to-text and text-to-speech capabilities
- File storage integration for audio assets

### Card System Features
- Batch generation with configurable size and format
- QR code generation and scanning
- Usage tracking and analytics
- Category-based organization with attributes

### Admin Interface
- Heavily customized SimpleUI theme
- Multi-language support (Chinese/English)
- Custom icons and organization for different modules