本地開發與驗證

準備開發環境、啟動 Core-first 服務堆疊，以及區分品質檢查和完整執行測試。

適用前提

這一頁是給已經持有經維護者確認的原始碼副本的開發者看的。目前原始碼的取得方式仍受限制；請不要從舊的資料庫備份或歷史環境檔案來恢復開發設定。以下所有命令都在原始碼根目錄執行。

環境需求：Node.js 20+、Corepack、鎖定版本的 pnpm 9.7.0、Docker Engine 和 Compose 2.24.4+。Compose 的開發覆蓋檔案使用了 !override，版本太舊可能無法正確解析。請先用 node --version、corepack pnpm --version、docker info、docker compose version 確認環境。

準備與啓動

./manage-services.sh setup
./manage-services.sh config
./manage-services.sh start
./manage-services.sh status

setup 會準備權限受限的 .state/core-dev.env 並安裝凍結的依賴；config 校驗合併設定模型並列出服務名稱。啟動時使用固定的 Compose project 名稱 mywebdrive-core-dev，入口為 http://127.0.0.1:8080。同名專案可能會與另一份開發副本衝突，不要同時啟動多個副本來做隔離測試。

開發堆疊包含資料庫、Redis、物件存儲、遷移、Core、Analytics Worker、郵件轉接器、Storage API/Worker、Prometheus、Web 和 Nginx。只有入口和開發郵件的連接埠對本機開放；不能只啟動前端就認為整個檔案流程可用。

開發郵箱的特別限制

開發設定會把郵件轉接器替換成 fake-email，監聽本機 8025；它不會向真實郵箱投遞。/v1/test/mailboxes/latest 需要設定 FAKE_EMAIL_TEST_TOKEN 並用收件人和 X-Test-Mailbox-Token 來讀取；預設的開發 overlay 沒有設定這個測試讀取 token，打開 8025 也不是可以直接看到驗證碼的網頁。

所以即使 start 成功，也不代表登入流程已經打通。需要測試登入時，請使用倉庫提供的隔離 smoke/瀏覽器測試設定，或由維護者設定私有的測試信箱讀取契約。不要公開 fake mailbox 或將測試 token 沿用到正式環境，也不要從資料庫裡反推驗證碼。

每日管理命令

命令	用途
`./manage-services.sh logs core-api`	查看指定有效服務最近 200 行日誌
`./manage-services.sh logs`	查看整個堆疊的最近日誌
`./manage-services.sh stop`	停止容器，保留資料卷和本機金鑰
`./manage-services.sh config`	校驗設定，不會印出完整的機密內容
`./manage-services.sh reset --confirm`	刪除本機容器和資料卷，保留狀態檔案；只在資料可以丟棄時執行

狀態檔案有異常時管理器會拒絕覆寫，應先確認檔案類型、權限和保留需求。不要把 reset 當成普通的重新啟動。

運行驗證

./manage-services.sh quality
./manage-services.sh smoke

quality 涵蓋當前活躍工作區的建置、型別、lint、測試、產出物和文件合約，不啟動容器；smoke 則會建置隔離堆疊、使用暫時性的資料卷並在結束後清理。pnpm run test:docs 和 pnpm run verify:docs 檢查的是文件與 OpenAPI 的一致性，不能替代實際的收信和檔案往返測試。

瀏覽器 smoke 測試要確認登入、上傳完成、下載內容、管理權限以及桌面和行動裝置版面。Linux 是上游的視覺基準權威，不應在 macOS 上覆寫 Linux 的基準。舊的 legacy:help 和 legacy:status 僅供觀察；其他 legacy 命令會以退出碼 64 結束。舊的拆分式服務遷移流程不屬於目前的啟動步驟。