knowhow_raw.md
5.92 KB
Publisher 内容上传技能 - 调研知识库
1. 任务概述
输入
- 通过审核的剧本（已审批、可发布状态）
输出
- 将剧本上传至生产端的内容发布系统
- 返回上传结果确认或错误处理
目标平台特性
- 模拟内容发布系统（CMS）
- 支持 REST API 接口
- 包含格式验证、元数据校验、状态确认机制
2. 数据源清单
2.1 内容管理系统（CMS）通用规范
| 数据源 | 描述 | 权威性 |
|---|---|---|
| REST API 设计最佳实践 | OpenAPI规范、RESTful接口设计原则 | 高 |
| JSON Schema 验证规范 | 结构化数据验证标准 | 高 |
| HTTP 状态码标准 | RFC 7231 定义的标准状态码 | 高 |
2.2 内容上传接口规范
| 数据源 | 描述 | 类型 |
|---|---|---|
| 文件上传 API | multipart/form-data 或 base64 编码 | 接口规范 |
| 元数据 API | 剧本标题、简介、标签、分类 | 接口规范 |
| 验证规则 API | 格式校验、敏感词检测、版权检查 | 接口规范 |
2.3 模拟内容发布系统架构
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ 输入 │────▶│ 发布系统 │────▶│ 输出确认 │
│ (剧本JSON) │ │ (模拟CMS) │ │ (状态+结果) │
└─────────────┘ └──────────────┘ └─────────────┘
│
┌──────┴──────┐
│ 验证层 │
│ - 格式验证 │
│ - 内容审核 │
│ - 元数据校验│
└─────────────┘
3. 接口规范
3.1 上传接口设计
端点: POST /api/v1/contents
请求头:
Content-Type: application/json
Authorization: Bearer {token}
请求体结构:
{
"title": "剧本标题",
"content": "剧本正文",
"metadata": {
"category": "剧情",
"tags": ["爱情", "都市"],
"author": "作者名",
"copyright": "版权声明",
"wordCount": 5000
},
"publishTime": "2026-03-27T10:00:00Z",
"status": "draft|pending|published"
}
3.2 验证规则
| 字段 | 必填 | 格式要求 | 限制 |
|---|---|---|---|
| title | 是 | 字符串 | 1-100字符 |
| content | 是 | 字符串 | 100-50000字符 |
| category | 是 | 字符串 | 预定义枚举 |
| tags | 否 | 数组 | 最多5个 |
| author | 是 | 字符串 | 1-50字符 |
| copyright | 否 | 字符串 | 0-200字符 |
3.3 响应格式
成功响应 (201 Created):
{
"success": true,
"data": {
"contentId": "cnt_abc123",
"status": "published",
"publishedAt": "2026-03-27T10:00:00Z",
"url": "https://content.example.com/cnt_abc123"
}
}
错误响应 (4xx/5xx):
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "标题不能为空",
"details": [
{"field": "title", "reason": "required"}
]
}
}
4. 常见错误处理
4.1 客户端错误 (4xx)
| 状态码 | 错误类型 | 处理策略 |
|---|---|---|
| 400 | 请求格式错误 | 修正JSON格式后重试 |
| 401 | 认证失败 | 检查token有效性 |
| 403 | 权限不足 | 检查上传权限 |
| 404 | 资源不存在 | 确认目标端点 |
| 422 | 验证失败 | 检查字段有效性 |
| 429 | 请求过于频繁 | 指数退避重试 |
4.2 服务器错误 (5xx)
| 状态码 | 错误类型 | 处理策略 |
|---|---|---|
| 500 | 服务器内部错误 | 记录日志，联系管理员 |
| 502 | 网关错误 | 等待后重试 |
| 503 | 服务不可用 | 指数退避重试 |
| 504 | 超时 | 增加超时时间 |
5. 验证规则详解
5.1 内容格式验证
- 标题验证: 非空、长度限制、非法字符检查
- 正文验证: 最小/最大长度、编码格式
- 元数据验证: 必填字段、枚举值范围
5.2 内容安全检查
- 敏感词过滤: 关键词黑名单匹配
- 版权检查: 原创声明或授权证明
- 质量检查: 错别字、格式规范性
5.3 业务规则
- 重复检测: 相同内容不能重复上传
- 状态流转: draft → pending → published
- 版本管理: 每次上传生成新版本
6. API 调用示例
6.1 Python requests 示例
import requests
import json
def upload_script(token, script_data):
url = "http://localhost:3000/api/v1/contents"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {token}"
}
response = requests.post(url, json=script_data, headers=headers)
if response.status_code == 201:
return response.json()
else:
raise Exception(f"Upload failed: {response.text}")
6.2 curl 示例
curl -X POST http://localhost:3000/api/v1/contents \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_token" \
-d '{
"title": "测试剧本",
"content": "剧本正文内容...",
"metadata": {
"category": "剧情",
"tags": ["都市"],
"author": "作者A"
}
}'
7. 关键知识点总结
- 接口设计: RESTful API、JSON格式、HTTP方法正确使用
- 验证机制: JSON Schema验证、业务规则校验、安全检查
- 错误处理: 状态码识别、重试策略、日志记录
- 状态管理: 内容状态流转、版本控制、发布确认
- 最佳实践: idempotency、重试机制、熔断保护