# Local Development Rules — AI Contract

**目标：** 快速修改、快速验证、快速调试（分钟级反馈）。

**不是目标：** 把笔记本变成迷你生产集群。

总原则见 [environment.md](environment.md)。

---

## MUST

1. Go API：本机 `go run` / **air** 热更新。  
2. user-h5：本机 **Node + Vite**（`npm run dev:h5`）。  
3. 依赖数据服务（Postgres；日后 Redis 等）：`docker compose -f docker-compose.dev.yml up -d`。  
4. 配置：根目录或 `apps/api` 使用 `.env` / `.env.local`（不提交）；模板见 `deploy/.env.example`。  
5. H5 通过 Vite proxy 访问本机 API（`/api` → `127.0.0.1:8080`），无需把前端放进容器。  
6. 验证优先：`go test`、`curl healthz`、浏览器 / Vite，而不是先写 Dockerfile。

## MUST NOT

- 每次改 Go/Vue 代码就 `docker build` 应用镜像再跑。  
- 用 production image / `APP_ENV=prod` 做日常开发。  
- `docker compose` 启动 **api + web** 作为默认本地工作流（除非任务明确是「验证 compose 集成」）。  
- 将本地环境完全等同生产（密钥、域名、副本数、对象存储真集群等）。  
- 把密钥写进 compose 或镜像层。

---

## Recommended local topology

```
Host (macOS / Linux)
├── Go 1.22+
│   ├── go run ./cmd/server   或   air
│   └── delve（可选调试）
├── Node 20+（npm workspaces；可选 pnpm）
│   └── Vite → :5173
└── Docker Desktop（仅服务）
    ├── PostgreSQL :5432
    ├── Redis（需要时再加）
    └── Object storage（需要时再加）
```

---

## Go Backend

| Item | Local |
|---|---|
| Runtime | 本机 Go |
| Entry | `apps/api` |
| Hot reload | 推荐 [air](https://github.com/air-verse/air)；配置 `.air.toml`（可选） |
| Env | `HTTP_ADDR=:8080` `DATABASE_URL=postgres://yuxingu:yuxingu@127.0.0.1:5432/yuxingu?sslmode=disable` `APP_ENV=dev` |
| Migrate | API 启动时自动应用 `apps/api/migrations/*.up.sql` |
| CN proxy | `export GOPROXY=https://goproxy.cn,direct` |

```bash
# terminal — deps
docker compose -f docker-compose.dev.yml up -d

# terminal — API
cd apps/api
go run ./cmd/server
# 或: air
```

## Vue H5

| Item | Local |
|---|---|
| Runtime | 本机 Node |
| Dev | `npm run dev:h5` → http://127.0.0.1:5173 |
| Build check | `npm run build:h5` |

```bash
npm install
npm run dev:h5
```

## Database / deps only

```bash
docker compose -f docker-compose.dev.yml up -d     # postgres
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml logs -f postgres
```

只起依赖，**不起** api / web / worker。

---

## Auth note (P1 local)

访客身份：`X-Device-Key`（H5 存 `localStorage.yxg_device_key`）。  
无需为本地开发先搭完整 JWT，除非任务是登录竖切。

---

## Before claiming Done (local)

- [ ] 未引入「Docker-only 改代码」流程  
- [ ] API 本机可 `healthz`  
- [ ] H5 本机 Vite 可打开  
- [ ] DB 用 compose.dev，而非把业务进程塞进同一默认 compose