# n8n-nodes-kbdb

KBDB 的 n8n 節點（community node，薄殼）。讓 n8n 使用者用
**sheet／field／record** 三個詞操作 KBDB，不用寫 SQL、不用懂底層。

- 詞彙定案：InkStoneCo `system-dev/wiki/kbdb-詞彙表.md`（2026-08-15）
- 動作集＝`system-dev/docs/4-guides/kbdb-動作對照表.md` 標 ✅ 的那半
- 薄殼鐵律：`.claude/rules/07-thin-shell.md`——每個動作恰好一個 API 呼叫，
  API 沒有的能力**不拼裝**（`nodes/Kbdb/actions.ts` 是唯一映射點，有測試釘死）

## 動作 ↔ API

| 動作 | API（cypher-executor `/kbdb/*` proxy） |
|---|---|
| Append Record | `POST /kbdb/records` |
| Get a Record | `GET /kbdb/records/:recordId` |
| Get Many Records | `GET /kbdb/records/by-template/:sheet` |
| Update a Record | `PATCH /kbdb/records/:recordId` |
| Create a Sheet | `POST /kbdb/templates` |
| Get Sheet Schema | `GET /kbdb/templates/:idOrName` |
| List Sheets | `GET /kbdb/templates` |
| Search | `GET /kbdb/search` |

### 刻意不在清單上的（不是漏做）

- **Add a Field**：對外門（proxy）沒有 `PATCH /kbdb/templates`（實測 404）；
  base 端的 `PATCH /templates/:id` 語意是 **slots 整組覆蓋**（實測：`["name","phone"]`
  PATCH `["hired_at"]` → 剩 `["hired_at"]`），不是「加一欄」。等 API 有真的
  add-field 能力再掛上來。
- **Archive（record／sheet）**：record 只有 DELETE（真的刪掉，語意不符）；
  sheet 連 DELETE 都沒有。
- **關係整組**（Link／Add record to sheet／Get linked／Unlink）：沒有 API
  （等 `Arcrun#132` 資料模型提案 confirm）。

## 認證

Credential「KBDB API」＝ Base URL（你的 Arcrun 實例 cypher-executor 網址）＋
API Key（namespace，走 `X-Arcrun-API-Key` header）。資料按 namespace 租戶隔離；
sheet（template）定義是全域共享的。

⚠️ 不要直連 kbdb worker 本體——它只收系統內部 Bearer，外面打一定 401（設計）。

## 開發

```bash
npm install
npm run build     # tsc → dist/
npm test          # vitest：動作↔API 映射（對照表的機器版）
```

本地 n8n 驗證：把本套件 `npm pack` 出 tarball，裝進
`$N8N_USER_FOLDER/.n8n/nodes/`（`npm install <tarball>`），啟動 n8n 即可在
節點清單看到 KBDB。