feat(overview-artifact): 產生可預覽總覽與截圖 fallback

2026-09-18 15:59:34 +08:00
parent c545f11ec1
commit 867a23497f
16 changed files with 605 additions and 324 deletions
@@ -0,0 +1,55 @@
+# Artifact 產物契約
+
+這份規則是需求級 HTML、截圖與議題附件的唯一正本。
+
+## 資料流
+
+1. `/sdlc-analyze` 完成排程後重新取得需求與工作包抽取 JSON。
+2. 流程組成一個 `schemaVersion: 1` 的需求根物件，暫存於 `.tmp/`。
+3. `scripts/overview-render.js --input <json> --output <html> --manifest <manifest>` 驗證並產生自包含 HTML。
+4. 預覽平台優先；沒有預覽能力時，使用可用 ephemeral port 短暫啟動 Node 靜態伺服器。
+5. 瀏覽器產生 full-page 與圖表局部 PNG，寫入 manifest。
+6. `scripts/issue-assets.js --repo ... --index ... --manifest ...` 上傳附件並就地更新需求議題附件索引。
+
+JSON、HTML、SVG 與 PNG 全部寫入 `.tmp/`，不寫入目標專案。
+
+## 根物件
+
+必要欄位：`schemaVersion`、`source`、`requirement`、`workPackages`、`overview`。
+
+`schemaVersion` 不是目前 renderer 支援的版本時必須停止；未知欄位保留。
+
+## 圖表
+
+圖表以抽象資料保存：`kind`、`direction`、`nodes`、`edges`。議題輸出由 renderer 產生 Mermaid；HTML 重新產生 SVG 或 HTML／CSS，不得直接搬用 Mermaid。
+
+流程、依賴、架構與網路圖使用 SVG；卡片與清單使用 HTML／CSS。布局必須固定且可重跑。
+
+## 公式
+
+公式是可選欄位，保存 LaTeX 原文、標題、說明與用途。議題使用 `formula` fenced block；HTML 使用自包含 SVG。單一公式解析失敗時保留原文並標記未渲染，不得靜默遺失；公式欄位結構錯誤仍使整體 schema 驗證失敗。
+
+## 截圖與附件
+
+manifest 的每個 screenshot 必須包含 `role`、`path`、`fileName`、`sha256`。PNG 使用固定語意檔名，內容 hash 用 SHA-256。
+
+full-page 與局部圖全部上傳為需求議題附件，不直接嵌入圖片。正文只保留一行附件索引；重跑時內容相同就重用，無法確認 hash 就新增附件。附件上傳或議題索引更新失敗是硬錯誤。
+
+若平台提供真正可用的 preview URL，才使用既有 `--overview-url` 回寫；不可把 `.tmp/` 或 `0.0.0.0` 寫回議題。
+
+## 截圖 backend
+
+平台 preview 是首選。沒有平台 preview 時，可執行：
+
+```
+node scripts/overview-capture.js --backend auto --url <preview-url> --output <png>
+```
+
+若沒有瀏覽器但有 SVG rasterizer：
+
+```
+node scripts/overview-capture.js --backend svg --svg <overview.svg> --output <png>
+```
+
+`auto` 優先使用 Firefox，再使用 `rsvg-convert` 或 `resvg`。找不到任何 backend
+必須失敗並保留 `.tmp/` 的 HTML／SVG，不得假裝已完成截圖。