Real Data

Wireframe IA 與資料規劃 設計決策

在 Wireframe 階段決定頁面的資訊架構——包含哪些模組、每個模組的商業邏輯、資料故事要說什麼。 同步在 Wireframe 標注上為每個商品模組決定 section 標籤代碼（例如「降價」、「相機」、「秒殺10點」）。 這些代碼後續會同時出現在 Google Sheets Staging 欄值和 HTML 的 data-filter 裡——先想清楚，後面執行才不會亂。

輸出：模組清單 + section 標籤代碼對照表。完整流程見 02 — 規劃階段。

Google Sheets 資料建構 一次性設定

在 Google Sheets Staging tab 新增 section 欄位（欄位標題必須是英文 section，全小寫）， 為每個商品填入對應的 section 標籤值。完成後執行 📤 匯出 JSON，更新本機 data/products.json。

關鍵原則：Apps Script 強制重新匯入不會覆蓋 section 欄——這個設定只需要做一次，之後每日更新不會被清掉。 複雜情境（Tab 切換、時段資料）的資料建構方式見 03 — Google Sheets 情境指南。

HTML 建置 一次性設定

引入 product-loader.js，為每個模組容器加上 data-api、data-filter="section:xxx"、 視需要加 data-max 和 data-label。 在瀏覽器確認每個模組都正確載入預期數量的商品，排版在真實資料下沒有破版。

HTML 設定完成後即固定，不需要每天重新設定。三條核心規則見 05，data-filter 語法速查見 06。

評審前資料更新 每日重複

每次想讓設計概念顯示最新商品資料（價格、優惠券、圖片）： Apps Script 🔄 強制重新匯入全部 → 📤 匯出 JSON → 貼入本機 products.json → 瀏覽器 Cmd+Shift+R。 整個流程約 5–7 分鐘。

⚠️ 一定要用 🔄 強制重新匯入，而不是 📥 匯入——後者只處理 name 欄空白的商品，無法更新已有名稱的商品價格。

在 Wireframe 上標記每個商品容器的「資料意圖」

Wireframe 完成後，為每個商品容器加一個標注，說明它的商業語意。 不需要特別工具，Figma annotation、便利貼備注、或設計規格表都行。 重點是在視覺設計開始前，先確認每個模組的資料邏輯——而不是等 HTML 建好才想。

標注範例：「最新降價商品區」→ 資料意圖：近期售價下降的商品，預計 6–8 筆

列出模組清單，決定 section 標籤代碼

為設計概念的所有商品模組列一份清單，每個模組決定一個 section 代碼。 這個代碼之後要填進 Google Sheets 的 section 欄，也要寫進 HTML 的 data-filter——兩個地方的值必須完全一致，包含大小寫。

推薦用中文代碼（如 降價、相機、秒殺10點）——可讀性好，維護直覺。英文也可以，但選一種格式統一，不要混用。

確認「這個 section，哪些商品應該有它？數量夠嗎？」

有了 section 代碼後，想一下你能找到多少商品可以被標為這個代碼。 如果「相機精選」這個 section 在 Staging 裡只有 1 件商品，版面就會塌陷——及早在 Wireframe 階段發現，調整設計或更換商品，比 HTML 建好才發現便宜得多。

特別是 tab 切換情境（如秒殺時時樂的 4 個時段 tab），每個 tab 至少需要 3–4 筆商品，共需準備 12–16 筆。 商品數量可行性要在 Wireframe 階段就確認。

新建 Google 試算表

前往 sheets.google.com → 點「+」建立空白試算表 → 把試算表名稱改成你的專案名稱（例如「SHP 電商首頁概念 2026-06」）。 試算表名稱不影響功能，只是方便你之後找到它。

匯入 CSV 範本

選單 檔案 → 匯入 → 上傳 → 選擇你下載的 shp-staging-template.csv

匯入設定請選：
• 匯入位置：取代試算表
• 分隔符號類型：逗號
• 將文字轉換為數字、日期和公式：否（避免價格被誤轉）

點「匯入資料」完成。

確認工作表名稱是「Staging」

