# 系统架构设计文档

本文档详细说明QY LTY Backend的整体架构设计、技术选型和关键组件。

## 1. 架构概览

### 1.1 系统架构图

```
                    ┌─────────────────────────────────────────┐
                    │              客户端层                    │
                    │  ┌─────────┐  ┌─────────┐  ┌─────────┐  │
                    │  │ Web App │  │ Mobile  │  │ Device  │  │
                    │  │         │  │   App   │  │  SDK    │  │
                    │  └─────────┘  └─────────┘  └─────────┘  │
                    └─────────────┬───────────────────────────┘
                                  │ HTTP/HTTPS + WebSocket
                    ┌─────────────┴───────────────────────────┐
                    │              网关/负载均衡              │
                    │         ┌─────────────────────┐         │
                    │         │      Nginx          │         │
                    │         └─────────────────────┘         │
                    └─────────────┬───────────────────────────┘
                                  │
                    ┌─────────────┴───────────────────────────┐
                    │             应用服务层                  │
                    │  ┌─────────────────────────────────────┐ │
                    │  │        Django Application          │ │
                    │  │  ┌─────────┐    ┌─────────────────┐ │ │
                    │  │  │  ASGI   │    │     Django      │ │ │
                    │  │  │ Server  │    │   HTTP Views    │ │ │
                    │  │  │(Daphne) │    │                 │ │ │
                    │  │  └─────────┘    └─────────────────┘ │ │
                    │  │  ┌─────────┐    ┌─────────────────┐ │ │
                    │  │  │WebSocket│    │       DRF       │ │ │
                    │  │  │Consumers│    │   API Views     │ │ │
                    │  │  └─────────┘    └─────────────────┘ │ │
                    │  └─────────────────────────────────────┘ │
                    └─────────────┬───────────────────────────┘
                                  │
                    ┌─────────────┴───────────────────────────┐
                    │              业务逻辑层                 │
                    │  ┌─────────┐ ┌─────────┐ ┌─────────────┐ │
                    │  │ UserApp │ │  AIApp  │ │    Card     │ │
                    │  └─────────┘ └─────────┘ └─────────────┘ │
                    │  ┌─────────┐ ┌─────────┐ ┌─────────────┐ │
                    │  │ Device  │ │Achievement│ │ Subscription│ │
                    │  └─────────┘ └─────────┘ └─────────────┘ │
                    └─────────────┬───────────────────────────┘
                                  │
                    ┌─────────────┴───────────────────────────┐
                    │              数据存储层                 │
                    │  ┌─────────┐ ┌─────────┐ ┌─────────────┐ │
                    │  │PostgreSQL│ │  Redis  │ │ File Storage│ │
                    │  │         │ │  Cache  │ │    (OSS)    │ │
                    │  └─────────┘ └─────────┘ └─────────────┘ │
                    └─────────────┬───────────────────────────┘
                                  │
                    ┌─────────────┴───────────────────────────┐
                    │             第三方服务层                │
                    │  ┌─────────┐ ┌─────────┐ ┌─────────────┐ │
                    │  │ AI服务  │ │音频服务 │ │   云服务    │ │
                    │  │ (Kimi)  │ │(多厂商) │ │ (阿里云等)  │ │
                    │  └─────────┘ └─────────┘ └─────────────┘ │
                    └─────────────────────────────────────────┘
```

### 1.2 技术栈总览

| 层级 | 技术组件 | 作用 |
|------|----------|------|
| **Web框架** | Django 4.2.13 | 核心Web框架 |
| **API框架** | Django REST Framework | RESTful API开发 |
| **实时通信** | Django Channels | WebSocket支持 |
| **ASGI服务器** | Daphne | 异步Web服务器 |
| **数据库** | PostgreSQL | 主数据库 |
| **缓存** | Redis | 缓存和消息队列 |
| **任务调度** | APScheduler | 定时任务管理 |
| **API文档** | drf-yasg | OpenAPI文档生成 |

## 2. 核心模块架构

