Deprecation Plan · 廢棄計畫

---
doc_type: "deprecation-plan"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["access-log", "endpoint-inventory"]
  optional: ["consumer-contact-list"]
---

# Deprecation Plan: <surface-name>

**Status:** Draft v0.X · **Owner:** <Architect / PO> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 3, 5, 7, 9），全部必填——刻意沿用完整版章節編號讓兩版可對照。每結論行內加 `（依據：log §XXX）`；每量化欄位帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造；最短公告期 90 天；caller 無法識別寫 `unknown_caller` 並列追查方式不假設；必須有 rollback 段（不准設「強制下線無例外」）。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行，主管 30 秒讀完。內容：要下架什麼、為何下架、何時 disable、有多少 affected caller -->

<3-5 行說明>

> **TL;DR:** <一句話：N 月內下架 X surface，影響 Y 個 caller，替代為 Z>

---

## 2. Deprecated Surface & Replacement

<!-- ai-rule: replacement_path 必須具體；feature_parity 為 partial / breaking_changes 必須列差異 -->

| Field | Value | Confidence |
|---|---|---|
| **Deprecated surface** | <e.g. GET /api/v1/users> | — |
| **Reason** | <為何下架> | **[H]** |
| **Replacement** | <e.g. GET /api/v2/users> | — |
| **Feature parity** | full / partial / breaking_changes | **[H]** |
| **Migration guide** | <link or `_TODO_`> | — |

### Breaking changes（若有）

- <change 1>
- <change 2>

---

## 3. Sunset Timeline

<!-- ai-rule: 總天數 ≥ 90；每個 phase 必須有日期；無合約資料時公告期需保守取上限 -->

| Phase | Date (ISO) | Trigger / Behaviour |
|---|---|---|
| **Announce** | YYYY-MM-DD | 公告 + status page |
| **Warning phase** | YYYY-MM-DD | 開始回傳 `Deprecation` header |
| **Read-only** | YYYY-MM-DD | 拒絕新 client |
| **Disable (soft)** | YYYY-MM-DD | 軟下線（保留快速回滾） |
| **Remove (hard)** | YYYY-MM-DD | 程式碼移除 |
| **Total days** | ≥ 90 | — |

---

## 5. Affected Consumers（top callers）

<!-- ai-rule: 列出 top callers（≥ 80% 流量）；unknown_caller bucket 必填即使 0 -->

| Caller | Tier | Req/30d | Contact | Migration ETA | Confidence |
|---|---|---|---|---|---|
| <org-a> | enterprise | 12k | a@x.com | YYYY-MM-DD | **[H]** |
| <unknown_caller bucket> | unknown | 800 | _TODO: 反查 IP/UA_ | _TODO_ | **[L]** |

---

## 7. Success Criteria & Rollback

<!-- ai-rule: 三條 metric 必填；rollback window ≥ 14d -->

| Metric | Target |
|---|---|
| **Caller count at disable** | 0 unknown + ≤ 5 known approved |
| **Traffic share at disable** | ≤ 0.1% of baseline |
| **Rollback window** | ≥ 14d, ≤ 1h to re-enable |

---

## 9. Decision Log（key 2-3 條）

<!-- ai-rule: 每條必含 chosen + 至少 1 個 rejected + 拒絕原因 -->

| Date | Decision | Options | Chosen | Rejected why | Confidence |
|---|---|---|---|---|---|
| YYYY-MM-DD | 公告期 90d vs 180d | 60d / 90d / 180d | 90d | 60d (違反合約 30d + 採購週期)、180d (延誤新版 ROI) | **[H]** |

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 3, 5, 7, 9）
> - [ ] Sunset timeline 含 5 個 phase + 總天數 ≥ 90
> - [ ] unknown_caller bucket 必填（即使 0）+ 附追查方法
> - [ ] Affected consumer 表覆蓋 ≥ 80% 流量
> - [ ] Success criteria 含 caller count + traffic share + rollback window
> - [ ] Rollback window ≥ 14d
> - [ ] Decision Log ≥ 1 條，每條有 rejected reason
> - [ ] 無 YAML / JSON schema 輸出