快電商素材庫交接規格書

一、專案定位

對外自助下載 Dropbox 素材的網站，給快電商（C2CBUY）的外部夥伴（經銷 / 推廣）用。

取代：Dropbox 手機 App 難用的痛點。外部夥伴不需要 Dropbox 帳號，也不需要登入。

存取控制：一組通關密語（?k=xxx 或首頁鎖屏輸入），密語存 sessionStorage。

部署路徑：/asset-library/（domain 底下的子路徑）。

二、資料來源（Dropbox）

項目	值
Dropbox 帳號	`[email protected]`
所屬 Team	美女子有限公司
Team Root Namespace ID	`12089691395`
Team Folder 路徑	`/快電商-C2CBUY`
Dropbox App 名稱	`meinvzi-asset-library`
Dropbox App Key	`oebuejmj6ainmcm`
App 類型	Scoped App / Full Dropbox
App 權限	`files.metadata.read`、`files.content.read`

結構：team folder /快電商-C2CBUY 底下的所有子資料夾都會自動顯示（無白名單），加上根目錄的直接檔案。

目前有 12 個分類：小編、快電商 IG Reels、快電商培育影片、快電商廣告素材、快電獎素材、業務-小編影片 2023、業務-小編影片 2024、要給寶特瓶拉、超速系統課程、大發、暫用上架（詠捻、上架暫用區。

三、技術棧

層	技術
部署平台	Cloudflare Pages（含 Pages Functions）
前端	純瀏覽器 vanilla JS，無框架、無 build step
後端（API）	Pages Functions（Node compatible runtime）
資料來源	Dropbox API v2（OAuth 2 refresh token）
Analytics 儲存	Cloudflare D1（見第十節）

Cloudflare 帳號 / Pages Project 名稱：由接手方指定，本規格書不寫死。