### 2.1 用户管理系统 (UserApp)

```
UserApp Architecture:
┌─────────────────────────────────────────────┐
│                UserApp                      │
│  ┌─────────────────────────────────────────┐ │
│  │            Models                       │ │
│  │  ┌─────────────────────────────────────┐ │ │
│  │  │        ParadiseUser                 │ │ │
│  │  │  - Custom User Model                │ │ │
│  │  │  - Phone, Email, Profile Fields    │ │ │
│  │  │  - MBTI, Interests, etc.           │ │ │
│  │  └─────────────────────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │            Views                        │ │
│  │  ┌─────────────┐  ┌──────────────────┐  │ │
│  │  │ Auth Views  │  │ Management Views │  │ │
│  │  │ - Login     │  │ - Profile CRUD   │  │ │
│  │  │ - Register  │  │ - User Search    │  │ │
│  │  │ - SMS       │  │ - Admin Panel    │  │ │
│  │  └─────────────┘  └──────────────────┘  │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │        Authentication                   │ │
│  │  - Token Authentication                 │ │
│  │  - Session Authentication              │ │
│  │  - Social Authentication (WeChat)      │ │
│  │  - SMS Verification (Aliyun)           │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```

**核心功能：**
- 自定义用户模型支持多种认证方式
- 手机短信验证集成阿里云SMS
- 社交登录集成微信等平台
- 用户配置文件管理（MBTI、兴趣等）

### 2.2 AI对话系统 (AIApp)

```
AIApp Architecture:
┌─────────────────────────────────────────────┐
│                 AIApp                       │
│  ┌─────────────────────────────────────────┐ │
│  │          Chat Engine                    │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │Single Chat  │  │   Multi Chat        │ │ │
│  │  │- Bot Based  │  │ - Session Based     │ │ │
│  │  │- Stateless  │  │ - Context Aware     │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │        Audio Processing                 │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │     ASR     │  │        TTS          │ │ │
│  │  │(Speech2Text)│  │   (Text2Speech)     │ │ │
│  │  │- Aliyun NLS │  │ - Volcengine        │ │ │
│  │  │- Multi Lang │  │ - Aliyun            │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │        AI Providers                     │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │    Kimi     │  │   OpenAI Compatible │ │ │
│  │  │(Moonshot AI)│  │      Models         │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```

**核心功能：**
- 支持单轮和多轮对话
- 语音输入输出完整支持
- 多AI服务提供商适配
- 上下文管理和会话持久化

### 2.3 卡片管理系统 (Card)

```
Card System Architecture:
┌─────────────────────────────────────────────┐
│                Card System                  │
│  ┌─────────────────────────────────────────┐ │
│  │           Data Models                   │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │CardTemplate │  │     CardBatch       │ │ │
│  │  │- Category   │  │   - Bulk Generate   │ │ │
│  │  │- Attributes │  │   - QR Code         │ │ │
│  │  │- Rarity     │  │   - Expiry          │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │    Card     │  │   UsageLog          │ │ │
│  │  │- Unique Code│  │ - Audit Trail       │ │ │
│  │  │- QR Image   │  │ - Analytics         │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │        Card Categories                  │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │   Dance     │  │       Song          │ │ │
│  │  │- Style      │  │ - Genre, BPM        │ │ │
│  │  │- Difficulty │  │ - Audio File        │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │  Clothing   │  │       Game          │ │ │
│  │  │- Style      │  │ - Type, Level       │ │ │
│  │  │- Season     │  │ - Rewards           │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```

**核心功能：**
- 模板化卡片生成系统
- 批次管理和二维码生成
- 分类属性系统（舞蹈、音乐、服装、游戏）
- 使用跟踪和分析

### 2.4 设备交互系统 (Device Interaction)

