# 知识图谱查询 API 文档

## API 接口: `/query-kg`

该 API 接口允许您使用自然语言查询知识图谱数据库。它利用 Deepseek API 将您的查询需求转换为 Cypher 脚本，并在 Neo4j 数据库上执行。

### 请求详情

- **请求方法**: POST
- **URL**: `/api/data_parse/query-kg`
- **Content-Type**: application/json

### 请求参数

| 参数名 | 类型 | 是否必需 | 描述 |
|-------|------|----------|------|
| `query_requirement` | 字符串 | 是 | 对要从知识图谱中查询信息的自然语言描述 |

#### 请求体示例
```json
{
  "query_requirement": "查找所有在上海的五星级酒店担任总经理职位的人才"
}
```

### 响应格式

API 返回具有以下结构的 JSON 对象：

| 字段 | 类型 | 描述 |
|-----|------|------|
| `code` | 整数 | HTTP 状态码（200 表示成功，4xx/5xx 表示错误）|
| `success` | 布尔值 | 操作是否成功 |
| `message` | 字符串 | 结果描述或错误信息 |
| `query` | 字符串 | 执行的 Cypher 查询语句（供参考）|
| `data` | 数组 | 包含查询结果的对象数组 |

#### 成功响应示例
```json
{
  "code": 200,
  "success": true,
  "message": "查询成功执行",
  "query": "MATCH (t:talent)-[r:WORKS_FOR]->(h:hotel) WHERE r.title_zh CONTAINS '总经理' AND h.hotel_zh CONTAINS '上海' RETURN t.name_zh as 姓名, t.email as 邮箱, r.title_zh as 职位, h.hotel_zh as 酒店名称 ORDER BY h.hotel_zh",
  "data": [
    {
      "姓名": "张三",
      "邮箱": "zhang@example.com",
      "职位": "总经理",
      "酒店名称": "上海四季酒店"
    },
    {
      "姓名": "李四",
      "邮箱": "li@example.com",
      "职位": "执行总经理",
      "酒店名称": "上海浦东丽思卡尔顿酒店"
    }
  ]
}
```

#### 错误响应示例
```json
{
  "code": 400,
  "success": false,
  "message": "请求数据为空或缺少query_requirement字段",
  "data": []
}
```

### 响应状态码

| 状态码 | 描述 |
|-------|------|
| 200 | 请求成功 |
| 400 | 错误请求（缺少或无效参数）|
| 500 | 服务器错误（处理错误或数据库连接失败）|

### 错误处理

如果发生错误，响应将包括：
- 非 200 状态码
- `success` 设置为 `false`
- 描述性错误信息
- 空的 `data` 数组

## 知识图谱结构

该 API 与包含以下节点和关系的知识图谱交互：

### 节点
1. **talent** - 人才节点
   - 属性: `pg_id`, `name_zh`, `name_en`, `mobile`, `email`, `updated_at`

2. **hotel** - 酒店节点
   - 属性: `hotel_zh`, `hotel_en`, `updated_at`

3. **talent_tag** - 人才标签节点
   - 属性: `name`, `category`, `en_name`

4. **hotel_tag** - 酒店标签节点
   - 属性: `name`, `category`, `en_name`

5. **brand_group** - 品牌集团节点
   - 属性: `name`, `en_name`

### 关系
1. **WORKS_FOR** - 工作关系 (人才在酒店工作)
   - `(talent)-[WORKS_FOR]->(hotel)`
   - 属性: `title_zh`, `title_en`, `updated_at`

2. **BELONGS_TO** - 从属关系
   - `(talent)-[BELONGS_TO]->(talent_tag)` - 人才属于某标签
   - `(hotel)-[BELONGS_TO]->(hotel_tag)` - 酒店属于某标签
   - `(hotel)-[BELONGS_TO]->(brand_group)` - 酒店属于某品牌集团

## 前端集成示例

```javascript
// 使用 Axios 的 Vue.js 示例
import axios from 'axios';

export default {
  data() {
    return {
      queryInput: '',
      queryResults: [],
      isLoading: false,
      error: null
    }
  },
  methods: {
    async queryKnowledgeGraph() {
      this.isLoading = true;
      this.error = null;
      
      try {
        const response = await axios.post('/api/data_parse/query-kg', {
          query_requirement: this.queryInput
        });
        
        if (response.data.success) {
          this.queryResults = response.data.data;
        } else {
          this.error = response.data.message;
        }
      } catch (error) {
        this.error = error.response?.data?.message || '查询失败，请稍后重试';
      } finally {
        this.isLoading = false;
      }
    }
  }
}
```

```html
<!-- Vue.js 模板示例 -->
<template>
  <div class="knowledge-graph-query">
    <h2>知识图谱查询</h2>
    
    <div class="query-input">
      <textarea 
        v-model="queryInput"
        placeholder="请输入查询需求，例如：查找所有在上海的五星级酒店担任总经理职位的人才"
        rows="3"
      ></textarea>
      <button 
        @click="queryKnowledgeGraph" 
        :disabled="isLoading || !queryInput"
      >
        {{ isLoading ? '查询中...' : '查询' }}
      </button>
    </div>
    
    <div v-if="error" class="error-message">
      {{ error }}
    </div>
    
    <div v-if="queryResults.length > 0" class="results-table">
      <table>
        <thead>
          <tr>
            <th v-for="(value, key) in queryResults[0]" :key="key">{{ key }}</th>
          </tr>
        </thead>
        <tbody>
          <tr v-for="(item, index) in queryResults" :key="index">
            <td v-for="(value, key) in item" :key="`${index}-${key}`">{{ value }}</td>
          </tr>
        </tbody>
      </table>
    </div>
    
    <div v-else-if="!isLoading && !error" class="no-results">
      还没有查询结果，请输入查询需求并点击查询按钮
    </div>
  </div>
</template>
```

## 查询示例

以下是一些可以使用的查询示例：

1. 查找特定酒店的所有员工：
   ```
   查找在上海四季酒店工作的所有人才及其职位
   ```

2. 查找特定职位的人才：
   ```
   查找所有担任总经理或执行总经理职位的人才及其所在酒店
   ```

3. 按标签查找人才：
   ```
   查找拥有"市场营销"标签的所有人才
   ```

4. 查找特定品牌集团的酒店：
   ```
   查找属于希尔顿集团的所有酒店
   ```

5. 复杂关系查询：
   ```
   查找在上海的酒店工作并且同时拥有"领导力"和"酒店管理"标签的人才
   ```

## 注意事项

- 查询结果格式取决于生成的Cypher脚本，列名将根据查询内容动态生成
- 复杂查询可能需要更详细的描述以生成准确的Cypher脚本
- 查询结果默认没有分页，如需处理大量数据，请在查询中指明限制条件