# 規格寫作 — 跨討論串接手 Brief v2

> **用途**：跨討論串接手。新 @Taco 看完此檔即可無縫接續，不用回問翠翠基本問題。
> **更新日**：2026-06-19
> **對應專案**：官網轉換 + 鼎新 ERP 串接
> **使用者**：翠翠（sender_id `U06UJ7RN7B9`），她的 profile 在 memory `user_tsuitsui_profile.md`

---

## 0. 給新 @Taco 的優先提醒（先讀這段）

1. **Sheet row 編號之前有 offset 問題** — 不要假設我講「Row 13」就是 sheet 上的 row 13。**永遠以「任務名稱」為準**，不要硬靠 row number 對齊。
2. **翠翠偏好「規格分開寫」** — 之前嘗試把「空運禁品 + 排除物流」合併成一份，她說「太複雜」。**預設不要合併**，需要時用 `關聯規格` 段 cross-reference。
3. **避免 jargon** — 她對術語敏感（「邊界條件」「出包」這種詞她會問為什麼這樣叫）。用**白話**：
   - 邊界條件 / 例外 / 異常 → **「其他情況」**（已定案）
   - 不要說「出包」，那只涵蓋第 4 類，太狹隘
4. **解釋簡短，給答案不繞圈** — 長篇大論她會說「我看不懂」。先給答案再展開。
5. **不會的 Notion 操作要給「示意圖」** — 她不熟「Open as page」「Tab 縮排」這類 Notion 操作詞，**口頭講她聽不懂**，要做一張 HTML mockup（之前做過 `notion_spec_mockup.html`）。
6. **她用零碎時間寫規格** — 不要一次推太多，**寫完一份 review 完再開下一個**。
7. **每次接手先 fetch Sheet 狀態**（curl 連結見 §6.1），不要問她「進度到哪」— 直接拉。
8. **HTML 報告慣例**：白底、mobile-friendly、vanilla（無依賴）、上傳 R2 keep。
9. **上傳 R2 用最新 upload.js**（charset=utf-8 已加回，中文不會亂碼）。
10. **她的 Notion 不對 bot 開放** — 你看不到她 Notion，要看內容只能讓她截圖。
11. **記憶協定**：專案狀態變更時更新 `~/.claude/projects/-home-node/memory/project_work_website_erp_migration.md`。
12. **多選項決策**：理論上走 `decision-compare` skill，但**引導式對話不適用**（她目前是在學寫規格，不是 A vs B 決策）。

---

## 1. 規格 Template — 8 個格子（已定案版）

```
## 規格：[功能名]

### 為什麼要做
（一句或兩句，講現況痛點 + 不做會怎樣。半年後回頭看才看得懂。）
**不是描述功能要做什麼**（那是主流程的事）

### 觸發情境
什麼時候啟動？哪個畫面、哪個動作後？

### 前置條件
跑這流程前需要滿足什麼？

### 主流程
1. 誰做 X
2. 系統判斷 Y
3. 若 Y=true → 做 A
4. 若 Y=false → 做 B
（步驟編號 = 時間順序；if/else 是同時點的兩條路，不用算兩個編號）

### 其他情況
主流程以外、需要處理的情況。涵蓋 4 類：
1. 使用者改變主意（取消、回上一步、修改）— 合理操作不是「出包」
2. 資料極端值（空白、零、超大、特殊字元）
3. 衝突組合（同時勾兩個矛盾選項）
4. 系統真的出錯（網路斷、後端掛）

### 影響的資料 / 欄位
新增 / 變更哪些 DB 欄位（值域、預設值）

### UI / 畫面影響
哪個畫面要改、改什麼、文案
（文案不確定 → 標 `[待確認 — 行銷康妮 / 客服 / ...]`）

### 驗收標準
做完後通過什麼條件算 done

### 關聯規格（選填）
跟哪份規格相關 → 連結過去（Notion link 或規格名）
```

---

## 2. 寫作原則（翠翠已內化的觀念）

1. **一個項目一份規格**，不合併（重要）
2. **卡住先標 `[待確認]`**，不要中斷思路
3. 規格只寫**自己的範圍**，相關邏輯交給別份規格用 `關聯規格` 串連
4. **不寫實作細節**（DB schema、UI 框架），那是廠商的事
5. **規格邊界判斷**：寫完問自己「廠商沒問就能照做嗎？」→ 不行就補
6. **每份規格的長短按複雜度決定**：簡單 UI 微調 5 個格子就夠；複雜邏輯填滿 8 個