```
Device Interaction Architecture:
┌─────────────────────────────────────────────┐
│           Device Interaction                │
│  ┌─────────────────────────────────────────┐ │
│  │         WebSocket Layer                 │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │  Consumer   │  │   Authentication    │ │ │
│  │  │- Message    │  │  - Token Based      │ │ │
│  │  │- Routing    │  │  - User Based       │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │        Device Management                │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │Device Types │  │   Device Batch      │ │ │
│  │  │- Categories │  │ - Production Info   │ │ │
│  │  │- Properties │  │ - Serial Numbers    │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │   Devices   │  │  User Bindings      │ │ │
│  │  │- MAC Address│  │ - Device-User Link  │ │ │
│  │  │- Activation │  │ - Primary Device    │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │        Message System                   │ │
│  │  ┌─────────────┐  ┌─────────────────────┐ │ │
│  │  │Message Types│  │    Integrations     │ │ │
│  │  │- Chat       │  │ - Weather API       │ │ │
│  │  │- Weather    │  │ - Music Service     │ │ │
│  │  │- Control    │  │ - Dance Library     │ │ │
│  │  └─────────────┘  └─────────────────────┘ │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```

**核心功能：**
- 基于Django Channels的WebSocket通信
- 设备生命周期管理
- 用户设备绑定系统
- 实时消息分发

## 3. 数据架构设计

### 3.1 数据库设计原则

**数据库选择：PostgreSQL**
- **原因**：支持JSON字段、全文搜索、扩展性好
- **版本**：PostgreSQL 12+
- **字符集**：UTF-8
- **时区**：Asia/Shanghai

### 3.2 核心数据模型关系

```sql
-- 用户系统
ParadiseUser ||--o{ UserDevice : binds
ParadiseUser ||--o{ UserAchievement : earns
ParadiseUser ||--o{ CardUsageLog : uses

-- 卡片系统
CardTemplate ||--o{ CardBatch : generates
CardBatch ||--o{ Card : contains
Card ||--o{ CardUsageLog : tracks

-- 设备系统
DeviceType ||--o{ DeviceBatch : groups
DeviceBatch ||--o{ Device : contains
Device ||--o{ UserDevice : binds

-- 成就系统
Achievement ||--o{ UserAchievement : awards
```

### 3.3 数据分区策略

```sql
-- 时间分区示例（日志表）
CREATE TABLE card_usage_logs (
    id BIGSERIAL,
    card_id INTEGER,
    user_id INTEGER,
    used_at TIMESTAMP,
    -- 其他字段
) PARTITION BY RANGE (used_at);

-- 月份分区
CREATE TABLE card_usage_logs_2023_01 PARTITION OF card_usage_logs
    FOR VALUES FROM ('2023-01-01') TO ('2023-02-01');
```

## 4. 缓存架构

### 4.1 Redis 缓存策略

```python
# 缓存层级设计
CACHE_LEVELS = {
    'L1': {  # 应用级缓存
        'timeout': 300,  # 5分钟
        'keys': [
            'user_profile:{user_id}',
            'card_template:{template_id}',
            'achievement_list'
        ]
    },
    'L2': {  # 会话级缓存
        'timeout': 1800,  # 30分钟
        'keys': [
            'chat_session:{session_id}',
            'device_status:{device_id}'
        ]
    },
    'L3': {  # 长期缓存
        'timeout': 86400,  # 24小时
        'keys': [
            'card_batch_stats:{batch_id}',
            'user_achievement_stats:{user_id}'
        ]
    }
}
```

### 4.2 Channel Layers配置

```python
# WebSocket消息通道配置
CHANNEL_LAYERS = {
    'default': {
        'BACKEND': 'channels_redis.core.RedisChannelLayer',
        'CONFIG': {
            "hosts": [('127.0.0.1', 6379)],
            "capacity": 1500,  # 每个通道最大消息数
            "expiry": 60,      # 消息过期时间（秒）
        },
    },
}
```

## 5. API设计架构

### 5.1 RESTful API设计原则

