docs: heatmap as full-pipeline visual search visualization layer

docs_v1.0/API_V1.0.0/TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md

@@ -1,15 +1,44 @@
 # Trace Heatmap Specification v1.0.0
 
-## Concept
+## Design Philosophy
 
-將臉部追蹤資料標準化為熱力圖格式，包含空間（畫面位置）和時間（影片進度）兩個維度。
+這是**全片視覺搜尋**的結果可視化層。
 
-## Data Model
+```
+Search Query
+     │
+     ▼
+┌─────────────────────┐
+│  Embedding / BM25   │  ← 找到符合條件的 chunks/frames
+└────────┬────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│  Heatmap Renderer   │  ← 把結果畫在空間 + 時間軸上
+│  ┌──────┬──────┐   │
+│  │ ██░░ │ ████ │   │  ← 哪裡有結果（spatial）
+│  ├──────┴──────┤   │
+│  │ ██░░██░░██ │   │  ← 何時有結果（temporal）
+│  └─────────────┘   │
+└─────────────────────┘
+         │
+         ▼
+   點擊熱區 → 跳到對應 frame / video segment
+```
 
-### 1. Spatial Heatmap — 臉在哪裡？
+核心：一個標準模組，**設定條件 → 熱力圖 + timeline + 位置參考**，適用於任何可追蹤實體。
-
-將畫面划分為 grid，計算每個 cell 的 face 活動量：
 
+```
+輸入條件                    輸出
+┌─────────────┐          ┌──────────────────────┐
+│ file_uuid   │          │  Spatial Heatmap     │
+│ identity_id │  ───→    │  ┌──────┬──────┐    │
+│ trace_ids   │          │  │ ██░░ │ ████ │    │
+│ confidence  │          │  ├──────┴──────┤    │
+│ time_range  │          │  │ Timeline   │    │
+│ type=face   │          │  │ ██░░██░░██ │    │
+│ object_class│          │  └─────────────┘    │
+└─────────────┘          └──────────────────────┘
 ```
 frame (1920×1080)
 ┌──────────────────────┐