---

## 3. Layer 1 / Layer 2 分層思維（翠翠頓悟過的點）

翠翠在討論串中發現：**多個商品上架欄位最終都在「結帳判斷」被一起判斷**，問怎麼處理。

答案是**分層**：
- **Layer 1（單點規格）**：每個欄位/功能獨立一份。例：`is_air_restricted` 欄位寫一份、`excluded_logistics` 欄位寫一份、`結帳設定` 寫一份
- **Layer 2（串接流程規格）**：把所有欄位串起來的流程。例：**子流程 1（訂單接入與成立）** spec 就是這個 Layer

Layer 1 寫單點，Layer 2 寫串接。寫 Layer 1 時提到「結帳會這樣那樣」就指向 Layer 2 連結，不重複寫。

**子流程 1 spec 連結**（Layer 2 已存在）：
https://r2.shinychang.net/keep/1781166180-13a9cc5f-website_erp_subflow_1.html

---

## 4. Spec A + Spec B 分開寫（翠翠採用的 pattern）

兩個相關功能（如「空運違禁品」+「排除物流」）：
- 各寫一份規格
- A 是主功能，B 用 A 的欄位
- B 規格只寫「我這個欄位是什麼、勾了會發生什麼到自動連動為止」
- 結帳邏輯交給 A 規格
- B 規格末尾加「關聯規格：A」

---

## 5. 整合 row（如「上架資料欄位增減」）的寫法

某些 row 是「ERP 端開發整合任務」（一次新增 N 個欄位），不是業務邏輯規格。

寫法很短：
```
## 規格：[整合任務名]

### 為什麼要做
為支援多個業務需求，需新增以下欄位。

### 新增欄位清單
| 欄位 | 型別 | 預設 | 對應業務規格 |
|---|---|---|---|
| is_air_restricted | Y/N | N | 空運違禁品 |
| excluded_logistics | 多選 | 空 | 排除物流 |
| ... |

### 驗收
- 各欄位可儲存
- 預設值符合表格
- 業務驗收見對應規格
```

不重複寫業務邏輯。

---

## 6. 接手必備資源

### 6.1 即時 Sheet（每次接手先 fetch）

```bash
curl -sL -o /tmp/sheet.csv "https://docs.google.com/spreadsheets/d/1-C2xvPEPSjjVMp9b8u8qkpPph57XX0vYBpHGzG48qQs/export?format=csv&gid=1699653235"
```

Sheet 連結（給她點看）：
https://docs.google.com/spreadsheets/d/1-C2xvPEPSjjVMp9b8u8qkpPph57XX0vYBpHGzG48qQs/edit?gid=1699653235

### 6.2 Notion（她寫規格的地方）

https://app.notion.com/p/4-21-320ca809b8298071b0b0e9ae6eb1d516
https://app.notion.com/p/312ca809b8298088b8cfdd316fed0ffc

⚠️ **新 @Taco 看不到 Notion 內容**（沒登入權限）。要看內容請她截圖。

### 6.3 本討論串的所有產出

| 資源 | 連結 |
|---|---|
| 專案 brief（過時，待更新）| https://r2.shinychang.net/keep/1781146562-220ad33a-website_erp_brief.md |
| 流程圖譜總表 | https://r2.shinychang.net/keep/1781164399-589217a5-website_erp_diagram_register.html |
| 子流程 1 spec（訂單接入與成立）| https://r2.shinychang.net/keep/1781166180-13a9cc5f-website_erp_subflow_1.html |
| 規格 template + 範例 | https://r2.shinychang.net/keep/1781767093-dd4406d5-spec_template.md |
| HTML checklist（localStorage 進度）| https://r2.shinychang.net/keep/1781767294-8b487fdf-spec_checklist.html |
| Notion 寫規格示意圖 | https://r2.shinychang.net/keep/1781769034-75adb03a-notion_spec_mockup.html |
| 開發需求分類報告（v3）| https://r2.shinychang.net/keep/1781242594-38da4024-website_erp_classification.html |
| 接手 brief v1（已被本檔取代）| https://r2.shinychang.net/keep/1781802928-0bcc2b3d-spec_handoff_brief.md |

---

## 7. 規格 Checklist（34 項，6/18 狀態）

⚠️ 以**任務名**為主，不要硬綁 row 編號（之前有 offset 過）。即時狀態請拉 Sheet。

