# QY LTY 后端服务 — 项目功能介绍

## 项目定位

QY LTY 是一个 AI 智能硬件（如陪伴机器人/智能玩具）的后端平台，基于 Django 构建，为设备提供 AI 对话、语音交互、实时通信能力，同时管理用户账号、卡密激活、订阅付费和成就激励体系。

---

## 代码目录结构

| 目录 | 说明 |
|------|------|
| `qy_lty/` | Django 主配置（settings、urls、asgi） |
| `userapp/` | 用户管理与认证 |
| `aiapp/` | AI 对话系统 |
| `card/` | 卡片/卡密系统 |
| `device_interaction/` | 设备 WebSocket 实时通信 |
| `achievement_app/` | 成就系统 |
| `subscription_app/` | 订阅管理 |
| `ali_vi_app/` | 阿里云视觉智能（换脸/美颜等） |
| `food_app/` | 食物系统（游戏道具） |
| `workflow_app/` | 工作流管理（开发中） |
| `common/` | 公共工具（响应格式、OSS、中间件） |
| `docs/` | 项目文档 |

---

## 功能模块详解

### 1. 用户管理（userapp/）

- 自定义用户模型 `ParadiseUser`，扩展字段：手机号、性别、生日、星座、MBTI、兴趣、社交身份
- 多种登录方式：手机号、邮箱、用户名、MAC 地址
- 阿里云短信验证码
- 微信社交登录（django-allauth）
- Redis Token 认证

**核心文件：**
- `models.py` — ParadiseUser 用户模型
- `views.py` — 注册、登录、资料更新接口
- `authentication.py` — RedisTokenAuthentication 自定义认证
- `utils.py` — 短信发送、Token 生成与管理

---

### 2. AI 对话系统（aiapp/）

- **单轮对话：** `/api/ai/chat/<bot_id>/`
- **多轮对话：** `/api/ai/multichat/`（保持上下文）
- 接入 Kimi（月之暗面）大模型
- **语音服务：** 多供应商抽象架构
  - `audio/AliyunAudioService.py` — 阿里云语音
  - `audio/TencentAudioService.py` — 腾讯云语音
  - `audio/HuoshanAudioService.py` — 火山引擎语音
- 支持语音合成（TTS）和语音识别（ASR）

**核心文件：**
- `models.py` — Bot 机器人模型、ChatMessage 对话记录模型
- `views.py` — ChatBotAPIView（单轮）、MultiChatAPIView（多轮）
- `kimi.py` — Kimi API 客户端（OpenAI 兼容接口）
- `audio/AudioService.py` — 音频服务工厂函数
- `audio/BaseAudioService.py` — 音频服务抽象基类

---

### 3. 设备实时通信（device_interaction/）

- WebSocket 连接：`ws://domain/ws/device/token/{token}/`
- 设备模型：设备类型、批次、序列号、电量、固件版本、WiFi、亮度
- 用户-设备绑定关系
- 消息类型：`chat_message`（聊天）、`weather`（天气）、`sing`（唱歌）、`dance`（跳舞）
- 集成和风天气 API、高德地图 API
- 火山引擎 RTC 实时音视频

**核心文件：**
- `models.py` — DeviceType、DeviceBatch、Device、UserDevice 模型
- `consumers.py` — DeviceConsumer WebSocket 消费者
- `views.py` — 设备管理 API
- `services.py` — Redis 设备连接状态追踪
- `auth.py` — TokenAuthMiddleware WebSocket 认证中间件
- `weather.py` — 和风天气 API 集成
- `amap_api.py` — 高德地图定位服务
- `volcengine_api.py` — 火山引擎 RTC 集成

---

### 4. 卡片/卡密系统（card/）

- 卡片模板：分类（服装、道具、歌曲、舞蹈、家具、装饰）、稀有度
- 批量生成卡密，支持 Excel 导出
- 二维码生成和扫码核销
- 使用日志追踪（扫描、使用、作废、发布、生产）
- 每个分类有独立属性模型（ClothingAttributes、PropAttributes 等）

**核心文件：**
- `models.py` — CardTemplate、Card、CardBatch、CardUsageLog 及各分类属性模型
- `views.py` — 模板 CRUD、批量生成、扫码核销、Excel 导出
- `storage.py` — OSSStorage 阿里云对象存储集成

---

### 5. 成就系统（achievement_app/）

