Django 后端 API

本文档页只作为 Django 后端 API 的入口。接口路径、请求参数、响应结构、认证方案和 schema 细节以自动生成的 OpenAPI 文档为准，不再在 docs/ 中维护逐接口手写副本。

自动文档入口

本地开发环境启动 Django 后端后，可访问：

用途	地址
Swagger UI	http://localhost:8000/api/docs/
Redoc	http://localhost:8000/api/redoc/
OpenAPI schema	http://localhost:8000/api/schema/

当前后端只在 DJANGO_DEBUG=true 时暴露这些文档路由。生产或测试环境是否开放文档入口，应由部署策略决定；如果通过反向代理发布，请使用对应环境的同源域名访问上述路径。

使用约定

• 业务 API 的公共前缀是 /api/v1/。
• Web 管理端主要使用 CookieJWTAuthentication，也支持 Authorization: Bearer <token>。
• 班牌设备接口使用独立的设备 Bearer token。
• 批量导入等长任务接口返回 task_id，任务状态通过 /api/v1/tasks/{id}/ 查询。
• 具体字段、枚举、分页参数、上传格式和响应 schema 请以 Swagger UI 或 Redoc 展示为准。

维护边界

docs/ 继续维护架构、业务流程、权限模型、部署和联调说明。接口事实由后端 serializer、view 和 drf-spectacular 注解生成。

新增或修改 API 时，应优先更新代码中的 schema 信息，并确保：

DJANGO_DEBUG=true ../.venv/bin/python manage.py spectacular --validate --file /tmp/myucspace-openapi.yaml

能够生成可用的 OpenAPI 文件。生成过程中的 error 必须修复；warning 应按影响范围逐步清理。