From 4818ba45c053d553771f711ed8622471ee1848ae Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Mon, 25 May 2026 09:34:27 +0800
Subject: [PATCH] docs(logbook): record callback evidence snapshots [skip ci]

---
 docs/LOGBOOK.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md
index 992a3bde..7af3e725 100644
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -1,3 +1,84 @@
+## 2026-05-25｜T167 Callback owner-review evidence snapshot 持久化
+
+**背景**：
+
+- T166 已讓 Telegram 詳情 / 歷史回覆顯示 KM owner-review triage。
+- 但 AwoooP callback evidence 仍只保存 callback reply 本身；KM owner-review 狀態主要靠 live query，日後回放時無法確認「按下詳情 / 歷史當下」流程跑到哪一階段。
+- 本階段只新增 read-only evidence snapshot，不改 Telegram 送訊頻率、不改 callback mutation、不寫入 KM / incident 狀態。
+
+**完成變更**：
+
+- Telegram detail/history callback reply 的 outbound source envelope 新增 `km_stale_completion_summary` compact snapshot：
+  - schema：`km_stale_owner_review_callback_reply_snapshot_v1`
+  - 保存當下 `status`、project / incident、ready / blocked / completed / failed counts。
+  - 保存 guardrail：`writes_on_read`、`batch_writes_allowed`、`manual_review_required`。
+  - 保存 triage 精簡欄位：`flow_stage`、`ai_lead_agent`、`supporting_agents`、`automation_state`、`safe_to_auto_repair`、`blocking_reason`、`matching_strategy`。
+- AwoooP callback replies API 新增 `persisted_km_stale_completion_summary`，讓前端能同時呈現：
+  - live `km_stale_completion_summary`：現在查到的 owner-review 狀態。
+  - persisted snapshot：Telegram callback 回覆當下寫進 DB 的 evidence。
+- Runs 頁 `TG Callback Evidence` card 新增「Callback-time Evidence Snapshot」區塊與中英文 i18n。
+
+**本地驗證**：
+
+```text
+python3 -m py_compile apps/api/src/services/telegram_gateway.py apps/api/src/services/platform_operator_service.py apps/api/src/api/v1/platform/operator_runs.py apps/api/tests/test_telegram_message_templates.py apps/api/tests/test_awooop_operator_timeline_labels.py
+/Users/ogt/.pyenv/versions/3.11.7/bin/ruff check --select F,E9 apps/api/src/services/telegram_gateway.py apps/api/src/services/platform_operator_service.py apps/api/src/api/v1/platform/operator_runs.py apps/api/tests/test_telegram_message_templates.py apps/api/tests/test_awooop_operator_timeline_labels.py
+DATABASE_URL='postgresql+asyncpg://test:test@localhost:5432/test?ssl=disable' /Users/ogt/.pyenv/versions/3.11.7/bin/pytest apps/api/tests/test_telegram_message_templates.py apps/api/tests/test_awooop_operator_timeline_labels.py -q
+  -> 91 passed
+pnpm --filter @awoooi/web exec tsc --noEmit --incremental false
+python3 -m json.tool apps/web/messages/zh-TW.json >/dev/null
+python3 -m json.tool apps/web/messages/en.json >/dev/null
+git diff --check
+pnpm --filter @awoooi/web exec eslint 'src/app/[locale]/awooop/runs/page.tsx'
+  -> 0 errors, 26 pre-existing i18n warnings in this file
+pnpm --filter @awoooi/web lint
+  -> blocked by existing src/app/[locale]/demo/page.tsx hook-order error, unrelated to T167
+```
+
+**production deploy / smoke**：
+
+```text
+Code commit:
+263d7523 feat(telegram): persist callback owner review snapshots
+
+Deploy marker:
+1bee07e7 chore(cd): deploy 263d752 [skip ci]
+
+Gitea Actions:
+3041 / run_number 2089 CD -> success
+  job 0 tests -> success
+  job 1 build-and-deploy -> success
+  job 2 post-deploy-checks -> success
+3042 / run_number 2090 Code Review -> success
+
+Production API regression:
+GET https://awoooi.wooo.work/api/v1/platform/runs/callback-replies?project_id=awoooi&per_page=3
+  -> total=2, items=2
+  -> response includes persisted_km_stale_completion_summary field
+  -> old rows safely return persisted_km_stale_completion_summary=null
+
+Production web smoke:
+HEAD https://awoooi.wooo.work/zh-TW/awooop/runs?project_id=awoooi
+  -> HTTP 200
+```
+
+**production health note**：
+
+- `GET /api/v1/health` 仍回 `status=degraded`：`ollama_gcp_a=down timeout`，routing/fallback 顯示 `ollama` degraded with `fallback active: ollama_gcp_b`。
+- API / PostgreSQL / Redis / OpenClaw / SigNoz 正常；本次 change 未改 AI provider routing。
+
+**目前整體進度**：
+
+- AwoooP 告警可觀測鏈：約 98.6%。
+- 低風險自動修復閉環：約 95%。
+- 前端 AI 自動化管理介面同步：約 95%。
+- Telegram detail/history 可解釋性：約 94%。
+- Callback evidence / DB 回放性：約 87%。
+- CI/CD 通知與部署證據鏈：約 99%。
+- 治理告警可讀性 / 可處置性：約 93.5%。
+- KM owner-review / completion 可治理鏈：約 83%。
+- 完整 AI 自動化管理產品化：約 91.8%。
+
 ## 2026-05-25｜T166 Telegram detail/history 顯示 owner-review triage
 
 **背景**：