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