🔧 API接口文档

MC部落日志分析器 - WebAPI v2.0.0

📋 接口概览

所有API基于RESTful设计，使用JSON格式交互。Base URL: https://mclans.sakurain.net

接口名称 Method 路径 描述
文件上传 POST /api/upload 上传日志文件
启动分析 POST /api/analyze/{task_id} 启动分析任务
查询状态 GET /api/status/{task_id} 获取任务状态
下载文件 GET /api/download/{filename} 下载结果文件
预览文件 GET /api/preview/{filename} 在线预览图片/PDF
WebSocket WS /ws/progress 实时进度推送

🔑 认证说明

当前版本API为内部使用，无需认证。后续版本将添加API Key机制。

📤 1. 文件上传

POST /api/upload

Content-Type: multipart/form-data

请求参数
参数 类型 必填 说明
files File[] 是 日志文件数组
响应示例
{
    "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "uploaded_files": [
        {
            "original_name": "pvp_logs_2025-01-10.log",
            "safe_name": "a1b2c3d4_pvp_logs_2025-01-10.log",
            "path": "/tmp/uploads/a1b2c3d4_pvp_logs_2025-01-10.log",
            "size": 1048576
        }
    ],
    "file_count": 1
}

🚀 2. 启动分析

POST /api/analyze/{task_id}

Content-Type: application/x-www-form-urlencoded

表单参数
参数 类型 可选值 说明
mode string pvp, shop 分析模式
output_format string xlsx, pdf, png, json 输出格式
响应示例
{
    "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "任务已提交"
}

📊 3. 查询状态

GET /api/status/{task_id}

响应示例
{
    "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "mode": "pvp",
    "format": "xlsx",
    "progress": "100% - 分析完成",
    "result_path": "/tmp/results/PvP_Report_20250110_143000.xlsx",
    "start_time": "1736509800.123"
}
状态说明
  • processing：正在处理中
  • completed：处理完成
  • failed：处理失败

📥 4. 下载文件

GET /api/download/{filename}

安全下载分析结果文件，自动处理路径遍历防护。

示例
GET /api/download/PvP_Report_20250110_143000.xlsx

返回：文件二进制流（Content-Disposition: attachment）

👁️ 5. 预览文件

GET /api/preview/{filename}

在线预览图片或PDF文件（Content-Disposition: inline）

支持格式
.png .jpg .jpeg .pdf

🔌 6. WebSocket实时通信

WS /ws/progress

连接后可接收实时进度更新。

连接示例
const ws = new WebSocket('ws://mclans.sakurain.net/ws/progress');
ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log(`任务 ${data.task_id}: ${data.progress}`);
};
消息格式
{
    "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "progress": "60% - 正在生成报告..."
}

📦 错误处理

所有接口返回HTTP标准状态码，错误时返回JSON格式错误信息：

{
    "detail": "错误描述信息"
}
常见状态码

📚 代码示例

Python调用示例 
import requests
import time

# 1. 上传文件
files = {'files': open('pvp.log', 'rb')}
upload_res = requests.post('https://mclans.sakurain.net/api/upload', files=files)
task_id = upload_res.json()['task_id']

# 2. 启动分析
data = {'mode': 'pvp', 'output_format': 'xlsx'}
requests.post(f'https://mclans.sakurain.net/api/analyze/{task_id}', data=data)

# 3. 轮询状态
while True:
    status = requests.get(f'https://mclans.sakurain.net/api/status/{task_id}').json()
    print(status['progress'])
    if status['status'] == 'completed':
        break
    time.sleep(1)

# 4. 下载结果
response = requests.get(f'https://mclans.sakurain.net/api/download/{status["result_path"].split("/")[-1]}')
open('result.xlsx', 'wb').write(response.content)
JavaScript调用示例 
// 上传文件
const formData = new FormData();
formData.append('files', fileInput.files[0]);

const uploadRes = await fetch('/api/upload', {
    method: 'POST',
    body: formData
});
const { task_id } = await uploadRes.json();

// 启动分析
await fetch(`/api/analyze/${task_id}`, {
    method: 'POST',
    body: new FormData().append('mode', 'pvp').append('output_format', 'xlsx')
});

// WebSocket监听进度
const ws = new WebSocket(`wss://mclans.sakurain.net/ws/progress`);
ws.onmessage = e => {
    const data = JSON.parse(e.data);
    if(data.task_id === task_id) {
        console.log(data.progress);
    }
};