chunyu_project/DOCUMENTATION.md

API View Documentation

📋 Table of Contents

1. GetIPDataView
2. BaiduFanyiView
3. User Views

---

🌐 GetIPDataView

File Location

api/views/GetIPDataView.py

Overview

Retrieves client IP address information from various HTTP headers and server variables.

Class Details

@permission_classes([AllowAny])
class GetIPDataView(APIView):
    def get(self, request):
        # Implementation...

Method: GET

Parameters

• No parameters required

Response Format

{
    "ip_info": {
        "remote_addr": "string",
        "http_x_forwarded_for": "string",
        "http_x_real_ip": "string",
        "http_client_ip": "string",
        "http_x_forwarded": "string",
        "http_x_cluster_client_ip": "string",
        "http_forwarded_for": "string",
        "http_forwarded": "string"
    }
}

HTTP Headers Checked

The view extracts IP information from the following HTTP headers:

Header	Description
REMOTE_ADDR	Direct connection IP (most reliable)
HTTP_X_FORWARDED_FOR	Proxy/load balancer forwarded IP
HTTP_X_REAL_IP	Real client IP from proxy
HTTP_CLIENT_IP	Client IP header
HTTP_X_FORWARDED	Forwarded header
HTTP_X_CLUSTER_CLIENT_IP	Cluster client IP
HTTP_FORWARDED_FOR	Standard forwarded for header
HTTP_FORWARDED	Standard forwarded header

Usage Example

curl -X GET http://your-api.com/api/get-ip-data/

Response:

{
    "ip_info": {
        "remote_addr": "192.168.1.100",
        "http_x_forwarded_for": "203.0.113.50, 198.51.100.25",
        "http_x_real_ip": "203.0.113.50",
        "http_client_ip": "",
        "http_x_forwarded": "",
        "http_x_cluster_client_ip": "",
        "http_forwarded_for": "",
        "http_forwarded": ""
    }
}

Error Handling

• Returns HTTP 200 with empty strings for missing headers
• No authentication required (@permission_classes([AllowAny]))

---

🌍 BaiduFanyiView

File Location

api/views/BaiduFanyiView.py

Overview

Provides translation and language recognition services using Baidu Translate API. All views are now fully asynchronous for better performance with Daphne ASGI server.

Class Details

# Async methods for all views
async def post(self, request):  # For text and language recognition
async def post(self, request):  # For picture translation
async def post(self, request):  # For speech recognition

1. BaiduFanyiView (Text Translation)

Endpoint: POST /api/translate/

Parameters

{
    "q": "text to translate",           // Required: Text content (max 3000 chars)
    "from_lang": "en",                  // Required: Source language code
    "to_lang": "zh"                     // Required: Target language code
}

Supported Languages

Check languages and auto_lang from info.baidu_lang_info

Response Example

{
    "message": "Success",
    "code": "10000",
    "data": {
        "trans_result": [
            {
                "src": "Hello world",
                "dst": "你好世界"
            }
        ],
        "from": "en",
        "to": "zh"
    }
}

2. RecognizeLangTypeViews (Language Recognition)

Endpoint: POST /api/recognize-language/

Parameters

{
    "q": "text to recognize"            // Required: Text to identify language
}

Response Example

{
    "message": "Success",
    "code": "10000",
    "data": {
        "lang": "en"
    }
}

3. PictureRecognizeViews (Picture Translation)

Endpoint: POST /api/picture-translate/

Parameters

• File upload via multipart/form-data
• Query parameters:
  • from_lang: Source language
  • to_lang: Target language
  • picture: Image format type

Request Format

curl -X POST http://your-api.com/api/picture-translate/
  -H "Content-Type: multipart/form-data"
  -F "file=@image.jpg"
  -G --data-urlencode "from_lang=en"
  --data-urlencode "to_lang=zh"
  --data-urlencode "picture=jpg"

4. SpeechRecognitionView (Speech Recognition)

Endpoint: POST /api/speech-recognition/

