lty/qy_lty/CLAUDE.md

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

# 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

# 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

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

# Generate message files
django-admin makemessages -l en
django-admin makemessages -l zh_HAns

# Compile translations
django-admin compilemessages

Docker Deployment

# 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

{
    "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