部署路徑：/asset-library/（domain 底下的子路徑）。原本規劃 /c2c/asset-library/，但 /c2c/* 路徑有 Cloudflare Access 內部保護（擋外部人），所以要放在根路徑或另一個沒 Access 保護的路徑底下。

四、環境變數 / Secrets

在 Cloudflare Pages Project 的 Production Environment 設定（Project 名稱由接手方指定）。

變數名	用途
`DROPBOX_APP_KEY`	OAuth 2 client_id
`DROPBOX_APP_SECRET`	OAuth 2 client_secret
`DROPBOX_REFRESH_TOKEN`	長效 refresh token（不過期）
`DROPBOX_ROOT_NAMESPACE_ID`	`12089691395`
`DROPBOX_ROOT_PATH`	`/快電商-C2CBUY`
`ASSET_LIBRARY_KEY`	URL `?k=xxx` 的通關密語，Tako 版目前為 `meinvzi2026`；電寶版是否沿用或換新，由使用者於接手時告知

設定指令範例：

CLOUDFLARE_ACCOUNT_ID=<接手方帳號 ID> \
  npx wrangler pages secret put DROPBOX_APP_KEY \
  --project-name=<接手方 Pages Project 名稱>
# stdin 輸入 secret 值

五、認證流程（Dropbox OAuth 2 Refresh Token）

為什麼用 refresh token

Dropbox 短效 access token 只活 4 小時，長期跑就會斷。改用 OAuth 2 授權碼 + offline flow 取得長效 refresh token（不過期，除非使用者手動撤銷），每次 API 呼叫前用 refresh token 換一次短效 access token 並 cache 3.5 小時。

一律延用 Tako 版的 App / Refresh Token

使用者拍板：Dropbox App、Refresh Token 一律延用 Tako 版現有那組，因為那是正式環境的授權，不重新申請。

App Key、App Secret：向使用者索取，或從 Tako 版 Cloudflare secret 匯出。
Refresh Token：同上（是 2026-08-20 使用者在正式環境授權的長效 token，不過期）。
App 名稱 meinvzi-asset-library、權限 files.metadata.read + files.content.read 都不變。

只有在使用者明確要求「換一組新的 App」時，才需要重跑下方新申請流程。

Refresh Token 取得步驟（新申請時用）

授權 URL（瀏覽器打開）：

https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&token_access_type=offline&response_type=code

Dropbox 帳號登入後拿到 authorization code（一次性）。

用 code 換 refresh token：

curl -X POST https://api.dropboxapi.com/oauth2/token \
  -u "<APP_KEY>:<APP_SECRET>" \
  -d "code=<AUTH_CODE>&grant_type=authorization_code"

Response 內有 refresh_token，這個存進 Cloudflare secret。

Runtime Auth Flow

每次 API 呼叫前：

查 Cloudflare Edge Cache（caches.default）有沒有 cached access token。
有就用，沒有（或過期）就 POST 到 https://api.dropboxapi.com/oauth2/token：
- Basic Auth：APP_KEY:APP_SECRET
- Body：grant_type=refresh_token&refresh_token=<REFRESH>
拿到 access token 後 cache 3.5 小時（12600 秒，保守留 30 分鐘 margin）。

Dropbox API 呼叫時必帶 Header

由於資料在 Team Folder，必須指定 root namespace：

Dropbox-API-Path-Root: {".tag":"root","root":"12089691395"}

不帶這個 header 會拿不到 Team Folder 的檔案，只會看到個人 Dropbox。

六、API 規格（Tako 現有 5 個，另新增 search 見第十節）

所有 endpoint 都吃 ?k=<ASSET_LIBRARY_KEY> 通關密語，錯誤或缺失 → HTTP 401 {"error":"unauthorized"}。

6.1 GET `/api/asset-library/folders`

用途：列出 team folder 根目錄的所有子資料夾 + 直接檔案。

Response（200 OK）：

{
  "folders": [
    { "name": "小編", "path": "/快電商-C2CBUY/小編", "id": "id:xxx", "count": null }
  ],
  "root_files": [
    {
      "id": "id:xxx",
      "name": "快電商c2c簡報.pdf",
      "path": "/快電商-C2CBUY/快電商c2c簡報.pdf",
      "size": 82844736,
      "ext": "PDF",
      "is_video": false,
      "is_image": false,
      "is_pdf": true,
      "modified": "2021-11-17T09:24:44Z"
    }
  ],
  "generated_at": "2026-08-30T12:46:31.566Z"
}

Behavior：呼叫 Dropbox /files/list_folder on DROPBOX_ROOT_PATH，recursive: false。

6.2 GET `/api/asset-library/files?folder=<name>`

用途：列出某個資料夾底下所有檔案（遞迴 flatten）。

Query：

folder=<name>：資料夾名稱（純名字，不帶 root path）。空字串或未帶 → 只回根目錄檔案。

Response（200 OK）：

{
  "folder": "小編",
  "count": 6,
  "truncated": false,
  "files": [
    {
      "id": "id:xxx",
      "name": "xxx.mp4",
      "path": "/快電商-C2CBUY/小編/子資料夾/xxx.mp4",
      "size": 12345678,
      "ext": "MP4",
      "is_video": true,
      "is_image": false,
      "is_pdf": false,
      "modified": "2024-01-15T10:20:30Z",
      "sub": "子資料夾",
      "can_thumbnail": true
    }
  ],
  "generated_at": "..."
}

Behavior：

資料夾內遞迴撈（recursive: true），只回檔案（不回資料夾）。
Hard limit 2000 筆，超過 truncated: true。
排序：modified 新到舊。
sub：檔案在該分類底下的相對子路徑（不只第一層）。
- 例 1：/快電商-C2CBUY/快電商廣告素材/2025 新品發表/xxx.jpg + 分類 快電商廣告素材 → sub = "2025 新品發表"。
- 例 2：更深層 /快電商-C2CBUY/快電商廣告素材/2025 新品發表/2月/xxx.jpg → sub = "2025 新品發表/2月"。
- 檔案直接在分類根目錄底下 → sub = ""。
can_thumbnail：Dropbox 支援縮圖的副檔名（jpg/png/gif/webp/bmp/tiff/tif/ppm/mp4/m4v/mov/avi/ogv/webm/flv/wmv/mpg/mkv/3gp/pdf）。

6.3 GET `/api/asset-library/download?path=<path>&name=<name>`

用途：下載單一檔案。

Query：

path：Dropbox 完整檔案路徑（/快電商-C2CBUY/...）。
name：顯示檔名（Content-Disposition 用）。

Response：檔案 stream，Header：

content-type：跟 Dropbox 回的一致（一般是 application/octet-stream 或原檔 MIME）。
content-disposition: attachment; filename="<encoded>"; filename*=UTF-8''<encoded>（RFC 5987，中文檔名不亂碼）。
cache-control: public, max-age=3600。

6.4 GET `/api/asset-library/thumbnail?path=<path>&size=<size>`

用途：取得檔案縮圖（JPEG）。

Query：

path：Dropbox 完整路徑。
size：w32h32、w64h64、w128h128、w256h256（預設）、w480h320、w640h480、w960h640、w1024h768、w2048h1536。

Response：JPEG stream，cache-control: public, max-age=86400（一天）。

行為：呼叫 Dropbox /files/get_thumbnail_v2，mode: strict，format: jpeg。不支援的副檔名回原 status code（一般 409），前端 img onerror 隱藏。

6.5 POST `/api/asset-library/zip`

用途：把多個檔案打包成 ZIP 串流下載。

Body（JSON）：

{
  "paths": [{ "path": "/快電商-C2CBUY/xxx.mp4", "name": "xxx.mp4" }],
  "zipName": "assets_20260830_2044.zip"
}

限制：paths 陣列上限 500 筆（超過會回 HTTP 400 錯誤：{"error":"too many files (max 500)"}）。

Response：ZIP stream，content-type: application/zip，Content-Disposition 附檔名。

實作要點（自己 stream 手寫 ZIP，不用 npm 套件）：

STORED 模式（無壓縮），理由：
1. 素材本身（mp4、jpg、pdf）都已壓縮過，DEFLATE 幾乎 0% 收益。
2. STORED 每 byte 零 CPU，適合 Cloudflare Workers 的 CPU 限制。
3. Finder、Windows Explorer、7z、WinRAR 都能讀。
UTF-8 檔名：General Purpose Bit Flag 設 0x0808（bit 3 = data descriptor after data、bit 11 = UTF-8 filenames），中文檔名不亂碼。
Data Descriptor 模式：邊 stream 邊算 CRC32 和 size，寫完檔案內容才寫 descriptor（不用一次載入整個檔案到記憶體）。
重複檔名：同 ZIP 內若檔名重複，自動加 (2)、(3)。
控制字元 / 非法字元：\x00-\x1F / \\ : * ? " < > | 替換為 _。

程式碼參考現有 functions/api/asset-library/zip.js（100 行純 JS，無 npm 相依）。

七、前端 UI 規格

7.1 頁面結構

┌─ Lock Screen（密語鎖屏，未帶 ?k 或密語錯時顯示）
│  └─ input + 「進入」按鈕
├─ Header（登入後顯示）
│  ├─ ≡ Hamburger（手機才顯示；桌機側邊欄常駐所以隱藏）
│  ├─ 素材庫（brand）
│  ├─ 搜尋 input（disabled，placeholder 寫「搜尋檔名... (準備中)」）
│  ├─ 「搜尋」按鈕（disabled）
│  └─ 「重新整理」按鈕
├─ Sidebar（桌機常駐左側 240px；手機 hamburger 開）
│  ├─ 「總覽」段
│  │  └─ 全部（根目錄）+ 檔案數
│  └─ 「分類」段
│     └─ 每個分類一列，右側「→」箭頭
├─ Main
│  ├─ 類型 Tabs：全部 / 照片 / 影片 / PDF / 其他
│  ├─ 右側「全選當前」按鈕
│  ├─ Meta line：「<分類名> · 共 N 個檔案」
│  └─ Grid（每張卡片）
│     ├─ 左上：勾選框
│     ├─ 左下：副檔名 badge（黃底黑字）
│     ├─ 右上：↓ 單檔下載按鈕
│     ├─ 縮圖（若 can_thumbnail 才呼叫 API）
│     ├─ 影片疊「▶」符號、PDF 疊「PDF」文字、其他疊副檔名文字
│     ├─ 檔名（最多兩行，超過省略號）
│     └─ 子資料夾 tag + 檔案大小 MB
└─ 浮動 Toolbar（勾選時才顯示）
   ├─ 「已選 N 個 · 總 XX MB」
   ├─ 「取消選取」
   └─ 「打包下載 (ZIP)」

7.2 色彩系統

--bg: #0d1524           /* 主背景（深藍） */
--panel: #111c30        /* 卡片 / 面板 */
--line: #1e2a44         /* 分隔線 */
--text: #e5e7eb         /* 主文字 */
--muted: #94a3b8        /* 次要文字 */
--accent: #facc15       /* 強調色（明亮黃） */
--accent-ink: #111827   /* 強調色上的文字（深黑） */
--sidebar: #0a1120      /* 側邊欄（比主背景更深） */

