# 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}
```

**请求体结构**:
```json
{
  "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):
```json
{
  "success": true,
  "data": {
    "contentId": "cnt_abc123",
    "status": "published",
    "publishedAt": "2026-03-27T10:00:00Z",
    "url": "https://content.example.com/cnt_abc123"
  }
}
```

**错误响应** (4xx/5xx):
```json
{
  "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 示例

```python
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 示例

```bash
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. 关键知识点总结

1. **接口设计**: RESTful API、JSON格式、HTTP方法正确使用
2. **验证机制**: JSON Schema验证、业务规则校验、安全检查
3. **错误处理**: 状态码识别、重试策略、日志记录
4. **状态管理**: 内容状态流转、版本控制、发布确认
5. **最佳实践**: idempotency、重试机制、熔断保护

---

## 参考资料

- [RFC 7231 - HTTP/1.1 Semantics and Content](https://tools.ietf.org/html/rfc7231)
- [JSON Schema Specification](https://json-schema.org/)
- [REST API Design Best Practices](https://restfulapi.net/)