客戶機房出錯時，原廠不必到場也查得出原因 — 設計定案

狀態：設計定案（D1–D13 全數拍板）｜日期：2026-09-18｜前作：FR-071.0 錯誤追蹤試用（母卡 CM-1906） 討論稿（含選項與被排除方案的完整推演）：discussion.html 原白話需求：requirement-draft.md（2026-09-02）

🔴 這份是設計決策，不是現況。 內文的行號、筆數與待辦停在 2026-09-18 定稿當時，之後實作改動的結果不回頭改寫這裡——現況一律看 FINAL-SPEC.md（實作完成後產出）。

1.1 前一棒做完了什麼

FR-071.0（母卡 CM-1906）做的是「先接一套錯誤收集，看看實際效果值不值得往下做」：

本機接一套 Sentry 相容站台實測六項全過，決策者看過效果後拍板往下做正式落地（見 §3 定案 A～E）。

1.2 🔴 前提修正：出貨機跑的是 dev 那套 logging 設定

連帶推翻的三個結論（討論稿的洞一、D3 前段、風險七都以它們為前提）：

STG 實查的分佈（2026-09-18，guidant_ai 庫）：

等級分佈：INFO 585,875／ERROR 503／WARNING 126。真稽核事件只有幾百筆（階段推進 6082 268 筆、登入 4625 163 筆…）。

最新三筆是 app_mw.py 的 before_request 印的 Request Body／Request Headers／API Request: GET /healthz——每一個請求（含每次健康檢查）固定寫三筆 INSERT 進資料庫，而且請求標頭裡的 Authorization 未遮罩就進了 DB。

1.3 這一棒要補的洞（修正後）

1.4 端到端流程

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant U as 客戶使用者
    participant BE as Guidant AI 後端
    participant L as log 檔／存取紀錄表
    participant GT as 外部錯誤收集站（選配）
    participant OP as 客戶管理員／到場工程師
    participant HQ as 原廠
    participant AI as 乾淨的 AI 對話

    U->>BE: 操作某功能
    BE->>BE: 產生追蹤編號 req-xxxx
    BE->>L: 每一行 log 都帶 req-xxxx
    BE->>BE: 炸了（5xx）
    BE->>L: 存取紀錄該筆標 ERROR，帶 req-xxxx
    BE->>GT: 送錯誤事件（有接站台時：堆疊＋變數值＋req-xxxx）
    BE-->>U: 回錯誤，標頭帶 X-Request-ID: req-xxxx

    Note over U,OP: 客戶回報「剛剛按下去就壞了」

    alt 一線先瞄一眼
        OP->>BE: 系統設定 → 支援 → 看最近 N 筆 ERROR
    end

    alt 客戶自己來（畫面）
        OP->>BE: 系統設定 → 支援 → 選時間範圍 → 匯出
        BE-->>OP: 下載 guidant-diag-*.tar.gz
    else 到場或 ssh（指令）
        OP->>OP: sudo guidant diag --since 2h
    end

    Note over OP,HQ: 客戶把包傳給原廠（不做自動回傳）

    OP->>HQ: 傳檔
    HQ->>AI: 只給「包 ＋ 原始碼倉庫」
    AI->>AI: 讀 manifest.json 知道每個檔是什麼
    AI->>AI: 用 commit hash 把原始碼切到同一版
    AI->>AI: 用 req-xxxx 把 log／存取紀錄／錯誤事件串起來
    AI-->>HQ: 指出根本原因與修法

追蹤編號在四個地方出現（這就是「串得起來」的全部機制）：

1.5 誰碰什麼（角色邊界）

決策者定調：客戶端的人不碰 Linux、不碰 docker。

檔案 log 是診斷包的原料，不是給客戶看的東西——所以本案不做「log 檢視畫面」，也不把 system_logs 做成一個選單頁（見 §3 D11 的排除理由）。

整案一句話：讓客戶機房裡發生的錯誤留得下完整證據，並且能被打包帶回原廠分析——原廠不必到場、客戶不必會下指令。

給非工程讀者的背景：軟體出錯時，工程師要的東西有三樣——錯在程式的哪一行（堆疊）、當時使用者在做什麼（那一次請求的內容）、當下資料長什麼樣（資料庫的相關資料）。這三樣現在都在客戶的機器裡，而且各自散著、對不起來。本案把它們串成一條線，再做一個「打包帶走」的功能。

依賴：①是地基；②可與①完全平行（兩條不同的線）；③要等①的 T-1.3 完成（沒有等級與編號就切不出東西）；④與③共用同一支打包核心，③的 T-3.1 完成後開工。

前置定案（A–E，決策者 2026-09-17）

