uncle6me-web
87f6de7c9f
leo 2026-08-15「有效才正式開發」下一格：紙上考卷驗過的動作集做成真的 n8n 節點。 詞彙照定案（sheet/field/record，InkStoneCo system-dev/wiki/kbdb-詞彙表.md）。 - 動作 ↔ API 映射收斂在 nodes/Kbdb/actions.ts（純函式），20 個 vitest 釘死 ——就是動作對照表 ✅ 那半的機器版；🔴/◐ 的動作刻意不存在，呼叫丟 「沒有這個能力」（07-thin-shell §3.1：API 沒有的能力不拼裝） - 對外走 cypher-executor /kbdb/* proxy（X-Arcrun-API-Key），不直連 kbdb worker - Add a field 不掛：proxy 無 PATCH /kbdb/templates（實測 404）；base 端 PATCH /templates/:id 語意是 slots 整組覆蓋（本地實測），不是加一欄 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
54 lines
2.2 KiB
Markdown
54 lines
2.2 KiB
Markdown
# 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。
|