LESSON-23 · solution

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

這一頁不是直接複製答案；先逐檔看差異、修改原因與驗收證據，再把需要的改動帶回自己的資料夾。這頁用可觀察證據和 anchor 指出下一個動作。

Starter4 個小成果

Checkpoint一個核心缺口

Solution5 個差異

開始前確認

這一頁的結果：四頁 sitemap、四個 user tasks 與優先級完整；Acceptance checklist 與 evidence.md 可逐項重現；沒有 TODO、CHECKPOINT 或未教的外部整合，390px 與 Tab 仍可操作

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

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

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

照這個順序做

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

目的

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

修改檔案

project-brief.md

程式碼位置

六頁 sitemap 與章節邊界

現在要做：先對照差異，再檢查在 project-brief.md 的「六頁 sitemap 與章節邊界」對照這項變更：| 頁面 | 檔名 | 責任 | | 首頁 | index.html | 建立品牌與商品入口 | | 商品 | products.html | 比較商品與特價 | | 購物車 | cart.html | 調整品項與數量 | | 結帳 | checkout.html | 收集購買人資料 | | 完成 | order-success.html | 顯示訂單編號與狀態 | | 聯絡 | contact.html | 收集聯絡內容 |

貼上位置：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 表。

卡住時先看這裡

常見錯誤：只複製完整答案，卻沒有先理解這一項差異的責任。

第一個檢查：只對照目前差異指定的檔案與 anchor。

目的

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

修改檔案

data-contract.md

程式碼位置

Product contract

現在要做：先對照差異，再檢查在 data-contract.md 的「Product contract」對照這項變更：Private: productId,name,image,price,salePrice,active Public: productId,name,image,price,salePrice

貼上位置：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 對照表與一筆運動器材範例。

卡住時先看這裡

常見錯誤：只複製完整答案，卻沒有先理解這一項差異的責任。

第一個檢查：只對照目前差異指定的檔案與 anchor。

目的

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

修改檔案

data-contract.md

程式碼位置

Order and Contact contracts

現在要做：先對照差異，再檢查在 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

貼上位置：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 欄。

卡住時先看這裡

常見錯誤：只複製完整答案，卻沒有先理解這一項差異的責任。

第一個檢查：只對照目前差異指定的檔案與 anchor。

目的

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

修改檔案

acceptance-matrix.md

程式碼位置

requirement to evidence

現在要做：先對照差異，再檢查在 acceptance-matrix.md 的「requirement to evidence」對照這項變更：| REQ | 章節 | 檔案 | 預期 | 證據 | | REQ-PRODUCT-01 | L25 | products.html | 顯示名稱／圖片／售價／特價 | DOM 與商品資料逐欄對照 |

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

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

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

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

卡住時先看這裡

常見錯誤：只複製完整答案，卻沒有先理解這一項差異的責任。

第一個檢查：只對照目前差異指定的檔案與 anchor。

目的

Checkpoint 只修一個資料契約缺口，證明特價不會在實作時失去來源。

修改檔案

data-contract.md

程式碼位置

Product salePrice row

貼上位置：data-contract.md 的 Product salePrice row 區塊

| 特價 | salePrice | number/null | 前端顯示、GAS 回傳 |

預期結果：Product 表同時包含 price 與 salePrice，REQ-PRODUCT-SALE 可追到此列。

驗收證據：data-contract.md 的 Product 表、acceptance-matrix.md 的 REQ-PRODUCT-SALE。

卡住時先看這裡

常見錯誤：只複製完整答案，卻沒有先理解這一項差異的責任。

第一個檢查：只對照目前差異指定的檔案與 anchor。

階段檔案

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

開啟 solution 的可執行入口

開啟index.html鐵刻運動電商頁面或發佈檔案。
開啟project-brief.md專案規劃契約：定義電商角色、頁面、資料模型、資料流與驗收邊界。
開啟data-contract.md鐵刻運動電商頁面或發佈檔案。
開啟acceptance-matrix.md鐵刻運動電商頁面或發佈檔案。
開啟evidence.md逐章驗收紀錄：保存操作、預期、實際結果與未完成邊界。

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

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

<!doctype html><html lang="zh-Hant"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>鐵刻運動電商規劃｜solution</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 · solution</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：solution
- Solution：頁面、資料模型、章節責任與安全邊界可互相追溯。

data-contract.md鐵刻運動電商頁面或發佈檔案。

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

# Data contract

## Product

- productId：string，商品唯一識別
- name：string，顯示名稱
- price：number，單價
- salePrice：number，優惠價格
- active：boolean，上架狀態

## Order

- orderNo：string，訂單編號
- buyer：object，購買人
- items：Product[]，訂單明細
- subtotal：number
- shipping：number
- total：number，伺服器計算總額
- status：string，訂單狀態

## Contact

- contactNo：string，聯絡編號
- name：string，姓名
- email：string，Email
- message：string，需求內容
- status：string，處理狀態

acceptance-matrix.md鐵刻運動電商頁面或發佈檔案。

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

# Acceptance matrix

| requirement | evidence |
| --- | --- |
| 六頁責任清楚 | project-brief.md 的頁面表 |
| Product 欄位完整 | data-contract.md 的 Product |
| Order 與 Contact 可追溯 | data-contract.md 的兩個契約 |
| 每項需求可驗證 | 每列 evidence 的檔案、畫面或 DevTools 結果 |

evidence.md逐章驗收紀錄：保存操作、預期、實際結果與未完成邊界。

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

# L23 驗收證據｜solution

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

完成驗收

四頁 sitemap、四個 user tasks 與優先級完整
Acceptance checklist 與 evidence.md 可逐項重現
沒有 TODO、CHECKPOINT 或未教的外部整合，390px 與 Tab 仍可操作
留下入口網址、修改檔案、操作步驟、預期結果與實際觀察。

下一步

Solution 對照完成後，回到 README 整理證據，並準備下一堂課的先備知識。

回到 README，整理本堂證據並銜接下一堂

繼續自主學習

開啟 examples/supplement/index.html；自學檔案不混入 Solution files。