D1 — log 與事件各保留多久

D2 — 追蹤編號在哪裡產生、長什麼樣

D3 — system_logs 怎麼處置

D4 — 收集站台自己的資料庫與 Redis

D5 — 打包核心放哪

D6 — 畫面版匯出的包要不要含錯誤事件

D7 — 診斷包要不要加密

D8 — 前端版本識別要不要這一棒補

D9 — 錯誤事件的節流值

D10 — 診斷包大小上限

D11 — 支援頁要不要直接列最近的錯誤

D12 — log 表的分區維護怎麼排程

事實（2026-09-18 實查）：api_logs 與 system_logs 已按月分區（scripts/sql/2026-06-03-log-tables-partitioning.sql），維護函式 public.maintain_log_partitions() 存在且功能完整（建本月～+2 月分區 ＋ DROP 超過 retention 的舊分區）。但它只在裝機時 scripts/init/99-stamp.sql:201 跑一次，之後沒有任何人呼叫——沒裝 pg_cron（該 migration 的檔頭註解自己寫了「排程未接」）、BE 也沒有對應排程。

STG 實查：分區只建到 2026_10。2026 年 11 月之後的新資料會全部掉進 _default 分區（分區失去意義，查詢退化成全表掃），而舊分區永遠不會被砍（retention 形同虛設，磁碟只增不減）。

D13 — 錯誤收集站台要不要進出貨包

追加子任務（不是決策，是本次補上的工作項）

5.1 log 設定的最終形狀

三份設定檔（config_dev / config_stg / config_prod）之間目前的差異是歷史殘留，不是刻意的環境取捨：prod／stg 把檔案輸出註解掉、去掉資料庫輸出、去掉 otel 欄位，而這三份從未在任何機器上生效過。

本案的處置：

5.2 追蹤編號中介層

產生（app_mw.py 的 before_request，在現有的 g.start_time 之後）：

上游帶了 X-Request-ID → 沿用（取前 64 字元，過白名單字元）
沒帶 → req-<uuid4().hex[:8]>
存進 g.request_id

四個去處：

背景排程：core/scheduler.py 的各支排程沒有 request context。每次排程執行產一個 job-<排程名>-<8 hex>，用 context var 而非 g（g 需要 app context）。

5.3 5xx 的脈絡行

現況 handler.py:33 只有 logger.error(f"Error in {類別}: {例外}", exc_info=True)。堆疊有了，但不知道是誰、打了哪支、送了什麼——而這三樣正是重建現場的必要條件。

補成一行結構化 JSON（堆疊仍照原樣多行輸出，JSON 那行是它的前導脈絡行）：

{"request_id": "req-3f8a2c1b", "method": "POST", "path": "/api/1.0/xxx",
 "user": "someone", "body": "<遮罩後>", "exc": "KeyError"}

5.4 診斷包的內容

guidant-diag-20260918-143022.tar.gz
├── manifest.json              ← 先讀這個：每個檔是什麼、時間範圍、產包當下的狀態
├── env/
│   ├── version.json           ← 版號 ＋ commit hash（分析端切原始碼用）
│   ├── guidant.env.masked     ← 設定檔，所有密碼金鑰已遮罩
│   ├── docker-ps.txt          ← 哪些服務在跑、跑多久、重啟過幾次
│   ├── docker-stats.txt       ← 記憶體 CPU 用量
│   ├── disk.txt               ← 磁碟餘量
│   ├── migration.txt          ← 資料庫改版水位（schema_migrations）
│   └── license.txt            ← 授權狀態（不含金鑰）
├── logs/
│   ├── app.log.slice          ← 應用 log 指定時間範圍切片（完整堆疊）
│   └── docker-<服務名>.log    ← 各容器記錄尾段
├── db/
│   ├── api_logs.csv           ← 存取紀錄時間範圍切片（含追蹤編號、等級）
│   ├── system_logs.csv        ← 稽核事件與 ERROR（D3 之後這張表只剩這兩種）
│   ├── row-counts.csv         ← 各表筆數（判斷資料規模用）
│   └── schema-notes.md        ← 上述每個檔的欄位說明
└── events/
    └── glitchtip-events.json  ← 錯誤事件（有接外部收集站時；沒接或拿不到時 manifest 註明）

manifest.json 是分析端的入口，欄位至少要有：

各項資料怎麼取：

5.5 兩支端點與支援頁

守門（兩支相同，照 FR-110／FR-107 的既有做法）：

• 路由只掛 @jwt_required
• 守門下沉到 app service 層，呼叫 require_platform_admin()（軸①，common/authz/platform.py → jedi_iam.authz.platform）
• 選單能力點沿用既有的系統設定那顆，不新開——新開一顆要 seed 到每個既有租戶的管理員角色，漏掉的症狀是那個租戶永遠 403 且沒有任何錯誤訊息