7.3 字型

"PingFang TC", "Noto Sans TC", "Microsoft JhengHei", sans-serif，基礎 14px，line-height 1.5。

7.4 Grid Breakpoint

螢幕寬度	Grid 欄數
> 1400px	5
1101 ~ 1400px	4
801 ~ 1100px	3
501 ~ 800px	3（手機版 layout，sidebar 收合）
≤ 500px	2

800px 以下切手機版：sidebar 變成 fixed，左移出畫面，hamburger 開合，backdrop 遮罩，header 的「素材庫」brand 跟「重新整理」按鈕隱藏（節省寬度）。

7.5 互動流程

進入
- URL 帶 ?k=xxx 或 sessionStorage 有值 → 直接進入。
- 否則顯示 lock screen，輸入密語 → 寫入 URL 和 sessionStorage → 進入。
- API 回 401 → 清 sessionStorage、清 URL、彈回 lock screen。
載入分類
- Boot 時打 /api/asset-library/folders 拿分類 + 根檔案。
- 預設選「全部（根目錄）」（folder = ''）。
切分類
- 點側邊分類 → 打 /api/asset-library/files?folder=<name> → 更新 grid。
- 切分類時清空選取（避免跨分類批次的困惑）。
- 手機切分類同時收 sidebar。
切類型 Tab
- 純前端 filter（不重打 API）。
勾選 / 全選
- 單張卡點勾選框 → toggle selected。
- 選中的卡片外框變黃色（accent 色 #facc15）+ 外圍淡黃色 outline 0 0 0 2px rgba(250,204,21,.35)，勾選框內顯示「✓」。
- 手機一次最多 20 個，超過彈 toast。
- 「全選當前」= 全選當前 tab 篩出來的檔案。若已全選 → toggle off。
- 勾任何一個 → 底部 toolbar 出現。
單檔下載
- 卡片右上「↓」→ 直接 <a> 導向 /api/asset-library/download。
批次下載（ZIP）
- 桌機、手機都走 server ZIP。
- 桌機超過 500MB 彈 confirm。
- 硬上限 500 個（server 端擋）。
- 手機仍限勾 20 個。
- ZIP 檔名：<分類名 or 素材庫>_<YYYYMMDD_HHMM>.zip。
- 打包中按鈕變「打包中...」+ disabled。
- 打包完成自動觸發下載，清空選取。
- iPhone 用戶：自動進「檔案 App」→ Downloads，點 zip 自動解壓。

