docs: Secret-not-Plain-text token, R2 optional, VITE_API_BASE for web build

README.md

@@ -152,8 +152,8 @@ pnpm --filter @chippot/worker test
 pnpm --filter @chippot/worker typecheck
 pnpm --filter @chippot/worker dev          # local wrangler dev
 
-# Frontends
-pnpm --filter @chippot/web build
+# Frontends — the web build requires VITE_API_BASE (your worker URL); admin does not
+VITE_API_BASE=https://chippot.<your-subdomain>.workers.dev pnpm --filter @chippot/web build
 pnpm --filter @chippot/admin build
 ```
 
@@ -171,16 +171,17 @@ so DB tests seed real parents and use a distinct id-space (9001+).
 # 1. Worker — applies D1 migrations, then deploys (carries the cron + admin.example.com/api route)
 pnpm --filter @chippot/worker run deploy
 
-# 2. Frontends → Pages
-cd packages/web   && pnpm build && wrangler pages deploy dist --project-name chippot-web   --branch main
+# 2. Frontends → Pages (the web build needs VITE_API_BASE = your worker URL)
+cd packages/web   && VITE_API_BASE=https://chippot.<your-subdomain>.workers.dev pnpm build && wrangler pages deploy dist --project-name chippot-web   --branch main
 cd packages/admin && pnpm build && wrangler pages deploy dist --project-name chippot-admin --branch main
 
 # 3. Register the guild slash commands (/繳費 · /發起繳費 · /綁定) — needs DISCORD_BOT_TOKEN, DISCORD_APPLICATION_ID, DISCORD_GUILD_ID in packages/worker/.dev.vars
 pnpm --filter @chippot/worker register
 ```
 
-Provision your own resources (D1, R2, an Access application) and fill in `wrangler.toml`
-accordingly — `database_id`, the R2 bucket, `ACCESS_*`, and the Discord vars.
+Provision your own resources (D1 and an Access application; **R2 is optional** — only needed for
+payment screenshots) and fill in `wrangler.toml` accordingly — `database_id`, the R2 bucket (drop
+`[[r2_buckets]]` to skip), `ACCESS_*`, and the Discord vars.
 
 ## Configuration
 

README.zh-TW.md

@@ -143,8 +143,8 @@ pnpm --filter @chippot/worker test
 pnpm --filter @chippot/worker typecheck
 pnpm --filter @chippot/worker dev          # 本地 wrangler dev
 
-# 前端
-pnpm --filter @chippot/web build
+# 前端 — web build 需要 VITE_API_BASE（你的 worker 網址）；admin 不需要
+VITE_API_BASE=https://chippot.<你的帳號子網域>.workers.dev pnpm --filter @chippot/web build
 pnpm --filter @chippot/admin build
 ```
 
@@ -161,16 +161,16 @@ pnpm --filter @chippot/admin build
 # 1. Worker — 套用 D1 migrations 後部署（含 cron trigger 與 admin.example.com/api 路由）
 pnpm --filter @chippot/worker run deploy
 
-# 2. 前端 → Pages
-cd packages/web   && pnpm build && wrangler pages deploy dist --project-name chippot-web   --branch main
+# 2. 前端 → Pages（web build 需帶 VITE_API_BASE = 你的 worker 網址）
+cd packages/web   && VITE_API_BASE=https://chippot.<你的帳號子網域>.workers.dev pnpm build && wrangler pages deploy dist --project-name chippot-web   --branch main
 cd packages/admin && pnpm build && wrangler pages deploy dist --project-name chippot-admin --branch main
 
 # 3. 註冊 guild slash 指令（/繳費 · /發起繳費 · /綁定）— 需在 packages/worker/.dev.vars 填入 DISCORD_BOT_TOKEN、DISCORD_APPLICATION_ID、DISCORD_GUILD_ID
 pnpm --filter @chippot/worker register
 ```
 