畫面底部的工作表標籤應該顯示「Staging」。 這個名稱非常重要——Apps Script 靠它識別工作表，名稱不對就找不到資料。

如果顯示的是「工作表1」或其他名稱：右鍵點工作表標籤 → 重新命名 → 輸入 Staging（注意大寫 S）。

開啟 Apps Script

在 Google Sheets 選單點 擴充功能 → Apps Script。 瀏覽器會在新分頁開啟 Apps Script 編輯器。

如果找不到「擴充功能」選單，確認你已登入 Google 帳號，以及試算表是「我的雲端硬碟」裡的檔案（不是他人分享的唯讀連結）。

清空預設程式碼

編輯器裡預設會有一段 function myFunction() {} 的空函數。 全選（Ctrl/Cmd+A）→ 刪除，把整個編輯區清空， 準備貼入完整的 SHP 商品管理程式碼。

選擇 onOpen 並執行

在編輯器頂部的函數下拉選單（預設顯示「選取函式」）， 選擇 onOpen。 點選左側的 ▶ 執行 按鈕。

點「查看權限」開始授權

系統會彈出「需要授權」對話框 → 點 「查看權限」。 接著選擇你的 Google 帳號（即擁有這份試算表的帳號）。

通過「Google 尚未驗證」警告

Google 會顯示「Google 尚未驗證這個應用程式」的警告頁面。 這是正常的——你自己寫的 Script 都會出現這個畫面，不代表程式有問題。

點左下角的 「進階」 展開隱藏選項 → 點 「前往 SHP 商品管理（不安全）」（名稱取決於你的專案名稱）。

點「允許」完成授權

確認權限要求頁面（會列出 Apps Script 需要的權限： 存取試算表、以你的身份連接外部服務）→ 點 「允許」。

授權完成後，畫面會回到 Apps Script 編輯器， 底部執行紀錄應顯示「執行完成」。

回到 Google Sheets 並重新整理

切回 Google Sheets 的分頁 → 按 Cmd+R（或 F5）重新整理頁面。 授權完成後，onOpen() 函數才會在頁面載入時執行，建立選單。

確認「商品管理」選單

重新整理後，頂部選單列應該出現 「商品管理」 選項。 點開確認有三個指令：
• 📥 匯入商品資料（只補空白名稱）
• 🔄 強制重新匯入全部
• ─────────────
• 📤 匯出商品 JSON

出現這三個選項代表安裝完成。

在 Staging tab 標題列找一個空白欄，填入欄位名稱

欄位標題輸入 section（全英文小寫）。 不能改成中文「模組」或其他名稱——這個名稱直接對應 products.json 的 key，系統要靠它識別欄位。 位置在哪一欄都可以。這個步驟只需要做一次。

為每件商品填入 section 標籤值

對應你的 Wireframe 模組清單，為每件商品填入對應的 section 代碼。 一件商品可同時屬於多個 section，用逗號分隔（不加空格）：降價,推薦。 不屬於任何設計概念模組的商品，section 欄留空。

⚠️ Apps Script 🔄 強制重新匯入不會覆蓋 section 欄——設定一次後，每日資料更新都不需要重填。

執行 📤 匯出 JSON，更新本機 data/products.json

商品管理 → 📤 匯出商品 JSON → 開啟 _JSON_Export 工作表 → 點 A1 → 全選複製 → 貼入本機 data/products.json（完整取代整個檔案）。 section 欄的值會自動包含在每筆商品資料裡，例如 "section": "相機,降價"。

在 Staging tab 新增 section 欄位（一次性設定）

在 Google Sheets Staging tab 的標題列找一個空白欄，輸入欄位標題 section（全英文小寫）。 欄位標題不能改成中文或其他名稱——這個名稱會直接成為 products.json 的 key，必須跟系統對得起來。 位置在哪一欄都可以。

這個步驟只需要做一次。之後 Apps Script 強制重新匯入時，section 欄的值不會被覆蓋——這正是 section 欄的設計意圖：讓設計師有一個 Apps Script 不會碰的自訂分類空間。

