# CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指导。

## 项目概述

QY LTY Backend 是一个基于 Django 的综合性后端服务，提供以下功能：
- 用户管理与认证系统
- AI 对话能力（支持语音的单轮/多轮聊天）
- 卡片管理系统，支持批量生成与二维码功能
- 通过 WebSocket 实时通信进行设备交互
- 成就系统
- 订阅管理
- 多种第三方集成（阿里云、火山引擎、腾讯等）

### 对接的客户端项目

本服务器作为统一后端，与以下客户端/管理端项目进行通讯和数据交互：

| 项目 | 路径 | 角色 | 通讯方式 |
|------|------|------|---------|
| **LTY_App_Project_URP** | `C:\Unity2022project\LTY_App_Project_URP` | 洛天依 APP（Unity URP 客户端） | HTTP REST API + WebSocket (`/ws/device/`) |
| **LTY_Project** | `C:\Unity2022project\LTY_Project` | 洛天依 Unity 项目（设备端/终端） | HTTP REST API + WebSocket + RTC（火山引擎） |
| **qy-lty-admin** | `../qy-lty-admin/`（`C:\Users\admin\Desktop\Lila-Server\qy-lty-admin`） | Web 管理后台（Next.js 15 + React 19） | HTTP REST API（`NEXT_PUBLIC_API_BASE_URL`） |

- 两个 Unity 客户端通过 `device_interaction` 模块共享同一套 WebSocket 通道（分组模型 `device_{user_id}`），设备端与 APP 端解析到同一 user_id 才能互通消息
- 管理后台通过 `/api/v1/admin/` 与各业务模块接口进行运营管理数据交互

## 开发命令

### 环境配置
```bash
# 安装依赖
pip install -r requirements.txt

# 复制环境配置文件
cp .env.bak .env

# 数据库迁移
python manage.py migrate

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

### 运行应用
```bash
# 启动开发服务器（支持 WebSocket 的 ASGI）
./run.sh

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

# 传统 Django 开发服务器（仅 HTTP）
python manage.py runserver
```

### 数据库管理
```bash
# 创建新的迁移文件
python manage.py makemigrations
python manage.py makemigrations [app_name]

# 应用迁移
python manage.py migrate

# 数据库 shell
python manage.py dbshell

# Django shell
python manage.py shell
```

### 国际化 (i18n)
```bash
# 生成消息文件
django-admin makemessages -l en
django-admin makemessages -l zh_HAns

# 编译翻译
django-admin compilemessages
```

### Docker 部署
```bash
# 构建并启动容器
docker-compose up -d --build

# 通过 http://localhost:12012 访问应用
```

## 架构概览

### 核心 Django 应用结构
- **userapp/**：自定义用户模型 (ParadiseUser)，包含认证、手机验证和用户管理
- **aiapp/**：AI 对话系统，集成 Kimi，通过多个服务商提供语音合成/识别
- **card/**：卡片管理系统，包含分类、批次、二维码和使用追踪
- **device_interaction/**：基于 WebSocket 的实时设备通信，带有认证机制
- **achievement_app/**：用户成就与进度追踪系统
- **subscription_app/**：用户订阅与计费管理
- **ali_vi_app/**：阿里云视觉智能集成
- **workflow_app/**：多租户工作流管理（开发中）

### 关键技术组件

#### ASGI/WebSocket 配置
- 使用 Django Channels 提供 WebSocket 支持
- 自定义基于 token 的 WebSocket 认证（`device_interaction.auth.TokenAuthMiddleware`，复用 `userapp.authentication.RedisTokenAuthentication`）
- 基于 Redis 的通道层用于实时消息传递
- WebSocket 路由：`ws://domain/ws/device/`（Header 鉴权）和 `ws://domain/ws/device/token/{token}/`（URL 鉴权）
- **分组模型**：`device_{user_id}` —— 设备端与手机端必须解析到 **同一个 user_id** 才能互通消息（详见下文"设备绑定与控制权"）

#### 认证系统
- 自定义用户模型：`userapp.ParadiseUser`，继承自 AbstractUser
- 基于 token 的 API 认证：token 存储在 Redis 中，普通用户 key 为 `token:{token}`，管理员为 `admin_token:{token}`，TTL 30 天（见 `userapp/utils.py:generate_token`）
- 通过短信进行手机验证（阿里云 SMS 服务）
- 通过 django-allauth 实现社交认证（微信）
- 设备端通过 `POST /api/user/mac-login/` 用 MAC 地址换取绑定用户的 user-token

#### 数据库配置
- 主库：PostgreSQL（可通过环境变量配置）
- Redis 用于缓存和 WebSocket 通道层
- 使用 python-decouple 进行基于环境的配置

#### 音频/语音服务
- 多服务商音频支持：阿里云、腾讯、火山引擎
- 通过 `AUDIO_SERVICE_PROVIDER` 配置切换服务商
- 支持语音合成与识别能力

## API 文档

### 访问入口
- Swagger UI：`http://localhost:8000/swagger/`
- ReDoc：`http://localhost:8000/redoc/`