**狀態符號**：✅ 已完成 / 🟡 草稿中 / ⬜ 未開始 / ⛔ 不開發

### A. 空運/物流相關（已動手）
- ✅ **物流判斷空運違禁品**（規格全文見 §8）
- ⬜ 商品上架增加「排除物流」← **下一個建議寫**（跟空運禁品配套）

### B. 商品上架欄位
- ⬜ 拆分結帳（購物車拆單）← 包含「結帳設定」欄位邏輯
- ⬜ 上架資料欄位增減 ← 整合 row，寫法見 §5

### C. 物流（黑貓相關）
- ⬜ 物流設定（黑貓）綁多個廠商客代
- ⬜ 訂單綁大宗單後黑貓客代判斷
- ⬜ 物流增加黑貓
- ⬜ 訂單貨態查詢物流商連結

### D. 訂單管理
- ⬜ 交易拆單
- ⬜ 訂單管理頁面增加篩選
- ⬜ 訂單自定義標籤
- ⬜ 每日出貨明細報表
- ⬜ 海外配送，配送編號的更新

### E. 金流
- ⬜ 未付款訂單，重新付款 20 分鐘
- ⬜ 新增金流：街口支付
- ⬜ 線上刷卡換中信銀行

### F. 退貨 / 發票
- ⬜ 退貨流程『會計執行退款』改自動
- ⬜ 開立發票時點修改

### G. 通知
- ⬜ Mail 工具串接
- ⬜ 官網特定情境通知信/簡訊

### H. 會員 / 註冊
- ⬜ 黑名單（**有完整範例可參考**，見 §9）
- ⬜ Google 快速登入
- ⬜ 驗證碼簡訊按鈕視覺強化（**有極簡範例可參考**，見 §9）

### I. 商品/UI
- ⬜ 商品列表頁文字呈現調整
- ⬜ 商品下架倒數計時器
- ⬜ 置頂 (Pin) 功能
- ⬜ 購物車滿額升等提醒
- ⬜ 加入購物車按鈕滾動固定
- ⬜ DPA 圖片抓取邏輯
- ⬜ 獨立 SEO 設定欄位
- ⬜ 全域訂單最低 100 元

### J. 跨平台
- ⬜ 超電串接 (API)（快電商）
- ⬜ 超電串接 (物流)（快電商）

### K. 門市（Q2 上線，不急）
- ⬜ 門市間在途調撥（庫存）

### 建議寫作順序（按業務相關性 cluster）
1. **排除物流**（接續空運禁品）
2. **拆分結帳 + 上架資料欄位增減**（拆單邏輯 + 商品欄位）
3. **物流相關打包**（4 項黑貓相關）
4. **黑名單**（有範例）
5. **發票 + 退貨**（流程相關）
6. **其他 UI 改動**（簡單，零碎時間寫）

---

## 8. 已完成規格全文 — 物流判斷空運違禁品

### 為什麼要做
- 某些商品（鋰電池、噴霧罐、易燃品）依航空法規不能空運
- 若消費者下訂含此類商品 + 選擇空運物流，通常超取都是走空運，離島黑貓有航運跟空運選擇，預計是空運。現行平台因未阻擋，客服在整理訂單時要先檢查，主動聯繫客人修改訂單，且這些處理都在消費者結單完成後發生，會讓客人感受不佳

### 觸發情境
商品上架頁面中，「空運違禁品 = Y」

### 主流程
1. 人員於商品上架頁面，勾選「空運違禁品 = Y」
2. 系統自動連動，將「排除物流」中的「不可超取 7-11」「不可超取全家」「海外配送」自動加勾
3. 人員仍可手動加勾其他項目（不阻擋）

### 其他情況
- 取消勾選「空運違禁品」時，自動連動的三項設定保留（不取消，由人員自己改）

### 影響的資料 / 欄位
- 商品主檔新增 `is_air_restricted`（Y / N，預設 N）

### UI / 畫面影響
- 商品上架頁，新增「空運違禁品」勾選框
- 商品頁面中的商品介紹要出現「此商品不可空運」之文字

### 驗收標準
- 勾選空運違禁品 → 排除物流欄位自動加勾三項
- 結帳時實際阻擋邏輯見「排除物流」規格

### 關聯規格
- 排除物流

---

## 9. 範例規格參考（指導寫作風格）

