DataOps-platform/data_parse_api_docs.md

数据解析 API 文档

本文档描述了数据解析模块的 API 接口，包括通用数据解析和名片解析功能。所有接口均采用 RESTful 风格，返回 JSON 格式的响应。

基础路径

所有 API 接口的基础路径为：/api/parse

1. 通用数据解析接口

1.1 解析数据

接口地址：/parse

请求方法：POST

功能描述：测试用的数据解析接口，目前没有实际使用。

请求参数：

请求体为 JSON 格式，具体格式取决于实际使用场景。

返回结果：

{
  "status": "success",
  "message": "Data parsed successfully",
  "data": {} // 解析后的数据
}

错误码：

HTTP 状态码	错误描述
400	No data provided
500	内部服务器错误

2. 名片解析接口

2.1 解析名片图片

接口地址：/business-card-parse

请求方法：POST

功能描述：处理上传的名片图片，提取名片中的信息，并保存到数据库。

请求参数：

Content-Type: multipart/form-data

参数名	参数类型	必须	描述
image	file	是	名片图片

返回结果：

成功时返回：

{
  "success": true,
  "message": "名片解析成功",
  "data": {
    "id": 1,
    "name_zh": "张三",
    "name_en": "Zhang San",
    "title_zh": "项目经理",
    "title_en": "Project Manager",
    "mobile": "13800138000",
    "phone": "010-12345678",
    "email": "zhangsan@example.com",
    "hotel_zh": "某酒店",
    "hotel_en": "Some Hotel",
    "address_zh": "北京市朝阳区某街某号",
    "address_en": "Some Street, Chaoyang District, Beijing",
    "postal_code_zh": "100000",
    "postal_code_en": "100000",
    "brand_zh": "某品牌",
    "brand_en": "Some Brand",
    "affiliation_zh": "某集团",
    "affiliation_en": "Some Group",
    "image_path": "unique-filename.jpg",
    "career_path": [],
    "brand_group": "",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": null,
    "updated_by": "system",
    "status": "active"
  }
}

错误码：

HTTP 状态码	错误描述	错误消息
400	请求参数错误	未上传图片
400	请求参数错误	未选择文件
400	请求参数错误	上传的文件不是图片
500	服务器内部错误	名片解析失败: {错误信息}
500	服务器内部错误	OCR无法从图像中提取文本
500	服务器内部错误	保存名片信息到数据库失败

2.2 更新名片信息

接口地址：/business-cards/<int:card_id>

请求方法：PUT

功能描述：更新已有名片记录的信息。

路径参数：

参数名	参数类型	描述
card_id	int	名片记录ID

请求参数：

请求体为 JSON 格式，可包含以下字段（所有字段都是可选的）：

{
  "name_zh": "张三",
  "name_en": "Zhang San",
  "title_zh": "高级项目经理",
  "title_en": "Senior Project Manager",
  "mobile": "13800138000",
  "phone": "010-12345678",
  "email": "zhangsan@example.com",
  "hotel_zh": "某酒店",
  "hotel_en": "Some Hotel",
  "address_zh": "北京市朝阳区某街某号",
  "address_en": "Some Street, Chaoyang District, Beijing",
  "postal_code_zh": "100000",
  "postal_code_en": "100000",
  "brand_zh": "某品牌",
  "brand_en": "Some Brand",
  "affiliation_zh": "某集团",
  "affiliation_en": "Some Group",
  "career_path": [{"company": "XX公司", "position": "经理"}],
  "brand_group": "品牌A,品牌B",
  "updated_by": "user"
}

返回结果：

成功时返回：

{
  "success": true,
  "message": "名片信息已更新",
  "data": {
    // 更新后的完整名片信息对象
  }
}

错误码：

HTTP 状态码	错误描述	错误消息
400	请求参数错误	请求数据为空
404	资源不存在	未找到ID为{card_id}的名片记录
500	服务器内部错误	更新名片信息失败: {错误信息}

2.3 获取所有名片列表

接口地址：/get-business-cards

请求方法：GET

功能描述：获取系统中所有的名片记录列表。

请求参数：无

返回结果：

成功时返回：

{
  "success": true,
  "message": "获取名片列表成功",
  "data": [
    {
      // 名片1的完整信息对象
    },
    {
      // 名片2的完整信息对象
    }
    // ...更多名片对象
  ]
}

错误码：

HTTP 状态码	错误描述	错误消息
500	服务器内部错误	获取名片列表失败: {错误信息}

2.4 更新名片状态

接口地址：/update-business-cards/<int:card_id>/status

请求方法：PUT

功能描述：更新名片的状态（激活或禁用）。

路径参数：

参数名	参数类型	描述
card_id	int	名片记录ID

请求参数：

{
  "status": "active" // 可选值: "active" 或 "inactive"
}

返回结果：

成功时返回：

{
  "success": true,
  "message": "名片状态已更新为: active",
  "data": {
    // 更新后的完整名片信息对象
  }
}

错误码：

HTTP 状态码	错误描述	错误消息
400	请求参数错误	请求数据为空或缺少status字段
400	请求参数错误	无效的状态值: {状态值}，必须为 active 或 inactive
404	资源不存在	未找到ID为{card_id}的名片记录
500	服务器内部错误	更新名片状态失败: {错误信息}

2.5 获取名片图片

接口地址：/business-cards/image/<path:image_path>

请求方法：GET

功能描述：从 MinIO 存储中获取名片图片。

路径参数：

参数名	参数类型	描述
image_path	string	MinIO中的图片路径

返回结果：

成功时返回图片的二进制数据流，Content-Type 根据图片类型设置。

错误码：

HTTP 状态码	错误描述	错误消息
500	服务器内部错误	MinIO客户端初始化失败
404	资源不存在	获取图片失败: {错误信息}

数据模型

名片模型 (BusinessCard)

字段名	类型	描述
id	Integer	主键
name_zh	String	中文姓名
name_en	String	英文姓名
title_zh	String	中文职位/头衔
title_en	String	英文职位/头衔
mobile	String	手机号码
phone	String	固定电话
email	String	电子邮箱
hotel_zh	String	中文酒店/公司名称
hotel_en	String	英文酒店/公司名称
address_zh	Text	中文地址
address_en	Text	英文地址
postal_code_zh	String	中文邮政编码
postal_code_en	String	英文邮政编码
brand_zh	String	中文品牌名称
brand_en	String	英文品牌名称
affiliation_zh	String	中文隶属关系
affiliation_en	String	英文隶属关系
image_path	String	MinIO中存储的路径
career_path	JSON	职业轨迹
brand_group	String	品牌组合
created_at	DateTime	创建时间
updated_at	DateTime	更新时间
updated_by	String	更新者
status	String	状态