-請自行建立資源（D1、R2、一個 Access application）並把對應值填進 `wrangler.toml`——
-`database_id`、R2 bucket、`ACCESS_*` 與 Discord 相關 vars。
+請自行建立資源（D1 與一個 Access application；**R2 為選填**，只有繳費截圖功能才需要）並把對應值填進
+`wrangler.toml`——`database_id`、R2 bucket（不需要就移除 `[[r2_buckets]]`）、`ACCESS_*` 與 Discord 相關 vars。
 
 ## 設定
 

docs/DEPLOY.md

@@ -24,7 +24,7 @@ Discord  ─┐                               ┌─ D1   (chippot-db)        SQ
 
 - **1 個 Worker**（`chippot`）：API、Discord 互動、每日 cron。
 - **2 個 Pages 專案**：`chippot-web`（公開的繳費上傳頁）、`chippot-admin`（受 Access 保護的後台）。
-- **1 個 D1 資料庫**、**1 個 R2 bucket**。
+- **1 個 D1 資料庫**（必要）、**1 個 R2 bucket**（**選填**，只有「成員上傳繳費截圖」需要──見第 2 節）。
 - **1 個 Cloudflare Access application**（保護後台）。
 - **1 個 Discord application + bot**。
 - 建議 3 個子網域（在你掛在 Cloudflare 的網域底下），例如：
