data_parse_api_docs.md 8.1 KB
数据解析 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 | 固定电话 |
| 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 | 状态 |