kbdb-graph-plugin/docs/3-specs/blocks-edit-api/tasks.md

KBDB Blocks Edit API — Tasks

對應 SDD：design.md 上次更新：2026-05-06（Phase 1 + Phase 2 完成）

---

Phase 1：補 PATCH endpoint ✅ 完成

1. PATCH /blocks/{id}

• 1.1 zod schema 直接放在 route 檔（既有 pattern）
• 1.2 寫 src/actions/block-update.ts（96 行，符合樂高法 < 100）
  • 取既有 block + getBlock fallback（id 或 logseq_uuid）
  • 權限檢查：partner key 比對 user_id 前綴
  • 自動重算 content_hash（如 content 變）
  • 觸發 embedding async 重算（不阻塞 PATCH 回應）
  • 寫回 D1
  • 回傳更新後的 block
• 1.3 寫 tests/blocks-update.test.ts（7 case 全通過）
  • happy: content + content_hash 重算
  • happy: tags + refs 同改
  • 400: 無欄位
  • 404: 不存在
  • 403: partner 越權
  • 200: partner 改自己 namespace
  • content_hash 在只改 tags 時不變
• 1.4 在 src/routes/blocks.ts 加 PATCH route（OpenAPI）
• 1.5 部署到 prod（kbdb.finally.click）+ smoke test 4 case 通過

2. Triplet 編輯：使用既有 PUT/DELETE /records/:id

• 2.1 設計修正：v3 萬物皆 Block，triplet 是 record，既有 endpoints 已涵蓋。本任務組無需新增 endpoint。
• 2.2 在 mira-app 前端「異見牆」實作呼叫 PUT /records/:id（待 mira 階段 3）

3. OpenAPI spec 同步

• 3.1 OpenAPIHono 自動產 swagger.json（route 用 createRoute 已自動納入）
• 3.2 部署後驗證 swagger UI 顯示新 route（待手動驗證）

---

Phase 2：建三個 templates ✅ 完成

• 4.1 確認 KBDB 內無同名 template（透過 GET /templates 確認）
• 4.2 用 internal token POST /templates 建 data-source-config（id: tpl-data-source-config）
• 4.3 用 internal token POST /templates 建 source-skill（id: tpl-source-skill）
• 4.4 用 internal token POST /templates 建 wiki-page（id: tpl-wiki-page）
• 4.5 驗證：3/3 templates 在 GET /templates 列表內

---

風險追蹤

• 風險 1：partner key 跨 org 越權 — ✅ unit test 已涵蓋（403 partner 越權）
• 風險 2：embedding 重算造成 D1 寫入 spike — ✅ 改成 fire-and-forget（不 await），不阻塞 PATCH
• 風險 3：content_hash 不一致 — ✅ unit test 驗證 hash 重算對應內容

Known Issues（不在本 SDD 範圍，待另開）

• POST /blocks/ingest 不寫入 source 欄位：input 接受 source 參數但僅用於 id slug 生成，未寫進 block 的 source 欄位（block-ingest.ts:84 的 INSERT 缺欄位）。對 mira 影響：所有 source 區分目前無效，需等 KBDB 修復或直接走 POST /blocks + slots。建議下一份 KBDB SDD block-ingest-source-fix 處理。

---

部署紀錄

• 2026-05-06: Worker version b7df3c38-e138-41fb-a16c-cc9d2dfeebea 部署上線
• Smoke test 通過：content 改寫 + hash 重算、tags 改寫、400 空 body、404 不存在