348 lines
8.8 KiB
Markdown
348 lines
8.8 KiB
Markdown
# 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 |