# 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。