# 网页文本解析API接口文档

## 接口概述

**接口名称**: 网页文本解析接口  
**接口路径**: `/api/data-parse/webpage-parse`  
**请求方法**: `POST`  
**内容类型**: `application/json`  
**功能描述**: 解析网页Markdown文本并使用QWen AI模型提取人员任命信息

---

## 输入参数

### 请求头
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| Content-Type | string | 是 | 必须为 `application/json` |

### 请求体参数
| 参数名 | 类型 | 必填 | 长度限制 | 说明 |
|--------|------|------|----------|------|
| markdown_text | string | 是 | 10-50000字符 | 网页的Markdown格式文本内容 |
| publish_time | string | 是 | - | 发布时间，用于设置career_path中的date字段，建议格式：YYYY-MM-DD |

### 请求体示例
```json
{
    "markdown_text": "![照片](https://example.com/photo.jpg)\n\n**张三先生**\n**Mr. Zhang San**\n\n北京万豪酒店\n总经理\n\n张三先生拥有15年酒店管理经验...",
    "publish_time": "2025-01-15"
}
```

---

## 输出参数

### 响应格式
所有响应均为JSON格式，包含以下基本结构：

```json
{
    "success": boolean,
    "message": string,
    "data": array|null
}
```

### 成功响应 (200)
```json
{
    "success": true,
    "message": "网页文本解析成功",
    "data": [
        {
            "name_zh": "张三",
            "name_en": "Zhang San",
            "title_zh": "总经理",
            "title_en": "General Manager",
            "hotel_zh": "北京万豪酒店",
            "hotel_en": "Beijing Marriott Hotel",
            "brand_group": "万豪",
            "pic_url": "https://example.com/photo.jpg",
            "career_path": [
                {
                    "date": "2025-01-15",
                    "hotel_en": "Beijing Marriott Hotel",
                    "hotel_zh": "北京万豪酒店",
                    "image_path": "",
                    "source": "webpage_extraction",
                    "title_en": "General Manager",
                    "title_zh": "总经理"
                }
            ]
        }
    ]
}
```

### 数据字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| name_zh | string | 人员中文姓名 |
| name_en | string | 人员英文姓名 |
| title_zh | string | 中文职位/头衔 |
| title_en | string | 英文职位/头衔 |
| hotel_zh | string | 中文酒店/公司名称 |
| hotel_en | string | 英文酒店/公司名称 |
| brand_group | string | 酒店品牌集团 |
| pic_url | string | 人员照片URL链接 |
| career_path | array | 职业轨迹数组 |

### career_path 对象说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| date | string | 任命日期 (使用传入的publish_time) |
| hotel_en | string | 英文酒店名称 |
| hotel_zh | string | 中文酒店名称 |
| image_path | string | 图片路径 (固定为空字符串) |
| source | string | 数据来源 (固定为"webpage_extraction") |
| title_en | string | 英文职位 |
| title_zh | string | 中文职位 |

---

## 错误响应

### 400 - 请求参数错误

#### 缺少必填参数
```json
{
    "success": false,
    "message": "缺少必填参数: markdown_text",
    "data": null
}
```

#### 参数类型错误
```json
{
    "success": false,
    "message": "markdown_text 必须是字符串类型",
    "data": null
}
```

#### 内容长度错误
```json
{
    "success": false,
    "message": "markdown_text 内容过长，最大支持50KB",
    "data": null
}
```

#### 请求格式错误
```json
{
    "success": false,
    "message": "请求必须是 JSON 格式",
    "data": null
}
```

### 500 - 服务器内部错误
```json
{
    "success": false,
    "message": "网页文本解析失败: 具体错误信息",
    "data": null
}
```

---

## 状态码说明

| 状态码 | 说明 | 响应示例 |
|--------|------|----------|
| 200 | 解析成功 | 返回提取的人员信息数据 |
| 400 | 请求参数错误 | 参数缺失、类型错误、内容格式问题等 |
| 500 | 服务器内部错误 | AI模型调用失败、系统异常等 |

---

## 使用说明

### 1. 环境要求
- 需要配置 `QWEN_API_KEY` 环境变量
- 服务器需要能访问阿里云QWen API

### 2. 支持的内容格式
- 支持标准Markdown格式文本
- 支持提取照片链接（`![描述](URL)` 格式）
- 支持中英文混合内容
- 支持多人员信息提取

### 3. 内容长度限制
- 最小长度：10字符
- 最大长度：50,000字符 (约50KB)

### 4. 最佳实践
- 提供结构化的Markdown内容以获得更好的提取效果
- 照片链接应放置在人员姓名前面，通过空行分隔
- 使用标准的日期格式 (YYYY-MM-DD) 作为 publish_time

---

## 测试样例

### 样例1：单人信息提取