7.6 SEO / Crawler

Meta 一律 noindex,nofollow,noarchive,nosnippet，避免搜尋引擎收錄。

八、批次下載為什麼統一走 Server ZIP（重要）

歷史：初版桌機用 server ZIP、手機用 sequential（前端跑 for loop，一個一個觸發 <a download>.click()）。

問題：iOS Safari 對非 user gesture context 的 <a download>.click() 靜默 block。sequential 用 setTimeout 觸發下一個 → iOS 完全下不動。畫面看到「完成」是假象，app loop 跑完但 Safari 全部丟棄。Chromium 反而 work，所以 unit test 過但用戶端失敗。

結論：唯一可靠的批次下載方法就是 server 打包成單一 ZIP 檔一次下載。

手機仍然限 20 個：不是技術限制，是 UX 考量（手機解 zip 檔案太多不方便）。

九、部署步驟

9.1 首次建立

在使用者指定的 Cloudflare 帳號下建立 Pages project（名稱由使用者指定）。
綁定使用者指定的 domain。
在 Production Environment 設所有 secrets（見第四節）。
部署：

cd <程式碼根目錄>
CLOUDFLARE_ACCOUNT_ID=<接手方帳號 ID> \
  npx wrangler pages deploy . \
  --project-name=<接手方 Pages Project 名稱> \
  --branch=main \
  --commit-dirty=true

