rtc_backend/CLAUDE.md

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

响应格式

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	系统

常用命令

# 运行测试
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 文档按模块分组展示。

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 命令查看。