商用網站架設實務

LESSON-23 · starter

定義運動器材電商需求、資料模型與驗收矩陣

你會依序完成4個本堂專屬微步驟；每一步只修改一個責任，看到結果後才進下一步。 這頁用 可觀察證據 和 anchor 指出下一個動作。

Starter4 個小成果
Checkpoint一個核心缺口
Solution5 個差異

開始前確認

這一頁的結果：規劃入口可以開啟

工作方式：先把這一階段複製到自己的工作資料夾，開啟 files/index.html，記下修改前的畫面、Elements、Console、鍵盤 focus 與 brief 內容狀態。

會用到的檔案：index.html、project-brief.md、data-contract.md、acceptance-matrix.md、evidence.md

本堂焦點：定義運動器材電商需求、資料模型與驗收矩陣

照這個順序做

一次只做一張卡。完成後先重新整理入口，再留下證據，才進入下一張。

TODO-1

先固定連續專案範圍，避免後續章節重做或提前串接。

目的

先固定連續專案範圍，避免後續章節重做或提前串接。

修改檔案

project-brief.md

程式碼位置

六頁 sitemap 與章節邊界

現在要做：請在 project-brief.md 的「六頁 sitemap 與章節邊界」完成：定義首頁、商品、購物車、結帳、訂單完成與聯絡六頁責任，並列出 L23–L28 各章唯一交付

貼上位置：project-brief.md：六頁 sitemap 與章節邊界 區塊。

| 頁面 | 檔名 | 責任 |
| 首頁 | index.html | 建立品牌與商品入口 |
| 商品 | products.html | 比較商品與特價 |
| 購物車 | cart.html | 調整品項與數量 |
| 結帳 | checkout.html | 收集購買人資料 |
| 完成 | order-success.html | 顯示訂單編號與狀態 |
| 聯絡 | contact.html | 收集聯絡內容 |

預期結果：六頁各有檔名、責任與主要行動；L25 明示零 fetch/GAS/Sheet，L28 明示不部署。

驗收證據：project-brief.md 的六列 sitemap 與六章 scope 表。

卡住時先看這裡

常見錯誤：只列頁名，沒有寫每頁責任，或把 GAS 提前放進 L25。

第一個檢查：先逐列確認六個檔名，再檢查 L25 與 L28 的禁止事項。

TODO-2

Products Sheet 與本地 mock 使用私有六欄；GAS 以 active 過濾後，公開回應只輸出 productId/name/image/price/salePrice。

目的

Products Sheet 與本地 mock 使用私有六欄；GAS 以 active 過濾後，公開回應只輸出 productId/name/image/price/salePrice。

修改檔案

data-contract.md

程式碼位置

Product contract

現在要做：請在 data-contract.md 的「Product contract」完成：定義私有 Product 的 productId、name、image、price、salePrice、active，並另列商品 GET 公開五欄

貼上位置：data-contract.md：Product contract 區塊。

Private: productId,name,image,price,salePrice,active
Public: productId,name,image,price,salePrice

預期結果：私有六欄完整；公開五欄不含 active；名稱、圖片、售價、特價皆有穩定 key。

驗收證據：data-contract.md 的 private/public 對照表與一筆運動器材範例。

卡住時先看這裡

常見錯誤：把 active 公開給前端，或在公開模型另加私有欄位。

第一個檢查：先數 private=6、public=5，再確認 active 只用於伺服器端過濾。

TODO-3

欄位 ownership 不清會讓前端偽造金額、後端漏存資料或 Sheet 錯欄。

目的

欄位 ownership 不清會讓前端偽造金額、後端漏存資料或 Sheet 錯欄。

修改檔案

data-contract.md

程式碼位置

Order and Contact contracts

現在要做：請在 data-contract.md 的「Order and Contact contracts」完成：定義訂單與聯絡完整欄位，並標示前端輸入、GAS 產生或 GAS 計算

貼上位置：data-contract.md：Order and Contact contracts 區塊。

Orders: orderNo, submissionId, timestamp, buyer, gender, phone, address, email, subtotal, shipping, total, status, itemsJson
Contacts: contactNo, submissionId, timestamp, name, gender, phone, email, message, status

預期結果：訂單 10 個使用者必備欄為編號、購買人、性別、電話、地址、信箱、商品總額、運費、訂單總額、狀態；聯絡 5 個必備欄為姓名、性別、電話、信箱、內容；submissionId、timestamp、itemsJson 另列為技術欄位。

驗收證據：data-contract.md 三張欄位表的需求勾選、技術欄位區分與 owner 欄。

卡住時先看這裡

常見錯誤：把購買人和聯絡姓名混成同一 key，或讓前端決定 orderNo／total。

第一個檢查：先逐字對照訂單 10 個使用者必備欄與聯絡 5 個必備欄，再另核對 submissionId、timestamp、itemsJson 技術欄位。

TODO-4

每一個需求都要能在第 28 章回查，不以『看起來完成』取代驗收。

目的

每一個需求都要能在第 28 章回查，不以『看起來完成』取代驗收。

修改檔案

acceptance-matrix.md

程式碼位置

requirement to evidence

現在要做：請在 acceptance-matrix.md 的「requirement to evidence」完成：建立需求 ID、章節、責任檔案、操作、預期與證據位置矩陣

貼上位置：acceptance-matrix.md：requirement to evidence 區塊。

| REQ | 章節 | 檔案 | 預期 | 證據 |
| REQ-PRODUCT-01 | L25 | products.html | 顯示名稱／圖片／售價／特價 | DOM 與商品資料逐欄對照 |

預期結果：商品、訂單、聯絡、品牌色、GAS 與不部署邊界都至少有一列可重現證據。