@@ -83,15 +83,15 @@ web build 的 `VITE_API_BASE`、以及 Cloudflare Access application 的 domain
 
 1. 進 [Cloudflare 後台](https://dash.cloudflare.com) → **Storage & Databases → D1**。
 2. 建立資料庫，名稱填 `chippot-db`。建立後頁面會顯示 **database_id**（一串 UUID）→ **記下來**，待會填 `wrangler.toml`。
-3. 進 **Storage & Databases → R2** → 建立 bucket，名稱填 `chippot-proofs`。
+3. （**選填**，需要繳費截圖功能才做）進 **Storage & Databases → R2** → 建立 bucket，名稱填 `chippot-proofs`。不需截圖可跳過，並移除 `wrangler.toml` 的 `[[r2_buckets]]` 區塊。
 
 ### 路徑二（CLI）
 
 ```bash
 # D1 資料庫 → 建立後輸出包含 database_id，記下來
 wrangler d1 create chippot-db
 
-# R2 bucket（存截圖，私有）
+# R2 bucket（存截圖，私有）── 選填，不需截圖可略過此行並移除 wrangler.toml 的 [[r2_buckets]] 區塊
 wrangler r2 bucket create chippot-proofs
 ```
 
@@ -189,17 +189,21 @@ git update-index --skip-worktree packages/worker/wrangler.toml
 5. 部署成功後，在 Workers Builds 頁或 Worker 的「Triggers」分頁找到 worker 網址，格式為 `https://chippot.<你的帳號子網域>.workers.dev`。**記下這個網址**，後面設 web 的 `VITE_API_BASE` 要用。
 
 6. 設定 **Worker runtime secret**：
-   進 Worker → **Settings → Variables and Secrets** → 新增 Secret：
+   進 Worker → **Settings → Variables and Secrets** → 新增變數：
+   - Type：**Secret**（加密）── ⚠️ **務必選 Secret，不要選 Plain text**，原因見下方警告
    - Name：`DISCORD_BOT_TOKEN`
    - Value：第 3 步取得的 bot token
 
-   > Secret 跨 deploy 保留，不會被後續部署覆寫。
+   > ⚠️ **類型一定要選「Secret」，不要選「Plain text」。** `wrangler deploy`（Workers Builds
+   > 每次部署都會跑）把 `wrangler.toml` 當成 runtime 變數的**唯一真相來源**：任何「在後台設、但
+   > `wrangler.toml` 沒有」的 **Plain text 變數，每次部署都會被清掉**——於是 bot token 一更新就消失、
+   > 每次都得重填。**Secret（加密）不受此影響，跨 deploy 永久保留**（除非你手動 `wrangler secret delete`）。
 
 7. 回到 Discord 開發者後台，把 **Interactions Endpoint URL** 設成：`https://<你的 worker 網址>/interactions`（按 Save，Discord 會即時驗證簽章）。
 
 #### 6-2. 部署 web（繳費上傳頁，Pages）
 
-> ⚠️ **先完成 6-1 再做這步**——web 需要 worker 網址才能設 `VITE_API_BASE`。若未設，繳費頁在瀏覽器載入時會立刻報錯（白屏/console error），這是刻意的 fail-loud 設計。
+> ⚠️ **先完成 6-1 再做這步**——web 需要 worker 網址才能設 `VITE_API_BASE`。若 build 時未設此變數，**Pages build 會直接失敗**（fail-fast，刻意設計），不會產出載入即白屏的 bundle；請務必在下方第 4 步填好。
 
 1. 進 Cloudflare 後台 → **Workers & Pages → Create → Pages（Connect to Git）**。
 2. 選你的 fork，branch 選 `main`，Project name 填 `chippot-web`。
@@ -361,7 +365,7 @@ DISCORD_BOT_TOKEN=... DISCORD_APPLICATION_ID=... DISCORD_GUILD_ID=... pnpm --fil
 
 | 名稱 | 類型 | 設定位置（路徑一 後台 / 路徑二 CLI） | 跨 deploy |
 |---|---|---|---|
-| `DISCORD_BOT_TOKEN` | Worker runtime secret | 後台 Worker → Settings → Variables and Secrets ／ `wrangler secret put` | 保留 |
+| `DISCORD_BOT_TOKEN` | Worker runtime secret（**類型須為 Secret，非 Plain text**） | 後台 Worker → Settings → Variables and Secrets ／ `wrangler secret put` | 保留（**Plain text 變數每次 deploy 會被清掉**，所以一定要設成 Secret） |
 | `DISCORD_APPLICATION_ID`、`DISCORD_PUBLIC_KEY`、`WEB_ORIGIN`、`ADMIN_ORIGIN`、`ACCESS_TEAM_DOMAIN`、`ACCESS_AUD` | Worker runtime var | `wrangler.toml [vars]`（兩路徑相同） | 由 toml 覆寫 |
 | `VITE_API_BASE` | Pages build 變數（非 secret） | web 的 Pages 專案 → 設定 → 變數（路徑一）／ build 時環境變數（路徑二） | build 當下（Pages UI 設定後對後續 build 持續生效） |
 
@@ -372,7 +376,7 @@ DISCORD_BOT_TOKEN=... DISCORD_APPLICATION_ID=... DISCORD_GUILD_ID=... pnpm --fil
 ## 10. 常見問題
 
 - **後台顯示「未授權，請重新登入」**：多半是 `ACCESS_AUD` / `ACCESS_TEAM_DOMAIN` 與你的 Access application 對不上，或登入的 email 不在 Access policy 內。檢查第 4、5 步。
-- **繳費上傳頁載入即報錯（白屏 / console error）**：`VITE_API_BASE` 未設定，繳費頁會立刻 fail-loud——這是刻意設計，避免打到別人的後端。確認 web 的 Pages build 變數 `VITE_API_BASE` 已正確設為你的 worker 網址。
+- **繳費上傳頁載入即報錯（白屏 / console error）**：表示這個 bundle 是在沒設 `VITE_API_BASE` 的情況下 build 的（新版 build 會 fail-fast 擋下，舊 bundle 才會有此症狀）。確認 web 的 Pages build 變數 `VITE_API_BASE` 已設為你的 worker 網址後**重新 build/部署**即可。
 - **繳費上傳頁送出失敗 / CORS**：`VITE_API_BASE`（build 期）要指向你的 worker，且 worker 的 `WEB_ORIGIN` 要等於 `https://pay.<你的網域>`（第 5、6 步）。
 - **Discord Slash 指令沒出現**：確認第 7 步用對 guild id、bot 已在伺服器且有 `applications.commands` scope；可再按一次設定頁的「註冊 / 更新」按鈕，或重跑 CLI `register`。
 - **`/interactions` 驗證失敗**：`DISCORD_PUBLIC_KEY` 要跟你的 application 一致（`wrangler.toml [vars]`）。