晴发文

📡 API接口地址

服务器地址：http://your-server:8000

🔑 1. 获取公钥

客户端首先需要获取服务器的RSA公钥用于加密：

GET /api/race/public_key

返回：
{
    "public_key": "-----BEGIN RSA PUBLIC KEY-----\\n...\\n-----END RSA PUBLIC KEY-----"
}

📋 2. 获取赛文列表

获取所有启用的赛文（返回数据已加密）：

GET /api/race/list

返回（加密）：
{
    "encrypted_data": "base64加密字符串"
}

解密后：
{
    "success": true,
    "races": [
        {
            "id": 1,
            "name": "每日赛文",
            "difficulty_group": 3,
            "allow_resubmit": false
        }
    ]
}

📝 3. 获取今日赛文

GET /api/race/daily_article?race_id={race_id}&user_id={user_id}

参数：
- race_id: 赛文ID（必填）
- user_id: 用户ID（必填）

返回（加密）包含：
- 赛文配置信息
- 今日文章内容
- 是否已提交
- 最佳成绩（如已提交）

📤 4. 提交成绩

POST /api/race/submit

请求体（加密前）：
{
    "race_id": 1,
    "user_id": 1,
    "username": "用户名",
    "article_id": 1,
    "date": "2024-01-01",
    "speed": 120.5,
    "time_cost": 248500,
    "char_count": 500,
    "keystroke": 150.0,
    "code_length": 2.5,
    "backspace_count": 10,
    "key_count": 1250,
    "key_accuracy": 95.5,
    "word_rate": 60.0,
    "input_method": "搜狗拼音",
    "signature": "数据签名"
}

⚠️ 所有字段均为必填，signature需要使用特定算法生成

📜 5. 获取历史文章列表

GET /api/race/articles?race_id={race_id}&page={page}&page_size={page_size}

参数：
- race_id: 赛文ID（必填）
- page: 页码，从1开始（可选，默认1）
- page_size: 每页数量（可选，默认30，最大100）

返回：
{
    "success": true,
    "msg": "获取成功",
    "articles": [
        {
            "id": 1,
            "date": "2024-01-01",
            "difficulty": 2.8,
            "difficulty_level": "难",
            "book_name": "红楼梦",
            "char_count": 500,
            "created_at": "2024-01-01 00:00:00"
        }
    ],
    "total": 100,  // 总文章数
    "page": 1,     // 当前页
    "page_size": 30,
    "total_pages": 4  // 总页数
}

⚠️ 注意：此接口仅限本机或内网访问

🏆 6. 获取排行榜

GET /api/race/leaderboard?race_id={race_id}&date_str={date}&limit={limit}

参数：
- race_id: 赛文ID（必填）
- date_str: 日期（可选，格式YYYY-MM-DD，不传则为今天）
- limit: 返回记录数（可选，默认100）

返回（加密）：
{
    "encrypted_data": "base64加密字符串"
}

解密后：
{
    "success": true,
    "msg": "获取成功",
    "date": "2024-01-01",
    "leaderboard": [
        {
            "username": "用户名",
            "speed": 120.5,
            "time_cost": 248500,
            "char_count": 500,
            "keystroke": 150.0,
            "code_length": 2.5,
            "backspace_count": 10,
            "key_count": 1250,
            "key_accuracy": 95.5,
            "word_rate": 60.0,
            "input_method": "搜狗拼音",
            "submit_time": "2024-01-01 12:00:00"
        }
    ]
}

说明：
- 排行榜按速度(speed)降序排列
- 如果速度相同，则按键准(key_accuracy)降序排列
- 每个用户只显示当天的最佳成绩

📊 7. 获取用户历史成绩

GET /api/race/history?race_id={race_id}&username={username}&limit={limit}

参数：
- race_id: 赛文ID（必填）
- username: 用户名（必填）
- limit: 返回记录数（可选，默认30）

返回（加密）包含用户在该赛文的历史成绩数据，用于绘制成绩曲线

🔒 加密说明

• 使用 RSA-2048 + AES-256 混合加密
• 客户端用服务器公钥加密数据
• 服务器返回的数据也是加密的
• 需要安装 pycryptodome 库

完整文档请查看项目中的 赛文API文档.md