84 lines
5.3 KiB
Markdown
84 lines
5.3 KiB
Markdown
# 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。
|