解析任务API接口文档

本文档提供了解析任务相关API接口的详细使用说明，包括创建解析任务、查询任务列表和获取任务详情的完整接口文档。

基础信息

服务器地址:
- 开发环境: http://localhost:5500
- 生产环境: http://192.168.3.143
API基础路径: /api/parse
内容类型: application/json
字符编码: UTF-8

1. 新增解析任务接口

接口概述

创建新的解析任务，支持多种文件类型上传到MinIO存储。

基本信息

URL: /api/parse/add-parse-task
HTTP方法: POST
内容类型: multipart/form-data

请求参数

参数名	类型	必填	说明
`task_type`	String	是	任务类型，可选值：`名片`、`简历`、`新任命`、`招聘`、`杂项`
`files`	File[]	否*	文件数组（招聘类型不需要文件）
`created_by`	String	否	创建者名称，默认为`api_user`

*注：除招聘类型外，其他类型必须上传文件

任务类型说明

任务类型	支持文件格式	存储目录	说明
名片	JPG, PNG	`talent_photos/`	名片图片解析
简历	PDF	`resume_files/`	简历文档解析
新任命	MD	`appointment_files/`	任命文档解析
招聘	无需文件	无	数据库记录处理
杂项	任意格式	`misc_files/`	其他类型文件

请求示例

JavaScript/AJAX示例

// 创建FormData对象
const formData = new FormData();

// 添加任务类型
formData.append('task_type', '名片');

// 添加文件（多文件上传）
const fileInput = document.getElementById('fileInput');
for (let i = 0; i < fileInput.files.length; i++) {
    formData.append('files', fileInput.files[i]);
}

// 添加创建者（可选）
formData.append('created_by', 'frontend_user');

// 发送请求
fetch('/api/parse/add-parse-task', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => {
    console.log('上传成功:', data);
})
.catch(error => {
    console.error('上传失败:', error);
});

jQuery示例

$('#uploadForm').on('submit', function(e) {
    e.preventDefault();
    
    const formData = new FormData();
    formData.append('task_type', $('#taskType').val());
    
    // 添加多个文件
    const files = $('#fileInput')[0].files;
    for (let i = 0; i < files.length; i++) {
        formData.append('files', files[i]);
    }
    
    formData.append('created_by', 'jquery_user');
    
    $.ajax({
        url: '/api/parse/add-parse-task',
        type: 'POST',
        data: formData,
        processData: false,
        contentType: false,
        success: function(response) {
            console.log('任务创建成功:', response);
        },
        error: function(xhr, status, error) {
            console.error('任务创建失败:', error);
        }
    });
});

cURL示例

# 上传名片文件
curl -X POST "http://localhost:5500/api/parse/add-parse-task" \
  -F "task_type=名片" \
  -F "files=@/path/to/business_card1.jpg" \
  -F "files=@/path/to/business_card2.png" \
  -F "created_by=test_user"

# 创建招聘任务（无需文件）
curl -X POST "http://localhost:5500/api/parse/add-parse-task" \
  -F "task_type=招聘" \
  -F "created_by=hr_user"

响应格式

成功响应 (HTTP 200)

{
    "success": true,
    "message": "解析任务创建成功，所有文件上传完成",
    "data": {
        "task_info": {
            "id": 123,
            "task_name": "parse_task_20250115_a1b2c3d4",
            "task_status": "待解析",
            "task_type": "名片",
            "task_source": "{\"minio_paths_json\":[\"http://192.168.3.143:9000/dataops-bucket/talent_photos/talent_photo_20250115_143012_a1b2c3d4.jpg\"],\"upload_time\":\"2025-01-15T14:30:25.123456\"}",
            "collection_count": 2,
            "parse_count": 0,
            "parse_result": null,
            "created_by": "api_user",
            "updated_by": "api_user",
            "created_at": "2025-01-15T14:30:25.123456",
            "updated_at": "2025-01-15T14:30:25.123456"
        },
        "upload_summary": {
            "task_type": "名片",
            "total_files": 2,
            "uploaded_count": 2,
            "failed_count": 0,
            "uploaded_files": [
                {
                    "original_filename": "business_card1.jpg",
                    "minio_path": "http://192.168.3.143:9000/dataops-bucket/talent_photos/talent_photo_20250115_143012_a1b2c3d4.jpg",
                    "relative_path": "talent_photos/talent_photo_20250115_143012_a1b2c3d4.jpg",
                    "file_size": 256000
                }
            ],
            "failed_uploads": []
        }
    }
}

