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>
This commit is contained in:
jackyu66git
+4
-4
@@ -37,10 +37,10 @@ Also always: `ai-contract.md`, `forbidden.md`, `file-map.md`, `workflow.md`, `co
|
||||
├── database.md
|
||||
├── ui.md # IA pointer → design/
|
||||
├── design/ # AI Design System Contract
|
||||
│ ├── design-system.md
|
||||
│ ├── component-catalog.md
|
||||
│ └── platform/
|
||||
├── deployment.md
|
||||
├── environment.md # Local / CI / Prod 分离
|
||||
├── development.md # 本地本机开发
|
||||
├── docker.md # Docker 用途边界
|
||||
├── deployment.md # 生产 / CI 部署
|
||||
├── testing.md
|
||||
├── security.md
|
||||
├── review.md
|
||||
|
||||
+9
-2
@@ -5,12 +5,19 @@ Do **not** build everything at once. Rules have maintenance cost.
|
||||
## Phase 1 — Now (shipped)
|
||||
|
||||
- Rules: constitution, architecture, domain, coding, api, database, ui, …
|
||||
- **Environment layer (FROZEN):** `environment.md` · `development.md` · `docker.md` · `deployment.md` · `commands.md`
|
||||
- ADR, patterns, examples, playbooks
|
||||
- Review / DoD / checklists / forbidden / commands / workflow / file-map
|
||||
- Review / DoD / checklists / forbidden / workflow / file-map
|
||||
- `ai-contract.md`
|
||||
- Cursor runtime: `.cursor/*` → symlink → `.ai/` (no content copy)
|
||||
|
||||
**Invest next engineering time in:** polishing `patterns/`, `examples/`, `playbooks/` while building real features — not more rule files.
|
||||
**Invest next time in product implementation, not more meta-rules:**
|
||||
|
||||
```
|
||||
产品冻结 → Domain → ERD → OpenAPI → 页面路由 → P1 编码
|
||||
```
|
||||
|
||||
Do **not** expand the engineering-spec layer unless a repeated AI failure demands it.
|
||||
|
||||
## Phase 2 — When the codebase grows
|
||||
|
||||
|
||||
+4
-2
@@ -11,8 +11,9 @@ MUST read:
|
||||
3. `.ai/domain.md` (+ `domain/domain-map.md` when touching models/API)
|
||||
4. `.ai/coding.md`
|
||||
5. Task-relevant: `api.md` / `database.md` / `ui.md` / `security.md` / `product/lexicon.md` + `product/feature-map.md`
|
||||
6. UI tasks: `design/design-system.md` + `design/component-catalog.md` + `design/platform/*`
|
||||
7. Relevant ADR under `.ai/adr/` if changing stack or style
|
||||
6. Run/dev tasks: `environment.md` + `development.md`（部署/镜像任务才读 `deployment.md` / `docker.md`）
|
||||
7. UI tasks: `design/design-system.md` + `design/component-catalog.md` + `design/platform/*`
|
||||
8. Relevant ADR under `.ai/adr/` if changing stack or style
|
||||
|
||||
## After coding
|
||||
|
||||
@@ -30,6 +31,7 @@ MUST:
|
||||
- Guess product requirement
|
||||
- Invent endpoints, tables, or domain words not in `.ai/domain.md` / OpenAPI / task
|
||||
- Silently reverse an Accepted ADR
|
||||
- Default local workflow to full-stack Docker / rebuild app images on every code change
|
||||
|
||||
## If unclear
|
||||
|
||||
|
||||
+51
-39
@@ -1,67 +1,79 @@
|
||||
# Commands — Do Not Guess
|
||||
|
||||
Run from repo root unless noted.
|
||||
Run from **repo root** unless noted.
|
||||
Policy: [environment.md](environment.md) · [development.md](development.md)
|
||||
|
||||
## Go API (`apps/api`)
|
||||
本仓库用 **npm workspaces**（`npm run …`）；等价于文档中的 pnpm 习惯用法。
|
||||
|
||||
---
|
||||
|
||||
## Local Development — First time
|
||||
|
||||
1. Install host toolchains: Go 1.22+ · Node 20+ · Docker Desktop（仅依赖服务）
|
||||
2. `npm install`
|
||||
3. `npm run deps:up`（或 `docker compose -f docker-compose.dev.yml up -d`）
|
||||
4. Start API once so migrations apply: `cd apps/api && go run ./cmd/server`
|
||||
5. Verify: `curl -s http://127.0.0.1:8080/api/v1/healthz`
|
||||
6. Start H5: `npm run dev:h5` → http://127.0.0.1:5173
|
||||
|
||||
Optional CN Go proxy: `export GOPROXY=https://goproxy.cn,direct`
|
||||
Optional API hot reload: install `air`, then `cd apps/api && air`（见 `.air.toml`）
|
||||
|
||||
---
|
||||
|
||||
## Local Development — Daily
|
||||
|
||||
```bash
|
||||
export GOPROXY=https://goproxy.cn,direct # if download timeout
|
||||
# Terminal 1 — infrastructure only
|
||||
npm run deps:up
|
||||
|
||||
# Terminal 2 — backend (host)
|
||||
cd apps/api
|
||||
air
|
||||
# 或: go run ./cmd/server
|
||||
|
||||
# Terminal 3 — frontend (host)
|
||||
npm run dev:h5
|
||||
```
|
||||
|
||||
Stop deps: `npm run deps:down`
|
||||
|
||||
---
|
||||
|
||||
## Go API
|
||||
|
||||
```bash
|
||||
cd apps/api
|
||||
go mod tidy
|
||||
go build ./...
|
||||
go test ./...
|
||||
go build ./...
|
||||
go run ./cmd/server
|
||||
```
|
||||
|
||||
Health:
|
||||
Env defaults / template: `deploy/.env.example`
|
||||
Migrate: applied on API startup (`apps/api/migrations/*.up.sql`)
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8080/api/v1/healthz
|
||||
curl -s http://127.0.0.1:8080/api/v1/ping
|
||||
```
|
||||
|
||||
**Do not** `docker build` the API for everyday coding.
|
||||
|
||||
---
|
||||
|
||||
## User H5
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev:h5
|
||||
npm run build:h5
|
||||
```
|
||||
|
||||
## Docker / DB
|
||||
**Do not** dockerize Vite for everyday coding.
|
||||
|
||||
```bash
|
||||
docker compose -f deploy/docker-compose.yml up -d
|
||||
docker compose -f deploy/docker-compose.yml down
|
||||
```
|
||||
---
|
||||
|
||||
## Lint (when configured)
|
||||
## CI / production
|
||||
|
||||
```bash
|
||||
# Go — after golangci-lint is added:
|
||||
# cd apps/api && golangci-lint run
|
||||
|
||||
# H5 — after eslint is added:
|
||||
# npm run lint -w @yuxingu/user-h5
|
||||
```
|
||||
|
||||
## Migrations (when make targets exist)
|
||||
|
||||
```bash
|
||||
# Preferred once Makefile lands:
|
||||
# make migrate
|
||||
# make migrate-down
|
||||
|
||||
# Until then: document the goose/migrate command used in the PR.
|
||||
```
|
||||
|
||||
## Dev all (local)
|
||||
|
||||
```bash
|
||||
# terminal 1
|
||||
cd apps/api && go run ./cmd/server
|
||||
|
||||
# terminal 2
|
||||
npm run dev:h5
|
||||
```
|
||||
见 [deployment.md](deployment.md) · [docker.md](docker.md)。
|
||||
仅在发布/CI 任务使用镜像与 `deploy/docker-compose.prod.yml`。
|
||||
|
||||
@@ -14,6 +14,7 @@
|
||||
8. Every feature deployable.
|
||||
9. Every API documented (OpenAPI or apps/docs).
|
||||
10. Every database change versioned (migration required).
|
||||
11. **Local feedback speed > local environment purity.** 本地开发追求分钟级反馈；生产/CI 追求环境一致。二者禁止混用工作流（见 `.ai/environment.md`）。
|
||||
|
||||
## Product Laws (YuXinGu)
|
||||
|
||||
|
||||
+18
-9
@@ -1,9 +1,10 @@
|
||||
# Database — Golden Rules
|
||||
|
||||
Schema source of truth for P1 tables: [domain/erd.md](domain/erd.md).
|
||||
|
||||
## Naming
|
||||
|
||||
- `snake_case` only for tables and columns.
|
||||
- Good: `user_profile`, `payment_order`, `user_session`.
|
||||
- Forbidden prefixes: `tbl_`, `t_`.
|
||||
|
||||
## Required columns on business tables
|
||||
@@ -17,9 +18,8 @@ deleted_at
|
||||
|
||||
## Types
|
||||
|
||||
- Never `varchar(5000)` as a habit.
|
||||
- Prefer bounded `varchar(n)`.
|
||||
- `TEXT` only when necessary (long content bodies).
|
||||
- `TEXT` only when necessary.
|
||||
- Timestamps: `timestamptz`.
|
||||
|
||||
## Keys & indexes
|
||||
@@ -27,13 +27,22 @@ deleted_at
|
||||
- Every foreign key indexed.
|
||||
- Unique business keys enforced with UNIQUE.
|
||||
|
||||
## Migrations
|
||||
## Migration Rules（强制）
|
||||
|
||||
- Schema change without migration = incomplete feature.
|
||||
- Migrations live in `apps/api/migrations/`.
|
||||
- Provide Up and Down when tool supports it.
|
||||
1. **Every schema change requires a migration** under `apps/api/migrations/`.
|
||||
2. **Never** modify production (or shared) databases by hand (`ALTER TABLE` in psql as a substitute for migration).
|
||||
3. **Migration files are immutable** after merge to `main` — fix forward with a new migration; do not rewrite history on shared branches.
|
||||
4. **Destructive changes** (drop column/table, type narrowing) require an explicit rollback/forward strategy in the same change set (Down file or follow-up migration + note).
|
||||
5. App code must not query columns that are not yet migrated.
|
||||
6. Local apply: start API（auto-migrate）or documented migrate command in [commands.md](commands.md).
|
||||
|
||||
## Soft delete
|
||||
|
||||
- Default: set `deleted_at`, do not hard delete user content in MVP.
|
||||
- Queries must filter `deleted_at IS NULL` unless explicitly including deleted.
|
||||
- Default: set `deleted_at`; do not hard-delete user content in P1.
|
||||
- Queries filter `deleted_at IS NULL` unless the task says otherwise.
|
||||
|
||||
## AI MUST NOT
|
||||
|
||||
- 「先改库再补 migration」
|
||||
- 在 handler 里拼临时 DDL
|
||||
- 发明未在 `domain.md` / `erd.md` 出现的表名（先改文档）
|
||||
|
||||
+76
-23
@@ -1,33 +1,86 @@
|
||||
# Deployment — Golden Rules
|
||||
# Production & CI Deployment — AI Contract
|
||||
|
||||
## Containers
|
||||
本文件只约束 **CI** 与 **Production**。
|
||||
本地编码见 [development.md](development.md)；Docker 角色见 [docker.md](docker.md)。
|
||||
|
||||
- Every runnable service that ships to prod must have a Dockerfile.
|
||||
- Never use image tag `latest` in production.
|
||||
- Always semantic version tags: `v0.1.0` or git SHA.
|
||||
---
|
||||
|
||||
## Health
|
||||
## Production Rules
|
||||
|
||||
- Liveness: `GET /api/v1/healthz` required.
|
||||
- When DB is required for traffic: add readiness endpoint (e.g. `/api/v1/readyz`) that checks DB.
|
||||
- Alias names `/health` `/readiness` `/liveness` may map to the above; keep one canonical path documented in OpenAPI.
|
||||
Production **MUST** use immutable images.
|
||||
|
||||
## Config
|
||||
### MUST NOT（生产）
|
||||
|
||||
- Secrets via env only. Commit `.env.example`, never `.env`.
|
||||
- Required: `APP_ENV`, `HTTP_ADDR`, `DATABASE_URL`.
|
||||
- 服务器上 `git pull` 后直接编译运行当主发布路径
|
||||
- 手工在机器上 `npm install` / `go mod download` 当发布步骤
|
||||
- 登录容器改代码或改依赖冒充发布
|
||||
- 使用镜像 tag `latest`
|
||||
- 把本地 `.env` / 开发密钥打进镜像
|
||||
|
||||
## CI
|
||||
### Happy path
|
||||
|
||||
- No manual prod deploy as the happy path — CI builds and tags.
|
||||
- Minimum gates: `go test ./...` (api), `npm run build:h5`.
|
||||
|
||||
## Local
|
||||
|
||||
```bash
|
||||
docker compose -f deploy/docker-compose.yml up -d
|
||||
cd apps/api && go run ./cmd/server
|
||||
npm run dev:h5
|
||||
```
|
||||
Git Push → CI → Test → Build Image → Registry → Deploy → Health Check
|
||||
```
|
||||
|
||||
If Go module download times out in CN: `export GOPROXY=https://goproxy.cn,direct`.
|
||||
### Health
|
||||
|
||||
- Liveness: `GET /api/v1/healthz`（必须）
|
||||
- Readiness（有 DB 流量时）: `GET /api/v1/readyz`（检查 DB；可后补）
|
||||
- Canonical paths 写入 OpenAPI
|
||||
|
||||
### Config
|
||||
|
||||
- Secrets **仅**环境变量 / 密钥管理系统
|
||||
- 提交 `deploy/.env.example`，永不提交 `.env`
|
||||
- 生产必备示例：`APP_ENV=prod` `HTTP_ADDR` `DATABASE_URL`（及日后支付/JWT 密钥）
|
||||
|
||||
### Containers
|
||||
|
||||
- 可运行的生产服务最终应有 Dockerfile（`deploy/Dockerfile.*`）
|
||||
- Tag：`v0.x.y` 或 git SHA
|
||||
|
||||
### Deployment Target（预留，勿提前复杂化）
|
||||
|
||||
| Phase | Target | When |
|
||||
|---|---|---|
|
||||
| **1** | Docker Compose on a VPS | 首版上线默认 |
|
||||
| **2** | Managed containers（云厂商容器服务） | 运维成本上去时 |
|
||||
| **3** | Kubernetes | 明确有多服务/扩缩容需求时 |
|
||||
|
||||
P1 **不要**引入 K8s。缺的 Dockerfile / prod compose **按发布任务再加**，不为本地写代码先造全套镜像工作流。
|
||||
|
||||
### Topology（Phase 1 目标）
|
||||
|
||||
```
|
||||
Docker Compose (VPS)
|
||||
├── Go API container
|
||||
├── Nginx（user-h5 静态或反代）
|
||||
├── PostgreSQL
|
||||
├── Redis（需要时）
|
||||
└── Object storage（需要时）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI Rules
|
||||
|
||||
CI 优先 **一致性**：
|
||||
|
||||
- `go test ./...`（`apps/api`）
|
||||
- `npm run build:h5`
|
||||
- （有 Dockerfile 后）build 镜像 smoke
|
||||
- 不在 CI 里要求开发者本机 Docker Desktop 才能合并文档/纯前端 PR（按 job 需要）
|
||||
|
||||
---
|
||||
|
||||
## Local vs Prod（对照）
|
||||
|
||||
| Topic | Local | Production |
|
||||
|---|---|---|
|
||||
| Go / Vue | 本机热更 | 镜像 |
|
||||
| Postgres | `docker-compose.dev.yml` | 托管或 compose/k8s |
|
||||
| 反馈 | 分钟级 | 发布质量与回滚 |
|
||||
| 配置 | `.env.local` / dev | 密钥系统 / prod env |
|
||||
|
||||
禁止把右栏流程套到左栏日常开发。
|
||||
|
||||
@@ -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
|
||||
@@ -0,0 +1,70 @@
|
||||
# Docker Policy — AI Contract
|
||||
|
||||
## Docker SHOULD be used for
|
||||
|
||||
| ✓ | Examples |
|
||||
|---|---|
|
||||
| 依赖数据服务 | PostgreSQL |
|
||||
| 缓存 | Redis（需要时） |
|
||||
| 消息队列 | 需要时再加 |
|
||||
| 对象存储 | MinIO / S3 兼容（需要时） |
|
||||
| 第三方依赖模拟 | mailhog 等（需要时） |
|
||||
| 生产/CI 应用交付 | 不可变 api / web 镜像 |
|
||||
|
||||
## Docker SHOULD NOT be used for
|
||||
|
||||
| ✗ | Why |
|
||||
|---|---|
|
||||
| Go API 日常开发 | 拖慢反馈；用本机 `go run` / `air` |
|
||||
| Vue H5 日常开发 | 拖慢 HMR；用本机 Vite |
|
||||
| Hot reload 工作流 | 禁止「改代码 → docker build → run」 |
|
||||
| 把本机当成迷你 K8s | 违反 constitution：本地反馈速度优先 |
|
||||
|
||||
见 [development.md](development.md) · [environment.md](environment.md)。
|
||||
|
||||
---
|
||||
|
||||
## Local compose（deps only）
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| `docker-compose.dev.yml`（仓库根） | **默认本地**：仅依赖服务 |
|
||||
| `deploy/docker-compose.yml` | 与 dev 对齐的依赖入口（兼容旧命令）；生产见 prod 文件 |
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml up -d
|
||||
```
|
||||
|
||||
**允许的服务（local）：** `postgres`（+ 需要时 `redis` / `minio`）
|
||||
**禁止默认加入（local）：** `api` · `user-h5` · `worker` · `nginx`
|
||||
|
||||
---
|
||||
|
||||
## Production / CI images
|
||||
|
||||
| Artifact | Location (target) |
|
||||
|---|---|
|
||||
| Backend Dockerfile | `deploy/Dockerfile.api`（按需新增） |
|
||||
| H5/Nginx Dockerfile | `deploy/Dockerfile.user-h5`（按需新增） |
|
||||
| Prod compose / K8s | `deploy/docker-compose.prod.yml` 等 |
|
||||
|
||||
生产镜像规则见 [deployment.md](deployment.md)：禁止 `latest`；语义化版本或 git SHA。
|
||||
|
||||
---
|
||||
|
||||
## AI MUST NOT
|
||||
|
||||
- 把「本地开发」文档写成只能 `docker compose up` 全栈。
|
||||
- 在业务 PR 里强制同事每次改代码都 build 应用镜像。
|
||||
- 将 `.env` 秘密 `COPY` 进镜像。
|
||||
- 混用 `docker-compose.dev.yml` 与 prod 环境变量文件。
|
||||
|
||||
---
|
||||
|
||||
## When full-stack compose is OK
|
||||
|
||||
仅当任务明确是：
|
||||
|
||||
- 验证 prod compose / 镜像入口
|
||||
- CI integration job
|
||||
- 演示「一键依赖+应用」给非开发角色（仍非日常编码默认）
|
||||
@@ -0,0 +1,62 @@
|
||||
# Environment Policy — AI Contract
|
||||
|
||||
项目环境分为三类，**禁止混用配置与工作流**：
|
||||
|
||||
| Environment | Goal | Typical tools |
|
||||
|---|---|---|
|
||||
| **1. Local Development** | 分钟级反馈、快速改代码 | 本机 Go / Node + Docker **仅依赖服务** |
|
||||
| **2. CI** | 一致性、可重复验证 | 容器构建、单测、集成测 |
|
||||
| **3. Production Deployment** | 稳定、不可变交付 | 镜像 + Compose/K8s |
|
||||
|
||||
## Principles
|
||||
|
||||
1. **Local 优先开发效率** — 改一行代码应秒级/十秒级可见，禁止「每次改代码都 docker build」。
|
||||
2. **CI 优先一致性** — 用干净环境证明可构建、可测试。
|
||||
3. **Production 优先稳定性** — 不可变镜像；禁止服务器上 `git pull && go build` 当主路径。
|
||||
|
||||
## AI MUST
|
||||
|
||||
- 本地写 Go / Vue 时默认 **本机 runtime**（见 [development.md](development.md)）。
|
||||
- Docker 本地用途默认 = **依赖服务**（Postgres 等），见 [docker.md](docker.md)。
|
||||
- 部署相关只改 [deployment.md](deployment.md) / `deploy/*`，不把 prod 流程套到本地编码。
|
||||
|
||||
## AI MUST NOT
|
||||
|
||||
- 假设「有 Docker = 本地必须 compose 起 api/web」。
|
||||
- 为改一行业务代码要求 rebuild application image。
|
||||
- 把 `.env` / 生产密钥写进镜像或提交进库。
|
||||
- 用 production `APP_ENV` / 生产 `DATABASE_URL` 跑本地热更。
|
||||
|
||||
---
|
||||
|
||||
## Configuration Ownership
|
||||
|
||||
| File | Owner | Committed? |
|
||||
|---|---|---|
|
||||
| `deploy/.env.example`（或根 `.env.example`） | 模板：键名 + 无秘密默认值 | **Yes** |
|
||||
| `.env.local` | 本地覆盖 | **No** |
|
||||
| `.env.test` / CI secrets | CI 注入或加密变量 | 密钥 **No** |
|
||||
| `.env.production` / 平台密钥 | 部署系统注入 | **No** |
|
||||
|
||||
### Rules
|
||||
|
||||
- Code **never** contains environment-specific secret values.
|
||||
- Local values stay in `.env.local`（已被 `.gitignore` 的 `*.local` / `.env` 覆盖）。
|
||||
- Production values are injected by the deployment system — not copied from a laptop.
|
||||
- `.env*` files containing secrets must **never** be committed.
|
||||
- Do not load `.env.production` in local `air` / Vite.
|
||||
- Prefer one template (`.env.example`)；按环境注入，勿把三套真密钥放进仓库。
|
||||
|
||||
---
|
||||
|
||||
## Freeze
|
||||
|
||||
环境层（本文件 + `development.md` + `docker.md` + `deployment.md` + `commands.md` 相关部分）**已冻结**。
|
||||
除非真实踩坑，否则不再横向扩工程规范；下一投入点 = P1 领域实现（schema / API / 页面）。
|
||||
|
||||
## Related
|
||||
|
||||
- Local: [development.md](development.md)
|
||||
- Docker role: [docker.md](docker.md)
|
||||
- Prod/CI deploy: [deployment.md](deployment.md)
|
||||
- Commands: [commands.md](commands.md)
|
||||
@@ -54,6 +54,18 @@ No raw `fetch` in `pages/`.
|
||||
|
||||
Rules, ADR, patterns, examples, playbooks, checklists. Not runtime code.
|
||||
|
||||
### Environment docs
|
||||
|
||||
| Path | Owns |
|
||||
|---|---|
|
||||
| `environment.md` | Local vs CI vs Prod policy |
|
||||
| `development.md` | Host Go / Vite local rules |
|
||||
| `docker.md` | When Docker is / is not used |
|
||||
| `deployment.md` | Prod immutable images / CI |
|
||||
| `commands.md` | Copy-paste commands |
|
||||
|
||||
Runtime compose for **deps only**: repo-root `docker-compose.dev.yml`.
|
||||
|
||||
### .ai/product/ & .ai/domain/
|
||||
|
||||
| Path | Owns |
|
||||
|
||||
+8
-1
@@ -19,14 +19,21 @@ AI obeys NEVER rules strictly.
|
||||
- Never invent response shapes other than `{code,message,data}`.
|
||||
- Never use POST for pure read/query.
|
||||
- Never skip migration when schema changes.
|
||||
- Never hand-apply schema changes on shared/prod DB instead of migrations.
|
||||
- Never edit already-merged migration files on `main` (fix forward).
|
||||
- Never hard-delete user PII without explicit task (use soft delete).
|
||||
|
||||
## Security / deploy
|
||||
## Security / deploy / environment
|
||||
|
||||
- Never hardcode passwords, tokens, or secrets.
|
||||
- Never commit `.env` or private keys.
|
||||
- Never use Docker image tag `latest` in production.
|
||||
- Never log full birthday + answers payloads casually.
|
||||
- Never introduce a **Docker-only** local coding workflow for Go/Vue.
|
||||
- Never require application **image rebuild** after every local code change.
|
||||
- Never put local secrets into Docker images.
|
||||
- Never mix local/dev config with production config or prod compose as daily default.
|
||||
- Never assume `docker compose up` must start api + web for development.
|
||||
|
||||
## Product / process
|
||||
|
||||
|
||||
@@ -15,7 +15,9 @@
|
||||
| 9 | Go 服务边界 | `architecture/go-services.md` |
|
||||
| 10 | Design System | `design/design-system.md` |
|
||||
|
||||
下一步：**按 P1 竖切实现**（Profile → Portrait → RelationInsight → Scale → Commerce mock → Ask 壳），不再横向加功能。
|
||||
环境规范层已冻结（`.ai/environment.md` 等）— **停止扩展工程 meta 文档**。
|
||||
|
||||
下一步：**按 P1 竖切实现**（Profile → Portrait → RelationInsight → Scale → Commerce mock → Ask 壳），不再横向加规范或加功能面。
|
||||
|
||||
## Review 清单（合并前必过）
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ After coding, check every item. Output a Review block.
|
||||
| Deployment | Migration / health / env noted if needed? |
|
||||
| Docs | OpenAPI / PRD touch if public behavior changed? |
|
||||
| Design | UI change? Tokens + catalog + platform contract followed? |
|
||||
| Environment | Local workflow still host Go/Vite + deps-only compose? No Docker-only coding? |
|
||||
| Scope | No unrelated files modified? |
|
||||
|
||||
## Output format (required)
|
||||
@@ -34,6 +35,7 @@ After coding, check every item. Output a Review block.
|
||||
- Deployment: PASS | FAIL — <note>
|
||||
- Docs: PASS | FAIL — <note>
|
||||
- Design: PASS | FAIL | N/A — <note>
|
||||
- Environment: PASS | FAIL | N/A — <note>
|
||||
- Scope: PASS | FAIL — <note>
|
||||
```
|
||||
|
||||
|
||||
+33
-18
@@ -1,33 +1,48 @@
|
||||
# Workflow — Default Development Loop
|
||||
# Workflow — Feature Development Flow
|
||||
|
||||
默认循环。环境：本机 Go/Vite + deps-only Docker（见 [development.md](development.md)）。
|
||||
|
||||
```
|
||||
Receive task
|
||||
↓
|
||||
Read AI Contract + constitution + architecture + domain
|
||||
1. Understand
|
||||
- feature-map / user-journey / lexicon（产品）
|
||||
- domain-map / erd / OpenAPI（数据与契约）
|
||||
- page-tree（路由）
|
||||
↓
|
||||
Architecture Check (ADR + file-map + layers)
|
||||
2. Design（若有缺口）
|
||||
- Update OpenAPI / erd / migration 草案
|
||||
- ADR if stack/API style changes
|
||||
↓
|
||||
Choose playbook (add-api / new-page / new-table / …)
|
||||
3. Implement
|
||||
- Backend（service 竖切）→ Frontend
|
||||
- Follow patterns + playbooks
|
||||
↓
|
||||
Coding (follow patterns + examples)
|
||||
4. Verify
|
||||
- commands（test / health / build:h5）
|
||||
- review.md
|
||||
- DoD + checklist
|
||||
↓
|
||||
Commands (build / test / health)
|
||||
5. Document
|
||||
- OpenAPI / erd / feature 标记若行为变化
|
||||
↓
|
||||
Review (.ai/review.md)
|
||||
↓
|
||||
DoD + checklist
|
||||
↓
|
||||
Commit (Conventional Commits, one concern)
|
||||
Commit（Conventional Commits，one concern）
|
||||
```
|
||||
|
||||
## Architecture Check questions
|
||||
## Architecture Check
|
||||
|
||||
1. Does this change reverse an Accepted ADR? If yes → ASK / new ADR.
|
||||
2. Correct layer? Handler / Service / Repository?
|
||||
3. Domain words match `.ai/domain.md`?
|
||||
4. API envelope still `{code,message,data}`?
|
||||
1. Reverse Accepted ADR? → ASK / new ADR.
|
||||
2. Correct layer? Handler / Service / Repository?
|
||||
3. Domain words = `.ai/domain.md` + lexicon for UI?
|
||||
4. Envelope still `{code,message,data}`?
|
||||
5. Local workflow still host runtime（非 Docker-only 编码）?
|
||||
|
||||
## Stop conditions
|
||||
|
||||
- Unclear requirement → ASK FIRST
|
||||
- Need GraphQL / new DB / new auth scheme → write or cite ADR before coding
|
||||
- Unclear requirement → **ASK FIRST**
|
||||
- Need GraphQL / new auth scheme / new datastore → ADR before coding
|
||||
- Urge to “just ALTER TABLE” → write migration instead
|
||||
|
||||
## Playbooks
|
||||
|
||||
Prefer: `add-api` · `new-page` · `new-table` · `payment` · `login`
|
||||
|
||||
Reference in New Issue
Block a user