# 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，不作為主前端框架替代品。

採用以下規則：

1. runtime 由 `WEBCRUMBS_*` 環境變數設定，正式頁面預設指向 momo-pro 同源 `/webcrumbs-assets/loader/webcrumbs-compatible-loader.js`。
2. `/webcrumbs-assets/` 只代理 allowlist prefix：`loader/`、`plugins/`、`demo/`，上游預設為 188 user-space Shared UI Hub `http://192.168.0.188:18088`。
3. `ewoooc_base.html` 只在 `WEBCRUMBS_ENABLED=true` 且 runtime URL 通過 http(s) 或同源絕對路徑檢查時輸出 script。
4. 新增 `/webcrumbs` 診斷入口，顯示 runtime URL、版本、plugin base 與 asset upstream 狀態。
5. Webcrumbs plugin 必須使用自架且版本化 URI，例如 `/webcrumbs-assets/plugins/<namespace>/<version>/`。
6. 禁止在生產使用官方 `@latest`、`app.webcrumbs.ai` 或未固定版本的官方 CDN。
7. 不把 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` 顯示狀態，不應阻斷主站。