jackyu66gitandCursor
0f320e040b
Add host-first environment contracts (Local vs CI vs Prod), deps-only compose, and the Profile → Portrait → deep-access mock payment slice with device identity and auto-migrate on API startup. Co-authored-by: Cursor <cursoragent@cursor.com>
106 lines
3.0 KiB
Markdown
106 lines
3.0 KiB
Markdown
# 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
|