# 更新文件 (Update Documentation)

將文件與程式碼庫保持同步，並從「單一事實來源」(source-of-truth) 檔案中自動生成。

## 步驟 1：識別事實來源 (Sources of Truth)

| 來源 | 生成內容 |
|--------|-----------|
| `package.json` 中的腳本 | 可用指令參考 |
| `.env.example` | 環境變數文件 |
| `openapi.yaml` / 路由檔案 | API 端點參考 |
| 原始碼匯出 (Exports) | 公共 API 文件 |
| `Dockerfile` / `docker-compose.yml` | 基礎設施設定文件 |

## 步驟 2：生成腳本參考 (Script Reference)

1. 讀取 `package.json` (或 `Makefile`, `Cargo.toml`, `pyproject.toml`)
2. 擷取所有腳本/指令及其描述
3. 生成參考表格：

```markdown
| 指令 | 描述 |
|---------|-------------|
| `npm run dev` | 啟動具備熱重載功能的開發伺服器 |
| `npm run build` | 進行帶有型別檢查的生產環境建置 |
| `npm test` | 執行帶有覆蓋率報告的測試套件 |
```

## 步驟 3：生成環境變數文件

1. 讀取 `.env.example` (或 `.env.template`, `.env.sample`)
2. 擷取所有變數及其用途
3. 分類為「必填」與「選填」
4. 記錄預期格式與有效值

```markdown
| 變數 | 是否必填 | 描述 | 範例 |
|----------|----------|-------------|---------|
| `DATABASE_URL` | 是 | PostgreSQL 連接字串 | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | 否 | 日誌詳細程度 (預設：info) | `debug`, `info`, `warn`, `error` |
```

## 步驟 4：更新貢獻指南 (Contributing Guide)

生成或更新 `docs/CONTRIBUTING.md`，包含：
- 開發環境設定 (先決條件、安裝步驟)
- 可用腳本及其用途
- 測試程序 (如何執行、如何撰寫新測試)
- 程式碼風格強制執行 (Linter, Formatter, Pre-commit hooks)
- PR 提交清單

## 步驟 5：更新維運手冊 (Runbook)

生成或更新 `docs/RUNBOOK.md`，包含：
- 佈署程序 (逐步指引)
- 健康檢查端點與監控
- 常見問題及其解決方案
- 回滾程序 (Rollback)
- 告警與呈報路徑

## 步驟 6：陳舊度檢查 (Staleness Check)

1. 找出超過 90 天未修改的文件檔案
2. 與最近的原始碼變更進行交叉比對
3. 將可能過期的文件標記為需要手動審查

## 步驟 7：顯示摘要

```
文件更新摘要
──────────────────────────────
已更新：  docs/CONTRIBUTING.md (腳本表格)
已更新：  docs/ENV.md (新增 3 個變數)
標記：    docs/DEPLOY.md (已陳舊 142 天)
跳過：    docs/API.md (未偵測到變更)
──────────────────────────────
```

## 規則

- **單一事實來源**：始終從程式碼生成，切勿手動編輯生成的區塊。
- **保留手動區塊**：僅更新生成的區塊；保留手寫的說明文字。
- **標註生成內容**：在生成的區塊前後使用 `<!-- AUTO-GENERATED -->` 標記。
- **不要擅自建立新文件**：除非指令明確要求，否則不要建立新的文件檔案。