所有腳本、文件、輸出、對話，全部使用繁體中文。嚴禁混用簡體字。違者視為交接違規。
任何改動前，先備份。任何診斷前，先看原始資料。
結構正常 ≠ 內容正確。目錄實掃 ≠ JSON 登記。HTTP 200 ≠ 資料合法。
資料庫要用關聯式資料庫（D1），不要用鍵值儲存（KV）做需要排序、查詢、關聯的事。子網域要提早拆分。
PowerShell 貼長 HTML 會被截斷，Python 腳本寫在 .py 檔裡不會。這是今天用血淚換來的教訓。
身份定位：
C:\Users\User\ahpal-staticC:\Users\User\ahpal-pet2126023801129b81447a887818428611praystone.workers.dev| 機器 | 電腦名稱 | 定位 | Python 環境 |
|---|---|---|---|
| 聯想 | AHPAL-LENOVO | 主力機（工作室） | v11.7 已完整建置 |
| 戴爾 | DESKTOP-AKLAM99 | 外出機（移動使用） | 早已建置完成 |
| 項目 | 數值 |
|---|---|
| 文章總數 | 9,334 篇（JSON 登記） |
| 分類數 | 12 個 |
| travel 分類 | 832 篇（JSON = 實體，幽靈 0） |
| R2 圖片 | 8,500+ 張 |
| 導覽列 | 10 個連結（含「⚔️ 打怪場」） |
| 項目 | 數值 |
|---|---|
| 前端網域 | pet.ahpal.com |
| 打怪場 | pet.ahpal.com/ |
| 戰績牆 | pet.ahpal.com/wall.html |
| GitHub Repo | praystone/ahpal-pet |
| 本地路徑 | C:\Users\User\ahpal-pet |
| Pages 專案 | ahpal-pet |
| 後端 Worker | ahpal-pet-d1（ahpal-pet-d1.praystone.workers.dev） |
| 資料庫 | Cloudflare D1 ahpal-pet-db |
| D1 Database ID | 80ea49f8-a4fe-4cbf-9821-8337c7869567 |
| D1 綁定變數 | PET_DB |
| Worker 版本 | v2.0（11 個 API） |
| 裝備數量 | 30 件 |
| 怪物數量 | 10 隻 |
從「交代版」（打怪、留言、排行榜）升級到「有深度版」（裝備系統、回合制戰鬥、戰績牆）。這是 v11.7 之後最重要的進展。
| 表名 | 用途 | 筆數 |
|---|---|---|
players | 玩家資料（暱稱、等級、經驗、擊殺） | 動態 |
comments | 留言 | 動態 |
equipment | 裝備定義（30 件：武器、防具、頭盔、盾牌、飾品） | 30 |
player_equipment | 玩家已獲得的裝備 | 動態 |
monsters | 怪物定義（史萊姆到地獄魔王） | 10 |
battles | 戰鬥紀錄 | 動態 |
_cf_KV | Cloudflare 內部用，不要動 | — |
| 方法 | 端點 | 功能 |
|---|---|---|
| POST | /api/hit | 打怪（含隨機掉落裝備） |
| GET | /api/stats?nickname=XXX | 查詢戰績 |
| GET | /api/leaderboard?page=1 | 排行榜（分頁） |
| POST | /api/comment | 新增留言 |
| GET | /api/comments?page=1 | 留言列表（分頁） |
| GET | /api/inventory?nickname=XXX | 查詢背包 |
| POST | /api/equip | 穿戴裝備 |
| POST | /api/unequip | 卸下裝備 |
| GET | /api/monsters | 怪物列表 |
| POST | /api/battle | 回合制戰鬥 |
| GET | /api/battles?nickname=XXX&page=1 | 戰鬥紀錄 |
| 區域 | 內容 |
|---|---|
| 頂部狀態條 | 暱稱、等級、擊殺、經驗、攻擊、防禦、HP（永遠可見） |
| 左欄 | 快速打怪 → 挑戰怪物 → 戰鬥紀錄 |
| 右欄 | 當前裝備（5 格）→ 背包 → 即時訊息 |
| 區域 | 內容 |
|---|---|
| 左欄 | 等級排行榜（分頁，前 3 名金銀銅）→ 最近戰鬥紀錄（全站 20 場） |
| 右欄 | 留言板（送出、分頁、字數統計、頻率限制） |
drop_rate 隨機掉落level * 100 升一級，支援多級連升| # | 防護 | 說明 |
|---|---|---|
| 1 | 字數限制 | 最多 500 字 |
| 2 | 繁體中文驗證 | 至少 2 個中文字，擋機器人 |
| 3 | 髒話過濾 | 擋掉常見髒話、廣告詞 |
| 4 | 頻率限制 | 同一暱稱 30 秒內只能留一次 |
| 5 | 暱稱長度限制 | 最多 20 字 |
用 PowerShell 的 @'...'@ here-string 貼 17KB 的 HTML，貼上時被截斷，$newHtml 是空的，然後 WriteAllText 把空字串寫進 pet-index.html，檔案從 16KB 變成 0 bytes。解法：大型 HTML 用 Python 腳本，寫在 .py 檔裡，不經過 PowerShell 貼上。
用 subprocess.run(..., encoding="utf-8") 讀取子進程輸出，遇到 CP950 位元組（0xab）解碼失敗。解法：直接用 python -c 執行，不繞 subprocess。
連續兩次「沒先驗證字串存在就寫取代邏輯」，導致取代失敗。解法：取代前先用 IndexOf 或 in 確認字串存在，或用正規表達式 + 先驗證。
用 $content -ne $original 判斷字串是否改變，但 PowerShell 的 -ne 對字串不區分大小寫，大小寫變化被視為「相等」。解法：比較大小寫變化用 -cne。
git push 成功，但 Pages 專案停在兩天前，沒抓到新 commit。解法：用 npx wrangler pages deploy . --project-name=ahpal-pet --branch=main --commit-dirty=true 直接上傳，繞過 Git 自動偵測。
BBS2 是獨立子網域 https://bbs2.ahpal.com/，不是掛在回憶館底下。
| 用途 | 指令 |
|---|---|
| 完整部署 / 主控台 | .\scripts\ahpal-master.ps1 → [1] |
| 死命令預檢 | .\scripts\preflight-check.ps1 |
| 黃金備份 | .\scripts\backup-system.ps1 -Golden |
| Git 管理工具（v3.9） | .\git-manager.ps1（6 倉庫） |
| 分類檢驗工具 | python scripts\check-category.py |
| 寵物遊戲部署（打怪場） | cd C:\Users\User\ahpal-pet; python deploy_v22.py |
| 寵物遊戲部署（戰績牆） | cd C:\Users\User\ahpal-pet; python deploy_wall.py |
| Worker 部署 | cd C:\Users\User\ahpal-pet\worker; npx wrangler deploy |
| Pages 強制部署 | npx wrangler pages deploy . --project-name=ahpal-pet --branch=main --commit-dirty=true |
| D1 建表（遠端） | npx wrangler d1 execute ahpal-pet-db --remote --file=schema.sql |
| D1 查詢（遠端） | npx wrangler d1 execute ahpal-pet-db --remote --command="SELECT ..." |
| # | 死命令 | 檢查方式 |
|---|---|---|
| 1 | 文章變更後強制檢查 | .\scripts\preflight-check.ps1 |
| 2 | 文章檔名強制使用英文 | 自動強制轉換 |
| 3 | CSS 靜態資產保護 | main.css 禁止自動覆蓋 |
| 4 | 文章清單集中管理 | master-articles.json + 新架構 |
| 5 | 設定 UTF-8 編碼 | .ps1 有 BOM、.json/.py/.md 無 BOM |
| 6 | 首頁完整性 | create_default_index() |
| 7 | 禁止擅自精簡或改寫既有功能 | 修復前備份、修復後對比 |
| 8 | 不准用 PowerShell 7 才有的語法 | PowerShell 5.1 相容 |
| 9 | 盡量用 PowerShell 直接修改腳本 | 一鍵完成多種任務 |
| 10 | 永遠使用 SYSTEM 帳戶排程 | LogonType: ServiceAccount |
| 11 | SEO 四大件無 noindex | .\scripts\seo-dashboard.ps1 |
| 12 | Production 部署唯一正門 | 禁止 npx wrangler pages deploy .（緊急時除外） |
| 13 | 純文字檔案寫入規範 | 單引號陣列 + WriteAllLines |
| 14 | JSON 合法性驗證 | 完整解析，不能只看 HTTP 200 |
| 15 | 禁止簡體字，一律使用繁體字 | 所有腳本、文件、輸出、對話 |
| 16 | 🆕 大型 HTML 用 Python 部署 | 不用 PowerShell 貼長字串 |
| 17 | 🆕 Python subprocess 讀輸出用 errors="replace" 或直接 python -c | 避免 UnicodeDecodeError |
| 18 | 🆕 取代字串前先驗證存在 | IndexOf 或 in |
| 19 | 🆕 比較大小寫變化用 -cne | PowerShell -ne 不區分大小寫 |
| 20 | 🆕 Cloudflare Pages 部署用 wrangler CLI | 不依賴 Git 自動偵測 |
前 100 條沿用 v11.7，新增以下 10 條：
len(content) > 5000，寫入後檢查 getsize > 5000，過小自動還原encoding="utf-8", errors="replace"，或直接 python -cIndexOf 或 in 確認字串存在，再取代-cne，不用 -nenpx wrangler pages deploy . --project-name=ahpal-pet --branch=main --commit-dirty=truenpx wrangler d1 execute ahpal-pet-db --remote --file=schema.sql，必須加 --remoteahpal-pet）https://bbs2.ahpal.com/，不是 memories.ahpal.com/bbs2/https://pet.ahpal.com/，另開新視窗前 70 條沿用 v11.7，新增以下 5 條：
errors="replace" 或 python -cIndexOf 確認-ne 不區分大小寫，改用 -cnenpx wrangler pages deploy . 直接上傳前 65 項沿用 v11.7，新增以下 10 項：
players、comments、equipment、player_equipment、monsters、battles、_cf_KV）pet.ahpal.com/ 可以打怪、掉裝備、戰鬥pet.ahpal.com/wall.html 可以看排行榜、戰鬥紀錄、留言pet.ahpal.comnpx wrangler deploy，不用 Dashboard 手動貼npx wrangler pages deploy .，不依賴 Git 自動偵測bbs2.ahpal.com| 項目 | 值 |
|---|---|
| 手冊版號 | v11.8 FINAL |
| 更新日期 | 2026-10-20 |
| 維護者 | 🦞 龍蝦總工程師 |
| 文件路徑 | C:\Users\User\ahpal-static\docs\ |
| 檔案名稱 | 打一份龍蝦總工程師-AI交接與新進工程師交接手冊-FINAL-v11.8.html |
| 項目 | v11.7 | v11.8 |
|---|---|---|
| 日期 | 2026-10-19 | 2026-10-20 |
| 寵物遊戲版本 | v11.6（打怪、留言、排行榜） | v2.2（裝備、戰鬥、戰績牆） |
| D1 資料表 | 2 張（players、comments） | 7 張（+equipment、player_equipment、monsters、battles） |
| Worker API | 5 個 | 11 個 |
| 裝備系統 | 無 | 30 件 |
| 戰鬥系統 | 無 | 回合制 |
| 戰績牆 | 簡易 | 排行榜 + 戰鬥紀錄 + 留言板 |
| 主站導覽列 | 無打怪場入口 | 有「⚔️ 打怪場」 |
| 核心口號 | 八條 | 九條 |
| 鐵律 | 五條 | 五條（更新第五條） |
| 死命令 | 15 條 | 20 條（+5） |
| 防錯守則 | 100 條 | 110 條（+10） |
| 異常排除 | 70 條 | 75 條（+5） |
| CheckList | 65 項 | 75 項（+10） |
教訓一：PowerShell 貼長 HTML 會被截斷
用 PowerShell 的 @'...'@ here-string 貼 17KB 的 HTML，貼上時被截斷，$newHtml 是空的，然後 WriteAllText 把空字串寫進 pet-index.html，檔案從 16KB 變成 0 bytes。以後大型 HTML 用 Python 腳本部署。
教訓二：Python subprocess 讀 Windows 中文輸出會 UnicodeDecodeError
用 subprocess.run(..., encoding="utf-8") 讀取子進程輸出，遇到 CP950 位元組（0xab）解碼失敗。以後直接用 python -c 執行，不繞 subprocess。
教訓三：Cloudflare Pages 的 Git 自動部署可能沒觸發
git push 成功，但 Pages 專案停在兩天前。以後用 npx wrangler pages deploy . --project-name=ahpal-pet --branch=main --commit-dirty=true 直接上傳。
教訓四：BBS2 網址是 bbs2.ahpal.com
BBS2 是獨立子網域 https://bbs2.ahpal.com/，不是掛在回憶館底下。
教訓五：導覽列入口要用「打怪場」代表整個寵物遊戲
主站導覽列「📧 聯絡我們」改成「⚔️ 打怪場」，連到 https://pet.ahpal.com/，另開新視窗。老會員從首頁就能找到。