## 接口清单

| 接口 | 方法 | 作用 |
|------|------|------|
| `https://pattern.aiddit.com/api/pattern/category_tree` | `GET` | 获取分类树扁平节点列表，用于组装 `category_tree.json` |
| `https://pattern.aiddit.com/api/pattern/tools/get_library_frequent_itemsets/execute` | `POST` | 获取 execution 对应的频繁项集库 |
| `https://pattern.aiddit.com/api/pattern/tools/get_itemset_detail/execute` | `POST` | 根据 `itemset_id` 获取 itemset 详情和 `post_ids` |
| `https://pattern.aiddit.com/api/pattern/posts/batch` | `POST` | 根据 `post_id` 批量获取帖子详情 |

说明：

- 实测时间：`2026-04-22`
- 当前文档只保留仍有实际用途的接口

---

## 接口详情

### 1. 分类树接口

**接口**

```text
GET https://pattern.aiddit.com/api/pattern/category_tree
```

**用途**

- 获取完整分类树节点
- 返回的是扁平 `categories`
- 本地再组装成 `category_tree.json`

对应代码：

- [collect_node_data.py](./collect_node_data.py)

**参数**

#### `execution_id`

- 位置：query 参数
- 是否必填：是
- 示例：

```bash
curl "https://pattern.aiddit.com/api/pattern/category_tree?execution_id=56"
```

**请求格式**

```text
GET /api/pattern/category_tree?execution_id=56
```

**返回格式**

```json
{
  "success": true,
  "categories": [
    {
      "id": 14886,
      "source_stable_id": 57,
      "source_type": "实质",
      "name": "装饰元素",
      "description": "用于装饰或美化的图案、纹理、文字等视觉元素",
      "category_nature": "领域",
      "path": "/表象/符号/装饰符号/装饰元素",
      "level": 4,
      "parent_id": 15718,
      "element_count": 8,
      "elements": []
    }
  ]
}
```

常见字段：

- `id`
- `source_stable_id`
- `source_type`
- `name`
- `description`
- `category_nature`
- `path`
- `level`
- `parent_id`
- `element_count`
- `elements`

### 2. 频繁项集库接口

**接口**

```text
POST https://pattern.aiddit.com/api/pattern/tools/get_library_frequent_itemsets/execute
```

**用途**

- 获取一个 execution 对应的频繁项集库
- 当前最稳定的用法是“按 execution 取全库”

对应代码背景：

- 旧代码原本调用的是 `get_frequent_itemsets`
- 当前可用的是 `get_library_frequent_itemsets`

**参数**

#### `execution_id`

- 位置：body 顶层
- 是否必填：是
- 最小可用请求：

```bash
curl -X POST "https://pattern.aiddit.com/api/pattern/tools/get_library_frequent_itemsets/execute" \
  -H "Content-Type: application/json" \
  -d '{"execution_id":56}'
```

#### `args.top_n`

- 位置：`args` 内
- 是否必填：否
- 作用：限制返回展示条数
- 示例：

```bash
curl -X POST "https://pattern.aiddit.com/api/pattern/tools/get_library_frequent_itemsets/execute" \
  -H "Content-Type: application/json" \
  -d '{"execution_id":56,"args":{"top_n":5}}'
```

#### `args.sort_by`

- 位置：`args` 内
- 是否必填：否
- 作用：当前至少不会报错
- 实测值：`absolute_support`
- 示例：

```bash
curl -X POST "https://pattern.aiddit.com/api/pattern/tools/get_library_frequent_itemsets/execute" \
  -H "Content-Type: application/json" \
  -d '{"execution_id":56,"args":{"sort_by":"absolute_support"}}'
```

#### `args.category_ids`

- 位置：`args` 内
- 是否必填：否
- 说明：沿用旧接口写法时会返回空结果
- 当前不建议使用

**请求格式**

最小请求：

```json
{
  "execution_id": 56
}
```

带参数请求：

```json
{
  "execution_id": 56,
  "args": {
    "top_n": 20,
    "sort_by": "absolute_support"
  }
}
```

**返回格式**

顶层返回：

```json
{
  "success": true,
  "tool_name": "get_library_frequent_itemsets",
  "result": "{\"total\": 612, \"showing\": 20, \"groups\": {...}}"
}
```

注意：

- `result` 是 JSON 字符串
- 需要再解析一次

解析后格式：

```json
{
  "total": 612,
  "showing": 20,
  "groups": {
    "full/max": {
      "dimension_mode": "full",
      "target_depth": "max",
      "total": 612,
      "itemsets": [
        {
          "id": 132046,
          "item_count": 3,
          "absolute_support": 28,
          "items": [
            {
              "point_type": "关键点",
              "dimension": "形式",
              "category_id": 15055,
              "category_path": "架构>修辞>...>拟人化主体"
            }
          ]
        }
      ]
    }
  }
}
```