部分成功响应 (HTTP 206)

{
    "success": true,
    "message": "解析任务创建成功，但有1个文件上传失败",
    "data": {
        "task_info": { /* 任务信息 */ },
        "upload_summary": {
            "task_type": "名片",
            "total_files": 2,
            "uploaded_count": 1,
            "failed_count": 1,
            "uploaded_files": [ /* 成功上传的文件 */ ],
            "failed_uploads": [
                {
                    "filename": "broken_file.jpg",
                    "error": "文件损坏无法上传"
                }
            ]
        }
    }
}

错误响应 (HTTP 400)

{
    "success": false,
    "message": "task_type参数必须是以下值之一：名片、简历、新任命、招聘、杂项",
    "data": null
}

状态码说明

状态码	说明
200	所有文件上传成功，任务创建成功
206	部分文件上传成功，任务创建成功
400	请求参数错误（缺少必填参数、文件格式不支持等）
500	服务器内部错误

2. 获取解析任务列表接口

接口概述

分页查询解析任务列表，支持按任务类型和状态过滤。

基本信息

URL: /api/parse/get-parse-tasks
HTTP方法: GET
内容类型: application/json

请求参数

参数名	类型	必填	默认值	说明
`page`	Integer	否	1	页码，从1开始
`per_page`	Integer	否	10	每页记录数，最大100
`task_type`	String	否	无	任务类型过滤
`task_status`	String	否	无	任务状态过滤

请求示例

JavaScript/Fetch示例

// 基础查询
fetch('/api/parse/get-parse-tasks?page=1&per_page=20')
    .then(response => response.json())
    .then(data => {
        console.log('任务列表:', data);
    });

// 带过滤条件的查询
const params = new URLSearchParams({
    page: 1,
    per_page: 10,
    task_type: '名片',
    task_status: '待解析'
});

fetch(`/api/parse/get-parse-tasks?${params}`)
    .then(response => response.json())
    .then(data => {
        console.log('过滤后的任务列表:', data);
    });

jQuery示例

$.ajax({
    url: '/api/parse/get-parse-tasks',
    type: 'GET',
    data: {
        page: 1,
        per_page: 15,
        task_type: '简历',
        task_status: '解析完成'
    },
    success: function(response) {
        console.log('查询成功:', response);
        // 处理任务列表数据
        if (response.success && response.data.tasks) {
            response.data.tasks.forEach(task => {
                console.log(`任务: ${task.task_name}, 状态: ${task.task_status}`);
            });
        }
    },
    error: function(xhr, status, error) {
        console.error('查询失败:', error);
    }
});

cURL示例

# 基础查询
curl "http://localhost:5500/api/parse/get-parse-tasks?page=1&per_page=10"

# 带过滤条件查询
curl "http://localhost:5500/api/parse/get-parse-tasks?page=1&per_page=20&task_type=名片&task_status=待解析"

响应格式

成功响应 (HTTP 200)

