210 lines
6.4 KiB
Markdown
210 lines
6.4 KiB
Markdown
# 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 |