常见字段：

- 顶层：`total` `showing` `groups`
- 分组：`dimension_mode` `target_depth` `total` `itemsets`
- itemset：`id` `item_count` `absolute_support` `items`
- item：`point_type` `dimension` `category_id` `category_path`

### 3. Itemset 详情接口

**接口**

```text
POST https://pattern.aiddit.com/api/pattern/tools/get_itemset_detail/execute
```

**用途**

- 根据 `itemset_id` 获取 itemset 详情
- 结果中包含 `post_ids`

对应代码：

- [collect_node_data.py](./collect_node_data.py)
- [get_itemset_posts.py](./get_itemset_posts.py)

**参数**

#### `execution_id`

- 位置：body 顶层
- 是否必填：是

#### `args.itemset_ids`

- 位置：`args` 内
- 是否必填：是
- 类型：整数数组

**请求格式**

```json
{
  "execution_id": 56,
  "args": {
    "itemset_ids": [132046]
  }
}
```

**请求示例**

```bash
curl -X POST "https://pattern.aiddit.com/api/pattern/tools/get_itemset_detail/execute" \
  -H "Content-Type: application/json" \
  -d '{"execution_id":56,"args":{"itemset_ids":[132046]}}'
```

**返回格式**

顶层返回：

```json
{
  "success": true,
  "tool_name": "get_itemset_detail",
  "result": "[{...}]"
}
```

注意：

- `result` 是 JSON 字符串
- 需要再解析一次

解析后格式：

```json
[
  {
    "id": 132046,
    "dimension_mode": "full",
    "target_depth": "max",
    "item_count": 3,
    "absolute_support": 28,
    "support": 0.0,
    "items": [],
    "post_ids": []
  }
]
```

常见字段：

- `id`
- `dimension_mode`
- `target_depth`
- `item_count`
- `absolute_support`
- `support`
- `items`
- `post_ids`

### 4. 帖子批量详情接口

**接口**

```text
POST https://pattern.aiddit.com/api/pattern/posts/batch
```

**用途**

- 根据一批 `post_id` 获取帖子详情
- 常用于：
  - 判断平台是不是 `xiaohongshu`
  - 获取标题、正文、图片、作者等字段

对应代码：

- [collect_node_data.py](./collect_node_data.py)
- [sort_requirements.py](./sort_requirements.py)
- [data_preparation/post_collector.py](./data_preparation/post_collector.py)
- [visualize/fetch_xhs_posts.py](./visualize/fetch_xhs_posts.py)

**参数**

#### `post_ids`

- 位置：body 顶层
- 是否必填：是
- 类型：字符串数组

**请求格式**

```json
{
  "post_ids": [
    "671f7fab000000003c01fffc",
    "63712737"
  ]
}
```

**请求示例**

```bash
curl -X POST "https://pattern.aiddit.com/api/pattern/posts/batch" \
  -H "Content-Type: application/json" \
  -d '{"post_ids":["671f7fab000000003c01fffc","63712737"]}'
```

**返回格式**

```json
{
  "success": true,
  "posts": [
    {
      "post_id": "671f7fab000000003c01fffc",
      "title": "...",
      "body_text": "...",
      "images": [],
      "like_count": 0,
      "comment_count": 0,
      "collect_count": 0,
      "platform": "xiaohongshu",
      "platform_account_name": "...",
      "publish_date": "...",
      "decode_result": {}
    }
  ]
}
```

常见字段：

- `post_id`
- `title`
- `body_text`
- `images`
- `like_count`
- `comment_count`
- `collect_count`
- `platform`
- `platform_account_name`
- `publish_date`
- `decode_result`

---

## 特殊情况

### 1. `execution_id` 的传法不统一

- `category_tree`：放在 query 参数
- `get_library_frequent_itemsets`：放在 body 顶层
- `get_itemset_detail`：放在 body 顶层

### 2. `get_library_frequent_itemsets` 和旧接口不是简单改名

虽然名字相近，但当前行为不同：

- 只传 `execution_id` 就能返回整库 itemset
- `args.top_n` 有效
- 旧接口常用的 `category_ids` 传进去会得到空结果

所以当前不要直接把旧接口 payload 原样搬过去。

### 3. `result` 字段常常是字符串

两个工具接口：

- `get_library_frequent_itemsets`
- `get_itemset_detail`

返回里都有：

```json
{
  "result": "..."
}
```

这里的 `result` 不是最终对象，而是 JSON 字符串，需要再解析一次。

### 4. 旧频繁项集接口已不可用

当前：

- `get_frequent_itemsets/execute` 会返回“不允许调用工具”
- 如果需要 itemset 数据，应改用 `get_library_frequent_itemsets/execute`