For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/web/project-structure.md (or send Accept: text/markdown).

專案結構

找到應用、共享包以及它們之間的邊界。

詢問本指南

安裝與配置

在執行任何步驟之前，請閱讀開始之前和終端基礎知識。這些說明假設您在 VS Code 中開啟了完整的 supastack monorepo；它的根 package.json 標記儲存庫根。在 pnpm 命令中，工作區包是應用程式或共享程式碼資料夾；在產品中，工作空間是團隊的資料容器和安全邊界。 corepack pnpm --filter ... 從 monorepo 選擇一個包，同時從其根執行命令。如果您僅開啟同步的移動或桌面資料夾，則它不包含 Web 後端、Docker 設定或根指令碼：從此 monorepo 或可訪問的託管伺服器執行後端，並使用平臺資料夾自己的指令碼。環境變數是儲存在本地 .env 檔案或託管儀錶板中的命名設定；更改後重新啟動相關應用程式，並將伺服器機密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1. 在 VS Code 中開啟根 package.json，然後瀏覽 apps/web 網站、apps/mobile 瀏覽 Expo、apps/desktop 桌面 shell，以及共享片段的包。

2. 從儲存庫根目錄執行 corepack pnpm --filter @supastack/web dev。

3. 開啟 http://localhost:3000. 預期：Web 應用程式從 apps/web 啟動，而共享包保留在同一儲存庫中；桌面視窗包含此 Web 應用程式而不是包含第二個產品。

pnpm workspace 包含 apps/web 裡的 Next.js、apps/mobile 裡的 Expo，以及 packages 下的共享包。從倉庫根目錄執行 workspace 命令。應用路由組合共享模組；產品專屬行為屬於使用方產品。

改動行為之前先讀 AGENTS.md 與 .ai/PROJECT_CONTEXT.md。.ai/ 中的檔案映象解釋了僅從元件可能看不出的決策與約束。

apps/web/app/       Routes and layouts
apps/web/src/       Web components and server composition
apps/mobile/        Expo application
packages/           Shared contracts and adapters
tests/              Cross-module and browser checks
docs/               Operational guides

要複製的命令

按照註釋檢視命令在哪個資料夾中執行。如果標記了兩個終端，請開啟兩個終端視窗，並在使用第二個命令時保持第一個命令執行。

corepack pnpm --filter @supastack/web dev

改動應該放在哪

動手改之前，先決定這個改動歸哪個應用或包管。經驗法則：只有一個產品介面需要它，就放進那個應用；每個介面都需要，就放進 packages/ 下的共享包。

Web 儲存庫和 All Platforms monorepo 包含下面所有資料夾。獨立的 Mobile 或 Desktop 檢出只包含它自己的應用——伺服器程式碼仍在 Web 儲存庫中。

構建你的第一個功能

新的營銷或落地頁 → apps/web/app/——公開網站。
登入後產品內的新介面 → apps/web/app/ 放路由、apps/web/src/ 放邏輯——頁面組合共享包。
新的 API 路由 → apps/web/app/api/——Web 應用的伺服器半區。
所有應用共享的改動——資料表、契約、提供商介面卡 → packages/ 中對應的資料夾。
僅手機的介面 → apps/mobile/——它與 Web 應用的 API 通訊，而不是自帶後端。
僅桌面的行為 → apps/desktop/——Tauri 外殼包裹 Web 應用，幾乎從不另起產品 UI。

實現流程

從擁有使用者動作的路由開始，跟隨它的服務端 handler，再看它呼叫的共享包。UI 元件不應重新實現工作區解析、計費授權或供應商選擇。

新增路由時先決定它是公開還是需認證。訪問使用者記錄之前在服務端解析已認證的歸屬，並把服務端憑證留在客戶端 import 之外。

驗證與排障

如果該命令報告沒有專案與過濾器匹配，請檢查終端是否位於包含根 package.json 的資料夾中。如果埠 3000 已被使用，請先停止其他本地 Web 伺服器。不要尋找單獨的桌面聊天或登入實現；桌面 shell 載入 Web 後端。

改動包契約後執行相關測試與型別檢查。修改共享型別時同時檢查 Web 與移動端呼叫方。Web 構建成功本身並不能證明與原生應用相容。