awoooi/docs/security/TELEGRAM-NOTIFICATION-EGRESS-MIGRATION-PLAN-DRAFT.md

Telegram 通知出口遷移計畫草稿

項目	內容
日期	2026-06-18
狀態	migration_plan_draft_ready_no_runtime_action
工具	scripts/security/telegram-notification-egress-migration-plan-draft.py
Snapshot	docs/security/telegram-notification-egress-migration-plan-draft.snapshot.json
Source snapshot	docs/security/telegram-notification-egress-owner-request-draft.snapshot.json
模式	metadata-only；不改 workflow、不改 script、不重構 API、不送 Telegram
runtime gate	0

1. 目的

Telegram 通知出口目前已完成三層只讀治理：

1. Inventory：固定 18 個 direct Bot API sendMessage call site。
2. Owner Request Draft：把 direct egress 檔案聚成 11 份人工送件前草稿。
3. Migration Plan Draft：把 11 份草稿排成三個遷移波次，定義 proposed target、owner response、maintenance window、rollback owner、delivery receipt 與 post-check。

這份文件只提供遷移計畫草稿，不代表可以直接修改 .gitea/workflows、scripts/ops 或 apps/api/src/services/channel_hub.py。

2. 固定數字

指標	數值	解讀
source_request_draft_count	11	來源 owner request draft 數
source_direct_bot_api_call_count	18	來源 direct Bot API call site
migration_candidate_count	11	每個 direct egress 檔案一個遷移候選
workflow_migration_candidate_count	6	Gitea workflow 候選
ops_script_migration_candidate_count	4	Ops script 候選
api_direct_migration_candidate_count	1	API sender 候選
proposed_wave_count	3	三個建議波次
plan_field_count	17	每個 candidate 的計畫欄位
reviewer_check_count	15	reviewer 必檢規則
outcome_lane_count	9	審查結果分流
blocked_action_count	21	草稿階段禁止動作

所有 owner response、migration authorized、workflow / script modification、API sender refactor、Telegram send、Bot API call、secret collection、raw payload storage、production write、runtime gate、action button 都維持 0 / false。

3. 建議波次

Wave	Scope	Proposed target	邊界
wave_1_workflow_notification_wrapper	6 個 Gitea workflow 檔案、13 個 direct send	scripts/ci/notify-awoooi-cicd.sh 或 AWOOI Alertmanager webhook	需 owner response、維護窗口、rollback owner、Gitea run / notification receipt post-check；不得直接改 workflow
wave_2_ops_notification_wrapper	4 個 ops script、4 個 direct send	scripts/ops/notify-awoooi-ops.sh 或 AWOOI Alertmanager webhook	需保留 API 離線情境的 break-glass fallback 決策；不得直接改 host script
wave_3_api_sender_gateway	apps/api/src/services/channel_hub.py 1 個 direct send	TelegramGateway final-exit formatter	需 API owner review、unit test、delivery receipt / mirror readback；不得直接重構 API sender

4. Reviewer checks

Reviewer 必須確認：

• source owner request draft 是目前版本。
• owner response、maintenance window、rollback owner、delivery receipt、post-check、redaction contract 與 no-false-green attestation 都存在。
• workflow change、script change、API sender refactor 都必須和本文件分離，另開 change evidence / runtime approval。
• 不收 secret value、hash、partial token、raw message payload 或未脫敏 log。
• 不把 CD success、route 200、UI 可見或 Telegram 送達當成 AI 自動化閉環完成。
• runtime gate 維持 0，直到有獨立人工批准與 post-check。

5. Outcome lanes

Lane	說明
draft_waiting_owner_response	尚未收到 owner response
ready_for_workflow_migration_review	workflow 類 metadata 完整，可進 migration review
ready_for_ops_script_migration_review	ops script 類 metadata 完整，可進 migration review
ready_for_api_sender_migration_review	API sender 類 metadata 完整，可進 migration review
request_missing_owner_response	缺 owner response
request_missing_maintenance_or_rollback	缺維護窗口或 rollback owner
reject_secret_or_raw_payload	收到 secret 或 raw payload 時拒收
reject_false_green_claim	false-green claim 時拒收
waiting_runtime_gate	metadata accepted 後仍等待 runtime gate

6. 禁止動作

此草稿階段禁止改 workflow、改 ops script、重構 API sender、送 Telegram、呼叫 Bot API、dispatch workflow、觸發 CD、production deploy、讀 secret store、收 secret value / hash / partial token、保存 raw payload / 未脫敏 log、改 chat route、改 Bot token、rotate secret、把 CD success / route 200 當 delivery receipt、開 runtime gate 或新增 action button。

7. 下一步

1. 等 owner response 補齊 11 個 candidate 的 route、message shape、redaction、receipt、maintenance、rollback 與 post-check。
2. 先做 workflow 類 migration review，但實作必須另開 change evidence / runtime approval，不在本草稿內執行。
3. Ops script 需先確認 API offline fallback 是否仍保留；若保留，必須有明確 break-glass reason 與 redacted message shape。
4. API sender 需由 channel_hub.py owner review 是否改走 TelegramGateway，並補 unit test / mirror readback。