first commit

docs/backend/RUNTIME_SDK_SPEC.md

@@ -0,0 +1,50 @@
+# Runtime SDK Spec
+
+## 目標
+
+定義 SDK 的部署、模式、payload 套用與追蹤邏輯，支援網站端實驗運行。
+
+## SDK 雙模式
+
+### Edit Mode
+
+- 配合 editor 做選取與變更預覽
+- 提供 overlay / bridge 事件
+
+### Runtime Mode
+
+- 正式流量分流
+- 套用 payload 變更
+- 回傳 impression / conversion 事件
+
+## 部署拓撲
+
+- 商家網站 -> 載入 SDK（CloudFront）
+- SDK -> 呼叫 FastAPI Runtime API
+- Origin 由自有 VPS 提供靜態檔
+
+## 變更規則（DOM Change）
+
+- change_type：replace_text / set_attribute / set_style / insert / remove / toggle_visibility
+- selector 必須穩定可重建
+- payload 必須可序列化與回放
+
+## Assignment 與 Payload
+
+- assignment 由 runtime API 決策
+- payload 由 release 快照提供
+- 套用前必須驗 selector 是否存在
+
+## 事件策略
+
+- FastAPI 先收事件，再依策略轉送 GA4/GTM
+- 事件層次：audit event、runtime event、forwarded analytics event
+
+## 風險與檢查
+
+- CSP
+- iframe / script injection
+- DOM 穩定性
+- style 汙染與 z-index 衝突
+- cookie / storage 相容性
+