# Production & CI Deployment — AI Contract

本文件只约束 **CI** 与 **Production**。  
本地编码见 [development.md](development.md)；Docker 角色见 [docker.md](docker.md)。

---

## Production Rules

Production **MUST** use immutable images.

### MUST NOT（生产）

- 服务器上 `git pull` 后直接编译运行当主发布路径  
- 手工在机器上 `npm install` / `go mod download` 当发布步骤  
- 登录容器改代码或改依赖冒充发布  
- 使用镜像 tag `latest`  
- 把本地 `.env` / 开发密钥打进镜像  

### Happy path

```
Git Push → CI → Test → Build Image → Registry → Deploy → Health Check
```

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

禁止把右栏流程套到左栏日常开发。