# 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，不得假裝已完成截圖。