# RTC Backend - Claude Code 项目指南

## 项目概述

物联网设备管理平台后端，支持设备绑定 AI 智能体（心灵）。

## 技术栈

- Django 6.0.1 + DRF 3.16.1
- Python 3.12+ / MySQL / Redis
- JWT 认证 / 阿里云 OSS

## 核心目录

```
rtc_backend/
├── config/          # Django 配置
├── apps/            # 业务应用
│   ├── users/       # App 用户（手机号登录）
│   ├── admins/      # 管理员（用户名密码）
│   ├── devices/     # 设备管理
│   ├── spirits/     # AI 智能体
│   ├── stories/     # 故事模块
│   ├── music/       # 音乐模块
│   ├── notifications/ # 通知模块
│   ├── system/      # 系统模块（反馈、版本）
│   └── inventory/   # 出入库
├── utils/           # 工具函数
└── tests.py         # 测试
```

## 关键规范

### API 路由

- App 端：`/api/v1/*`
- 管理端：`/api/admin/*`

### 响应格式

```python
from utils.response import success, error
from utils.exceptions import ErrorCode

return success(data={...})
return error(ErrorCode.DEVICE_NOT_FOUND)
```

### 认证

- `AppJWTAuthentication` - App 用户
- `AdminJWTAuthentication` - 管理员
- **两套认证完全隔离，Token 不互通**

### 错误码范围

| 范围 | 模块 |
|------|------|
| 0 | 成功 |
| 1-99 | 通用 |
| 100-199 | 用户 |
| 200-299 | 设备 |
| 300-399 | 智能体 |
| 400-499 | 批次 |
| 500-599 | 管理员 |
| 600-699 | 故事 |
| 700-799 | 音乐 |
| 800-899 | 通知 |
| 900-999 | 系统 |

## 常用命令

```bash
# 运行测试
cd rtc_backend && python manage.py test

# 生成迁移
python manage.py makemigrations

# 运行开发服务器
python manage.py runserver

# 查看 API 文档
# http://localhost:8000/api/docs/
```

## 开发规范

1. 新增 API 必须添加对应测试用例
2. 错误码按模块范围分配
3. 使用 `utils/response.py` 统一响应
4. 复杂业务逻辑放入 `services.py`

### Swagger 文档分组规范（必须遵守）

每个 ViewSet **必须**使用 `@extend_schema(tags=['标签名'])` 装饰器标注所属模块，确保 Swagger 文档按模块分组展示。

```python
from drf_spectacular.utils import extend_schema

@extend_schema(tags=['模块名'])
class MyViewSet(viewsets.ViewSet):
    ...
```

**标签映射表**（新增 ViewSet 时按此表选择 tag）：

| 模块 | tag 名称 | 适用 ViewSet |
|------|---------|-------------|
| App 认证 | `认证` | AuthViewSet |
| App 用户 | `用户` | UserViewSet |
| 设备 | `设备` | DeviceViewSet |
| 智能体 | `智能体` | SpiritViewSet |
| 故事 | `故事` | StoryViewSet, ShelfViewSet |
| 音乐 | `音乐` | MusicViewSet |
| 通知 | `通知` | NotificationViewSet |
| 系统 | `系统` | FeedbackViewSet, VersionViewSet |
| 管理员认证 | `管理员-认证` | AdminAuthViewSet, AdminProfileViewSet |
| 管理员用户管理 | `管理员-用户管理` | AdminUserManageViewSet (users) |
| 管理员账号管理 | `管理员-账号管理` | AdminUserManageViewSet (admins) |
| 管理员库存 | `管理员-库存` | DeviceTypeViewSet, DeviceBatchViewSet |

**新增模块时**：
1. 在 `config/settings.py` 的 `SPECTACULAR_SETTINGS['TAGS']` 中添加新标签
2. 在 ViewSet 类上添加 `@extend_schema(tags=['新标签'])` 装饰器

## 参考

完整技术规范请使用 `/rtc-spec` 命令查看。