263 lines
8.7 KiB
Markdown
263 lines
8.7 KiB
Markdown
# QY LTY Backend 文档中心
|
||
|
||
欢迎来到QY LTY Backend（气元科技AI智能设备后端服务）的文档中心。本文档库包含了系统的完整技术文档，帮助开发者快速理解和参与项目开发。
|
||
|
||
## 📋 项目概览
|
||
|
||
QY LTY Backend是一个基于Django的综合性AI智能设备后端服务，提供以下核心功能：
|
||
|
||
- **用户管理系统** - 多种认证方式、用户配置文件管理
|
||
- **AI对话系统** - 单轮/多轮对话，支持语音输入输出
|
||
- **卡片管理系统** - 模板化卡片生成、批次管理、二维码系统
|
||
- **设备交互系统** - WebSocket实时通信、设备管理
|
||
- **成就系统** - 用户成就追踪、奖励机制
|
||
- **多平台集成** - 阿里云、火山引擎、腾讯云等服务
|
||
|
||
## 🗂️ 文档结构
|
||
|
||
### 📚 API文档 (`/api/`)
|
||
|
||
系统提供的RESTful API接口文档：
|
||
|
||
| 文档 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| [AI对话API](api/ai_api.md) | AI对话系统接口，支持单轮和多轮对话，语音输入输出 | ✅ 完整 |
|
||
| [卡片系统API](api/card_api.md) | 卡片模板、批次管理、使用跟踪等接口 | ✅ 完整 |
|
||
| [成就系统API](api/achievement_api.md) | 成就管理、用户成就进度跟踪接口 | ✅ 完整 |
|
||
| [设备交互API](device_api.md) | 设备管理、消息发送、WebSocket连接接口 | ✅ 完整 |
|
||
| [用户认证API](user_authentication_api.md) | 用户注册、登录、认证相关接口 | ✅ 完整 |
|
||
|
||
### 🛠️ 开发文档 (`/development/`)
|
||
|
||
开发环境搭建和系统架构文档：
|
||
|
||
| 文档 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| [环境搭建指南](development/setup.md) | 详细的开发环境配置步骤和常见问题解决 | ✅ 完整 |
|
||
| [系统架构设计](development/architecture.md) | 完整的技术架构、模块设计和扩展性规划 | ✅ 完整 |
|
||
| [数据库设计](development/database.md) | 数据模型设计、迁移管理、性能优化 | 🚧 待补充 |
|
||
| [部署指南](development/deployment.md) | 生产环境部署、Docker容器化、监控配置 | 🚧 待补充 |
|
||
|
||
### 🔗 集成文档 (`/integrations/`)
|
||
|
||
第三方服务集成指南：
|
||
|
||
| 文档 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| [音频服务集成](integrations/audio_services.md) | 多厂商音频服务配置、使用和最佳实践 | ✅ 完整 |
|
||
| [阿里云服务集成](integrations/aliyun.md) | 阿里云SMS、OSS、NLS等服务集成 | 🚧 待补充 |
|
||
| [火山引擎集成](integrations/volcengine.md) | 火山引擎语音服务、RTC集成配置 | 🚧 待补充 |
|
||
|
||
### ⚡ 功能特性 (`/features/`)
|
||
|
||
核心功能实现详解：
|
||
|
||
| 文档 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| [WebSocket实现](features/websocket.md) | 实时通信架构、Consumer实现、客户端示例 | ✅ 完整 |
|
||
| [认证系统详解](features/authentication.md) | 多种认证方式实现、安全策略 | 🚧 待补充 |
|
||
| [卡片系统详解](features/card_system.md) | 卡片生成流程、属性系统、业务逻辑 | 🚧 待补充 |
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 环境准备
|
||
|
||
```bash
|
||
# 克隆项目
|
||
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. 配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
cp .env.bak .env
|
||
|
||
# 编辑环境变量（必须配置的关键变量）
|
||
# SECRET_KEY - Django密钥
|
||
# POSTGRESQL_DATABASE_* - 数据库配置
|
||
# REDIS_* - Redis配置
|
||
# KIMI_API_KEY - AI服务密钥
|
||
```
|
||
|
||
### 3. 数据库设置
|
||
|
||
```bash
|
||
# 运行数据库迁移
|
||
python manage.py migrate
|
||
|
||
# 创建超级用户
|
||
python manage.py createsuperuser
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
```bash
|
||
# 启动开发服务器（支持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/
|
||
|
||
详细的环境搭建步骤请参考：[环境搭建指南](development/setup.md)
|
||
|
||
## 🏗️ 技术栈
|
||
|
||
### 后端框架
|
||
- **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
|
||
|
||
### 测试策略
|
||
```bash
|
||
# 运行测试
|
||
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](../LICENSE) 文件
|
||
|
||
---
|
||
|
||
## 🗺️ 文档导航
|
||
|
||
### 👨💻 开发者路径
|
||
1. **新手开发者**: [环境搭建](development/setup.md) → [系统架构](development/architecture.md) → [API文档](api/)
|
||
2. **前端开发者**: [API文档](api/) → [WebSocket实现](features/websocket.md)
|
||
3. **运维工程师**: [部署指南](development/deployment.md) → [监控配置](development/monitoring.md)
|
||
|
||
### 🎯 功能路径
|
||
1. **AI对话功能**: [AI对话API](api/ai_api.md) → [音频服务集成](integrations/audio_services.md)
|
||
2. **卡片系统**: [卡片API](api/card_api.md) → [卡片系统详解](features/card_system.md)
|
||
3. **实时通信**: [设备交互API](device_api.md) → [WebSocket实现](features/websocket.md)
|
||
|
||
### 📋 维护路径
|
||
1. **系统维护**: [架构文档](development/architecture.md) → [数据库设计](development/database.md)
|
||
2. **服务集成**: [集成文档](integrations/) → [第三方服务配置]
|
||
3. **监控运维**: [部署指南](development/deployment.md) → [性能优化]
|
||
|
||
---
|
||
|
||
*最后更新: 2023年1月*
|
||
*文档版本: 1.0* |