""" + NAV + """

🌾 農場遊戲交接手冊 v2.5

D1 七表 · Worker 十三 API · 12 種作物 · 天氣 + 留言板

2026-10-29 · 開心農場 v2.4

一、系統總覽

項目	值
前端網址	`https://farm.ahpal.com`
Worker URL	`https://ahpal-farm-api.praystone.workers.dev`
Pages 專案	`ahpal-farm`（GitHub Actions 部署）
D1 資料庫	`ahpal-farm-db`
GitHub repo	`praystone/ahpal-farm`
Turnstile Site Key	`0x4AAAAAAFq7xrbRdmP4m73Y`
Turnstile Secret	已存 Worker Secret `TURNSTILE_SECRET`

二、D1 七張表

#	表名	用途
1	`crops`	12 種作物（8 菜 4 水果），含 `category`
2	`farms`	每塊田（含 `stolen_at`）
3	`farm_logs`	播種/收成/偷菜紀錄
4	`farm_players`	玩家金幣
5	`farm_weather`	當前天氣（Cron 每 6 小時換）
6	`farm_comments`	留言板（Turnstile 保護）

12 種作物：🥕蘿蔔 60s / 🥬菠菜 120s / 🍅番茄 300s / 🥬高麗菜 600s / 🌽玉米 1800s / 🎃南瓜 3600s / 🌶️辣椒 5400s / 🍓草莓 7200s / 🍆茄子 7200s / 🫐藍莓 14400s / 🍉西瓜 28800s / 🍇葡萄 43200s（8 菜 4 水果）

三、Worker 十三 API

#	端點	方法	用途
1	`/api/crops`	GET	作物清單
2	`/api/plant`	POST	種植
3	`/api/farm`	GET	查看自己的田
4	`/api/harvest`	POST	收成（含天氣加成）
5	`/api/player`	GET	讀金幣
6	`/api/steal`	POST	偷菜
7	`/api/random-farm`	GET	隨機找成熟田
8	`/api/recent-steals`	GET	公告牆（含苦主）
9	`/api/steal-history`	GET	偷菜總表（分頁+近 N 天）
10	`/api/weather`	GET	當前天氣
11	`/api/weather/forecast`	GET	天氣預報
12	`/api/comments`	GET/POST	留言板（POST 需 Turnstile）

重要：POST /api/comments 必須帶 turnstileToken，後端會打 Cloudflare siteverify 驗證，失敗回 403。GET 和 POST 已分開，GET 有 request.method === "GET" 限制。

四、v2.4 已上線功能

#	功能	狀態
1	種菜、收成、金幣	✅
2	偷菜 + 隨機偷	✅
3	偷菜公告牆（含苦主 + 相對時間）	✅
4	偷菜總表（可展開、可翻頁、近 1/3/7 天）	✅
5	天氣系統（四種天氣 + Cron + 收成加成）	✅
6	12 種作物（8 菜 4 水果）	✅
7	留言板（Turnstile 人機驗證）	✅
8	導航列（照寵物格式）	✅
9	田區 grid 兩排	✅

五、v2.6 缺口（下一輪）

#	功能	狀態
1	等級門檻（crops 沒 level_required）	❌ v2.5
2	多季作物（crops 沒 season_count）	❌ v2.5
3	化肥加速	❌ v2.5
4	偷竊次數上限	❌ v2.5
5	雜草蟲害	❌ v2.5
6	土地擴張	❌ v2.5

六、這幾輪踩的坑（給下一個 AI）

Turnstile CSP：_headers 的 script-src、frame-src、connect-src、style-src 都要放行 challenges.cloudflare.com
Turnstile token：用 data-callback="onTurnstileSuccess" 取 token，不要用 querySelector("[name='cf-turnstile-response']")（Managed 模式可能抓不到）
路由方法：if (path === "/api/comments") 要加 request.method === "GET"，不然 POST 會被攔截
函數初始化：refreshWeather()、loadHistory("all")、loadComments(1) 都要在「頁面初始化區」呼叫，不能在函數定義裡
相對時間：D1 存 UTC，顯示時用 toRelTime() 轉「剛剛/N 分鐘前」，避免時區錯亂
猜錨點必失敗：改 HTML/PS1 前，先印出真實碼再改
逐個 script node --check：HTML 的 JS 也要驗語法，不能只驗 Worker

八、v2.5 已上線（2026-10-29）

一句話：v2.5 加了等級門檻、偷竊上限、多季作物、exp 修正，D1 加 11 欄位。

#	功能	D1 欄位	Worker	前端
1	等級門檻	crops.level_required、farm_players.level/exp	`/api/plant` 檢查、`/api/level`	Lv/EXP 顯示
2	偷竊上限	farm_players.daily_steal_count/last_steal_date	`/api/steal` 每日 10 次	—
3	多季作物	crops.season_count/regrow_seconds	`/api/harvest` 判斷季數	—
4	exp 修正	—	`/api/harvest` 移到 return 前	`refreshLevel()`

D1 現在 7 表：_cf_KV、crops、farm_comments、farm_logs、farm_players、farm_weather、farms

D1 新增 11 欄位：
crops：level_required、season_count、regrow_seconds
farm_players：level、exp、daily_steal_count、last_steal_date
farms：fertilized_at、weed、bug、is_locked

七、給下一個 AI 的話

「照 SOP 走，先診斷，再動手。」
「Token 只放 Worker Secret，不放前端、不放 wrangler.toml。」
「改 HTML 前，先印出插入點前後 10 行，確認 div 閉合。」
「改完逐個 script node --check，再看 Console。」
「v2.5 缺口：等級門檻、多季作物、化肥、偷竊上限、雜草蟲害、土地擴張。」

🌾 2009 年，你在偷誰的菜？

2009 年，Facebook 開心農場。你半夜設鬧鐘起來，就為了偷同學那顆快熟的番茄。那時候，我們都還年輕。放學衝回家，打開電腦，偷菜、種菜、被偷，一個都不能少。

17 年後，開心農場回來了。不是 Facebook，是 AHPAL。

你的菜，還在長。你的青春，還在等你。