sync from local backup
This commit is contained in:
chunyu
@@ -0,0 +1,348 @@
|
||||
# User Views Documentation
|
||||
|
||||
## 📄 **File Location**
|
||||
`user/views/user.py`
|
||||
|
||||
### **Overview**
|
||||
Handles user authentication, email verification, and registration processes. All views have been converted to asynchronous operations with standardized response codes for better performance and maintainability.
|
||||
|
||||
### **Class Details**
|
||||
|
||||
```python
|
||||
@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
|
||||
```
|
||||
|
||||
#### **Permissions**
|
||||
- **Access Level**: Public (no authentication required)
|
||||
- **Authentication**: None (`@permission_classes([AllowAny])`)
|
||||
|
||||
### **Method Details**
|
||||
|
||||
---
|
||||
|
||||
### **1. SendUserEmailAPIView (Email Verification)**
|
||||
|
||||
#### **Endpoint**: `POST /api/send-email/`
|
||||
|
||||
##### **Description**
|
||||
Sends verification emails for user registration or login. Generates and stores 8-digit verification codes in cache for validation.
|
||||
|
||||
##### **Parameters**
|
||||
```json
|
||||
{
|
||||
"to_email": "user@example.com" // Required: Recipient email address
|
||||
}
|
||||
```
|
||||
|
||||
##### **Response Format**
|
||||
|
||||
**Success - Registration Email:**
|
||||
```json
|
||||
{
|
||||
"message": "账号未注册，已发送注册邮件",
|
||||
"code": "10001",
|
||||
"data": {
|
||||
"email_sent": true,
|
||||
"type": "register"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Success - Login Email:**
|
||||
```json
|
||||
{
|
||||
"message": "邮件发送成功",
|
||||
"code": "10002",
|
||||
"data": {
|
||||
"email_sent": true,
|
||||
"type": "login"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### **Logic Flow**
|
||||
1. Validate email parameter
|
||||
2. Check if user exists in database
|
||||
3. If user doesn't exist: send registration email
|
||||
4. If user exists: send login email
|
||||
5. Store verification code in Redis cache with 10-minute timeout
|
||||
6. Return appropriate success response
|
||||
|
||||
##### **Error Responses**
|
||||
|
||||
| Code | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 20002 | Bad Request | Email parameter missing or empty |
|
||||
| 20003 | Internal Server Error | Email sending failed |
|
||||
|
||||
---
|
||||
|
||||
### **2. UserLoginOrRegisterAPIView (Authentication)**
|
||||
|
||||
#### **Endpoint**: `POST /api/login-register/`
|
||||
|
||||
##### **Description**
|
||||
Handles both user registration and login processes using email verification codes. Supports JWT token generation for authenticated sessions.
|
||||
|
||||
##### **Parameters**
|
||||
```json
|
||||
{
|
||||
"email": "user@example.com", // Required: User email address
|
||||
"code": "12345678" // Required: Verification code
|
||||
}
|
||||
```
|
||||
|
||||
##### **Response Format**
|
||||
|
||||
**Successful Registration:**
|
||||
```json
|
||||
{
|
||||
"message": "注册成功",
|
||||
"code": "10003",
|
||||
"data": {
|
||||
"user": {
|
||||
"id": 1,
|
||||
"email": "user@example.com",
|
||||
"username": "example_user"
|
||||
},
|
||||
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 604800 // 7 days in seconds
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Successful Login:**
|
||||
```json
|
||||
{
|
||||
"message": "登录成功",
|
||||
"code": "10004",
|
||||
"data": {
|
||||
"user": {
|
||||
"id": 1,
|
||||
"email": "user@example.com",
|
||||
"username": "example_user"
|
||||
},
|
||||
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 604800 // 7 days in seconds
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### **Logic Flow**
|
||||
|
||||
**Registration Flow:**
|
||||
1. Validate email and code parameters
|
||||
2. Get user from database (expecting None for registration)
|
||||
3. Retrieve verification code from cache (`register_{email}`)
|
||||
4. Verify code matches
|
||||
5. Validate user data via serializer
|
||||
6. Create user account
|
||||
7. Generate JWT tokens
|
||||
8. Return success response
|
||||
|
||||
**Login Flow:**
|
||||
1. Validate email and code parameters
|
||||
2. Get existing user from database
|
||||
3. Retrieve verification code from cache (`login_{email}`)
|
||||
4. Verify code matches
|
||||
5. Generate JWT tokens for existing user
|
||||
6. Return success response
|
||||
|
||||
##### **Error Responses**
|
||||
|
||||
| Code | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 20001 | Bad Request | Parameter validation error |
|
||||
| 20004 | Bad Request | Registration verification code expired |
|
||||
| 20005 | Bad Request | User data validation failed |
|
||||
| 20006 | Bad Request | Registration verification code incorrect |
|
||||
| 20007 | Bad Request | Login verification code expired |
|
||||
| 20008 | Bad Request | Login verification code incorrect |
|
||||
| 20009 | Internal Server Error | Server internal error |
|
||||
|
||||
---
|
||||
|
||||
### **Implementation Details**
|
||||
|
||||
#### **Async Operations**
|
||||
All database operations use `sync_to_async` for non-blocking execution:
|
||||
|
||||
```python
|
||||
# Database query becomes async
|
||||
user = await sync_to_async(FUser.objects.filter)(email=to_email).first()
|
||||
```
|
||||
|
||||
#### **Email System**
|
||||
- Uses Django's `EmailMessage` class
|
||||
- Sends from `cs10086086@qq.com`
|
||||
- Verification codes stored in Redis with 10-minute timeout
|
||||
- Separate cache keys: `register_{email}` and `login_{email}`
|
||||
|
||||
#### **Token System**
|
||||
- Uses Django REST Framework Simple JWT
|
||||
- Access token expires in 7 days
|
||||
- Refresh token system implemented
|
||||
- Token payload includes expiration time calculation
|
||||
|
||||
#### **Data Validation**
|
||||
- UserSerializer handles data validation
|
||||
- create_by_email method handles user creation
|
||||
- Comprehensive error handling for invalid data
|
||||
|
||||
---
|
||||
|
||||
### **Security & Performance**
|
||||
|
||||
#### **Verification Code Security**
|
||||
- 8-digit numeric codes generated randomly
|
||||
- 10-minute expiration window
|
||||
- One-time use (consumed after validation)
|
||||
- Stored in secure Redis cache
|
||||
|
||||
#### **Rate Limiting Considerations**
|
||||
- No built-in rate limiting
|
||||
- Consider implementing client-side limits
|
||||
- Redis can be used for distributed rate limiting
|
||||
|
||||
#### **Input Validation**
|
||||
- Email format validation
|
||||
- Code length and format validation
|
||||
- Parameter presence validation
|
||||
- Database constraint enforcement
|
||||
|
||||
#### **Error Handling**
|
||||
- Comprehensive try-catch blocks
|
||||
- Meaningful error messages
|
||||
- Proper HTTP status codes
|
||||
- No sensitive information leakage
|
||||
|
||||
---
|
||||
|
||||
### **Usage Examples**
|
||||
|
||||
#### **Python Client**
|
||||
```python
|
||||
import requests
|
||||
|
||||
# Send registration email
|
||||
response = requests.post('/api/send-email/', json={'to_email': 'test@example.com'})
|
||||
if response.status_code == 201:
|
||||
print("Registration email sent")
|
||||
|
||||
# Register user
|
||||
response = requests.post('/api/login-register/', json={
|
||||
'email': 'test@example.com',
|
||||
'code': '12345678'
|
||||
})
|
||||
if response.status_code == 200:
|
||||
tokens = response.json()['data']
|
||||
print(f"Access token: {tokens['access']}")
|
||||
```
|
||||
|
||||
#### **JavaScript Frontend**
|
||||
```javascript
|
||||
// Send email verification
|
||||
const sendVerificationEmail = async (email) => {
|
||||
const response = await fetch('/api/send-email/', {
|
||||
method: 'POST',
|
||||
headers: {'Content-Type': 'application/json'},
|
||||
body: JSON.stringify({to_email: email})
|
||||
});
|
||||
return response.json();
|
||||
};
|
||||
|
||||
// Register user
|
||||
const registerUser = async (email, code, userData) => {
|
||||
const response = await fetch('/api/login-register/', {
|
||||
method: 'POST',
|
||||
headers: {'Content-Type': 'application/json'},
|
||||
body: JSON.stringify({email, code, ...userData})
|
||||
});
|
||||
return response.json();
|
||||
};
|
||||
```
|
||||
|
||||
#### **Testing Endpoints**
|
||||
```bash
|
||||
# Send email verification
|
||||
curl -X POST http://localhost:8000/api/send-email/
|
||||
-H "Content-Type: application/json"
|
||||
-d '{"to_email":"test@example.com"}'
|
||||
|
||||
# Register user
|
||||
curl -X POST http://localhost:8000/api/login-register/
|
||||
-H "Content-Type: application/json"
|
||||
-d '{"email":"test@example.com","code":"12345678","username":"testuser"}'
|
||||
|
||||
# Login user
|
||||
curl -X POST http://localhost:8000/api/login-register/
|
||||
-H "Content-Type: application/json"
|
||||
-d '{"email":"test@example.com","code":"87654321"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Integration Notes**
|
||||
|
||||
#### **Django URL Configuration**
|
||||
```python
|
||||
# urls.py
|
||||
from django.urls import path
|
||||
from user.views.user import SendUserEmailAPIView, UserLoginOrRegisterAPIView
|
||||
|
||||
urlpatterns = [
|
||||
path('send-email/', SendUserEmailAPIView.as_view(), name='send-email'),
|
||||
path('login-register/', UserLoginOrRegisterAPIView.as_view(), name='login-register'),
|
||||
]
|
||||
```
|
||||
|
||||
#### **Frontend Integration**
|
||||
- Use response `data.access` for API authentication
|
||||
- Store `data.refresh` for token refresh
|
||||
- Handle different message codes for user feedback
|
||||
- Implement countdown timer for code expiration
|
||||
|
||||
#### **Mobile App Integration**
|
||||
- Same API endpoints work for mobile apps
|
||||
- Include proper error handling for network issues
|
||||
- Implement offline caching for better UX
|
||||
|
||||
#### **Third-party Services**
|
||||
- Email service: QQ Mail SMTP
|
||||
- Authentication: JWT-based
|
||||
- Storage: MySQL + Redis cache
|
||||
|
||||
---
|
||||
|
||||
### **Monitoring & Debugging**
|
||||
|
||||
#### **Logging**
|
||||
- Email sending operations logged
|
||||
- Parameter validation errors logged
|
||||
- Consider adding structured logging for production
|
||||
|
||||
#### **Metrics**
|
||||
- Email delivery success rates
|
||||
- Registration completion rates
|
||||
- Login success rates
|
||||
- Token refresh patterns
|
||||
|
||||
#### **Health Checks**
|
||||
- Redis connectivity
|
||||
- SMTP server availability
|
||||
- Database connection pool
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: Current Session
|
||||
**Version**: 1.0
|
||||
Reference in New Issue
Block a user