zyc/lty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
lty/qy_lty/docs/README.md
zyc 0c610c1e49 first commit
2026-03-17 13:17:02 +08:00

8.7 KiB
Raw Permalink Blame History

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 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