# Commands — Do Not Guess

Run from **repo root** unless noted.  
Policy: [environment.md](environment.md) · [development.md](development.md)

本仓库用 **npm workspaces**（`npm run …`）；等价于文档中的 pnpm 习惯用法。

---

## Local Development — First time

1. Install host toolchains: Go 1.22+ · Node 20+ · Docker Desktop（仅依赖服务）  
2. `npm install`  
3. `npm run deps:up`（或 `docker compose -f docker-compose.dev.yml up -d`）  
4. Start API once so migrations apply: `cd apps/api && go run ./cmd/server`  
5. Verify: `curl -s http://127.0.0.1:8080/api/v1/healthz`  
6. Start H5: `npm run dev:h5` → http://127.0.0.1:5173  

Optional CN Go proxy: `export GOPROXY=https://goproxy.cn,direct`  
Optional API hot reload: install `air`, then `cd apps/api && air`（见 `.air.toml`）

---

## Local Development — Daily

```bash
# Terminal 1 — infrastructure only
npm run deps:up

# Terminal 2 — backend (host)
cd apps/api
air
# 或: go run ./cmd/server

# Terminal 3 — frontend (host)
npm run dev:h5
```

Stop deps: `npm run deps:down`

---

## Go API

```bash
cd apps/api
go mod tidy
go test ./...
go build ./...
go run ./cmd/server
```

Env defaults / template: `deploy/.env.example`  
Migrate: applied on API startup (`apps/api/migrations/*.up.sql`)

```bash
curl -s http://127.0.0.1:8080/api/v1/healthz
curl -s http://127.0.0.1:8080/api/v1/ping
```

**Do not** `docker build` the API for everyday coding.

---

## User H5

```bash
npm run dev:h5
npm run build:h5
```

**Do not** dockerize Vite for everyday coding.

---

## CI / production

见 [deployment.md](deployment.md) · [docker.md](docker.md)。  
仅在发布/CI 任务使用镜像与 `deploy/docker-compose.prod.yml`。