# Cloudflare Pages 部署說明 / Cloudflare Pages deployment guide

## 摘要 / Summary

本目錄包含 `build/` 中已產生的靜態部署產物。它不需要 Node.js 建置環境即可上傳，也沒有遠端 API、資料庫或分析腳本。任何上傳、Git 推送或自訂網域綁定都必須由具備帳號權限的人員手動執行；本交付物**沒有**執行任何外部上傳。

This directory contains the prebuilt static deployment artifact in `build/`. It can be uploaded without a Node.js build environment and contains no remote API, database, or analytics script. Any upload, Git push, or custom-domain binding must be performed manually by a person with account authority. This deliverable **has not** performed an external upload.

## 部署包內容 / Deployment artifact contents

| 檔案 / File | 用途 / Purpose |
|---|---|
| `index.html` | 應用程式進入點 / Application entry |
| `app.js`, `cash-close-core.js`, `validation.js`, `storage.js`, `csv-export.js`, `i18n.js` | 瀏覽器 PWA 模組 / Browser PWA modules |
| `sw.js` | 同源靜態資源離線快取 / Same-origin offline cache |
| `manifest.webmanifest` | PWA 安裝資訊清單 / Install manifest |
| `icon-192.svg`, `icon-512.svg` | 應用程式圖示 / App icons |
| `DEPLOY.md` | 本部署說明 / This guide |

## 本地重新建構 / Local rebuild

```bash
cd /data/workspace/bbd-daily-cash-close
node -v   # 需 Node.js 18 或更新版本 / Requires Node.js 18+
npm install
npm test
npm run build
```

測試與建構均只使用本機檔案系統與 Node.js 內建模組。若 `npm test` 回傳非零結束碼，或 `npm run build` 未產生 `build/index.html`，請不要上傳。

The tests and build use only the local file system and Node.js built-ins. If `npm test` returns a non-zero exit code or `npm run build` does not create `build/index.html`, do not upload.

## 選項 A：使用 Wrangler 直接上傳（推薦，無 Git 也能部署） / Option A: Direct upload with Wrangler

1. 安裝並登入 Wrangler：

   ```bash
   npm install -g wrangler
   wrangler login
   ```

2. 建立 Cloudflare Pages 專案（只在第一次執行）：

   ```bash
   wrangler pages project create bbd-daily-cash-close --production-branch=main
   ```

3. 上傳本地 `build/`：

   ```bash
   wrangler pages deploy ./build --project-name=bbd-daily-cash-close --branch=main
   ```

   說明文件指出，未先建立專案時首次部署可能找不到專案；因此先建立再上傳較穩定。[3]

4. 成功後，Wrangler 會回傳 `*.pages.dev` 網址。請以 HTTPS 開啟，確認 `manifest.webmanifest`、`sw.js` 與 `icon-192.svg` 均可載入，並在瀏覽器開發者工具的「Application / 應用程式」面板確認 PWA 清單。

## 選項 B：連接 Git 儲存庫（自動建構） / Option B: Git integration

1. 建立遠端 Git 儲存庫，例如：`https://github.com/<owner>/bbd-daily-cash-close.git`。
2. 在沙盒中設定遠端並推送：

   ```bash
   git remote add origin https://github.com/<owner>/bbd-daily-cash-close.git
   git push -u origin main
   ```

3. 登入 Cloudflare 儀表板，進入 **Workers & Pages**，建立專案並選擇 **Import an existing Git repository / 匯入現有 Git 儲存庫**。
4. 設定：
   - Production branch：`main`
   - Build command：`npm ci && npm run build`
   - Build output directory：`build`
   - Node.js version：18 或更新版本 / Node.js 18+
5. 官方文件說明，未使用框架時可將建構指令設為 `exit 0`，但本專案必須執行 `npm run build`，因此應明確設定 `npm ci && npm run build`。[1]

## 自訂網域 / Custom domain

部署完成並取得 `*.pages.dev` 網址後，才在專案的 **Custom domains** 設定中新增網域。若是頂層網域，須先將名稱伺服器指向 Cloudflare；若是子網域，可由外部 DNS 建立指向 `<project>.pages.dev` 的 CNAME。僅手動建立 CNAME 而不在 Cloudflare Pages 專案內綁定網域，可能無法解析。[2]

## 範圍與資料邊界 / Scope and data boundary

- 每筆記錄是一個營業日、一個店鋪標籤、一個班次標籤。
- 支援 TND、USD、EUR 作為顯示幣別；不執行匯率換算。
- 所有資料僅存在瀏覽器 `localStorage`，CSV 由使用者裝置下載。
- 沒有追蹤、帳號、伺服器同步或第三方請求。
- 多店鋪僅為文字標籤，未實作店鋪主檔、權限或跨裝置同步。

## 回滾 / Rollback

Cloudflare Pages 保留歷次部署。若新版本異常，可從儀表板回到前一個成功的部署；本地亦可保留 `build/` 的 Git 版本。PWA 安裝後的使用者會在下一次載入時取得新版 Service Worker；若清單或快取行為變更，應先清除測試裝置的網站資料與 Service Worker。

## 驗證清單 / Verification checklist

- [ ] `npm test` 全部通過 / All tests pass
- [ ] `npm run build` 成功產生 `build/index.html`
- [ ] `https://<project>.pages.dev/manifest.webmanifest` 回傳 `application/manifest+json` 或 `application/json`
- [ ] 首頁可儲存一筆記錄、即時顯示預期結餘與差額
- [ ] CSV 下載後以試算表開啟，公式注入字串以引號包圍
- [ ] HTTPS 網址可安裝 PWA（部分瀏覽器需先開啟頁面）

## 引用來源 / References

[1] https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
> Before you continue All of the framework guides assume you already have a fundamental understanding of Git.

[2] https://clean-deps.cloudflare-docs-7ou.pages.dev/pages/configuration/custom-domains/
> If you do not want to point your nameservers to Cloudflare, you must create a custom CNAME record to use a subdomain with Cloudflare Pages.

[3] https://community.benhalpern.com/ajramirezdev/-how-i-deployed-a-nextjs-15-pwa-on-cloudflare-pages-with-zero-backend-iha
> Wrangler won't create the Pages project automatically on first deploy.