digital-psychology/.ai/commands.md

Commands — Do Not Guess

Run from repo root unless noted.
Policy: environment.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. cp apps/api/config.example.yaml apps/api/config.local.yaml（填 database.* 与 deepseek.api_key）
4. npm run deps:up（或 docker compose -f docker-compose.dev.yml up -d）
5. Start API once so migrations apply: cd apps/api && go run ./cmd/server
6. Verify: curl -s http://127.0.0.1:8080/api/v1/healthz
7. Start H5: npm run dev:h5 → http://127.0.0.1:5173
8. （可选）埋点：cp apps/user-h5/.env.example apps/user-h5/.env.local，填 VITE_GA_MEASUREMENT_ID；调试可设 VITE_ANALYTICS_DEBUG=1（见 feature-spec/analytics.md）

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

# 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

cd apps/api
go mod tidy
go test ./...
# L2（需 deps:up）：Portrait / Relation / Membership 三流
go test ./internal/integration/ -count=1
go build ./...
go run ./cmd/server

根目录快捷：npm run test:api · npm run test:api:integration（L2 需先 deps:up）

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

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

npm run dev:h5
npm run build:h5
npm run test:h5          # Vitest
npm run test:e2e         # Playwright（先 build:h5；用系统 Chrome）

Do not dockerize Vite for everyday coding.

---

Admin H5（Ops Phase A · ECR-006）

# config.local.yaml 需 admin.bootstrap_*（见 config.example.yaml）；仅空库种子
npm run dev:admin        # http://127.0.0.1:5174/
npm run build:admin
npm run test:e2e:admin   # Playwright（preview + mock API，无需 Go）
npm run test:e2e:live    # 前后台联调（需 deps:up + API :8080；见 e2e-live/）

---

CI / production

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