# /labellist 接口说明（DataLabel 列表查询）

本文档描述数据接口模块提供的 DataLabel 列表查询接口，便于前端接入与调试。

## 基本信息
- **URL**：`/labellist`（最终完整路径取决于 `data_interface` 蓝图注册前缀，例如 `/api/data_interface/labellist`）
- **方法**：`POST`
- **内容类型**：`application/json`
- **返回格式**：`application/json`

## 请求参数（JSON Body）
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| current | int | 否 | 页码，默认 1 |
| size | int | 否 | 每页条数，默认 10 |
| name_en | str | 否 | 标签英文名模糊匹配 |
| name_zh | str | 否 | 标签中文名模糊匹配 |
| category_filter | dict/list/str | 否 | 分类过滤。支持：<br>- `dict`：键为属性名，值为匹配内容，如 `{ "category": "质量", "scope": "公共" }`<br>- `list`：元素为 `{ "field": "...", "value": "..." }` 或单键值对，如 `[{"field":"category","value":"质量"},{"group":"公共"}]`<br>- `str`：等同于按 `category` 字段模糊匹配 |
| group | str | 否 | 分组名模糊匹配 |

说明：
- 所有字符串匹配均使用 Cypher `CONTAINS`（大小写敏感视 Neo4j 配置而定）。
- `category_filter` 会按提供的多个条件叠加 `AND` 过滤。

## 响应字段
成功时（`code=200`，`message="success"`）：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 123,
        "name_zh": "示例标签",
        "name_en": "sample_label",
        "category": "质量",
        "group": "公共",
        "describe": null,
        "scope": null,
        "number": 4
      }
    ],
    "total": 57,
    "size": 10,
    "current": 1
  }
}
```

失败时（例如参数错误或 Neo4j 异常）：
```json
{
  "code": 500,
  "message": "错误描述",
  "data": {}
}
```

## 请求示例
```http
POST /labellist
Content-Type: application/json

{
  "current": 1,
  "size": 10,
  "name_zh": "标签",
  "category_filter": [
    {"field": "category", "value": "质量"},
    {"field": "scope", "value": "公共"}
  ],
  "group": "模型"
}
```

## 返回示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 321,
        "name_zh": "标签-质量",
        "name_en": "label_quality",
        "category": "质量",
        "group": "模型",
        "describe": null,
        "scope": null,
        "number": 2
      }
    ],
    "total": 5,
    "size": 10,
    "current": 1
  }
}
```

## 前端对接提示
- 必须以 `POST + JSON` 调用；若使用 Fetch/axios，设置 `headers: { "Content-Type": "application/json" }`。
- 分页字段 `current`、`size` 需为整数，未传时后端使用默认值。
- `category_filter` 支持多条件 AND 过滤，请确保字段名为合法的 Neo4j 属性名（只含字母、数字、下划线，且非数字开头）。
- 返回的 `number` 字段表示该标签入度+出度关系数量，可用于前端展示关联数。