shipping-and-launch

上線與發布

概述

安心發布。目標不只是部署——而是安全地部署，有監控機制、準備好回退計畫，並清楚了解成功的樣貌。每次發布都應可逆、可觀察，且逐步進行。

使用時機

• 首次將功能部署到正式環境
• 向使用者發布重大變更
• 遷移資料或基礎設施
• 開啟 Beta 或早期存取計畫
• 任何有風險的部署（所有部署都有風險）

上線前檢查清單

程式碼品質

• [ ] 所有測試通過（單元測試、整合測試、端對端測試）
• [ ] 建置成功且無警告
• [ ] Lint 與型別檢查通過
• [ ] 程式碼已審查並核准
• [ ] 沒有應在上線前解決的 TODO 註解
• [ ] 正式環境程式碼中沒有 console.log 除錯陳述式
• [ ] 錯誤處理涵蓋預期的失敗模式

安全性

• [ ] 程式碼或版本控制中沒有機密資訊
• [ ] npm audit 顯示無重大或高風險漏洞
• [ ] 所有面向使用者的端點都有輸入驗證
• [ ] 已設置身分驗證與授權檢查
• [ ] 已設定安全標頭（CSP、HSTS 等）
• [ ] 身分驗證端點有速率限制
• [ ] CORS 設定為特定來源（非萬用字元）

效能

• [ ] 核心網頁指標在「良好」閾值內
• [ ] 關鍵路徑沒有 N+1 查詢
• [ ] 圖片已最佳化（壓縮、響應式尺寸、延遲載入）
• [ ] 套件大小在預算內
• [ ] 資料庫查詢有適當的索引
• [ ] 靜態資源與重複查詢已設定快取

無障礙

• [ ] 所有互動元素支援鍵盤導航
• [ ] 螢幕閱讀器能傳達頁面內容與結構
• [ ] 色彩對比符合 WCAG 2.1 AA（文字 4.5:1）
• [ ] 焦點管理在模態框與動態內容中正確
• [ ] 錯誤訊息具描述性且與表單欄位關聯
• [ ] axe-core 或 Lighthouse 中無無障礙警告

基礎設施

• [ ] 正式環境的環境變數已設定
• [ ] 資料庫遷移已套用（或準備套用）
• [ ] DNS 與 SSL 已設定
• [ ] CDN 已為靜態資源設定
• [ ] 日誌與錯誤回報已設定
• [ ] 健康檢查端點存在且正常回應

文件

• [ ] README 已更新任何新的設定需求
• [ ] API 文件為最新
• [ ] 任何架構決策已撰寫 ADR
• [ ] 更新日誌已更新
• [ ] 面向使用者的文件已更新（若適用）

功能開關策略

透過功能開關發布，將部署與釋出分離：

// 功能開關檢查
const flags = await getFeatureFlags(userId);

if (flags.taskSharing) {
  // 新功能：任務分享
  return <TaskSharingPanel task={task} />;
}

// 預設：既有行為
return null;

功能開關生命週期：

1. 部署時開關關閉     → 程式碼在正式環境中但未啟用
2. 為團隊/Beta 啟用     → 在正式環境中進行內部測試
3. 逐步發布          → 5% → 25% → 50% → 100% 的使用者
4. 每個階段監控      → 觀察錯誤率、效能、使用者回饋
5. 清理              → 全面發布後移除開關與死路徑

規則：

• 每個功能開關都有負責人與到期日
• 全面發布後兩週內清理開關
• 不要巢狀嵌套功能開關（會產生指數級組合）
• 在 CI 中測試開關的兩種狀態（開啟與關閉）

分階段發布

發布順序

1. 部署到測試環境
   └── 在測試環境中執行完整測試套件
   └── 手動冒煙測試關鍵流程

2. 部署到正式環境（功能開關關閉）
   └── 確認部署成功（健康檢查）
   └── 檢查錯誤監控（無新錯誤）

3. 為團隊啟用（開關對內部使用者開啟）
   └── 團隊在正式環境中使用功能
   └── 24 小時監控窗口

4. 金絲雀發布（開關對 5% 使用者開啟）
   └── 監控錯誤率、延遲、使用者行為
   └── 比較指標：金絲雀 vs. 基準線
   └── 24-48 小時監控窗口
   └── 僅在所有閾值通過時才前進（見下表）

5. 逐步增加（25% -> 50% -> 100%）
   └── 每個步驟相同監控
   └── 可隨時回退到先前的百分比

6. 全面發布（開關對所有使用者開啟）
   └── 監控一週
   └── 清理功能開關

發布決策閾值

使用這些閾值來決定在每個階段是否前進、暫停或回退：