支援頁版面（系統設定 → 支援，pid=47、sort=40）：

5.6 遮罩管線

一條管線、兩個入口共用（指令版與畫面版各寫一套就是兩套真相的起點）。

5.7 錯誤追蹤 SDK 接線

產品出的是接線，不是站台（D13）。連線字串（DSN）留空時整支不啟用——後端不 import SDK，前端連 @sentry/vue 都不下載。設了值就把錯誤事件送往該位址，不管那是客戶自架的 GlitchTip、客戶自己的 Sentry、或未來雲端版的集中站。

後端初始化（core/plugins/api_log.py 的 init_error_tracking()，呼叫 jedi-log 的 error_tracking/）：

送出前的三道處理（順序固定）：

前端怎麼拿到 DSN：前端是「一顆 image 賣所有客戶」，Vite 的環境變數在建置時就烙進產物，裝機腳本無法為每個客戶寫入各自的站台位址。因此出貨路徑改成執行期向後端取：

• 免認證是必要的：這支要在任何頁面、登入前就跑得起來——登入頁自己出錯時尤其需要
• 未設定時回空字串，不回 null 也不回 404：前端一律走同一條路（拿到空字串＝不啟用）；用狀態碼區分會讓「沒設定」與「端點壞了」長得一樣
• 不新增環境變數：這支只是把後端已有的 SENTRY_DSN 讀出來給前端
• 前端三種情況：建置時有烙 VITE_SENTRY_DSN → 直接用（開發機接法不變）；沒烙 → 打端點取；端點拿不到或值為空 → 當作沒設定，靜默不啟用（不報錯、不噴紅）

前端版本識別（D8）：建置時注入 VITE_APP_RELEASE，格式 guidant-ai-fe@<版號>+<commit>，與後端的 guidant-ai@<版號>+<commit> 對齊——前後端事件要在站台上串成同一條，一邊有版本一邊沒有就看不出是哪一版的組合。

追蹤標頭傳遞：前端開 browserTracingIntegration 並設 tracePropagationTargets 涵蓋 API 的 host。沒有它就不會產生 trace、追蹤標頭也不會送出，前後端錯誤永遠串不成同一條；API 走絕對網址時只寫 /^\/api\// 會漏掉。

依賴鏈：FR-071.1（log 地基）∥ FR-071.2（SDK 接線）→ FR-071.3（指令版）→ FR-071.4（支援頁），最後 .5 收口。

「動套件」欄標示該子任務是否觸及 jedi-common / jedi-log——動套件的一律走 poetry path dependency，不發版；feature 完成後還原 pin 一起 commit，且驗收要在 pin 還原後重打一次。

FR-071.1 log 地基 — 依賴：無（可與 .2 完全平行）

FR-071.2 錯誤追蹤 SDK 接線 — 依賴：無（可與 .1 完全平行）

②那一棒的出貨側子任務（T-2.2～T-2.5、T-2.7）已取消，見 D13 與 CM-1944：站台不進出貨包，compose 維持六常駐服務＋db-init，安裝包不收站台映像，維運指令沒有站台相關子命令。SDK 側的 T-2.6／T-2.8 保留並已完成。

FR-071.3 指令版診斷包 — 依賴：FR-071.1 的 T-1.3

FR-071.4 支援頁（ERROR 列表 ＋ 匯出） — 依賴：FR-071.3 的 T-3.1

FR-071.5 收口

序列摘要：.1 內部 T-1.1 → T-1.2 → {T-1.3, T-1.4, T-1.7, T-1.8}，T-1.5／T-1.6／T-1.9 可與它們平行（T-1.9 只依賴 T-1.1）；.2 的 T-2.6／T-2.8 全程可平行；.3 等 T-1.3；.4 等 T-3.1，T-4.4 全程可平行。

決策者 2026-09-18 裁定：POC 就用出貨設定 RUN_ENV=prod，不為了「怕問題多」留在 dev——留得住 log、錯誤看得到這兩件 prod 都有；dev 多出來的只是每個請求三筆 INSERT 進 DB 的垃圾。POC 等同 production，一開始就用出貨設定，驗的才是客戶會拿到的東西。「怕問題」時該放寬的是下面這幾個旋鈕，全部用環境變數開，不動程式：

第一版問題多時的查法是支援頁的 ERROR 列表 ＋ 匯出診斷包——這兩樣不依賴任何外部站台。

全部在 DEV 做（環境異動鐵律：不碰 STG／POC）。

各子需求的決策者親手檢查法