9.2 檔案結構

<repo 根目錄>/
├─ asset-library/
│  └─ index.html          # 前端 SPA（單檔）
└─ functions/
   └─ api/
      └─ asset-library/
         ├─ _common.js    # getAccessToken / dbxPost / dbxContent / checkKey / json
         ├─ folders.js    # GET /api/asset-library/folders
         ├─ files.js      # GET /api/asset-library/files
         ├─ download.js   # GET /api/asset-library/download
         ├─ thumbnail.js  # GET /api/asset-library/thumbnail
         ├─ zip.js        # POST /api/asset-library/zip
         └─ search.js     # GET /api/asset-library/search（新增，見第十節）

9.3 更新部署

同上指令，Wrangler 會自動 diff 上傳。

十、電寶版必做功能（Tako 版沒做，使用者拍板要加）

10.1 搜尋（必做）

目的：外部夥伴不用一個個資料夾點進去慢慢找，直接打字找檔案。

前端規格：

Header 已有的搜尋 input 拿掉 disabled 屬性，placeholder 從「搜尋檔名... (準備中)」改成「搜尋檔名...」。
觸發：按 Enter 或點「搜尋」按鈕。
空字串 = 清除搜尋，回到目前選的分類 grid。
搜尋結果 grid 每張卡片右下多顯示所屬分類 tag（跟現有 sub tag 樣式一致），方便使用者知道檔案在哪個分類。
Meta 列顯示：搜尋「<關鍵字>」· 共 N 個結果。

API 規格（新增）：GET /api/asset-library/search?k=xxx&q=<keyword>&type=<all|image|video|pdf|other>

Query：
- q：關鍵字（必填），至少 1 個字。
- type：類型過濾（選填，預設 all）。

Response（200 OK）：

{
  "q": "喵星機",
  "count": 3,
  "truncated": false,
  "files": [
    {
      "id": "...", "name": "...", "path": "...", "size": ...,
      "ext": "MP4", "is_video": true, "is_image": false, "is_pdf": false,
      "modified": "...", "sub": "喵星機/16-9", "can_thumbnail": true,
      "category": "快電商廣告素材"
    }
  ],
  "generated_at": "..."
}

Behavior：
- 呼叫 Dropbox /files/search_v2，options.path 設 team folder 根路徑，options.filename_only: true（只搜檔名，不搜檔案內容）。
- 過濾出 metadata.metadata['.tag'] === 'file' 的項目。
- category：從 path_display 抽出第一層子資料夾名（例：/快電商-C2CBUY/快電商廣告素材/xxx.jpg → 快電商廣告素材）；根目錄檔案 category = ""。
- type 過濾在 server 端做（跟 files.js 同一套 is_image / is_video / is_pdf 判斷）。
- Hard limit 200 筆（Dropbox /files/search_v2 一次 call 可設 max_results 至 1000，本規格取 200 保守；若使用者未來反映不夠可調高）。

