🐬Spotfire 匯出 CSV 的實際架構解析：為什麼「產生下載連結」的 Script 並不決定資料表？

前言：Spotfire 匯出流程為什麼常讓人誤判？

在維護 Spotfire 專案時，常見一個問題：

「這段 Script 到底是匯出哪一張 Data Table？」

實際追下去才發現：

• Script 裡完全沒看到 Document.Data.Tables["XXX"]

• 但 CSV 卻確實被產生了

• 使用者也能成功下載

這並不是 Spotfire 的黑魔法，而是刻意設計的分層架構。

---

一、常見錯誤理解：一支 Script 就該負責所有事情？

很多人會直覺認為：

X「既然是 Export Script，那一定在這裡指定資料表」X

但在企業級 Spotfire 專案中，這通常是反模式（Anti-pattern）。

原因很簡單：

• 匯出流程（檔案、路徑、下載）

• 與資料邏輯（資料表、過濾、欄位）

👉 應該拆開處理

---

二、實務上的標準分層設計（Architecture）

常見實作會拆成兩層 Script

[UI / Download Script]
        ↓
[Data Export Script]
        ↓
[Spotfire Data Table]

各層責任劃分

層級	負責內容
UI / Download Script	路徑、檔名、時間戳、下載連結
Data Export Script	決定資料來源、欄位、過濾條件
Data Table	Spotfire 中已存在的資料集

---

三、下載 Script 在做的事（不是你以為的那些）

以下是完全重寫後的示意邏輯（不含任何實際專案細節）：

1️⃣ 建立匯出目錄（避免覆寫）

import os
from datetime import datetime

base_dir = "D:/spotfire_export"
date_folder = datetime.now().strftime("%Y%m%d")
run_folder = datetime.now().strftime("%H%M%S")

export_dir = os.path.join(base_dir, date_folder, run_folder)
os.makedirs(export_dir, exist_ok=True)

👉 重點：

• Download Script 只負責檔案系統

• 與資料完全無關

---

2️⃣ 定義輸出檔案路徑

csv_path = os.path.join(export_dir, "export.csv")

⚠️ 到這一步為止，CSV 還是空的

---

3️⃣ 呼叫「真正匯出資料」的 Script

params = {
    "targetFile": csv_path
}

run_script("Export_Data_Table", params)

👉 關鍵觀念：

• Export_Data_Table 才是核心

• Download Script 不知道也不該知道：

  • 用哪張 Data Table

  • 是否套過濾

  • 欄位順序

---

4️⃣ 組合下載 URL（Web 層責任）

download_url = f"https://server/download/{date_folder}/{run_folder}/export.csv"

---

5️⃣ 更新畫面（HTML / Property）

<a href="download_url">Download CSV</a>

---

四、那資料表到底是在哪裡指定的？

答案一定在 被呼叫的那支 Script。

Data Export Script 的典型責任

table = get_data_table("FACT_SALES")

export_table_to_csv(
    table=table,
    path=targetFile,
    include_headers=True
)

為什麼這樣設計是「正確的」？

原因	說明
可重用	多個頁面共用同一匯出流程
可維護	改資料 ≠ 改下載
易除錯	問題能快速定位在資料層或 UI 層
安全	敏感資料集中控管

---

五、實務上最常見的 3 個踩雷點

❌ 1. 在 Download Script 直接指定 Data Table

• 造成 Script 複雜

• 無法重用

• 每加一張表就複製一份

---

❌ 2. 用硬編碼路徑

• 無法跨環境（DEV / UAT / PROD）

• 權限問題頻繁發生

---

❌ 3. HTML 視覺化名稱寫死

• UI 改標題就壞

• 建議用 Property 或 Tag 控制

---

六、如何快速判斷「匯出邏輯寫在哪」？

工程師實戰建議：

1. 看到 Script 沒有 Data Table API → 一定不是資料邏輯

2. 搜尋 TryGetScript / ExecuteScript

3. 找被呼叫的 Script 名稱

4. 檢查是否有：

   • Document.Data.Tables

   • FilteringSelection

   • DataOperations.Export

---

結語：這不是 Spotfire 特例，而是企業系統常態

這種設計不只出現在 Spotfire：

• Web API（Controller vs Service）

• ETL Pipeline（Trigger vs Transform）

• Batch Job（Scheduler vs Processor）

👉 下載只是流程的一環，不是核心邏輯

理解這個架構後，你在 Spotfire 專案中會：

• 更快定位問題

• 更敢重構

• 更容易和其他工程師交接