# Folders

## 文件夹列表

`GET /folders`

```json
{
  "tags": [
    "Folders"
  ],
  "summary": "文件夹列表",
  "description": "所有永久配置文件中唯一的非空文件夹标签。",
  "responses": {
    "200": {
      "description": "文件夹名称。",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "work",
              "scrapers"
            ]
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## 重命名文件夹

`PATCH /folders/{folder}`

```json
{
  "tags": [
    "Folders"
  ],
  "summary": "重命名文件夹",
  "description": "为文件夹中所有配置文件更新标签。返回受影响的配置文件数量。",
  "parameters": [
    {
      "name": "folder",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name"
          ],
          "properties": {
            "name": {
              "type": "string",
              "description": "新文件夹名称。"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "已重命名。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "renamed_to": {
                "type": "string"
              },
              "profiles": {
                "type": "integer",
                "description": "已重新打标签的配置文件数量。"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## 删除文件夹

`DELETE /folders/{folder}`

```json
{
  "tags": [
    "Folders"
  ],
  "summary": "删除文件夹",
  "description": "删除文件夹标签。若 `delete_profiles=true`，文件夹内的配置文件也会被删除；\n否则它们移至\"全部\"（仅移除标签）。\n",
  "parameters": [
    {
      "name": "folder",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "delete_profiles",
      "in": "query",
      "required": false,
      "description": "删除文件夹中的配置文件（默认 false = 仅移除标签）。",
      "schema": {
        "type": "boolean",
        "default": false
      }
    }
  ],
  "responses": {
    "200": {
      "description": "已删除。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "deleted_folder": {
                "type": "string"
              },
              "delete_profiles": {
                "type": "boolean"
              },
              "profiles": {
                "type": "integer",
                "description": "受影响的配置文件数量。"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## 在文件夹中创建配置文件

`POST /folders/{folder}/profiles`

```json
{
  "tags": [
    "Folders"
  ],
  "summary": "在文件夹中创建配置文件",
  "description": "与 `POST /profiles` 相同，但文件夹从路径中获取\n（覆盖请求体中的 `folder` 字段）。\n",
  "parameters": [
    {
      "name": "folder",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateProfileRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "已创建配置文件的元数据。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProfileMeta"
          }
        }
      }
    },
    "400": {
      "description": "缺少 `fingerprint` 或其不是对象，或代理字符串无法解析。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```