- 成就定义：名称、描述、图标、达成条件（JSON）
- 稀有度：普通 / 珍贵 / 稀有 / 史诗 / 传说
- 类型：登录 / 活动 / 社交 / 使用 / 特殊 / 隐藏
- 用户成就进度追踪与通知

**核心文件：**
- `models.py` — Achievement 成就定义、UserAchievement 用户成就记录

---

### 6. 订阅管理（subscription_app/）

- 订阅计划：月付 / 季付 / 年付
- 增值包购买（AddOnPackage）
- 计费记录（TenantBilling）
- 定时任务处理订阅续期

**核心文件：**
- `models.py` — SubscriptionPlan、Subscription、AddOnPackage、SubscriptionAddOn、TenantBilling
- `scheduler.py` — 定时任务
- `tasks.py` — 异步任务

---

### 7. 阿里云视觉智能（ali_vi_app/）

- 人脸融合/换脸
- 人脸美颜
- 面部液化、妆容、肤质优化

**核心文件：**
- `vi.py` — VI 类，封装阿里云 FaceBody API（add_template、merge_image_face、face_beauty 等）

---

### 8. 食物系统（food_app/）

- 食物道具：水果、蔬菜、肉类、海鲜等 11 种分类
- 稀有度等级、卡路里、口味标签、营养值
- 游戏效果、使用次数限制、上架时间窗口
- 用户食物背包、使用日志

**核心文件：**
- `models.py` — Food 食物定义、UserFood 用户背包、FoodUsageLog 使用日志

---

### 9. 公共基础设施（common/）

- 标准化 API 响应格式：`{success, code, message, data}`
- 阿里云 OSS 文件上传
- 阿里云日志服务
- 自定义分页（默认 10 条，最大 100 条）
- 火山引擎 Token 管理

**核心文件：**
- `responses.py` — api_response、success_response、error_response 等标准响应函数
- `middleware.py` — StandardResponseMiddleware 统一响应中间件
- `pagination.py` — CustomPageNumberPagination 分页器
- `oss.py` — OSSUploader 文件上传工具
- `aliyun_logging.py` — 阿里云日志配置

---

## API 接口一览

| 路径 | 说明 |
|------|------|
| `/api/user/` | 用户认证与管理 |
| `/api/ai/` | AI 对话接口 |
| `/api/device/` | 设备管理与消息推送 |
| `/api/card/` | 卡片系统管理 |
| `/api/achievement/` | 成就系统 |
| `/api/v1/admin/` | 管理后台接口 |
| `/swagger/` | Swagger API 文档 |
| `/redoc/` | ReDoc API 文档 |

**WebSocket 端点：**
- `ws://domain/ws/device/` — 设备连接
- `ws://domain/ws/device/token/{token}/` — 带 Token 认证的设备连接

---

## 技术栈

| 层面 | 技术 |
|------|------|
| 框架 | Django 4.2.13 + Django REST Framework |
| 实时通信 | Django Channels + Daphne ASGI |
| 数据库 | PostgreSQL |
| 缓存/消息 | Redis |
| AI 模型 | Kimi（OpenAI 兼容接口） |
| 语音服务 | 阿里云 / 腾讯 / 火山引擎（可配置切换） |
| 文件存储 | 阿里云 OSS |
| 短信服务 | 阿里云 SMS |
| 视觉智能 | 阿里云 FaceBody |
| 地图/天气 | 高德地图 / 和风天气 |
| 音视频 | 火山引擎 RTC |
| 部署 | Docker + docker-compose |
| API 文档 | drf-yasg（Swagger / ReDoc） |
| 后台管理 | django-simpleui |

---

## 环境配置

### 必需环境变量（.env）

- `SECRET_KEY` — Django 密钥
- `DEBUG` — 调试模式
- `POSTGRESQL_DATABASE_*` — 数据库连接
- `REDIS_LOCATION`、`REDIS_PASSWORD` — Redis 配置
- `KIMI_API_KEY`、`KIMI_BASE_URL` — Kimi AI 配置
- `ALIYUN_*` — 阿里云各服务凭证
- `VOLCENGINE_ACCESS_KEY`、`VOLCENGINE_SECRET_KEY` — 火山引擎配置
- `AUDIO_SERVICE_PROVIDER` — 语音服务商选择

### 快速启动

```bash
# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.bak .env

# 数据库迁移
python manage.py migrate

# 启动服务（支持 WebSocket）
daphne -b 0.0.0.0 -p 8000 qy_lty.asgi:application

# Docker 部署
docker-compose up -d --build
```