### 範例 A：黑名單會員結帳限制（中等複雜度）
完整範例見 spec_template.md 連結。展示了 if/else 邏輯 + 欄位定義 + 驗收標準。

### 範例 B：驗證碼簡訊按鈕視覺強化（極簡）
完整範例見 spec_template.md 連結。展示了純 UI 改動只需 5 個格子。

---

## 10. 專案時程（已敲定）

| 階段 | 上線日 | 內容 |
|---|---|---|
| A | 2027-01-01 | 官網 + 共用底層（**規格 checklist 中 33/34 屬於此階段**）|
| B | 2027 Q1 (1-2 月) | 通路（蝦皮先接）|
| C | 2027-05-01 | 鼎新自動串接（原 4/1，已往後 1 個月）|
| D | 2027 Q2 | 門市試水溫（**1/34 屬於此階段**）|

vendor lock：
- 康德 7/15 前
- 鼎新 9/1 前

---

## 11. Sheet 欄位定義（給新 Taco 看 Sheet 時參考）

| 欄位 | 用途 | 例值 |
|---|---|---|
| 核對 | TRUE/FALSE | TRUE = 要做 / FALSE = 不做 |
| 必要性 | RYG | R 必要 / Y 想要 / G 加分 |
| 平台 | 業務 scope | 官網 / 共用 / 快電商 / 門市 / 通路 / (官網/共用 slash 表示跨層) |
| 分類 | 業務模組 | 物流 / 訂單 / 退貨 / 庫存 / 金流 / 商品 / 通知 / 廣告 / 註冊 / 發票 |
| 任務說明 | 任務名 | （主鍵，以此對齊）|
| 細項說明 | 細節 | 多行內容 |
| 報價時數5.26 | 康德報價（天）| 0/0.5/1/3/... |
| 需求單位 | 內部誰提的 | 行銷康妮 / 資訊部Tracy |
| 康德負責人員 | 對接誰 | Kevin（前端 PM）/ 百吉（後端 PM）/ Felix（前期工程師）/ 林郁授（門市對接）|
| 狀態(待辦需求) | 待辦狀態 | 待辦需求 / 啟動超電... |
| Note | 卡點/待辦 | 自由文字 |
| 畫面/需求細項 | 連結 | Canva / Notion |
| 康德報價(人天)| 重複欄 | 同報價時數 |
| 需求單位備註說明 | 補充 | 自由文字 |
| 需求單位確認簽名 | 對齊用 | 簽名 |

**沒有的欄位**（建議加但未加）：
- 階段欄（paste-ready 已備好，39 列 A + 1 列 D）
- 規格狀態欄（用 HTML checklist 或 Notion 內追蹤亦可）

---

## 12. 懸而未決 / 等待中

| 項目 | 狀態 | 期限 |
|---|---|---|
| 鼎新 Amelia 回 M1 最少 ready 範圍 | 等回覆 | 6/30 |
| Row 3「超電串接 (API)」對接窗口 | 確認百吉 or Felix | 隨時可確認 |
| Sheet「階段」欄補上 | 翠翠補 | 隨時 |
| Sheet Row 29/30/53「官網/共用」slash 寫法 | 統一成「官網」 | 隨時 |
| Gantt 圖更新（鼎新 5/1）| 我做 | 翠翠 OK 即動 |
| 記憶 + brief md 同步新時程 | 我做 | 翠翠 OK 即動 |

---

## 13. 翠翠的工作節奏（給新 Taco 參考）

- 用**零碎時間**寫規格，不會一次坐下來寫完
- 寫完一份會傳 screenshot 來，期待 review
- 卡住時直接問「這個怎麼寫」「這是什麼意思」
- 不喜歡被推太多，**一次給一份**繼續
- 偏好「先給結論再展開」的回應結構
- Slack 訊息不要太長，**結論先講**

---

## 14. 新對話如何開始

新 @Taco 收到請她貼此檔案 + 一句話 instruction（例如「規格寫作接手，繼續寫排除物流」），請：

1. **不要再問翠翠基本問題**（template、原則、寫過哪些）— 本檔都有
2. **先 fetch Sheet**（指令見 §6.1）拿即時狀態
3. **直接從 §7 checklist 的「下一個建議寫」開始**
4. **每份規格寫完 review 完，回頭把 §7 checklist 對應項目標 ✅**
5. **新狀態變化更新 memory `project_work_website_erp_migration.md`**
6. **若新做 HTML/markdown 報告，記得 r2-upload 帶 --keep**