73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# Webcrumbs 共用 UI Runtime 接入手冊
|
||
|
||
> 目的：讓 momo-pro 與其他專案共用同一套自架 Webcrumbs microfrontend runtime，避免每個專案各自引用官方 CDN 或複製 runtime。
|
||
|
||
## 定位
|
||
|
||
- Webcrumbs 在本專案只作為 microfrontend/plugin loader。
|
||
- 不把 Webcrumbs 上游 repo 整包放進 momo-pro 主服務。
|
||
- 不依賴官方 `app.webcrumbs.ai` 或官方 `cdn.webcrumbs.dev/@latest`。
|
||
- 生產環境必須走自架 runtime，並固定版本。
|
||
|
||
## momo-pro 設定
|
||
|
||
`.env` 建議值：
|
||
|
||
```env
|
||
WEBCRUMBS_ENABLED=true
|
||
WEBCRUMBS_BASE_URL=https://webcrumbs.wooo.work
|
||
WEBCRUMBS_RUNTIME_VERSION=shared-ui-poc-0.1.0
|
||
WEBCRUMBS_RUNTIME_PATH=/webcrumbs-assets/loader/webcrumbs-compatible-loader.js
|
||
WEBCRUMBS_RUNTIME_URL=
|
||
WEBCRUMBS_PLUGIN_BASE_URL=/webcrumbs-assets/plugins
|
||
WEBCRUMBS_ASSET_UPSTREAM_URL=http://192.168.0.188:18088
|
||
```
|
||
|
||
目前正式頁面預設走 momo-pro 同源 asset proxy：
|
||
|
||
- `/webcrumbs-assets/loader/...`
|
||
- `/webcrumbs-assets/plugins/...`
|
||
- `/webcrumbs-assets/demo/...`
|
||
|
||
這樣即使 `webcrumbs.wooo.work` 的公網 TLS 或 Basic Auth 尚未完全收斂，momo-pro 頁面仍可用 `mo.wooo.work` 同源載入 loader 與 plugin。若日後要改回獨立 Webcrumbs CDN，直接設定：
|
||
|
||
```env
|
||
WEBCRUMBS_RUNTIME_URL=https://webcrumbs.wooo.work/shared-ui/loader/webcrumbs-compatible-loader.js
|
||
WEBCRUMBS_PLUGIN_BASE_URL=https://webcrumbs.wooo.work/shared-ui/plugins
|
||
```
|
||
|
||
## 頁面嵌入方式
|
||
|
||
全站 runtime 由 `templates/ewoooc_base.html` 載入。頁面只需要放 plugin tag：
|
||
|
||
```html
|
||
<stock-platform-plugin uri="/webcrumbs-assets/plugins/finance.market-ticker-strip/0.1.0"></stock-platform-plugin>
|
||
```
|
||
|
||
Plugin 目錄至少應提供：
|
||
|
||
```text
|
||
bundle.js
|
||
style.css
|
||
```
|
||
|
||
## 治理規則
|
||
|
||
- Plugin URI 必須使用自架 domain。
|
||
- 在 momo-pro 正式頁面，優先使用同源 `/webcrumbs-assets/` URI。
|
||
- Plugin 目錄必須版本化，不使用浮動 `latest`。
|
||
- Plugin 不得包含 secret、token、內部 API key。
|
||
- Plugin 若需要正式資料，必須讀 momo-pro 既有 API，不得自行打 DB。
|
||
- 修改 Webcrumbs runtime 本體時需注意 AGPL-3.0 授權義務。
|
||
|
||
## 驗收
|
||
|
||
- `/webcrumbs` 顯示 runtime URL、版本與 plugin base。
|
||
- `/webcrumbs` 會嵌入同源 `/webcrumbs-assets/plugins/...` 的 live plugin preview，並由 momo-pro 注入只讀 MOMO/PChome exact 價差摘要；若資料源不可用或無風險候選，改注入診斷空狀態，避免 plugin fallback demo 數字在正式頁面被誤認成真實市場或 AI 建議。
|
||
- `/api/webcrumbs/marketplace-host-data` 會回傳同一份登入後只讀 host data contract，供 plugin / QA / 其他專案 proxy 驗證；即使全站 `DISABLE_LOGIN=true`，此 API 仍必須要求登入 session 或 `X-Internal-Key`，boundary 必須標示 `writes_database=false`、`calls_llm=false`、`fetches_external=false`。
|
||
- Host data metadata 需同時輸出 `matched_count/coverage_rate` 與 `fresh_match_count/fresh_match_rate/stale_match_count/pending_match_count`，讓共用 UI 分清「身份覆蓋」與「價格新鮮度」。
|
||
- `/webcrumbs` 未取得登入 session 或 `X-Internal-Key` 時只能注入 `auth_required` 空狀態，不得把真實 SKU、價格或價差寫進 inline seed data。
|
||
- `/webcrumbs-assets/loader/webcrumbs-compatible-loader.js` 回 200 且 content type 是 JavaScript。
|
||
- `ewoooc_base.html` 在 `WEBCRUMBS_ENABLED=true` 且 runtime URL 有效時輸出 `<script data-webcrumbs-runtime=...>`。
|
||
- 任一試點頁嵌入 plugin 後，瀏覽器 console 不應有 `MISSING_URI`、`STYLE_LOAD_ERROR`、`SCRIPT_LOAD_ERROR`。
|