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
parent dd94e57277
commit 0f320e040b
49 changed files with 1907 additions and 191 deletions
@@ -0,0 +1,105 @@
+# 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