> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 專案結構

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

## 安裝與配置

在執行任何步驟之前，請閱讀[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md) 和[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)。這些說明假設您在 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 儲存庫中。

[構建你的第一個功能](https://supastack.dev/zh-tw/docs/web/first-feature.md)

- 新的營銷或落地頁 → `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 構建成功本身並不能證明與原生應用相容。


## 下一篇

[配置](https://supastack.dev/zh-tw/docs/web/configuration.md)