# Screenplay API 路由注册

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

---

## 变更概述

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

---

## 变更详情

### 修改文件

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

### 新增导入

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

### 新增路由注册

```python
# 剧本 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. 检查语法

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

### 2. 启动服务（Docker 容器）

```bash
# 重启 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 测试：

```bash
# 测试创建角色
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` - 服务器错误

---

## 相关文档

- [Screenplay Services 实现](./2026-02-03-screenplay-services-implementation.md)
- [Screenplay 实现总结](./2026-02-03-screenplay-implementation-summary.md)
- [剧本管理服务需求](../../requirements/backend/04-services/project/screenplay-service.md)
- [剧本标签管理服务需求](../../requirements/backend/04-services/project/screenplay-tag-service.md)

---

## 下一步

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

---

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