lty/qy_lty/docs

QY LTY Backend 文档中心

欢迎来到QY LTY Backend（气元科技AI智能设备后端服务）的文档中心。本文档库包含了系统的完整技术文档，帮助开发者快速理解和参与项目开发。

📋 项目概览

QY LTY Backend是一个基于Django的综合性AI智能设备后端服务，提供以下核心功能：

• 用户管理系统 - 多种认证方式、用户配置文件管理
• AI对话系统 - 单轮/多轮对话，支持语音输入输出
• 卡片管理系统 - 模板化卡片生成、批次管理、二维码系统
• 设备交互系统 - WebSocket实时通信、设备管理
• 成就系统 - 用户成就追踪、奖励机制
• 多平台集成 - 阿里云、火山引擎、腾讯云等服务

🗂️ 文档结构

📚 API文档 (/api/)

系统提供的RESTful API接口文档：

文档	描述	状态
AI对话API	AI对话系统接口，支持单轮和多轮对话，语音输入输出	✅ 完整
卡片系统API	卡片模板、批次管理、使用跟踪等接口	✅ 完整
成就系统API	成就管理、用户成就进度跟踪接口	✅ 完整
设备交互API	设备管理、消息发送、WebSocket连接接口	✅ 完整
用户认证API	用户注册、登录、认证相关接口	✅ 完整

🛠️ 开发文档 (/development/)

开发环境搭建和系统架构文档：

文档	描述	状态
环境搭建指南	详细的开发环境配置步骤和常见问题解决	✅ 完整
系统架构设计	完整的技术架构、模块设计和扩展性规划	✅ 完整
数据库设计	数据模型设计、迁移管理、性能优化	🚧 待补充
部署指南	生产环境部署、Docker容器化、监控配置	🚧 待补充

🔗 集成文档 (/integrations/)

第三方服务集成指南：

文档	描述	状态
音频服务集成	多厂商音频服务配置、使用和最佳实践	✅ 完整
阿里云服务集成	阿里云SMS、OSS、NLS等服务集成	🚧 待补充
火山引擎集成	火山引擎语音服务、RTC集成配置	🚧 待补充

⚡ 功能特性 (/features/)

核心功能实现详解：

文档	描述	状态
WebSocket实现	实时通信架构、Consumer实现、客户端示例	✅ 完整
认证系统详解	多种认证方式实现、安全策略	🚧 待补充
卡片系统详解	卡片生成流程、属性系统、业务逻辑	🚧 待补充

🚀 快速开始

1. 环境准备

# 克隆项目
git clone https://github.com/your-org/qy_ai_backend.git
cd qy_ai_backend

# 创建conda环境
conda create -n lty python=3.9
conda activate lty

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

2. 配置环境变量

# 复制环境变量模板
cp .env.bak .env

# 编辑环境变量（必须配置的关键变量）
# SECRET_KEY - Django密钥
# POSTGRESQL_DATABASE_* - 数据库配置
# REDIS_* - Redis配置  
# KIMI_API_KEY - AI服务密钥

3. 数据库设置

# 运行数据库迁移
python manage.py migrate

# 创建超级用户
python manage.py createsuperuser

4. 启动服务

# 启动开发服务器（支持WebSocket）
./run.sh

# 或使用daphne
daphne -b 0.0.0.0 -p 8000 qy_lty.asgi:application

5. 验证安装

访问以下URL验证服务：

• Django Admin: http://localhost:8000/admin/
• API文档: http://localhost:8000/swagger/
• ReDoc文档: http://localhost:8000/redoc/

详细的环境搭建步骤请参考：环境搭建指南

🏗️ 技术栈

后端框架

• Django 4.2.13 - Web框架
• Django REST Framework - API框架
• Django Channels - WebSocket支持
• Daphne - ASGI服务器

数据库和缓存

• PostgreSQL - 主数据库
• Redis - 缓存和消息队列
• Django Redis - Redis集成

第三方服务

• AI服务: Kimi (Moonshot AI)
• 音频服务: 阿里云NLS、火山引擎、腾讯云
• 云服务: 阿里云OSS、SMS、视觉智能
• 地图天气: 高德地图API、和风天气

📖 核心概念

用户系统

• 自定义用户模型: 扩展Django User，支持手机号、MBTI等字段
• 多种认证方式: 用户名密码、邮箱、手机验证码、MAC地址
• 社交登录: 微信等第三方平台集成

AI对话系统

• 单轮对话: 基于Bot ID的即时对话
• 多轮对话: 带上下文的连续对话
• 语音支持: 语音识别(ASR)和语音合成(TTS)
• 多AI提供商: 支持不同AI服务的适配

卡片系统

• 模板驱动: 可配置的卡片模板系统
• 批次管理: 大批量卡片生成和管理
• 分类属性: 舞蹈、音乐、服装、游戏等不同类别
• 二维码集成: 自动生成和管理二维码

设备交互

• WebSocket通信: 基于Django Channels的实时通信
• 设备管理: 设备类型、批次、绑定关系
• 消息系统: 支持多种消息类型的分发

成就系统

• 进度跟踪: 用户行为和成就进度追踪
• 奖励机制: 多样化的成就奖励系统
• 统计分析: 成就数据统计和排行榜

🔧 开发工具和规范

推荐开发工具

• IDE: VS Code + Python扩展，或PyCharm
• API测试: Postman、HTTPie
• 数据库: pgAdmin、DBeaver
• Git: 使用规范的提交格式

代码规范

• 格式化: Black、isort
• 代码检查: flake8
• 提交格式: 遵循Conventional Commits

测试策略

# 运行测试
python manage.py test

# 运行特定应用测试
python manage.py test userapp
python manage.py test aiapp

📊 监控和日志

日志系统

• 结构化日志: 使用JSON格式记录
• 分级处理: 区分DEBUG、INFO、WARNING、ERROR
• 云端集成: 阿里云日志服务集成

性能监控

• 数据库性能: 连接监控和查询优化
• 缓存效率: Redis使用情况跟踪
• API性能: 响应时间和成功率监控

🤝 贡献指南

开发流程

1. Fork项目 并创建功能分支
2. 编写代码 遵循项目规范
3. 添加测试 确保代码质量
4. 更新文档 保持文档同步
5. 提交PR 并通过代码审查

文档贡献

• 发现文档问题请创建Issue
• 欢迎提交文档改进PR
• 新功能开发请同步更新文档

📞 支持和反馈

获取帮助

• 技术问题: 查阅相关文档或创建Issue
• Bug报告: 使用Issue模板提供详细信息
• 功能建议: 通过Issue讨论新功能需求

联系方式

• 项目维护者: [维护者邮箱]
• 团队协作: [团队沟通渠道]
• 技术支持: [技术支持渠道]

📝 版本历史

版本	日期	主要变更
v1.0.0	2023-01	初始版本发布
v1.1.0	2023-02	添加成就系统
v1.2.0	2023-03	优化音频服务

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

---

🗺️ 文档导航

👨‍💻 开发者路径

1. 新手开发者: 环境搭建 → 系统架构 → API文档
2. 前端开发者: API文档 → WebSocket实现
3. 运维工程师: 部署指南 → 监控配置

🎯 功能路径

1. AI对话功能: AI对话API → 音频服务集成
2. 卡片系统: 卡片API → 卡片系统详解
3. 实时通信: 设备交互API → WebSocket实现

📋 维护路径

1. 系统维护: 架构文档 → 数据库设计
2. 服务集成: 集成文档 → [第三方服务配置]
3. 监控运维: 部署指南 → [性能优化]

---

最后更新: 2023年1月 文档版本: 1.0