# VPP／IVSD FOV 文件 Archify 遷移規格 狀態：Accepted for staged implementation 日期：2026-08-28 交付 repository：`ShoushanZoo/CameraSimulator` ## 1. 目標 把 `docs/vpp-ivsd-fov/` 從各頁自行繪製、風格不一致的靜態 HTML，分階段改成可探索、可驗證的 Archify 文件組。讀者不需要是 VPP 或 IVSD RD，也能回答： 1. VPP 現在使用哪些輸入、fallback 與公式產生 Current H/V FOV、ground projection、2D shape 與 DORI layer？ 2. CameraSimulator、VPP Portal、VPP simulator 與 IVSD Server 各自扮演什麼角色？ 3. 哪些敘述來自實作、哪些是 runtime observed、哪些是推導或待確認推論？ 4. VPP 幾何、IVSD 實驗工具行為與 IVSD Server native contract 在哪裡相同、不同或尚未對帳？ ## 2. 四個來源的責任邊界 | 來源 | 定位 | 在文件中的用途 | |---|---|---| | `ShoushanZoo/CameraSimulator` | IVSD 原本提供的實驗工具；同時是本文件組的交付 repository | 說明 browser/WASM 實驗工具行為；存放 Archify JSON、HTML 與驗證證據 | | `webtech-monorepo/packages/app-one-portal` | VPP 現行產品實作 | VPP Current 資料流、公式、fallback、render policy 的主要實作證據 | | `vpp-design-tool-simulator` | VPP 測試／試作工具 | 用來重現與驗證 VPP prototype；不是 VPP Current 或 IVSD 真實契約的替代品 | | `vca.vivotek.com` 與 Server native contract | IVSD 目前的主要真實資料來源 | IVSD 參數契約、native 計算結果與 runtime behavior 的優先依據 | ### 證據標籤 - **Source**：能指到實作、資料檔或正式契約。 - **Observed**：由 Server、WASM、測試或 probe 實際重現。 - **Derived**：可由圖上列出的輸入與公式重算。 - **Inference**：尚未驗證；必須附確認方式。 IVSD Server 與 CameraSimulator 不一致時，分別標為 **IVSD Server observed** 與 **IVSD experimental tool observed**。差異保留為待確認事項，不以一方悄悄覆蓋另一方。 ## 3. 交付架構 正式 Archify 產物放在： ```text docs/vpp-ivsd-fov/archify/ ..json .html .visual-check.json .visual-check.html .visual-check.*.png ``` - `..json` 是圖的 SSOT。 - HTML 是由 `archify deliver` 產生並 committed 的 standalone artifact。 - Visual-check sidecars 是驗收證據，不是另一份內容來源。 - 現有 HTML 與 URL 在遷移期間保留；入口頁只在對應替代圖完成後新增連結或切換導覽。 - `vpp-ivsd-model-matrix.html` 繼續作為可搜尋的資料工具，不強行改成圖；Archify 只呈現它與其他來源的關係。 ## 4. 圖組與既有頁面對照 | Archify 交付 | 類型 | 回答的問題 | 對應既有頁面 | |---|---|---|---| | System evidence map | `architecture` | 四個來源的責任、資料與證據邊界 | `index.html` | | VPP Camera FOV pipeline | `dataflow` | spec／resolved input → Current FOV → ground projection／DORI → 2D shape | `vpp-camera-fov-overview.html`、`vpp-camera-fov-detail.html` | | VPP fallback and exceptions | `workflow` | 欄位優先序、缺值、zoom interpolation、fisheye／panoramic／thermal 等例外 | `vpp-camera-fov-detail.html` | | IVSD capability flow | `workflow` 或 `dataflow` | CameraSimulator 實驗工具與 Server 的能力閘門、輸入輸出及差異 | `ivsd-camera-fov-detail.html`、`ivsd-camera-capability-guide.html` | | IVSD Server request | `sequence` | browser → Node wrapper → native binaries → rendered result | `ivsd-camera-fov-detail.html`、`vpp-ivsd-2d-spec-compatibility.html` | | Model evidence boundary | `architecture` | Model Matrix、Portal catalog、CameraSimulator intrinsics 與 Server models 的資料責任 | `vpp-ivsd-model-matrix.html`、`vpp-ivsd-2d-spec-compatibility.html` | ## 5. 閱讀與視覺規則 - 主要語言為繁體中文；程式識別字、API 欄位、公式符號與原始錯誤保留原文。 - Archify renderer 目前不提供繁中 locale；繁中 authored content 會搭配英文 Viewer controls，`` 也回退英文。交付文件必須揭露此限制。 - 預設使用 classic static；每張圖支援 light/dark。 - Guided views 只用在入口級總覽，最多五個章節；細節圖保持一條明確主路徑。 - 每張圖最多約 12 個主要節點；公式或 policy 細節放在 cards，不把主圖做成文字牆。 - 圖上需分清「VPP Current」、「VPP prototype」、「IVSD experimental tool」與「IVSD Server」。 - DORI 必須表述為規劃像素密度／顯示 policy，不表述為辨識保證。 ## 6. 每張圖的驗收條件 1. JSON SSOT 通過 `archify validate --quality showcase --json`，receipt 為 9/9、0 composition errors、0 warnings。 2. 使用 `archify deliver` 產生 HTML；記錄 specification／artifact SHA-256 與 bytes。 3. 使用 `archify visual-check` 檢查 1440×900、1600×1000、1920×1080、2048×1320，所有尺寸皆無水平或垂直 overflow。 4. 人工檢視最小與最大尺寸的 light/dark screenshots，確認可讀、無遮擋、無誤導性連線，且最大尺寸沒有失衡的空白帶。 5. 關鍵公式、參數來源、fallback、zoom interpolation 與例外均能追到 Source／Observed／Derived／Inference 之一。 6. 相對連結與既有導覽通過 repository 的文件連結測試。 7. Standards review 與 Spec review 均無 blocking finding。 ## 7. 分階段 tickets 與阻擋關係 | Ticket | 交付 | Blocked by | |---|---|---| | T1 / [#21](https://github.com/ShoushanZoo/CameraSimulator/issues/21) | 正式化 VPP Camera FOV pipeline，建立 `archify/` 交付慣例 | 無 | | T2 / [#22](https://github.com/ShoushanZoo/CameraSimulator/issues/22) | System evidence map 與四方角色入口 | T1 | | T3 / [#20](https://github.com/ShoushanZoo/CameraSimulator/issues/20) | VPP fallback and exceptions workflow | T1 | | T4 / [#23](https://github.com/ShoushanZoo/CameraSimulator/issues/23) | IVSD capability flow | T2 | | T5 / [#24](https://github.com/ShoushanZoo/CameraSimulator/issues/24) | IVSD Server request sequence | T2 | | T6 / [#26](https://github.com/ShoushanZoo/CameraSimulator/issues/26) | Model evidence boundary | T2、T4 | | T7 / [#25](https://github.com/ShoushanZoo/CameraSimulator/issues/25) | 更新入口與導覽、完成舊頁／新圖 coverage audit | T2–T6 | 每張 implementation ticket 使用獨立 branch／PR；完成相稱驗證後開 Draft PR，不自行 merge。後續 ticket 只有在 blockers merge 後才開始。 ## 8. 第一張 tracer bullet：VPP Camera FOV pipeline 第一張圖沿用 [`prototypes/archify-vpp-camera-fov-flow/`](../../prototypes/archify-vpp-camera-fov-flow/README.md) 的已驗證資訊架構，但需在正式路徑重新 deliver 與驗收。它必須完整呈現： T1 的 VPP Current 查證 revision：`webtech-monorepo/packages/app-one-portal` commit `821ea36a29ad3a74fcdaa20c686f2d43844cb005`（2026-08-14）。圖中的 Source／Derived 標籤使用 Evidence ID；同目錄 evidence ledger 必須把每個 ID 一對一展開為此 revision 下的完整 path＋symbol。 - Camera product spec 與 Placement／Channel 的輸入責任。 - Channel → Placement → default 的 resolved input 優先序。 - Current H/V FOV 的 spec、pinhole fallback 與 varifocal correction interpolation。 - `tilt ± V/2`、`d = h / tan(α)` 的 near／far ground projection。 - H-FOV、resolution 與 280／150／80／30 PPM DORI distances。 - `effectiveFar`、footprint、rotation／origin 與 Konva shape。 - Fixed-focal、varifocal／thermal、near-vertical、未落地、超廣角、fisheye／panoramic 的 policy 或例外。 - 證據範圍與不在本圖處理的 wall occlusion、API schema、IVSD parity。 完成後，舊的 `vpp-camera-fov-detail.html` 仍保留；正式 Archify artifact 先作為可比較的新入口。 ## 9. 非目標 - 不在本工作修改 VPP Portal、VPP simulator 或 IVSD Server。 - 不宣稱已知 WASM／native binary 的 C++ 內部公式。 - 不把 CameraSimulator 的實驗行為升格為 IVSD 正式契約。 - 不在文件 PR 觸發部署、Server 重啟或 production cutover。 - 不在本階段刪除舊 HTML 或改壞既有 URL。