# HTML 閱讀版維護

主要讀者：文件維護者。

`build.mjs` 從八份 Markdown、OpenAPI 與 `biz-bdd/` 產生閱讀版；不要直接修改產出的 HTML 或 `style.css`。版型樣式修改 `reader.css`，圖片互動修改 `viewer.js`／`viewer.html`。OpenAPI 閱讀介面由 `openapi.mjs` 產生，外框高度由 `openapi-host.js` 管理，內部樣式與互動在 `openapi/reference.css`／`openapi/reference.js`。BPMN 圖面不因版型換色。

## 1 依賴與建置

`SA_TOOL_MODULES` 指向既有 `node_modules`，需含 `marked`、`mermaid` 與 `puppeteer`。`BDD_TOOL_MODULES` 指向含 `@cucumber/gherkin` 42.0.1 與 `@cucumber/messages` 34.2.1 的目錄；若省略則沿用 `SA_TOOL_MODULES`。可將新增工具安裝到獨立暫存目錄，不修改業務專案依賴：

```bash
npm install --prefix /tmp/sa-bdd-tools --ignore-scripts --no-audit --no-fund @cucumber/gherkin@42.0.1 @cucumber/messages@34.2.1 yaml@2.8.1
SA_TOOL_MODULES=/path/to/render/node_modules BDD_TOOL_MODULES=/tmp/sa-bdd-tools/node_modules node sa_specs/pages/build.mjs
```

`OPENAPI_TOOL_MODULES` 指向含 `yaml` 2.8.1 的套件目錄；省略時依序沿用 `BDD_TOOL_MODULES`、`SA_TOOL_MODULES`。可用 `npm install --prefix /tmp/sa-openapi-tools --ignore-scripts --no-audit --no-fund yaml@2.8.1` 安裝，再於建置命令加上 `OPENAPI_TOOL_MODULES=/tmp/sa-openapi-tools/node_modules`。

閱讀版自帶 Bootstrap 5.3.8 與 Swagger UI 5.34.0，見 [資源與授權](vendor/README.md)。開啟 HTML 不需要網路、Node.js 或 Cucumber；上述依賴只供重建與檢查使用。Mermaid 有來源雜湊快取，圖面未改時不會再次啟動瀏覽器。

## 2 檢查

```bash
BDD_TOOL_MODULES=/tmp/sa-bdd-tools/node_modules node sa_specs/pages/bdd.mjs --check
python3 sa_specs/pages/verify.py
SA_TOOL_MODULES=/path/to/render/node_modules node sa_specs/pages/check-ui.mjs
SA_TOOL_MODULES=/path/to/render/node_modules OPENAPI_TOOL_MODULES=/tmp/sa-openapi-tools/node_modules node sa_specs/pages/check-openapi.mjs
```

Python 需安裝 `PyYAML` 與 `openapi-spec-validator`。BDD 原檔使用英文 Gherkin 關鍵字與中文敘述。第一項檢查語法與情境結構，第二項檢查文件與連結，第三項以本機瀏覽器檢查桌面／手機閱讀版及圖片縮放、關閉與焦點。OpenAPI 專項另檢查 YAML 內容一致性、API 展開、分類篩選、模型展開、手機寬度與離線請求。皆不執行平台業務測試。

## 3 圖片閱讀操作

點擊圖片或 PNG／SVG 連結開啟視窗。可用「放大」、「縮小」、「符合視窗」、「原始大小」，再捲動查看細節。右上角關閉、Esc 或桌面視窗外遮罩都可關閉，焦點會回到原連結；手機以全螢幕呈現。保留「開啟原圖」與無 JavaScript 時的原始連結。

## 4 檢查紀錄

- [文件與連結](verification.json)
- [BDD 解析](../biz-bdd/validation.json)
- [桌面／手機與圖片操作](visual-validation.json)

## 5 OpenAPI 閱讀方式

左側仍使用既有文件目錄。「05 OPENAPI」右側由 Swagger UI 顯示分類、方法與路徑、參數、請求內容、回應及 Schemas，可展開閱讀與篩選。保留原始 YAML 下載。

建置時將 `openapi.yaml` 轉成內嵌資料，寫入 `openapi/index.html`；以獨立文件隔開 Swagger UI 與 Bootstrap 樣式，並隨內容調整高度。可直接用瀏覽器開啟 `openapi.html`，不需啟動伺服器。重建時不要手改產出的 `openapi/index.html`。

內嵌合約初始化後，解析器使用固定的文件識別位址來解析 OpenAPI 3.1 內部參照，避免 `file://` 解析錯誤；該位址不會被讀取或顯示為下載連結。

`Try it out` 與線上規格驗證已停用；資源全由本機載入，內容頁也禁止連線請求。套件更新須保留授權文件並重新執行離線檢查。

- [OpenAPI 閱讀版檢查](openapi-validation.json)

文件顯示名稱取自各文件標題，目錄順序由 `build.mjs` 的 `navigation` 定義。檔名保留既有名稱，避免影響原有連結；檔名前綴不代表畫面排序。