Fallback：若 Dropbox search API 有 rate limit 問題或體驗差，可改前端 substring filter（前端 boot 時預拉全庫 metadata → 本地 filter）。這個選項留給電寶視實測情況決定。

10.2 Analytics（必做）

目的：讓使用者（快電商內部）可以看「外部夥伴下載了什麼、什麼時候、多常用」，作為素材優化依據。

後端規格：

每次呼叫 /api/asset-library/download 或 /api/asset-library/zip 時，同步寫一筆記錄到 Cloudflare D1。

D1 table schema（建議）：

CREATE TABLE IF NOT EXISTS asset_library_downloads (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  ts TEXT NOT NULL DEFAULT (datetime('now')),
  kind TEXT NOT NULL,          -- 'single' 或 'zip'
  file_path TEXT,              -- 單檔下載才有
  file_name TEXT,              -- 同上
  file_size INTEGER,           -- 同上（單檔）
  zip_count INTEGER,           -- zip 才有，檔案數
  zip_total_size INTEGER,      -- zip 才有，總 byte
  zip_names TEXT,              -- zip 才有，JSON array of file names (最多前 20 個)
  category TEXT,               -- 從 path 抽出的第一層分類名
  ua TEXT,                     -- User-Agent
  ip TEXT,                     -- Cloudflare CF-Connecting-IP header
  country TEXT                 -- Cloudflare CF-IPCountry header
);

CREATE INDEX IF NOT EXISTS idx_asset_dl_ts ON asset_library_downloads (ts);
CREATE INDEX IF NOT EXISTS idx_asset_dl_cat ON asset_library_downloads (category);

實作要點：

用 Cloudflare Pages Functions 綁定 D1（env.DB）。
記錄動作 fire-and-forget，不 block 下載回應（用 ctx.waitUntil()）。
不記通關密語（避免密語洩漏）。
不記姓名、Email、電話等個人身分資料（外部夥伴頁面本來也沒收集這些）。
只記錄用於流量統計的技術欄位：IP、國家、UA、下載檔案內容。這些於一般網站分析屬於常見紀錄。

管理介面（MVP）：先不做管理頁。使用者要看數據時，Tako 從 D1 撈報表（例：本週最熱門素材、下載總量、獨立 IP 數）。

未來可加（列出，但不列必做）：

網頁版管理面板（另 route + 加密碼）
週報自動 email

10.3 不做（使用者拍板）

內部資料夾隱藏：使用者 2026-08-30 拍板不做。目前顯示 team folder 底下所有子資料夾（包含「小編」「業務-小編影片 2023 / 2024」「暫用上架（詠捻」「上架暫用區」「要給寶特瓶拉」等），這是可接受的行為。

理由：Dropbox 側整理才是正確做法，不用在網站硬藏。若未來要藏，Dropbox 端直接把該資料夾搬出 /快電商-C2CBUY team folder 即可。

10.4 可選優化（電寶視情況做）

以下不是必做，是電寶如果有餘裕可以做的優化：

項目	現況痛點	建議做法
KV Cache metadata	每次 request 都打 Dropbox API，稍慢	用 Cloudflare KV cache `folders` / `files` response（TTL 5 分鐘）
首次載入速度	大分類遞迴撈慢（每 folder 一個 API call）	由上面的 KV cache 解決
縮圖 fallback icon	不支援縮圖的檔案只顯示副檔名文字（灰底）	改成有 icon 圖示（PDF / DOC / ZIP 等各自 icon）

十一、外部依賴 / Quota

Dropbox API

免費 tier 沒有硬 rate limit，但有 burst limit（單一 endpoint 短時間爆量會被 429）。
目前使用量：每次 request 打 1 次 metadata + N 次 thumbnail，總量小。
Refresh token flow：每 3.5 小時換一次 access token，一天 ~7 次。

Cloudflare Pages

免費 tier：每月 500 次 build、100k requests / day。
Pages Functions：每天 100k invocation（免費）。
Workers CPU：每 request 上限 10ms CPU time（免費 tier）。ZIP endpoint 是 IO bound（不吃 CPU），OK。

Cloudflare Edge Cache

