# Smart Folder

{% hint style="danger" %}
**此功能尚未發佈**：此 API 需要 Eagle 4.0 Build 22 或更高版本。詳細發佈時間請關注 Eagle 官網。
{% endhint %}

## 端點概覽

| 方法   | 端點                             | 說明              |
| ---- | ------------------------------ | --------------- |
| GET  | `/api/v2/smartFolder/get`      | 列出智慧型資料夾        |
| POST | `/api/v2/smartFolder/get`      | 列出智慧型資料夾（請求主體）  |
| POST | `/api/v2/smartFolder/create`   | 建立智慧型資料夾        |
| POST | `/api/v2/smartFolder/update`   | 更新智慧型資料夾        |
| POST | `/api/v2/smartFolder/remove`   | 刪除智慧型資料夾        |
| GET  | `/api/v2/smartFolder/getItems` | 取得符合條件的項目       |
| POST | `/api/v2/smartFolder/getItems` | 取得符合條件的項目（請求主體） |
| GET  | `/api/v2/smartFolder/getRules` | 取得可用規則 schema   |

***

## GET /api/v2/smartFolder/get <a href="#list" id="list"></a>

列出所有智慧型資料夾，或以 ID 篩選。

### 查詢參數

* `id` string（可選）— 以 ID 回傳單一智慧型資料夾
* `ids` string（可選）— 以逗號分隔的智慧型資料夾 ID

### 回應

```json
{
    "status": "success",
    "data": [
        {
            "id": "LRK3AQGN7VCB1",
            "name": "大尺寸圖片",
            "conditions": [
                {
                    "rules": [
                        { "property": "width", "method": ">", "value": [1920] }
                    ],
                    "match": "AND",
                    "boolean": "TRUE"
                }
            ],
            "description": "",
            "icon": "",
            "iconColor": "blue",
            "children": [],
            "modificationTime": 1700000000000,
            "imageCount": 42
        }
    ]
}
```

### 範例

```javascript
// 列出所有智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/get").then(r => r.json());

// 以 ID 取得單一智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/get?id=LRK3AQGN7VCB1").then(r => r.json());
```

***

## POST /api/v2/smartFolder/get <a href="#list-post" id="list-post"></a>

與 GET 相同，但接受 JSON 主體中的篩選參數。

### 請求主體

* `id` string（可選）— 智慧型資料夾 ID
* `ids` string\[]（可選）— 智慧型資料夾 ID 陣列

### 範例

```javascript
// 以多個 ID 取得智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["SMART_FOLDER_ID_1", "SMART_FOLDER_ID_2"]
    })
}).then(r => r.json());
```

***

## POST /api/v2/smartFolder/create <a href="#create" id="create"></a>

建立新的智慧型資料夾。

### 請求主體