### 主要 API 模块
- `/api/user/` - 用户认证与管理
- `/api/ai/` - AI 对话接口
- `/api/device/` - 设备交互与 WebSocket 消息
- `/api/card/` - 卡片系统管理
- `/api/achievement/` - 成就系统
- `/api/v1/admin/` - 管理功能

### WebSocket 消息类型
```json
{
    "type": "message_type",
    "message": "content",
    "user_id": "user_id"
}
```

支持的类型（见 `device_interaction/consumers.py:DeviceConsumer.receive`）：
- `chat_message` — 默认文本消息
- `weather` — 天气信息（message 为 JSON 字符串）
- `sing` / `dance` / `touch` — 动作指令
- `flow_light` — 流水灯开关
- `device_info` — 设备上报 MAC、电量、固件、WiFi 等，会写库并刷新心跳
- `device_state` — 手机端设备状态
- `conversation_status` / `conversation_subtitle` — 火山引擎对话回调转发
- `factory_reset` — 恢复出厂设置

### RTC（火山引擎）
- 端点 `/api/device/rtc-token/get_by_mac/?mac_address=...` 不需鉴权，根据 MAC 返回该设备绑定用户对应的 RTC token
- `room_id = f"room_{user_id}"`、token 缓存 key 为 `rtc_room:{user_id}:{task_id}`
- `room_id` 与 WebSocket 分组绑定的是同一个 user_id，保持端到端一致

## 环境配置

### 必需的环境变量 (.env)
- `SECRET_KEY` - Django 密钥
- `DEBUG` - 开发模式标志
- 数据库：`POSTGRESQL_DATABASE_*` 系列变量
- Redis：`REDIS_LOCATION`、`REDIS_PASSWORD`
- Kimi AI：`KIMI_API_KEY`、`KIMI_BASE_URL`
- 阿里云服务：各类 `ALIYUN_*` 密钥
- 音频服务：服务商相关配置
- 火山引擎：`VOLCENGINE_ACCESS_KEY`、`VOLCENGINE_SECRET_KEY`

## 关键依赖

### 核心框架
- Django 4.2.13 配合 Django REST Framework
- Django Channels 提供 WebSocket 支持
- Daphne ASGI 服务器

### 第三方集成
- 阿里云：SMS、OSS、NLS（语音）、视觉智能
- 火山引擎（字节跳动）：RTC 服务
- 腾讯：音频服务
- OpenAI 兼容 API（Kimi）

### 开发工具
- django-debug-toolbar 用于开发环境调试
- django-simpleui 用于增强后台管理界面
- drf-yasg 用于生成 API 文档

## 代码模式与约定

### 模型结构
- 自定义用户模型，包含丰富的资料字段（性别、MBTI、兴趣等）
- 卡片系统采用基于批次的生成方式，配合分类管理
- 成就系统包含稀有度等级与进度追踪

### API 响应格式
- 通过 `common.middleware.StandardResponseMiddleware` 实现标准化响应
- 自定义分页：`common.pagination.CustomPageNumberPagination`

### 日志
- 集成阿里云日志服务用于生产环境日志记录
- 为 aiapp、userapp、common 模块配置专用日志记录器

### 文件存储
- 使用 OSS（阿里云对象存储）存储音频和媒体文件
- 开发环境使用本地存储，路径可配置

## 开发说明

### WebSocket 开发
- 设备连接需要基于 token 的认证
- 通道层使用 Redis 进行消息传递
- 自定义消费者位于 `device_interaction.consumers`
- 设备心跳：每次收消息时刷新 `device:last_seen:{mac}`（TTL 5 分钟），断连时把 `Device.status` 标记为 `disconnected`

### 设备绑定与控制权（重要）
- `UserDevice` 关联表的 `Meta.ordering = ['-bound_at']`
- **"后绑的挤掉先绑的"语义**：`userapp/views.py` 的 MAC 登录显式按 `order_by('-bound_at').first()` 取最新绑定者并签发 user-token；`device_interaction/views.py` 中的 `bind_status` / `rtc-token/get_by_mac` 等使用 `.first()` 隐式依赖该 ordering，结果一致
- 由于 WebSocket 分组是 `device_{user_id}`，**同一台设备同一时刻只有一个用户能真正控制它**——即最近一次绑定的那个用户
- 旧的 `UserDevice` 记录**不会**被自动删除，仅在控制权解析中被忽略；如需"换绑"语义请显式删除旧记录
- `is_primary` 是"用户视角的主设备"（每个用户最多一个），**不是**"设备视角的主控用户"——同一台设备可能出现多条 `is_primary=True` 的记录
- **测试 MAC `AA:BB:CC:DD:EE:FF`** 在 `device_interaction/serializers.py` 与 `views.py` 中被硬编码跳过"设备已被其他用户绑定"校验，仅供测试用

### 音频服务集成
- 通过 `aiapp.audio.AudioService` 提供与服务商无关的接口
- 支持语音转文本与文本转语音能力
- 集成文件存储用于音频资源管理

### 卡片系统功能
- 批量生成，支持配置数量与格式
- 二维码生成与扫描
- 使用追踪与数据分析
- 基于分类的组织管理，支持属性配置

### 后台管理界面
- 深度定制 SimpleUI 主题
- 支持多语言（中文/英文）
- 为不同模块配置自定义图标与组织结构