為每個商品填入 section 標籤值

決定每個商品屬於哪個設計概念模組，在 section 欄填入對應的標籤值。值可以是中文，推薦用中文——可讀性好，設計師日常維護更直覺。

單一模組：直接填入，例如 相機 或 降價
屬於多個模組：逗號分隔（不加空格），例如 相機,降價
不屬於任何模組：留空即可，不影響其他商品

填入範例：FUJIFILM X-HF1 → 相機,推薦　SONY RX100VII → 相機,降價

匯出 JSON（section 值會一起帶出）

section 欄填完後，執行正常的匯出流程： 商品管理 → 📤 匯出商品 JSON → 複製 _JSON_Export A1 內容 → 貼入本機 data/products.json。 section 欄的值會自動包含在每筆商品資料裡，例如： "section": "camera,price-drop"。

在 HTML 用 data-filter="section:xxx" 篩選

products.json 更新後，HTML 裡的 data-filter="section:camera" 就能正確篩選出有 camera 標籤的商品。 product-loader.js 使用包含比對（contains）—— section 值為 camera,price-drop 的商品，用 section:camera 篩選時也會被篩到。

定義模組與 section 標籤代碼（動手前）

列出設計概念的所有模組，為每個模組決定一個 section 標籤代碼。 例如：最新降價 → price-drop、相機精選 → camera、你可能會喜歡 → recommended。

標籤代碼建議用英文小寫加連字號，語意清晰即可。中文也可以，但 Staging 欄值和 HTML data-filter 值必須完全一致（包含大小寫）。

在 Staging 填入 section 值並匯出 JSON（動手前）

打開 Google Sheets Staging tab，確認 section 欄位已存在（第一次使用需要手動新增欄）。 為每個商品填入對應的 section 值，執行 📤 匯出 JSON，更新本機 data/products.json。

⚠️ 最常踩到的坑：忘了更新 products.json，導致 HTML 篩不到任何資料。先完成這個步驟，才能確認 data-filter 寫對了。

寫 HTML：data-filter + data-max + data-label

Staging 資料確認後，在每個模組容器加上對應的 data-filter="section:xxx"、 視需要加 data-max 限制數量， 以及 data-label 標示模組名稱（方便 console debug）。

真實資料驗證（建置後）

在 browser 開 DevTools，確認每個模組都正確載入了預期數量的商品。 如果某個模組顯示 0 筆，先檢查 Staging 的 section 欄是否已填值並重新匯出 JSON，再排查 HTML 語法。 空白模組在評審時會造成版面塌陷，及早發現及早修正。

確認 Staging tab 的 source_url

每列的 source_url 欄位必須是有效的 Yahoo 商品網址。如果某個商品已下架，這一列要移除或更換 URL，否則重新匯入時會失敗並產生空白資料。

選擇正確的匯入指令

更新現有商品（價格/標籤）→ 🔄 強制重新匯入全部（所有有 source_url 的列都重抓）。
新增商品（name 欄位空白）→ 📥 匯入商品資料。
⚠️ 最常見錯誤：用 📥 匯入試圖更新價格——它只處理 name 為空的列，有名稱的商品會被跳過。每日更新一律用 🔄 強制重新匯入。

目視確認 Staging 資料正確

重新匯入完成後，快速掃一眼 name、price、tag1、tag2 欄位是否正確。特別注意 tag1/tag2——Apps Script 只抓未登入狀態下可見的優惠券，個人化優惠不會出現（這是正常行為，不是 bug）。

匯出 JSON 並更新本機檔案

商品管理 → 📤 匯出商品 JSON → 開啟 _JSON_Export 工作表 → 點 A1 → 全選複製 → 貼入本機 data/products.json（完整取代整個檔案內容）。

強制重新整理瀏覽器確認更新生效

到 http://localhost:8088 按 Cmd+Shift+R（強制重新整理）——這會清除 10 分鐘的 stale-while-revalidate 快取，確保看到最新資料。 普通的 Cmd+R 可能因為快取而仍顯示舊資料，如果更新後看起來沒有改變，先試試 Cmd+Shift+R。