* `name` string（必填）— 智慧型資料夾名稱
* `conditions` Object\[]（必填）— 篩選條件（格式請參考下方 [conditions 格式說明](#conditions)）
* `description` string（可選）— 說明
* `icon` string（可選）— 圖示
* `iconColor` string（可選）— 圖示顏色。可選值：`red`、`orange`、`yellow`、`green`、`aqua`、`blue`、`purple`、`pink`
* `parent` string（可選）— 父智慧型資料夾 ID。若省略則建立在根層級。

### 回應

回傳新建立的智慧型資料夾物件。

```json
{
    "status": "success",
    "data": {
        "id": "NEW_SMART_FOLDER_ID",
        "name": "大尺寸圖片",
        "conditions": [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] }
                ],
                "match": "AND"
            }
        ],
        "description": "",
        "icon": "",
        "iconColor": "",
        "children": [],
        "modificationTime": 1700000000000,
        "imageCount": 150
    }
}
```

### 範例

```javascript
// 建立篩選寬度大於 1920 的 PNG 圖片的智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        name: "大尺寸 PNG",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] },
                    { "property": "type", "method": "equal", "value": "png" }
                ],
                "match": "AND"
            }
        ],
        iconColor: "blue"
    })
}).then(r => r.json());
```

***

## POST /api/v2/smartFolder/update <a href="#update" id="update"></a>

更新現有智慧型資料夾的中繼資料。只有您包含的欄位會被修改。

### 請求主體

* `id` string（必填）— 要更新的智慧型資料夾 ID

**可修改的欄位：**

* `name` string（可選）— 新名稱
* `conditions` Object\[]（可選）— 新篩選條件
* `description` string（可選）— 新說明
* `icon` string（可選）— 新圖示
* `iconColor` string（可選）— 新圖示顏色

### 回應

回傳更新後的智慧型資料夾物件。

### 範例

```javascript
// 更新智慧型資料夾名稱和顏色
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        name: "超大尺寸圖片",
        iconColor: "green"
    })
}).then(r => r.json());

// 更新篩選條件
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [3840] }
                ],
                "match": "AND"
            }
        ]
    })
}).then(r => r.json());
```

***

## POST /api/v2/smartFolder/remove <a href="#remove" id="remove"></a>

刪除智慧型資料夾。同時會刪除其所有子智慧型資料夾。

### 請求主體

* `id` string（必填）— 要刪除的智慧型資料夾 ID

### 回應

```json
{
    "status": "success",
    "data": true
}
```

### 範例

```javascript
await fetch("http://localhost:41595/api/v2/smartFolder/remove", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id: "LRK3AQGN7VCB1" })
}).then(r => r.json());
```

***

## GET /api/v2/smartFolder/getItems <a href="#get-items" id="get-items"></a>

取得符合智慧型資料夾篩選條件的項目。

### 查詢參數

* `smartFolderId` string（必填）— 智慧型資料夾 ID
* `orderBy` string（可選）— 排序欄位
* `fields` string（可選）— 以逗號分隔的回傳欄位列表

### 回應

```json
{
    "status": "success",
    "data": [
        {
            "id": "M3QSGJNQTC2DG",
            "name": "wallpaper",
            "ext": "png",
            "width": 3840,
            "height": 2160,
            "tags": ["wallpaper"],
            "folders": []
        }
    ]
}
```

### 範例

```javascript
// 取得智慧型資料夾中的所有項目
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1")
    .then(r => r.json());

// 只回傳特定欄位
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1&fields=id,name,tags")
    .then(r => r.json());
```

***

## POST /api/v2/smartFolder/getItems <a href="#get-items-post" id="get-items-post"></a>

與 GET 相同，但接受 JSON 主體中的參數。

### 請求主體

* `smartFolderId` string（必填）— 智慧型資料夾 ID
* `orderBy` string（可選）— 排序欄位
* `fields` string\[]（可選）— 要回傳的欄位

### 範例

```javascript
await fetch("http://localhost:41595/api/v2/smartFolder/getItems", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        smartFolderId: "LRK3AQGN7VCB1",
        fields: ["id", "name", "ext", "width", "height"]
    })
}).then(r => r.json());
```

***

## GET /api/v2/smartFolder/getRules <a href="#get-rules" id="get-rules"></a>

取得可用的篩選規則 schema。回傳每個 property 支援的 methods、valueType、options 等資訊，讓呼叫者可以動態建構合法的 conditions。

### 回應

```json
{
    "status": "success",
    "data": {
        "name": {
            "methods": ["contain", "uncontain", "equal", "startWith", "endWith", "empty", "not-empty", "regex"],
            "valueType": "string"
        },
        "width": {
            "methods": ["=", ">=", "<=", ">", "<", "between"],
            "valueType": "number"
        },
        "type": {
            "methods": ["equal", "unequal"],
            "valueType": "string",
            "options": ["jpg", "png", "gif", "svg", "bmp", "webp", "..."]
        }
    }
}
```

### 範例

```javascript
// 取得可用規則，用於動態建構 conditions
await fetch("http://localhost:41595/api/v2/smartFolder/getRules").then(r => r.json());
```

{% hint style="info" %}
**使用提示：** 先呼叫 `getRules` 取得所有可用的 property 和 method，再根據回傳的 schema 建構 `conditions` 傳入 `create` 或 `update`，可避免無效的篩選條件。
{% endhint %}

***

## Conditions 格式說明 <a href="#conditions" id="conditions"></a>

智慧型資料夾的 `conditions` 是一個條件群組陣列，每個群組包含多條規則：

```json
[
    {
        "rules": [
            { "property": "name", "method": "contain", "value": "cat" },
            { "property": "width", "method": ">", "value": [1920] }
        ],
        "match": "AND",
        "boolean": "TRUE"
    }
]
```

### 條件群組屬性

| 屬性        | 類型        | 說明                                        |
| --------- | --------- | ----------------------------------------- |
| `rules`   | Object\[] | 規則陣列                                      |
| `match`   | string    | 規則間的邏輯運算。`"AND"`：全部符合；`"OR"`：任一符合         |
| `boolean` | string    | 群組的包含/排除邏輯。`"TRUE"`（包含，預設）或 `"FALSE"`（排除） |

### 規則屬性

| 屬性         | 類型     | 說明                            |
| ---------- | ------ | ----------------------------- |
| `property` | string | 篩選屬性（如 `name`、`width`、`type`） |
| `method`   | string | 篩選方法（如 `contain`、`>`、`equal`） |
| `value`    | any    | 篩選值（格式依屬性和方法而定）               |

{% hint style="info" %}
**提示：** 使用 `GET /api/v2/smartFolder/getRules` 可查詢所有可用的 property、method 及其對應的 valueType。
{% endhint %}

***

## SmartFolder 屬性 <a href="#properties" id="properties"></a>

API 回傳的智慧型資料夾包含以下屬性：

| 屬性                 | 類型        | 說明          |
| ------------------ | --------- | ----------- |
| `id`               | string    | 唯一智慧型資料夾 ID |
| `name`             | string    | 名稱          |
| `conditions`       | Object\[] | 篩選條件        |
| `description`      | string    | 說明          |
| `icon`             | string    | 圖示          |
| `iconColor`        | string    | 圖示顏色        |
| `children`         | Object\[] | 子智慧型資料夾     |
| `modificationTime` | integer   | 最後修改時間戳記    |
| `imageCount`       | integer   | 符合條件的項目數量   |