yu-zhi-ran/platform/API_REQUIREMENTS.md

# 宇之然内容创作平台 - API 需求清单

## 🔐 认证相关

### 1. 用户登录
```http
POST /api/auth/login
Content-Type: application/json

{
  "username": string,
  "password": string
}

Response:
{
  "token": string,        // JWT token
  "role": string,       // "admin"
  "user": {
    "id": number,
    "username": string,
    "role": string,
    "created_at": string
  }
}
```

### 2. 获取当前用户信息
```http
GET /api/auth/me
Authorization: Bearer <token>

Response:
{
  "id": number,
  "username": string,
  "role": string,
  "created_at": string
}
```

## 📊 系统状态

### 3. 获取系统概览状态
```http
GET /api/system/status
Authorization: Bearer <token>

Response:
{
  "total_topics": number,
  "today_articles": number,
  "topics_by_status": {
    "待处理": number,
    "待审查": number,
    "待发布": number,
    "已发布": number
  },
  "generated_count": number,
  "published_count": number
}
```

### 4. 获取流水线状态
```http
GET /api/system/pipeline/status
Authorization: Bearer <token>

Response:
{
  "status_distribution": {
    "待处理": number,
    "待审查": number,
    "待发布": number
  },
  "topics_count": number,
  "pipeline_modules": {
    "creator": {
      "exists": boolean,
      "has_error": boolean,
      "last_run": string,
      "error": string
    },
    "collector": {
      "exists": boolean,
      "has_error": boolean,
      "last_run": string,
      "error": string
    }
  }
}
```

## 📝 选题管理

### 5. 获取选题列表（支持筛选）
```http
GET /api/topics?status=&page=1&size=20
Authorization: Bearer <token>

Response:
[
  {
    "id": number,
    "title": string,
    "field": string,
    "priority_score": number,
    "status": string,           // "待处理" | "待审查" | "待发布" | "已发布"
    "compliance_score": number,
    "created_at": string,       // ISO 8601
    "updated_at": string,       // ISO 8601
    "generated_at": string,     // ISO 8601 (可为空)
    "published_at": string,     // ISO 8601 (可为空)
    "published_urls": object    // { platform: url }
  }
]
```

### 6. 批量创建选题
```http
POST /api/system/generate/run
Authorization: Bearer <token>
Content-Type: application/json

{
  "topic_ids": [number]   // 可选，如果为空则处理所有待处理选题
}

Response:
{
  "result": {
    "ok": true,
    "count": number
  }
}
```

### 7. 批量优化选题
```http
POST /api/system/optimize/run
Authorization: Bearer <token>
Content-Type: application/json

{
  "topic_ids": [number]
}

Response:
{
  "summary": {
    "passed_auto": number,
    "need_manual": number,
    "total": number
  }
}
```

### 8. 单个选题操作（创建/优化）
```http
POST /api/system/generate/run?topic_id=123
Authorization: Bearer <token>

POST /api/system/optimize/run
Authorization: Bearer <token>
Content-Type: application/json

{
  "topic_ids": [123]
}
```

### 9. 发布选题
```http
POST /api/publishing/create
Authorization: Bearer <token>
Content-Type: application/json

{
  "topic_id": number
}

Response:
{
  "success": true,
  "urls": {
    "zhihu": "https://...",
    "wechat": "https://...",
    "xiaohongshu": "https://..."
  }
}
```

## 📄 预览功能

### 10. 获取文章预览
```http
GET /api/articles/{topic_id}/preview?platform=zhihu
Authorization: Bearer <token>

Response:
{
  "html": string          // 完整的HTML内容
}
```

## 📜 日志系统

### 11. 获取日志内容
```http
GET /api/system/logs/{date}?log_type=creator
Authorization: Bearer <token>

Response:
{
  "content": [
    "2026-04-26 10:00:00 INFO 创建选题：人工智能发展趋势",
    "2026-04-26 10:05:00 INFO 选题状态更新为：待审查",
    "..."
  ]
}
```

## 👥 用户管理（管理员）

### 12. 获取用户列表
```http
GET /api/admin/users
Authorization: Bearer <token>

Response:
[
  {
    "id": number,
    "username": string,
    "role": string,
    "created_at": string,
    "last_login": string
  }
]
```

### 13. 创建用户
```http
POST /api/admin/users
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": string,
  "password": string,
  "role": string               // "admin" or "user"
}

Response:
{
  "id": number,
  "username": string,
  "role": string,
  "created_at": string
}
```

### 14. 删除用户
```http
DELETE /api/admin/users/{id}
Authorization: Bearer <token>

Response:
{ "success": true }
```

## 🛡️ 中间件要求

1. **JWT验证中间件** - 所有受保护路由都需要
2. **权限检查中间件** - 用户管理接口只允许 admin
3. **CORS配置** - 允许前端域名跨域请求
4. **错误处理** - 统一错误格式和HTTP状态码

## 📈 性能考虑

1. **分页** - topics 列表支持 page/size 参数
2. **缓存** - system/status 可设置缓存（5秒）
3. **并发控制** - generate/optimize 接口需防止重复提交

## 🔒 安全要求

1. **密码加密** - 使用 bcrypt 存储密码
2. **JWT过期** - token 有效期 7天
3. **输入验证** - 所有用户输入需验证
4. **SQL注入防护** - 使用 ORM 或参数化查询
5. **XSS防护** - HTML输出需转义

---

**优先级**：高（必须实现）
**完成时间**：3-5个工作日
**技术栈建议**：FastAPI + SQLAlchemy + JWT