ljwx-shiti/docs/API.md

WrongBook API 文档

基础信息

• Base URL: http://localhost:8000/api/v1
• 认证方式: JWT Bearer Token
• 响应格式: JSON

统一响应格式

所有 API 响应遵循统一格式：

{
  "code": 0,
  "data": {},
  "message": "success"
}

错误响应：

{
  "code": 错误码,
  "data": null,
  "message": "错误描述"
}

错误码

错误码	说明
0	成功
1001	参数错误
1002	认证失败
1003	权限不足
1004	资源不存在
1005	资源已存在
2001	数据库错误
2002	外部服务错误
9999	未知错误

认证

注册

POST /auth/register
Content-Type: application/json

{
  "username": "user123",
  "password": "password123",
  "nickname": "昵称"
}

响应：

{
  "code": 0,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "user": {
      "id": "uuid",
      "username": "user123",
      "nickname": "昵称",
      "created_at": "2024-01-01T00:00:00Z"
    }
  },
  "message": "success"
}

登录

POST /auth/login
Content-Type: application/json

{
  "username": "user123",
  "password": "password123"
}

响应格式同注册。

刷新 Token

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJ..."
}

题目管理

创建题目

POST /questions/
Authorization: Bearer <token>
Content-Type: multipart/form-data

image: <file>
subject: 数学
difficulty: 中等

响应：

{
  "code": 0,
  "data": {
    "id": "uuid",
    "user_id": "uuid",
    "subject": "数学",
    "difficulty": "中等",
    "original_image_url": "https://...",
    "status": "processing",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "message": "success"
}

获取题目列表

GET /questions/?page=1&page_size=20&subject=数学&difficulty=中等
Authorization: Bearer <token>

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "uuid",
        "subject": "数学",
        "difficulty": "中等",
        "knowledge_points": "函数,导数",
        "review_count": 3,
        "last_reviewed_at": "2024-01-01T00:00:00Z",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  },
  "message": "success"
}

获取题目详情

GET /questions/{id}
Authorization: Bearer <token>

响应：

{
  "code": 0,
  "data": {
    "id": "uuid",
    "user_id": "uuid",
    "subject": "数学",
    "difficulty": "中等",
    "knowledge_points": "函数,导数",
    "original_image_url": "https://...",
    "clean_image_url": "https://...",
    "recognized_text": "题目文本...",
    "ai_analysis": "这是一道关于...",
    "user_notes": "我的笔记...",
    "review_count": 3,
    "last_reviewed_at": "2024-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "message": "success"
}

更新题目

PUT /questions/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "subject": "物理",
  "difficulty": "困难",
  "user_notes": "更新的笔记"
}

删除题目

DELETE /questions/{id}
Authorization: Bearer <token>

搜索题目

GET /questions/search?q=导数&page=1&page_size=20
Authorization: Bearer <token>

响应格式同获取题目列表。

记录复习

POST /questions/{id}/review
Authorization: Bearer <token>

响应：

{
  "code": 0,
  "data": {
    "review_count": 4,
    "last_reviewed_at": "2024-01-01T00:00:00Z"
  },
  "message": "success"
}

WebSocket

连接

ws://localhost:8000/ws?token=<jwt_token>

消息格式

客户端发送：

{
  "type": "ping"
}

服务端响应：

{
  "type": "pong",
  "timestamp": "2024-01-01T00:00:00Z"
}

题目处理进度推送：

{
  "type": "question_progress",
  "data": {
    "question_id": "uuid",
    "status": "processing",
    "progress": 50,
    "message": "正在识别题目..."
  }
}

题目处理完成：

{
  "type": "question_completed",
  "data": {
    "question_id": "uuid",
    "status": "completed"
  }
}

限流

• 认证端点: 5 次/分钟
• 题目创建: 10 次/分钟
• 其他端点: 60 次/分钟

分页

所有列表接口支持分页参数：

• page: 页码，从 1 开始
• page_size: 每页数量，默认 20，最大 100

排序

部分接口支持排序参数：

• sort_by: 排序字段
• order: asc 或 desc

示例：

GET /questions/?sort_by=created_at&order=desc

过滤

支持多种过滤参数：

• subject: 科目
• difficulty: 难度
• knowledge_points: 知识点（逗号分隔）
• created_after: 创建时间起始
• created_before: 创建时间结束

示例：

GET /questions/?subject=数学&difficulty=中等&created_after=2024-01-01