lty/qy_lty/docs/项目功能介绍.md

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 — 语音服务商选择

快速启动

# 安装依赖
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