88b8f023f4
Some checks failed
Build and Deploy Backend / build-and-deploy (push) Failing after 1m36s
130 lines
3.4 KiB
Markdown
130 lines
3.4 KiB
Markdown
# 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` 命令查看。
|