{
    "success": true,
    "message": "获取解析任务列表成功",
    "data": {
        "tasks": [
            {
                "id": 123,
                "task_name": "parse_task_20250115_a1b2c3d4",
                "task_status": "待解析",
                "task_type": "名片",
                "task_source": "{\"minio_paths_json\":[\"http://192.168.3.143:9000/dataops-bucket/talent_photos/file1.jpg\"],\"upload_time\":\"2025-01-15T14:30:25.123456\"}",
                "collection_count": 2,
                "parse_count": 0,
                "parse_result": null,
                "created_by": "api_user",
                "updated_by": "api_user",
                "created_at": "2025-01-15T14:30:25.123456",
                "updated_at": "2025-01-15T14:30:25.123456"
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 10,
            "total": 50,
            "pages": 5,
            "has_next": true,
            "has_prev": false
        }
    }
}

错误响应 (HTTP 400)

{
    "success": false,
    "message": "分页参数错误",
    "data": null
}

状态码说明

状态码	说明
200	查询成功
400	请求参数错误
500	服务器内部错误

3. 获取解析任务详情接口

接口概述

根据任务名称获取指定解析任务的详细信息。

基本信息

URL: /api/parse/get-parse-task-detail
HTTP方法: GET
内容类型: application/json

请求参数

参数名	类型	必填	说明
`task_name`	String	是	任务名称

请求示例

JavaScript/Fetch示例

// 获取任务详情
const taskName = 'parse_task_20250115_a1b2c3d4';
fetch(`/api/parse/get-parse-task-detail?task_name=${encodeURIComponent(taskName)}`)
    .then(response => response.json())
    .then(data => {
        if (data.success) {
            console.log('任务详情:', data.data);
            // 解析任务来源信息
            const taskSource = JSON.parse(data.data.task_source);
            console.log('MinIO文件路径:', taskSource.minio_paths_json);
        }
    });

jQuery示例

function getTaskDetail(taskName) {
    $.ajax({
        url: '/api/parse/get-parse-task-detail',
        type: 'GET',
        data: { task_name: taskName },
        success: function(response) {
            if (response.success) {
                const task = response.data;
                console.log('任务详情:', task);
                
                // 解析文件路径
                const taskSource = JSON.parse(task.task_source);
                const filePaths = taskSource.minio_paths_json;
                
                // 显示文件列表
                filePaths.forEach((path, index) => {
                    console.log(`文件${index + 1}: ${path}`);
                });
            }
        },
        error: function(xhr, status, error) {
            console.error('获取任务详情失败:', error);
        }
    });
}

// 使用示例
getTaskDetail('parse_task_20250115_a1b2c3d4');

cURL示例

# 获取任务详情
curl "http://localhost:5500/api/parse/get-parse-task-detail?task_name=parse_task_20250115_a1b2c3d4"

响应格式

成功响应 (HTTP 200)

{
    "success": true,
    "message": "成功获取任务 parse_task_20250115_a1b2c3d4 的详细信息",
    "data": {
        "id": 123,
        "task_name": "parse_task_20250115_a1b2c3d4",
        "task_status": "解析完成",
        "task_type": "名片",
        "task_source": "{\"minio_paths_json\":[\"http://192.168.3.143:9000/dataops-bucket/talent_photos/talent_photo_20250115_143012_a1b2c3d4.jpg\",\"http://192.168.3.143:9000/dataops-bucket/talent_photos/talent_photo_20250115_143015_b2c3d4e5.jpg\"],\"upload_time\":\"2025-01-15T14:30:25.123456\"}",
        "collection_count": 2,
        "parse_count": 2,
        "parse_result": "{\"parsed_cards\":[{\"name\":\"张三\",\"company\":\"ABC公司\",\"position\":\"技术总监\"}]}",
        "created_by": "api_user",
        "updated_by": "api_user",
        "created_at": "2025-01-15T14:30:25.123456",
        "updated_at": "2025-01-15T15:45:30.789012"
    }
}

错误响应 (HTTP 400)

{
    "success": false,
    "message": "任务名称参数不能为空",
    "data": null
}

错误响应 (HTTP 404)

{
    "success": false,
    "message": "未找到任务名称为 invalid_task_name 的记录",
    "data": null
}

状态码说明

状态码	说明
200	查询成功
400	请求参数错误
404	任务不存在
500	服务器内部错误

测试数据示例

测试用文件准备

# 创建测试文件目录
mkdir -p test_files

# 准备名片图片文件
cp sample_business_card.jpg test_files/
cp sample_business_card.png test_files/

# 准备简历PDF文件
cp sample_resume.pdf test_files/

# 准备任命MD文件
echo "# 新任命通知\n\n## 任命信息\n- 姓名：张三\n- 职位：技术总监" > test_files/appointment.md

完整测试流程

// 1. 创建名片解析任务
async function testCreateTask() {
    const formData = new FormData();
    formData.append('task_type', '名片');
    formData.append('files', document.querySelector('#fileInput').files[0]);
    formData.append('created_by', 'test_user');
    
    const response = await fetch('/api/parse/add-parse-task', {
        method: 'POST',
        body: formData
    });
    
    const result = await response.json();
    console.log('任务创建结果:', result);
    
    if (result.success) {
        const taskName = result.data.task_info.task_name;
        return taskName;
    }
}

// 2. 查询任务列表
async function testGetTasks() {
    const response = await fetch('/api/parse/get-parse-tasks?page=1&per_page=10&task_type=名片');
    const result = await response.json();
    console.log('任务列表:', result);
}

// 3. 获取任务详情
async function testGetTaskDetail(taskName) {
    const response = await fetch(`/api/parse/get-parse-task-detail?task_name=${taskName}`);
    const result = await response.json();
    console.log('任务详情:', result);
}

// 完整测试
async function runFullTest() {
    try {
        const taskName = await testCreateTask();
        if (taskName) {
            await testGetTasks();
            await testGetTaskDetail(taskName);
        }
    } catch (error) {
        console.error('测试失败:', error);
    }
}

常见问题与解决方案

1. 文件上传失败

问题: 上传文件时返回400错误 解决方案:

检查文件格式是否符合任务类型要求
确认文件大小不超过限制
验证task_type参数值是否正确

2. 任务查询为空

问题: 查询任务列表返回空数组 解决方案:

确认数据库中有对应的任务记录
检查过滤条件是否正确
验证分页参数是否合理

3. MinIO路径无法访问

问题: 返回的MinIO路径无法直接访问 解决方案:

确认MinIO服务器配置正确
检查网络连接和防火墙设置
验证MinIO访问权限配置

4. 任务状态更新

问题: 如何更新任务状态 解决方案:

使用其他API接口更新任务状态
通过后台程序自动更新
检查解析进度和结果

版本信息

文档版本: v1.0
API版本: v1.0
最后更新: 2025-07-15
维护者: DataOps团队

联系方式

如有疑问或需要技术支持，请联系：

开发团队: dataops-dev@company.com
技术文档: [内部文档链接]
问题反馈: [GitHub Issues]

api_documentation_parse_task.md 16 KB Geçmiş Ham

解析任务API接口文档

基础信息

1. 新增解析任务接口

接口概述

基本信息

请求参数

任务类型说明

请求示例

JavaScript/AJAX示例

jQuery示例

cURL示例

响应格式

成功响应 (HTTP 200)

部分成功响应 (HTTP 206)

错误响应 (HTTP 400)

状态码说明

2. 获取解析任务列表接口

接口概述

基本信息

请求参数

请求示例

JavaScript/Fetch示例

jQuery示例

cURL示例

响应格式

成功响应 (HTTP 200)

错误响应 (HTTP 400)

状态码说明

3. 获取解析任务详情接口

接口概述

基本信息

请求参数

请求示例

JavaScript/Fetch示例

jQuery示例

cURL示例

响应格式

成功响应 (HTTP 200)

错误响应 (HTTP 400)

错误响应 (HTTP 404)

状态码说明

测试数据示例

测试用文件准备

完整测试流程

常见问题与解决方案

1. 文件上传失败

2. 任务查询为空

3. MinIO路径无法访问

4. 任务状态更新

版本信息

联系方式

api_documentation_parse_task.md 16 KB

Geçmiş Ham