pmc
bd95ba470c
- Update food, outfits, props, home-decor pages and components - Add permissions page and sidebar updates - Update API client and all API modules (auth, food, dances, etc.) - Add card model migrations for optional fields - Update Django views, serializers, and authentication - Add affinity level migrations and user app updates - Add project documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
239 lines
7.7 KiB
Markdown
239 lines
7.7 KiB
Markdown
# 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
|
||
```
|