Files

T

jackyu66gitandCursor 0f320e040b feat: P1 profile/portrait API and freeze local-dev environment

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>

2026-08-02 16:24:57 +08:00

3.0 KiB

Raw Permalink Blame History

Local Development Rules — AI Contract

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

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

总原则见 environment.md。

MUST

Go API：本机 go run / air 热更新。
user-h5：本机 Node + Vite（npm run dev:h5）。
依赖数据服务（Postgres；日后 Redis 等）：docker compose -f docker-compose.dev.yml up -d。
配置：根目录或 apps/api 使用 .env / .env.local（不提交）；模板见 deploy/.env.example。
H5 通过 Vite proxy 访问本机 API（/api → 127.0.0.1:8080），无需把前端放进容器。
验证优先：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；配置 `.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`

# 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`

npm install
npm run dev:h5

Database / deps only

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

3.0 KiB Raw Permalink Blame History Unescape Escape