指標	前進（綠燈）	暫停調查（黃燈）	回退（紅燈）
錯誤率	在基準線的 10% 以內	高於基準線 10-100%	超過基準線 2 倍
P95 延遲	在基準線的 20% 以內	高於基準線 20-50%	高於基準線 50% 以上
用戶端 JS 錯誤	無新錯誤類型	新錯誤低於 0.1% 工作階段	新錯誤高於 0.1% 工作階段
業務指標	持平或正向	下降 <5%（可能為雜訊）	下降 >5%

何時回退

若出現以下情況，立即回退：

• 錯誤率增加超過基準線 2 倍
• P95 延遲增加超過 50%
• 使用者回報的問題激增
• 發現資料完整性問題
• 發現安全漏洞

監控與可觀測性

監控項目

應用程式指標：
├── 錯誤率（總計與按端點）
├── 回應時間（p50、p95、p99）
├── 請求量
├── 活躍使用者
└── 關鍵業務指標（轉換率、參與度）

基礎設施指標：
├── CPU 與記憶體使用率
├── 資料庫連線池使用量
├── 磁碟空間
├── 網路延遲
└── 佇列深度（若適用）

用戶端指標：
├── 核心網頁指標（LCP、INP、CLS）
├── JavaScript 錯誤
├── 從用戶端視角的 API 錯誤率
└── 頁面載入時間

錯誤回報

// 設定含回報的錯誤邊界
class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    // 回報到錯誤追蹤服務
    reportError(error, {
      componentStack: info.componentStack,
      userId: getCurrentUser()?.id,
      page: window.location.pathname,
    });
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback onRetry={() => this.setState({ hasError: false })} />;
    }
    return this.props.children;
  }
}

// 伺服器端錯誤回報
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  reportError(err, {
    method: req.method,
    url: req.url,
    userId: req.user?.id,
  });

  // 不要向使用者暴露內部資訊
  res.status(500).json({
    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
  });
});

發布後驗證

發布後的第一小時內：

1. 檢查健康端點是否回傳 200
2. 檢查錯誤監控儀表板（無新錯誤類型）
3. 檢查延遲儀表板（無回歸）
4. 手動測試關鍵使用者流程
5. 確認日誌正常輸出且可讀
6. 確認回退機制可運作（若可能，進行乾執行）

回退策略

每次部署都需要在事前準備好回退計畫：

## [功能/版本] 的回退計畫

### 觸發條件
- 錯誤率 > 基準線 2 倍
- P95 延遲 > [X] 毫秒
- 使用者回報 [特定問題]

### 回退步驟
1. 停用功能開關（若適用）
   或
1. 部署先前版本：`git revert <commit> && git push`
2. 驗證回退：健康檢查、錯誤監控
3. 溝通：通知團隊回退

### 資料庫考量
- 遷移 [X] 有回退：`npx prisma migrate rollback`
- 新功能插入的資料：[保留 / 清理]

### 回退時間
- 功能開關：< 1 分鐘
- 重新部署先前版本：< 5 分鐘
- 資料庫回退：< 15 分鐘

參見

• 關於專案層級的「完成定義」，所有變更在通過此檢查清單前都必須滿足，請參閱 references/definition-of-done.md
• 關於安全上線前檢查，請參閱 references/security-checklist.md
• 關於效能上線前檢查清單，請參閱 references/performance-checklist.md
• 關於上線前的無障礙驗證，請參閱 references/accessibility-checklist.md

常見合理化藉口

合理化藉口	現實
「在測試環境沒問題，正式環境也沒問題」	正式環境有不同的資料、流量模式與邊界案例。部署後要監控。
「這個功能不需要功能開關」	每個功能都受益於一個緊急停止開關。即使是「簡單」的變更也可能出錯。
「監控是額外負擔」	沒有監控意味著你從使用者抱怨而不是儀表板發現問題。
「我們之後再加監控」	在上線前就加上。你看不到的東西就無法除錯。
「回退就是承認失敗」	回退是負責任的工程。發布有問題的功能才是失敗。

紅旗警示

• 沒有回退計畫就部署
• 正式環境中沒有監控或錯誤回報
• 大爆炸式發布（一次全部，沒有測試環境）
• 功能開關沒有到期日或負責人
• 部署後第一小時無人監控
• 正式環境設定靠記憶而非程式碼
• 「現在是星期五下午，我們發布吧」

驗證

部署前：

• [ ] 上線前檢查清單完成（所有章節綠燈）
• [ ] 功能開關已設定（若適用）
• [ ] 回退計畫已文件化
• [ ] 監控儀表板已設定
• [ ] 團隊已收到部署通知

部署後：

• [ ] 健康檢查回傳 200
• [ ] 錯誤率正常
• [ ] 延遲正常
• [ ] 關鍵使用者流程正常運作
• [ ] 日誌正常輸出
• [ ] 回退已測試或確認就緒