驗收證據：acceptance-matrix.md 每列都有 requirement、lesson、file、expected、evidence。

卡住時先看這裡

常見錯誤：只列 checklist，沒有責任檔案或實際證據位置。

第一個檢查：任選 REQ-ORDER-TOTAL，確認能一路追到 L27 GAS 計價與 Sheet 證據。

階段檔案

完整檔案收在可展開的卡片中；先完成上方微步驟，再用這裡查閱與複製。檔案位置要和目前的相對路徑一致。

開啟 starter 的可執行入口

index.html鐵刻運動電商頁面或發佈檔案。

這段要貼在哪裡：先在自己的工作資料夾建立同名相對位置，再複製內容。

​
<!doctype html><html lang="zh-Hant"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>鐵刻運動電商規劃｜starter</title><style>*{box-sizing:border-box}body{margin:0;font-family:system-ui;line-height:1.7;color:#20242a;background:#f6f7f8}main{width:min(100% - 2rem,760px);margin:2rem auto;padding:clamp(1rem,4vw,2rem);background:#fff;border-top:8px solid #f6c90e}button{padding:.7rem 1rem;background:#303841;color:#fff;border:0;border-radius:.5rem;font:inherit}:focus-visible{outline:4px solid #f6c90e;outline-offset:3px}</style></head><body><main><p>LESSON-23 · planning-only · starter</p><h1>鐵刻運動 23–28 連續專案</h1><p>本堂只驗證電商 brief，不建立商品、購物車、GAS、Sheet 或部署。</p><ol id="milestones"><li>商品資料模型</li><li>訂單資料模型</li><li>聯絡資料模型</li><li>六章累積路線</li></ol><button id="check" type="button">檢查規劃項目</button><p id="status" role="status" aria-live="polite">尚未檢查</p></main><script>document.querySelector("#check").addEventListener("click",()=>{const count=document.querySelectorAll("#milestones li").length;document.querySelector("#status").textContent="規劃項目："+count+"；功能請從 L24 才開始實作";});</script></body></html>
project-brief.md專案規劃契約：定義電商角色、頁面、資料模型、資料流與驗收邊界。

這段要貼在哪裡：先在自己的工作資料夾建立同名相對位置，再複製內容。

​
# 鐵刻運動｜23–28 連續專案 brief

## 目標與範圍

- 訪客：想在家建立訓練空間的消費者。
- 主要任務：瀏覽商品 → 加入購物車 → 填寫訂單 → 查看 server-authoritative 結果。
- 次要任務：送出聯絡資料並取得可觀察回應。
- 視覺：黃色與鐵灰為主，紅色只用於特價、錯誤與少量提示。

## 頁面

| 頁面 | 檔案 | 責任 |
| --- | --- | --- |
| 首頁 | index.html | 品牌、精選商品與商品入口 |
| 商品 | products.html | 顯示名稱、圖片、售價、特價與 active 商品 |
| 購物車 | cart.html | localStorage 加減、刪除與前端估算 |
| 結帳 | checkout.html | 購買人、性別、電話、地址、信箱與商品數量 |
| 訂單結果 | order-success.html | 顯示後端回傳的編號、金額與狀態 |
| 聯絡 | contact.html | 姓名、性別、電話、信箱與內容 |

## 資料模型

- Product：productId、name、image、price、salePrice、active。
- Order：orderNo、buyer、gender、phone、address、email、subtotal、shipping、total、status、items。
- Contact：contactNo、name、gender、phone、email、message、status。

## 23–28 累積路線

1. L23：planning-only；只完成本 brief、預覽與 evidence，不建立商店功能。
2. L24：建立語意 shell、首頁與商品入口。
3. L25：只用 local mock 完成商品、購物車、checkout 與聯絡；不發網路請求、不寫外部資料。
4. L26：加入 GAS Web App 的 listProducts／createOrder／createContact GET/POST 契約。
5. L27：加入 Products／Orders／Contacts schema、server-authoritative totals、submissionId 去重及 idle/loading/success/error/timeout。
6. L28：以同一份 canonical descriptors 產生 Solution 與 dist/project/e-commerce，完成本機 release smoke；不宣稱已部署。

## 本階段

- Stage：starter
- TODO：逐欄補上訪客任務、資料欄位與每章驗收證據。
data-contract.md鐵刻運動電商頁面或發佈檔案。

這段要貼在哪裡：先在自己的工作資料夾建立同名相對位置，再複製內容。

​
# Data contract

<!-- TODO-2：補上 Product、Order、Contact 的欄位、型別與必要性。 -->
acceptance-matrix.md鐵刻運動電商頁面或發佈檔案。

這段要貼在哪裡：先在自己的工作資料夾建立同名相對位置，再複製內容。

​
# Acceptance matrix

<!-- TODO-3：把每一項需求連到可觀察的檔案、畫面或鍵盤證據。 -->
evidence.md逐章驗收紀錄：保存操作、預期、實際結果與未完成邊界。

這段要貼在哪裡：先在自己的工作資料夾建立同名相對位置，再複製內容。

​
# L23 驗收證據｜starter

- [ ] brief 能對回 Product／Order／Contact 指定欄位。
- [ ] 六頁責任與 L23–28 累積路線清楚。
- [ ] 本堂沒有商品互動、網路請求、Sheet 寫入或部署。
- [ ] 390px 無水平溢位，Tab 可到達檢查按鈕。

完成驗收

下一步

Starter 完成後，不要直接看 Solution；先前往 Checkpoint，自己找出最後一個核心缺口。

前往 Checkpoint，自己補最後一個核心缺口