ADR-037: Webcrumbs 共用 UI Runtime 接入

Status: Accepted Date: 2026-05-31

Context

momo-pro 的前端已進入 V2/V3 視覺治理階段，後續會需要更穩定的跨頁 UI 元件、microfrontend/plugin loader 與跨專案視覺實驗入口。Webcrumbs 可作為共用 UI runtime，但若各專案各自引用官方 CDN、使用 @latest，或把上游 repo 整包放進 momo-pro，會造成供應鏈、版本漂移、授權與生產可控性風險。

本專案目前仍以 Flask/Jinja 為正式 runtime，不能因導入外部 UI runtime 而繞過既有登入、CSRF、health check、部署與真實資料不退化紅線。

Decision

Webcrumbs 在 momo-pro 中只作為「自架、固定版本、可診斷」的共用 UI runtime/plugin loader，不作為主前端框架替代品。

採用以下規則：

runtime 由 WEBCRUMBS_* 環境變數設定，正式頁面預設指向 momo-pro 同源 /webcrumbs-assets/loader/webcrumbs-compatible-loader.js。
/webcrumbs-assets/ 只代理 allowlist prefix：loader/、plugins/、demo/，上游預設為 188 user-space Shared UI Hub http://192.168.0.188:18088。
ewoooc_base.html 只在 WEBCRUMBS_ENABLED=true 且 runtime URL 通過 http(s) 或同源絕對路徑檢查時輸出 script。
新增 /webcrumbs 診斷入口，顯示 runtime URL、版本、plugin base 與 asset upstream 狀態。
Webcrumbs plugin 必須使用自架且版本化 URI，例如 /webcrumbs-assets/plugins/<namespace>/<version>/。
禁止在生產使用官方 @latest、app.webcrumbs.ai 或未固定版本的官方 CDN。
不把 Webcrumbs 上游 repo 整包納入 momo-pro 主服務；若修改 runtime 本體，需另外處理 AGPL-3.0 授權義務。

Alternatives Considered

A. 每個頁面自行引用官方 Webcrumbs CDN

拒絕。版本不可控，且容易讓正式頁面受外部服務可用性與上游 breaking change 影響。

B. 把 Webcrumbs repo vendoring 到 momo-pro

拒絕。這會增加主服務體積、授權治理與升級成本，也會讓 UI runtime 與業務後端部署生命週期綁死。

C. 暫不接任何 runtime，只保留純 Jinja/CSS

保留作為 fallback，但不足以支援後續跨專案 microfrontend/plugin 化需求。導入 Webcrumbs 時仍維持現有 Jinja 頁面為主，不強制改寫。

Consequences

momo-pro 可在不替換 Flask/Jinja 的前提下，逐步嵌入自架 UI plugin。
生產部署需同步管理 WEBCRUMBS_* 變數與 Shared UI Hub asset upstream。
後續任何 Webcrumbs plugin 上線前，仍需通過真實資料、權限、RWD、效能與 fallback 檢查。
若 runtime URL 無效，系統只會跳過 script 載入並在 config warning / /webcrumbs 顯示狀態，不應阻斷主站。

2.7 KiB Raw Permalink Blame History Unescape Escape