docs: update notes, tasks, and gitignore

2026-02-07 17:01:22 +09:00
parent 943dbd6ef5
commit 4a93fb8260
4 changed files with 194 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -174,3 +174,5 @@ cython_debug/
 # PyPI configuration file
 .pypirc

+# macOS
+.DS_Store
--- a/README.md
+++ b/README.md
@@ -400,6 +400,7 @@ curl -s http://127.0.0.1:8092/health
 - `POST /db/query`: SELECT-only の読み取りクエリ（`X-API-KEY` 必須）
 - `POST /kb/upsert`: 1ドキュメントを upsert（`X-API-KEY` 必須、`id` は UUID）
 - `POST /kb/search`: ベクトル検索（`X-API-KEY` 必須）
+- `POST /kb/delete`: ドキュメント削除（`X-API-KEY` 必須、`id` または `filter`。`doc_id` 単体は不可）
 - `GET /collections`: コレクション一覧（`X-API-KEY` 必須）
 - `GET /admin/collections`: 管理者向けコレクション一覧（`X-ADMIN-API-KEY` 必須）
 - `GET /admin/api-keys`: 管理APIキー一覧（`X-ADMIN-API-KEY` 必須）
@@ -407,6 +408,25 @@ curl -s http://127.0.0.1:8092/health
 - `PATCH /admin/api-keys/{id}`: 管理APIキー更新（`X-ADMIN-API-KEY` 必須）
 - `POST /admin/api-keys/{id}/revoke`: 管理APIキー失効（`X-ADMIN-API-KEY` 必須）

+### MCP メモ
+
+- `dev_log_upsert` では `content_hash` 未指定時に MCP 側で自動計算される
+- `visibility` 未指定時の既定値は `private`
+- `content_hash` の計算式: `title + "\n" + body` を trim & LF 正規化して SHA-256 を計算し、`sha256:<hex>` で保存
+- `dev_log_upsert` は `ts` 未指定時に現在時刻を自動補完する
+- `dev_log_upsert` は `author` 未指定時に `PGVECTER_DEFAULT_AUTHOR` または `USER` を使用する
+- `dev_log_search` は `metadata.visibility=private` をデフォルトで付与する
+- `dev_log_upsert` は `metadata.id` にも `id` を保存する（IDでの検索用）
+- `trade_event_upsert` は `metadata.id` にも `id` を保存する（IDでの検索用）
+- `doc_upsert` は `metadata.id` にも `id` を保存する（IDでの検索用）
+- `security_upsert` は `metadata.id` にも `id` を保存する（IDでの検索用）
+- `*_delete` は `dry_run: true` で件数のみ確認できる
+- `*_delete` で期間指定する場合は `filter` が必須
+- `diary_upsert` は `dev_diary` / `chitchat_diary` のみ許可
+- `diary_upsert` は `source` / `author` / `topic` / `ts` / `tags` / `visibility` / `content_hash` を自動補完
+- `diary_upsert` の `content_hash` は本文 (`content`) を trim & LF 正規化して SHA-256 を計算し、`sha256:<hex>` で保存
+- `*_search_by_id` は `metadata.id` を `eq` で検索するショートカット
+
 ### 例: /kb/search

 ```bash
@@ -415,3 +435,52 @@ curl -s -X POST http://localhost:8080/kb/search \
  -H "Content-Type: application/json" \
  -d '{"query":"hello world","top_k":5}'
 ```
+
+### 例: /kb/delete (id 指定)
+
+```bash
+curl -s -X POST http://localhost:8080/kb/delete \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{"id":"00000000-0000-0000-0000-000000000001"}'
+```
+
+### 例: /kb/delete (metadata 条件 + 期間)
+
+```bash
+curl -s -X POST http://localhost:8080/kb/delete \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "collection":"dev_log",
+    "filter": {"and":[
+      {"contains": {"metadata.tags": "error"}},
+      {"lt": {"metadata.ts": "2025-12-01T00:00:00+09:00"}}
+    ]}
+  }'
+```
+
+### 例: /kb/delete (dry_run で件数のみ確認)
+
+```bash
+curl -s -X POST http://localhost:8080/kb/delete \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "collection":"dev_log",
+    "filter": {"contains": {"metadata.tags": "error"}},
+    "dry_run": true
+  }'
+```
+
+削除リクエストは `kb_delete_audit` に監査ログとして記録されます。
+
+### 例: MCP `*_search_by_id`
+
+```json
+{"id":"00000000-0000-0000-0000-000000000001"}
+```
+
+```json
+{"collection":"dev_diary","id":"00000000-0000-0000-0000-000000000001"}
+```
--- a/docs/mcp_dev_memo.md
+++ b/docs/mcp_dev_memo.md
@@ -122,6 +122,8 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
 - `visibility` -> `metadata.visibility`
 - `content_hash` -> `metadata.content_hash`
 - `embedding` -> 省略して自動生成 (bge-m3 固定運用)
+- `id` を `metadata.id` にも保存する（検索用）
+- `id` を `metadata.id` にも保存する（検索用）

 **コレクション名**
 - `dev_log`
@@ -132,6 +134,10 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
 - 正規化: 先頭/末尾の空白を trim、改行を LF に統一
 - ハッシュ: SHA-256
 - 保存形式: `sha256:<hex>`
