From 67c70c071b285f43c7dc7fc77d6e57f4aa7883a2 Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Thu, 7 May 2026 01:18:46 +0800
Subject: [PATCH] docs(logbook): record telegram incident threading deploy
 [skip ci]

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

diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md
index b5d4a0df..27f3a4a4 100644
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -4612,3 +4612,93 @@ HTTP:
 ```
 
 判讀：這次只改 Telegram 顯示邊界，未改 AI provider、費用策略、routing 或 MCP 執行路徑。下一步應延續「訊息治理」方向，把同一 incident / firing fingerprint 的多則執行結果聚合成單一 thread / timeline，並讓 Telegram 只保留摘要與人工決策入口。
+
+### 01:24 Telegram Incident Follow-up Threading
+
+**背景**：
+
+- 前一輪已把 Runbook / Governance 訊息改成卡片，但同一 Incident 的後續訊息仍可能以新頂層訊息送出，造成群組洗版。
+- 既有主告警卡片已將 Telegram `message_id` 寫入 Redis `tg_msg:{incident_id}`，但只有部分 caller 顯式使用 reply。
+- 本輪目標是先做最小可部署的「同 Incident 後續訊息接回原卡」，不改 provider、routing、MCP 或 approval 狀態機。
+
+**改動**：
+
+- `telegram_gateway.py` 新增 Incident ID 擷取：
+  - 從出站文字擷取 `INC-YYYYMMDD-XXXXXX` 形狀的 Incident ID。
+  - `ACTION REQUIRED` 主告警卡不自動接舊訊息，避免新主卡被串到舊 thread。
+- `_send_request("sendMessage", payload)` 在送出前自動 threading：
+  - 若 payload 尚未指定 `reply_to_message_id` / `reply_parameters`。
+  - 且文字含 Incident ID。
+  - 且 Redis 找得到 `tg_msg:{incident_id}`。
+  - 則自動加上 Telegram Bot API `reply_parameters: {message_id, allow_sending_without_reply}`。
+- `outbound_message` 分類同步調整：
+  - reply context 也納入 `reply_parameters`。
+  - `RUNBOOK REVIEW｜待審核` 即使是 reply，也仍分類為 `approval_request`，避免 AwoooP 將知識審核誤判成一般 final。
+- 補測：
+  - 可從 Runbook 文本擷取 Incident ID。
+  - 非主卡後續訊息會自動加 `reply_parameters`。
+  - `ACTION REQUIRED` 主卡不會自動 reply。
+  - `reply_parameters` 會被 outbound type inference 視為 threaded 訊息。
+
+**驗證**：
+
+```text
+py_compile:
+apps/api/src/services/telegram_gateway.py
+apps/api/tests/test_telegram_message_templates.py
+# passed
+
+pytest:
+apps/api/tests/test_telegram_message_templates.py
+# 25 passed
+
+pytest:
+apps/api/tests/test_failover_alerter.py
+apps/api/tests/test_phase25_auto_harvesting.py
+apps/api/tests/test_telegram_message_templates.py
+# 56 passed
+
+note:
+ruff --select I apps/api/src/services/telegram_gateway.py 仍會掃到該大型檔案既有 inline import 排序問題；
+本輪未做全檔 import 重排，避免把 Telegram 橙區小改動擴大成大範圍 churn。
+```
+
+**生產部署**：
+
+```text
+Commit:
+1f4a16e6 fix(telegram): thread incident follow-up messages
+
+Gitea workflows:
+1839 CD Pipeline:
+- tests -> success
+- build-and-deploy -> success
+- post-deploy-checks -> success
+1840 Code Review -> success
+
+CD deploy marker:
+18b34fed chore(cd): deploy 1f4a16e [skip ci]
+
+awoooi-api image:
+192.168.0.110:5000/awoooi/api:1f4a16e625f4f594f26750bd2f707e3a9a8b9faf
+
+awoooi-web image:
+192.168.0.110:5000/awoooi/web:1f4a16e625f4f594f26750bd2f707e3a9a8b9faf
+
+K8s rollout:
+awoooi-api -> successfully rolled out
+awoooi-web -> successfully rolled out
+awoooi-api pods -> 2/2 Running, 0 restarts
+
+HTTP:
+/api/v1/health             -> 200
+/zh-TW                     -> 200
+/zh-TW/awooop              -> 200
+/zh-TW/awooop/runs         -> 200
+/zh-TW/awooop/approvals    -> 200
+
+API log:
+近 5 分鐘未見 telegram_request_failed / telegram_api_error / telegram_outbound_mirror_failed。
+```
+
+判讀：Runbook Review、Escalation、同 incident 的後續摘要會先嘗試接回原告警卡，Telegram 不再把這些訊息全部打成頂層。下一步要處理的是「跨 incident 同 fingerprint 聚合」與 AwoooP Timeline UI，把完整執行歷程放到 Console，Telegram 只保留摘要與人工入口。