本機開發

設定 Netstamp 工作區、啟動各個應用程式、重新產生合約，並使用範圍明確的驗證指令。

Netstamp 是一個 pnpm 工作區，包含 Go 控制器與探測器 agent、TypeSpec API 合約、React/Vite 應用程式、共用 React UI 套件，以及 Astro 說明文件網站。

前置需求

請先安裝：

  • Node.js 22.12 或更新版本；
  • pnpm 11.9；
  • Go 1.26，供控制器或探測器 agent 開發使用；
  • just，用來執行程式碼儲存庫提供的工作指令；
  • Docker，需要 PostgreSQL、TimescaleDB 或完整自行託管環境時使用。

複製程式碼儲存庫並安裝工作區相依套件：

bash
git clone https://github.com/yorukot/netstamp.git
cd netstamp
pnpm install

安裝步驟也會設定程式碼儲存庫的 Git hook。

啟動控制器開發用 PostgreSQL

控制器需要啟用 TimescaleDB 擴充功能的 PostgreSQL。本機開發可以只啟動部署用 Compose 檔案中的資料庫服務：

bash
cp deployments/docker/example.env deployments/docker/.env
docker compose --env-file deployments/docker/.env \
-f deployments/docker/compose.yaml up -d postgres

複製控制器環境變數範本：

bash
cp server/.env.example server/.env

將 server/.env 的 DATABASE_PASSWORD 設為與 deployments/docker/.env 相同的值，接著套用資料庫遷移：

bash
just backend-migrate-up

這兩個環境檔都是本機設定。請勿提交已填入內容的環境檔或正式環境憑證。

啟動控制器與 Web 應用程式

使用 Air 熱重新載入功能啟動 Go 控制器：

bash
just dev

控制器預設監聽 http://localhost:8080。另開一個終端機視窗啟動 Vite：

bash
just web-dev

Vite 預設會將 /api 反向代理到 http://localhost:8080。如果控制器使用其他來源網址，請設定 VITE_NETSTAMP_API_PROXY_TARGET。

全新資料庫中第一個成功註冊的帳號會成為系統管理員。這項初始化規則只適用於空白系統；系統管理員權限與專案成員資格是兩套不同的權限。

啟動說明文件與 Storybook

啟動 Astro 說明文件網站：

bash
just docs-dev

開發 @netstamp/ui 時，可另外啟動共用元件目錄：

bash
pnpm dev:storybook

正式的說明文件建置會先產生靜態 Storybook 網站，再建置 Astro。除非程式碼儲存庫明確將其視為來源檔，否則不要提交產生的預覽或截圖檔。

依範圍建置與測試

開發過程中請使用範圍明確的指令：

bash
pnpm --filter @netstamp/web typecheck
pnpm --filter @netstamp/web lint
pnpm --filter @netstamp/web test
pnpm --filter @netstamp/web build

pnpm --filter @netstamp/docs build
pnpm --filter @netstamp/ui build

just backend-test
just backend-lint
just backend-build

整個程式碼儲存庫的共用入口如下：

bash
just lint
just test
just build

修改 API 合約

api/ 下的 TypeSpec 是 HTTP 合約的唯一準據。修改後，請重新產生所有需要提交的使用端檔案：

bash
pnpm generate:openapi

這個指令會更新公開 OpenAPI 文件、控制器內嵌的副本，以及 Web 應用程式產生的 TypeScript 型別宣告。請勿手動編輯這些產生的檔案。

修改使用者會看到的文字

英文 UI 翻譯資源與英文 MDX 是翻譯來源。請新增語意清楚的翻譯 key，不要直接在 React 元件中嵌入新的英文句子，接著執行：

bash
pnpm check:i18n
pnpm test:i18n
pnpm test:web
pnpm test:docs:i18n

修改在地化內容前，請先閱讀翻譯 Netstamp。該頁會說明哪些檔案由 Crowdin 管理，以及哪些技術識別名稱必須保持原樣。

遵循各區域指南

開始修改前，請先閱讀程式碼儲存庫中距離工作範圍最近的 AGENTS.md。後端、API、Web、共用 UI 與 Docs 各有不同的主要依據與驗證規則；會改變畫面的 UI 工作也必須遵循 design.md。

分支名稱、commit、pull request 與完整審閱清單，請接著閱讀貢獻指南。