+- MCP 側で `content_hash` が未指定の場合は自動計算する
+- MCP 側で `ts` が未指定の場合は現在時刻を自動補完する
+- MCP 側で `author` が未指定の場合は `PGVECTER_DEFAULT_AUTHOR` または `USER` を使う
+- dev_log_search は `metadata.visibility=private` をデフォルトで付与する

 ## dev_log テンプレ

@@ -145,6 +151,7 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/upsert \
    "collection":"dev_log",
    "content":"【タイトル】\n本文をここに書く。",
    "metadata":{
+      "id":"00000000-0000-0000-0000-000000000001",
      "title":"タイトル",
      "ts":"2026-02-06T21:30:00+09:00",
      "tags":["llama.cpp","pgvector"],
@@ -175,6 +182,21 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
  }'
 ```

+### search by id (dev_log)
+```bash
+curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "collection":"dev_log",
+    "query":"dummy",
+    "top_k":1,
+    "filter": {
+      "eq": {"metadata.id":"00000000-0000-0000-0000-000000000001"}
+    }
+  }'
+```
+
 ## trade_event スキーマと補足

 **想定フィールド**
@@ -226,6 +248,7 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/upsert \
    "collection":"trade_event",
    "content":"【見積】A社 2026-01-15\n50万円の見積。担当:山田。参照: Q-2026-001。",
    "metadata":{
+      "id":"00000000-0000-0000-0000-000000000002",
      "event_date":"2026-01-15",
      "partner_name":"A社",
      "event_type":"見積",
@@ -264,6 +287,39 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
  }'
 ```

+### search by date range (trade_event)
+```bash
+curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "collection":"trade_event",
+    "query":"去年の取引",
+    "top_k":5,
+    "filter": {
+      "and":[
+        {"gte": {"metadata.event_date":"2025-01-01"}},
+        {"lte": {"metadata.event_date":"2025-12-31"}}
+      ]
+    }
+  }'
+```
+
+### search by id (trade_event)
+```bash
+curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "collection":"trade_event",
+    "query":"dummy",
+    "top_k":1,
+    "filter": {
+      "eq": {"metadata.id":"00000000-0000-0000-0000-000000000002"}
+    }
+  }'
+```
+
 ## doc テンプレ

 ### upsert (doc)
@@ -276,6 +332,7 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/upsert \
    "collection":"doc",
    "content":"【契約書要約】A社\n契約期間は2026年4月〜2027年3月。解約は30日前通知。",
    "metadata":{
+      "id":"00000000-0000-0000-0000-000000000003",
      "title":"A社 取引基本契約書",
      "ts":"2026-02-06T22:00:00+09:00",
      "tags":["契約","A社"],
@@ -300,6 +357,21 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
  }'
 ```

+### search by id (doc)
+```bash
+curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "collection":"doc",
+    "query":"dummy",
+    "top_k":1,
+    "filter": {
+      "eq": {"metadata.id":"00000000-0000-0000-0000-000000000003"}
+    }
+  }'
+```
+
 ## security テンプレ

 ### upsert (security)
@@ -312,6 +384,7 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/upsert \
    "collection":"security",
    "content":"Fail2Ban: 203.0.113.10 を 10分 ban。理由: SSH brute force。",
    "metadata":{
+      "id":"00000000-0000-0000-0000-000000000004",
      "ts":"2026-02-06T22:05:00+09:00",
      "tags":["fail2ban","ssh"],
      "source":"fail2ban",
@@ -335,3 +408,33 @@ curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
    }
  }'
 ```
+
+### search by severity (security)
+```bash
+curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "collection":"security",
+    "query":"重大アラート",
+    "top_k":5,
+    "filter": {
+      "eq": {"metadata.severity":"error"}
+    }
+  }'
+```
+
+### search by id (security)
+```bash
+curl -s -X POST https://labo.sunamura-llc.com/pgvecter/kb/search \
+  -H "X-API-KEY: pgv_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "collection":"security",
+    "query":"dummy",
+    "top_k":1,
+    "filter": {
+      "eq": {"metadata.id":"00000000-0000-0000-0000-000000000004"}
+    }
+  }'
+```
--- a/remaining_tasks.md
+++ b/remaining_tasks.md
@@ -0,0 +1,20 @@
+# pgvecterAPI Remaining Tasks
+
+## 未着手（開発メモ起点）
+- なし
+
+## 機能強化（品質・運用改善）
+- [ ] `doc_upsert` の `ts` 既定補完（未指定時に現在時刻）
+- [ ] `security_upsert` の `ts` 既定補完（未指定時に現在時刻）
+
+## 完了
+- [x] `/kb/delete` エンドポイント追加（`id` または `filter` 必須）
+- [x] MCP削除ツール追加（`dev_log` / `trade_event` / `doc` / `security`）
+- [x] 削除のドライラン対応（件数のみ取得）
+- [x] 削除監査ログ `kb_delete_audit` 追加
+- [x] 日記系メタデータ方針の自動補完ロジック追加
+- [x] `dev_diary` 用の MCP ツール追加（`diary_upsert` / `diary_search`）
+- [x] `chitchat_diary` 用の MCP ツール追加（`diary_upsert` / `diary_search`）
+- [x] `dev_diary` / `chitchat_diary` を `dev_log` と同等の convenience に統一（`content_hash` / `ts` / `author` / `visibility`）
+- [x] ID検索ショートカット（MCP側で `*_search_by_id` 的な薄いラッパー）
+- [x] `trade_event` の `content` を「summary + detail の主要項目テキスト化」に拡張