5.1 KiB

Raw Permalink Blame History

Screenplay API 路由注册

变更日期：2026-02-03
变更类型：功能集成
影响范围：API 路由层

变更概述

将新实现的 Screenplay（剧本）和 ScreenplayTag（剧本标签）API 路由注册到主应用，使其可通过 HTTP 访问。

变更详情

修改文件

文件：server/app/api/v1/__init__.py

新增导入

from app.api.v1 import (
    # ... 其他导入
    screenplays,        # 新增
    screenplay_tags,    # 新增
    # ... 其他导入
)

新增路由注册

# 剧本 API
api_router.include_router(
    screenplays.router, 
    prefix="/screenplays", 
    tags=["剧本"]
)

# 剧本标签 API
api_router.include_router(
    screenplay_tags.router, 
    prefix="/screenplay-tags", 
    tags=["剧本标签"]
)

API 端点清单

剧本 API（`/api/v1/screenplays`）

方法	完整路径	功能	标签
POST	`/api/v1/screenplays/{screenplay_id}/characters`	创建角色	剧本
GET	`/api/v1/screenplays/{screenplay_id}/characters`	获取角色列表	剧本
POST	`/api/v1/screenplays/{screenplay_id}/locations`	创建场景	剧本
GET	`/api/v1/screenplays/{screenplay_id}/locations`	获取场景列表	剧本
POST	`/api/v1/screenplays/{screenplay_id}/props`	创建道具	剧本
GET	`/api/v1/screenplays/{screenplay_id}/props`	获取道具列表	剧本

剧本标签 API（`/api/v1/screenplay-tags`）

方法	完整路径	功能	标签
POST	`/api/v1/screenplay-tags`	创建标签	剧本标签
GET	`/api/v1/screenplay-tags/element/{element_type}/{element_id}`	获取元素的所有标签	剧本标签
GET	`/api/v1/screenplay-tags/screenplay/{screenplay_id}`	获取剧本的所有标签	剧本标签
PATCH	`/api/v1/screenplay-tags/{tag_id}`	更新标签	剧本标签
DELETE	`/api/v1/screenplay-tags/{tag_id}`	删除标签	剧本标签

OpenAPI 文档

注册后，这些 API 将自动出现在 Swagger UI 文档中：

Swagger UI：http://localhost:8000/docs
ReDoc：http://localhost:8000/redoc

文档中将包含：

完整的请求/响应 Schema
参数说明
示例数据
认证要求

验证步骤

1. 检查语法

# ✅ 已通过
getDiagnostics(["server/app/api/v1/__init__.py"])

2. 启动服务（Docker 容器）

# 重启 FastAPI 应用容器
docker restart jointo-server-app

# 查看日志
docker logs -f jointo-server-app

3. 访问 API 文档

打开浏览器访问：

http://localhost:8000/docs

在 Swagger UI 中应该能看到：

剧本标签组（6 个端点）
剧本标签 标签组（5 个端点）

4. 测试 API 端点

使用 Swagger UI 或 curl 测试：

# 测试创建角色
curl -X POST "http://localhost:8000/api/v1/screenplays/{screenplay_id}/characters" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "张三",
    "description": "男主角",
    "role_type": "main",
    "order_index": 1
  }'

# 测试获取角色列表
curl -X GET "http://localhost:8000/api/v1/screenplays/{screenplay_id}/characters?page=1&page_size=20" \
  -H "Authorization: Bearer {token}"

依赖关系

前置条件

✅ ScreenplayService 已实现
✅ ScreenplayTagService 已实现
✅ Schema 层已定义
✅ API 路由已实现
✅ 数据库表已创建（screenplays, screenplay_characters, screenplay_locations, screenplay_props, screenplay_element_tags）

后续依赖

这些 API 将被以下模块使用：

前端剧本管理界面
AI 解析剧本功能
分镜创建功能（需要关联剧本元素）

注意事项

认证要求

所有端点都需要认证：

使用 get_current_user 依赖注入
需要有效的 JWT Token
需要项目访问权限

权限检查

创建操作：需要 editor 权限
查询操作：需要 viewer 权限
更新/删除操作：需要 editor 权限

错误处理

API 会返回标准的错误响应：

400 Bad Request - 请求参数错误
401 Unauthorized - 未认证
403 Forbidden - 权限不足
404 Not Found - 资源不存在
500 Internal Server Error - 服务器错误

下一步

启动服务验证：重启 Docker 容器，访问 Swagger UI 验证端点
编写集成测试：测试完整的 API 调用流程
前端集成：前端团队可以开始调用这些 API
性能测试：测试大量数据下的查询性能

变更日期：2026-02-03
变更作者：System
审核状态：待验证
验证方式：启动服务 + Swagger UI 检查

5.1 KiB Raw Permalink Blame History