存 access token 用 caches.default，免費 unlimited。

十二、交接注意事項

Refresh Token 延用

Tako 版的 refresh token 是 2026-08-20 由使用者授權的，只要 App Key / Secret 不變，電寶版可以延用同一個 token（不用重新授權）。若要換新的 App，就要重跑第五節的取得流程。

Team Folder 權限

[email protected] 這個帳號要被加入「美女子有限公司」team 且能看 /快電商-C2CBUY 這個 team folder。目前已設定好，接手時不用動。

Domain / Pages Project 名稱

由接手方另行指定，本規格書不寫死。使用者會在部署階段告知電寶要掛哪一組 domain、哪個 Cloudflare 帳號、Pages project 用什麼名字。

Dev / Test

沒有 staging 環境。要測改動：

本地 dev：npx wrangler pages dev .（需要在 .env 或 CLI 帶 secrets）。
或部署到 Cloudflare 的 preview branch（--branch=preview），拿到 preview URL 測。

更新流程建議

改 code
部署到 preview branch 拿 preview URL 驗證
使用者驗證 OK 後才部署到 main branch（覆蓋 canonical URL）

十三、Tako 版程式碼位置（供參考）

Tako 版原始碼位於 Tako 的 workspace repo（notes/taco/qtracychen-net/ 底下）。使用者可以另行提供 zip 或 GitHub 讀取權，讓電寶拿當起點，或完全從零重寫皆可。

UI 設計、色彩、互動流程請以本規格書第七節為準，不需另外討論。

十四、規格拍板紀錄

以下事項使用者 2026-08-30 已拍板，本規格書據此定稿：

項目	拍板
UI / 色彩 / 互動流程	照 Tako 現況鎖定，不再議
搜尋功能	必做（規格見第 10.1 節）
Analytics	必做（規格見第 10.2 節）
內部資料夾隱藏	不做
Dropbox App / Refresh Token	延用 Tako 版現有那組（正式環境授權）
Domain / Pages Project 名稱	由使用者接手時另行告知電寶

一、專案定位

二、資料來源（Dropbox）

三、技術棧

四、環境變數 / Secrets

五、認證流程（Dropbox OAuth 2 Refresh Token）

為什麼用 refresh token

一律延用 Tako 版的 App / Refresh Token

Refresh Token 取得步驟（新申請時用）

Runtime Auth Flow

Dropbox API 呼叫時必帶 Header

六、API 規格（Tako 現有 5 個，另新增 search 見第十節）

6.1 GET /api/asset-library/folders

6.2 GET /api/asset-library/files?folder=<name>

6.3 GET /api/asset-library/download?path=<path>&name=<name>

6.4 GET /api/asset-library/thumbnail?path=<path>&size=<size>

6.5 POST /api/asset-library/zip

七、前端 UI 規格

7.1 頁面結構

7.2 色彩系統

7.3 字型

7.4 Grid Breakpoint

7.5 互動流程

7.6 SEO / Crawler

八、批次下載為什麼統一走 Server ZIP（重要）

九、部署步驟

9.1 首次建立

9.2 檔案結構

9.3 更新部署

十、電寶版必做功能（Tako 版沒做，使用者拍板要加）

10.1 搜尋（必做）

10.2 Analytics（必做）

10.3 不做（使用者拍板）

10.4 可選優化（電寶視情況做）

十一、外部依賴 / Quota

Dropbox API

Cloudflare Pages

Cloudflare Edge Cache

十二、交接注意事項

Refresh Token 延用

Team Folder 權限

Domain / Pages Project 名稱

Dev / Test

更新流程建議

十三、Tako 版程式碼位置（供參考）

十四、規格拍板紀錄

6.1 GET `/api/asset-library/folders`

6.2 GET `/api/asset-library/files?folder=<name>`

6.3 GET `/api/asset-library/download?path=<path>&name=<name>`

6.4 GET `/api/asset-library/thumbnail?path=<path>&size=<size>`

6.5 POST `/api/asset-library/zip`