```
API 设计规范:
┌─────────────────────────────────────────────┐
│                API Layer                    │
│  ┌─────────────────────────────────────────┐ │
│  │           URL Structure                 │ │
│  │  /api/{version}/{module}/{resource}/    │ │
│  │  例如: /api/v1/user/auth/login/         │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │         HTTP Methods                    │ │
│  │  GET    - 查询资源                     │ │
│  │  POST   - 创建资源                     │ │
│  │  PUT    - 更新资源（完整）             │ │
│  │  PATCH  - 更新资源（部分）             │ │
│  │  DELETE - 删除资源                     │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │        Response Format                  │ │
│  │  {                                      │ │
│  │    "status": "success/error",           │ │
│  │    "code": 200,                         │ │
│  │    "data": {...},                       │ │
│  │    "message": "操作成功"                │ │
│  │  }                                      │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```

### 5.2 认证和授权架构

```python
# 认证流程
AUTHENTICATION_FLOW = {
    'Token': {
        'header': 'Authorization: Bearer {token}',
        'use_case': 'API客户端',
        'expiry': '永久（直到撤销）'
    },
    'Session': {
        'header': 'Cookie: sessionid={id}',
        'use_case': 'Web浏览器',
        'expiry': '2周'
    },
    'WebSocket': {
        'query_param': '?token={token}',
        'use_case': 'WebSocket连接',
        'validation': 'Token或用户ID'
    }
}
```

## 6. 第三方服务集成架构

### 6.1 AI服务适配层

```python
# AI服务抽象层
class AIServiceInterface:
    def single_chat(self, message: str, bot_id: int) -> Response:
        pass
    
    def multi_chat(self, message: str, session_id: str) -> Response:
        pass

# 具体实现
class KimiAIService(AIServiceInterface):
    def __init__(self, api_key, base_url):
        self.client = OpenAI(api_key=api_key, base_url=base_url)
    
    def single_chat(self, message, bot_id):
        # Kimi API调用实现
        pass
```

### 6.2 音频服务适配层

```python
# 音频服务工厂模式
class AudioServiceFactory:
    @staticmethod
    def get_service(provider: str) -> BaseAudioService:
        services = {
            'aliyun': AliyunAudioService,
            'huoshan': HuoshanAudioService,
            'tencent': TencentAudioService
        }
        return services[provider]()

# 统一音频服务接口
class BaseAudioService:
    def text_to_speech(self, text: str) -> AudioFile:
        pass
    
    def speech_to_text(self, audio: bytes) -> str:
        pass
```

### 6.3 云服务集成

```python
# 阿里云服务集成
ALIYUN_SERVICES = {
    'SMS': {
        'service': 'dysmsapi',
        'use_case': '短信验证码发送'
    },
    'OSS': {
        'service': 'oss2',
        'use_case': '文件存储'
    },
    'NLS': {
        'service': 'nls',
        'use_case': '语音识别'
    },
    'VI': {
        'service': 'facebody',
        'use_case': '图像识别'
    }
}
```

## 7. 消息队列和异步处理

### 7.1 任务队列架构

```python
# 使用APScheduler进行任务调度
from apscheduler.schedulers.django import DjangoScheduler

scheduler = DjangoScheduler()

# 定时任务示例
@scheduler.scheduled_job('cron', hour=0, minute=0)
def cleanup_expired_cards():
    """清理过期卡片"""
    pass

@scheduler.scheduled_job('cron', hour=2, minute=0)
def update_achievement_stats():
    """更新成就统计"""
    pass
```

### 7.2 异步任务设计

```python
# 异步任务装饰器
import asyncio
from functools import wraps

def async_task(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        loop = asyncio.get_event_loop()
        return loop.run_in_executor(None, func, *args, **kwargs)
    return wrapper

@async_task
def process_audio_file(audio_file):
    """异步处理音频文件"""
    # 耗时的音频处理操作
    pass
```

## 8. 安全架构

### 8.1 安全策略

