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