**请求**:
```bash
curl -X POST http://localhost:5000/api/data-parse/webpage-parse \
  -H "Content-Type: application/json" \
  -d '{
    "markdown_text": "![照片](https://example.com/sandra.jpg)\n\n**周银萍 女士**\n**Ms. Sandra Zhou**\n\n深圳中洲万豪酒店\n人力资源总监\n\n近日，深圳中洲万豪酒店正式任命周银萍女士为酒店人力资源总监...",
    "publish_time": "2025-01-15"
  }'
```

**响应**:
```json
{
    "success": true,
    "message": "网页文本解析成功",
    "data": [
        {
            "name_zh": "周银萍",
            "name_en": "Sandra Zhou",
            "title_zh": "人力资源总监",
            "title_en": "Director of Human Resources",
            "hotel_zh": "深圳中洲万豪酒店",
            "hotel_en": "Shenzhen Marriott Hotel Nanshan",
            "brand_group": "万豪",
            "pic_url": "https://example.com/sandra.jpg",
            "career_path": [
                {
                    "date": "2025-01-15",
                    "hotel_en": "Shenzhen Marriott Hotel Nanshan",
                    "hotel_zh": "深圳中洲万豪酒店",
                    "image_path": "",
                    "source": "webpage_extraction",
                    "title_en": "Director of Human Resources",
                    "title_zh": "人力资源总监"
                }
            ]
        }
    ]
}
```

### 样例2：多人信息提取

**请求**:
```bash
curl -X POST http://localhost:5000/api/data-parse/webpage-parse \
  -H "Content-Type: application/json" \
  -d '{
    "markdown_text": "**1**\n\n![照片1](https://example.com/photo1.jpg)\n\n**曲晶 女士**\n\n诺金国际\n市场营销副总裁\n\n**2**\n\n![照片2](https://example.com/photo2.jpg)\n\n**扎西央宗 女士**\n\n北海涠洲岛悦苑酒店\n总经理",
    "publish_time": "2025-01-15"
  }'
```

**响应**:
```json
{
    "success": true,
    "message": "网页文本解析成功",
    "data": [
        {
            "name_zh": "曲晶",
            "name_en": "",
            "title_zh": "市场营销副总裁",
            "title_en": "",
            "hotel_zh": "诺金国际",
            "hotel_en": "",
            "brand_group": "诺金",
            "pic_url": "https://example.com/photo1.jpg",
            "career_path": [...]
        },
        {
            "name_zh": "扎西央宗",
            "name_en": "",
            "title_zh": "总经理",
            "title_en": "",
            "hotel_zh": "北海涠洲岛悦苑酒店",
            "hotel_en": "",
            "brand_group": "悦榕",
            "pic_url": "https://example.com/photo2.jpg",
            "career_path": [...]
        }
    ]
}
```

### 样例3：参数错误

**请求**:
```bash
curl -X POST http://localhost:5000/api/data-parse/webpage-parse \
  -H "Content-Type: application/json" \
  -d '{
    "markdown_text": "内容太短"
  }'
```

**响应**:
```json
{
    "success": false,
    "message": "缺少必填参数: publish_time",
    "data": null
}
```

---

## 开发指南

### Python 示例
```python
import requests
import json

def parse_webpage_text(markdown_text, publish_time):
    url = "http://localhost:5000/api/data-parse/webpage-parse"
    headers = {"Content-Type": "application/json"}
    data = {
        "markdown_text": markdown_text,
        "publish_time": publish_time
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 使用示例
result = parse_webpage_text("网页内容...", "2025-01-15")
if result["success"]:
    print(f"成功提取 {len(result['data'])} 个人员信息")
else:
    print(f"提取失败: {result['message']}")
```

### JavaScript 示例
```javascript
async function parseWebpageText(markdownText, publishTime) {
    const response = await fetch('/api/data-parse/webpage-parse', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            markdown_text: markdownText,
            publish_time: publishTime
        })
    });
    
    return await response.json();
}

// 使用示例
parseWebpageText("网页内容...", "2025-01-15")
    .then(result => {
        if (result.success) {
            console.log(`成功提取 ${result.data.length} 个人员信息`);
        } else {
            console.error(`提取失败: ${result.message}`);
        }
    });
```

---

## 注意事项

1. **API密钥**: 确保服务器已正确配置 `QWEN_API_KEY` 环境变量
2. **网络访问**: 服务器需要能够访问阿里云QWen API服务
3. **内容质量**: 提供结构化、清晰的Markdown内容可以获得更好的提取效果
4. **并发限制**: 建议控制并发请求数量，避免超出API调用限制
5. **错误处理**: 建议在客户端实现适当的错误处理和重试机制
6. **数据验证**: 建议对返回的数据进行二次验证，确保提取质量

---

## 更新日志

**版本 2.0** (2025-01-15)
- 新增 `publish_time` 必填参数
- 更新 career_path 中 date 字段的设置逻辑
- 增强参数验证和错误处理
- 更新API文档和使用示例

**版本 1.0** (初始版本)
- 基础的网页文本解析功能
- 支持单人和多人信息提取
- 集成QWen AI模型