```python
SECURITY_MEASURES = {
    'Authentication': {
        'token_expiry': '不过期（需要主动撤销）',
        'session_expiry': '2周',
        'password_policy': '最少8位，包含数字和字母'
    },
    'Authorization': {
        'role_based': 'Django用户组和权限系统',
        'resource_based': 'DRF权限类',
        'device_binding': '设备MAC地址绑定'
    },
    'Data_Protection': {
        'encryption': 'Django内置密码加密',
        'sensitive_data': 'PII数据不记录在日志中',
        'api_rate_limit': 'DRF限流机制'
    }
}
```

### 8.2 CORS和CSRF配置

```python
# CORS配置
CORS_ALLOW_ALL_ORIGINS = True  # 开发环境
CORS_ALLOWED_ORIGINS = [       # 生产环境
    "https://yourdomain.com",
    "https://www.yourdomain.com",
]

# CSRF保护（API禁用，Web界面启用）
CSRF_EXEMPT_URLS = [
    r'^api/',  # API接口豁免CSRF
]
```

## 9. 监控和日志架构

### 9.1 日志系统设计

```python
# 分层日志配置
LOGGING_ARCHITECTURE = {
    'Application_Logs': {
        'level': 'INFO',
        'handler': 'AliyunLogHandler',
        'format': 'structured_json',
        'retention': '30天'
    },
    'Access_Logs': {
        'level': 'INFO',
        'handler': 'FileHandler',
        'format': 'nginx_format',
        'rotation': '每日'
    },
    'Error_Logs': {
        'level': 'ERROR',
        'handler': 'AliyunLogHandler + EmailHandler',
        'format': 'detailed_traceback',
        'alert': True
    }
}
```

### 9.2 性能监控

```python
# 数据库连接监控
def print_database_and_cache_info():
    """启动时打印数据库和缓存连接信息"""
    # 测试数据库连接延迟
    # 测试缓存连接延迟
    # 记录连接状态到日志
    pass
```

## 10. 扩展性设计

### 10.1 水平扩展策略

```
扩展架构:
┌─────────────────────────────────────────────┐
│              Load Balancer                  │
│                (Nginx)                      │
└─────────────┬───────────────────────────────┘
              │
    ┌─────────┴─────────┬─────────────────────┐
    │                   │                     │
┌───▼────┐         ┌───▼────┐           ┌───▼────┐
│App     │         │App     │           │App     │
│Server 1│         │Server 2│    ...    │Server N│
└────────┘         └────────┘           └────────┘
    │                   │                     │
    └─────────┬─────────┴─────────────────────┘
              │
    ┌─────────▼─────────┐
    │                   │
┌───▼────┐         ┌───▼────┐
│Database│         │ Redis  │
│Cluster │         │Cluster │
└────────┘         └────────┘
```

### 10.2 模块化插件架构

```python
# 插件系统设计
class PluginBase:
    def __init__(self, config):
        self.config = config
    
    def initialize(self):
        pass
    
    def process(self, data):
        pass

# 音频服务插件
class AudioPlugin(PluginBase):
    def process(self, audio_data):
        # 音频处理逻辑
        pass

# 插件管理器
class PluginManager:
    def __init__(self):
        self.plugins = {}
    
    def register_plugin(self, name, plugin_class):
        self.plugins[name] = plugin_class
    
    def get_plugin(self, name):
        return self.plugins.get(name)
```

## 11. 部署架构

### 11.1 容器化部署

```dockerfile
# 多阶段构建
FROM python:3.9-slim as builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.9-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.9/site-packages /usr/local/lib/python3.9/site-packages
COPY . .
CMD ["daphne", "-b", "0.0.0.0", "-p", "8000", "qy_lty.asgi:application"]
```

### 11.2 云原生部署

```yaml
# Kubernetes部署示例
apiVersion: apps/v1
kind: Deployment
metadata:
  name: qy-lty-backend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: qy-lty-backend
  template:
    metadata:
      labels:
        app: qy-lty-backend
    spec:
      containers:
      - name: backend
        image: qy-lty-backend:latest
        ports:
        - containerPort: 8000
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
```

这个架构文档涵盖了系统的各个方面，为开发者提供了全面的技术架构理解。每个组件都经过精心设计，支持高可用、可扩展和可维护的系统架构。