# 進銷存模組 — GCP & Vercel 設定 Checklist

本指南把 Vercel Function (`/api/inventory.js`) 接到 Google Sheet「愛嬌青春製冰室 進銷存」。
完成後 dashboard「進銷存」分頁會自動讀真實資料。

預估時間：**30 分鐘**（GCP 第一次設定 20 分鐘 + Vercel 環境變數 10 分鐘）

---

## Phase 1 — Google Cloud：開 Service Account（20 分鐘）

### 1.1 開 GCP Project
1. 用 **terrel.yeh@gmail.com** 登入 [console.cloud.google.com](https://console.cloud.google.com/)
2. 上方專案選單 → **新增專案**
3. 專案名稱：`aikyo-inventory`（或 `aikyo-pos`）
4. 建立完成後**切換到該專案**

### 1.2 啟用 Sheets API
1. 左側選單 → **API 和服務 → 程式庫**
2. 搜尋 `Google Sheets API`
3. 點進去 → **啟用**

### 1.3 建立 Service Account
1. 左側選單 → **IAM 與管理 → 服務帳戶**
2. 點上方 **+ 建立服務帳戶**
3. 名稱：`inventory-reader`
4. 服務帳戶 ID：自動產生即可（例 `inventory-reader@aikyo-inventory.iam.gserviceaccount.com`）
5. **建立並繼續** → 角色不用設（讀公開分享的 Sheet 不需要 IAM 角色）→ **完成**

### 1.4 下載 Service Account 金鑰
1. 在服務帳戶清單，點剛建好的 `inventory-reader`
2. 上方分頁 **金鑰 → 新增金鑰 → 建立新的金鑰**
3. 類型選 **JSON** → 建立
4. **JSON 檔案會自動下載**，請妥善保管（這檔案只會給你一次）
5. 打開 JSON 檔，記下兩個值：
   - `client_email`（例：`inventory-reader@aikyo-inventory.iam.gserviceaccount.com`）
   - `private_key`（一大串 `-----BEGIN PRIVATE KEY-----...`）

> ⚠️ **這份 JSON 不能 commit 進 git**。請放在不會被同步的地方（例如 1Password、本機 `~/.gcp-keys/`）

---

## Phase 2 — 把 Service Account 加進 Sheet 共用（1 分鐘）

1. 開[進銷存 Sheet](https://docs.google.com/spreadsheets/d/1e57hOOVInWqdDSI0CWNi5gpiXAIkTXz8fK8Au4nS6LE/edit)
2. 右上角 **共用**
3. 把 Phase 1.4 拿到的 `client_email` 貼進去
4. 權限選 **檢視者**（Viewer）即可，不用編輯權
5. **取消勾選**「通知使用者」（Service Account 沒信箱）
6. 共用

> ✅ 完成後 Sheet 本身仍是「私密」，只有你和 Service Account 看得到

---

## Phase 3 — Vercel 環境變數（5 分鐘）

### 3.1 進 Vercel Dashboard
1. 開 [vercel.com](https://vercel.com) → 找到 `aikyo-pos` 專案
2. **Settings → Environment Variables**

### 3.2 新增 3 個變數

| Name | Value | Environments |
|---|---|---|
| `GOOGLE_SA_EMAIL` | Phase 1.4 的 `client_email` 整串 | Production + Preview + Development |
| `GOOGLE_SA_KEY` | Phase 1.4 的 `private_key` 整串（含 `-----BEGIN...-----END...-----\n`）| Production + Preview + Development |
| `SHEET_ID` | `1e57hOOVInWqdDSI0CWNi5gpiXAIkTXz8fK8Au4nS6LE` | Production + Preview + Development |

> 💡 **`GOOGLE_SA_KEY` 的換行處理**：
> JSON 裡的 `private_key` 會看到很多 `\n`（字面 backslash-n）。
> 在 Vercel UI 直接整段貼上即可（包含開頭 `-----BEGIN PRIVATE KEY-----`、結尾 `-----END PRIVATE KEY-----` 和中間的 `\n`）。
> Function 裡的 `key.replace(/\\n/g, '\n')` 會把字面 `\n` 轉成真換行。

### 3.3 觸發 redeploy
環境變數改完後要 redeploy 才會生效：
- Vercel Dashboard → Deployments → 最新一筆 → 右側 **⋯ → Redeploy**
- 或本機 `git push` 任何 commit

---

## Phase 4 — 驗證（5 分鐘）

### 4.1 直接打 API 看 JSON
打開瀏覽器：
```
https://aikyo-pos.vercel.app/api/inventory
```

預期回傳：
```json
{
  "meta": { "lastUpdate": "2026-05-09", "isMock": false, ... },
  "today": { "date": "2026-05-09", "flavors": [...] },
  "monthSummary": { ... },
  "trend30d": [...],
  "nonSalesTop": [...]
}
```

### 4.2 看 dashboard
打開 [https://aikyo-pos.vercel.app/?inventory](https://aikyo-pos.vercel.app/?inventory)

應該會看到：
- Sheet 真實資料的卡片、趨勢圖、月度核對
- Mock 標籤消失

---

## 常見錯誤排查

| 錯誤訊息 | 原因 | 解法 |
|---|---|---|
| `403 The caller does not have permission` | Service Account 沒被加進 Sheet 共用 | 回到 Phase 2 |
| `404 Requested entity was not found` | `SHEET_ID` 錯了，或 Sheet 被刪 | 檢查 `SHEET_ID` |
| `Missing env vars` | Vercel 環境變數沒設 / 沒 redeploy | 回到 Phase 3 |
| `error:1E08010C:DECODER routines::unsupported` | `GOOGLE_SA_KEY` 換行格式問題 | 確認貼入時 `\n` 完整保留 |
| `Unable to parse range` | 分頁名稱不符 | 確認 Sheet 內分頁名稱與 v3 相符（`① 設定`、`② 每日盤點`、`③ 投料紀錄`、`④ 非銷售消耗`、`⑤ 進貨紀錄`、`⑥ 投料週期結算`、`⑦ 月度核對`） |
| Dashboard 顯示「MOCK 資料」 | 前端還在用 INVENTORY_MOCK，沒切到 fetch | 後續任務（前端串接） |

---

## 下一步

完成本指南後告訴我，我會：
1. 把前端 `renderInventory()` 從 mock 切到 `fetch('/api/inventory')`
2. 處理「資料還沒填」的 empty state
3. 把 dashboard 的營業額 join 進來，算出真實成本率