Parameters

• Voice file upload via multipart/form-data
• Query parameters:
  • speech_type: Audio format (e.g., "pcm")
  • from_lang: Source language
  • to_lang: Target language

Error Codes

Code	Description
10000	Success
20001	Language not supported
20002	Invalid audio format
20003	Service temporarily unavailable

Async Implementation Benefits

• ✅ Non-blocking I/O operations
• ✅ Better concurrency handling
• ✅ Improved response times
• ✅ Full Daphne ASGI compatibility

---

👤 User Views

File Location

user/views/user.py

Overview

Handles user authentication and email verification. Now fully converted to async operations with standardized response codes.

Class Details

@permission_classes([AllowAny])
class SendUserEmailAPIView(APIView):
    async def post(self, request):  # Email sending

@permission_classes([AllowAny])
class UserLoginOrRegisterAPIView(APIView):
    async def post(self, request):  # Login/Registration

1. SendUserEmailAPIView

Endpoint: POST /api/send-email/

Parameters

{
    "to_email": "user@example.com"      // Required: Recipient email address
}

Response Examples

Registration Email:

{
    "message": "账号未注册，已发送注册邮件",
    "code": "10001",
    "data": {
        "email_sent": true,
        "type": "register"
    }
}

Login Email:

{
    "message": "邮件发送成功",
    "code": "10002",
    "data": {
        "email_sent": true,
        "type": "login"
    }
}

2. UserLoginOrRegisterAPIView

Endpoint: POST /api/login-register/

Parameters

{
    "email": "user@example.com",        // Required: User email
    "code": "12345678"                  // Required: Verification code
}

Response Examples

Successful Registration:

{
    "message": "注册成功",
    "code": "10003",
    "data": {
        "user": { /* user data */ },
        "refresh": "jwt_refresh_token",
        "access": "jwt_access_token",
        "token_type": "bearer",
        "expires_in": 604800
    }
}

Successful Login:

{
    "message": "登录成功",
    "code": "10004",
    "data": {
        "user": { /* user data */ },
        "refresh": "jwt_refresh_token",
        "access": "jwt_access_token",
        "token_type": "bearer",
        "expires_in": 604800
    }
}

Error Responses

{
    "message": "邮箱地址不能为空",
    "code": "20002",
    "data": {}
}

Standardized Response Format

All responses follow the unified structure:

{
    "message": "Human readable message",
    "code": "10000",          // 5-digit zero-padded string
    "data": {                 // Optional, null for errors
        // Response payload
    }
}

Async Implementation Features

• ✅ Database operations wrapped with sync_to_async
• ✅ Email sending as async operation
• ✅ Full error handling with try-catch blocks
• ✅ Type-safe enum usage for codes/messages

---

📊 Summary Statistics

View Class	Method	Async?	Error Codes	Status Codes
GetIPDataView	GET	❌ Sync	N/A	200
BaiduFanyiView	POST	✅ Async	Multiple	200, 400, 503
RecognizeLangTypeViews	POST	✅ Async	Multiple	200, 400, 503
PictureRecognizeViews	POST	✅ Async	Multiple	200, 400, 503
SpeechRecognitionView	POST	✅ Async	Multiple	200, 503
SendUserEmailAPIView	POST	✅ Async	3+	200, 201, 400, 500
UserLoginOrRegisterAPIView	POST	✅ Async	6+	200, 400, 500

---

🚀 Quick Start Guide

Testing Endpoints:

# Get IP Data
curl -X GET http://localhost:8000/api/get-ip-data/

# Send Email
curl -X POST http://localhost:8000/api/send-email/
  -H "Content-Type: application/json"
  -d '{"to_email":"test@example.com"}'

# Text Translation
curl -X POST http://localhost:8000/api/translate/
  -H "Content-Type: application/json"
  -d '{"q":"Hello","from_lang":"en","to_lang":"zh"}'

Running with Daphne:

pip install aiohttp
daphne chunyu_project.asgi:application --port 8000