# CONTRIBUTING

## AI-first

本仓库由 [`.ai/`](.ai/) 约束。入口：[AGENTS.md](AGENTS.md)。

环境分流（必读）：

- [`.ai/environment.md`](.ai/environment.md) — Local / CI / Prod 分离  
- [`.ai/development.md`](.ai/development.md) — 本地本机 Go + Vite  
- [`.ai/docker.md`](.ai/docker.md) — Docker 只做依赖与部署  
- [`.ai/deployment.md`](.ai/deployment.md) — 生产不可变镜像  

## Local（默认）

```bash
# 1) 依赖服务 only
docker compose -f docker-compose.dev.yml up -d

# 2) API — 本机 Go（不要 docker build api）
export GOPROXY=https://goproxy.cn,direct   # 如需要
cd apps/api && go run ./cmd/server
# 可选热更: air

# 3) H5 — 本机 Vite（不要 docker build web）
npm install && npm run dev:h5
```

- API: http://127.0.0.1:8080/api/v1/healthz  
- H5: http://127.0.0.1:5173  

## Git

Trunk-Based；Conventional Commits（`feat:` / `fix:` / `docs:` …）。

## PR

- 一个功能点。  
- API 变更同步 `proto/openapi.yaml`。  
- 勿把「本地必须全量 compose 起 api/web」写进新文档。