# 版本发布与回滚 (Release)

---

## 1. 版本号规范

本项目采用 **语义化版本** (Semantic Versioning 2.0.0)：`MAJOR.MINOR.PATCH`。

| 组成 | 含义 | 何时递增 |
|------|------|----------|
| MAJOR | 不兼容的 API 变更 | 删除端点、修改响应结构、删除字段 |
| MINOR | 向后兼容的功能新增 | 新增端点、新增可选字段 |
| PATCH | 向后兼容的缺陷修复 | Bug 修复、安全补丁、文档修正 |

预发布版本可附加标签，如 `1.2.0-rc.1`、`1.2.0-beta.1`。

---

## 2. 发布流程

### 2.1 完整流程

**Step 1 — 更新版本号**

```bash
# Maven 项目版本
mvn versions:set -DnewVersion=1.2.0
mvn versions:commit
```

**Step 2 — 更新 CHANGELOG.md**

在 `CHANGELOG.md` 顶部添加新版本段落，列出 Added、Changed、Fixed、Removed 各类变更。

**Step 3 — 提交并打 Tag**

```bash
git add -A
git commit -m "chore(release): v1.2.0"
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags
```

**Step 4 — CI 自动构建**

Tag push 触发 CI Pipeline：运行全部测试（`mvn clean verify`）；构建 Docker 镜像并推送（`tmpl-api:1.2.0` + `tmpl-api:latest`）；生成 GitHub Release（附 CHANGELOG 摘要）。

**Step 5 — 更新 Kustomize 镜像标签**

```bash
./deploy/scripts/update-image-tag.sh <env> 1.2.0
git add deploy/overlays/<env>/kustomization.yaml
git commit -m "deploy(<env>): update image tag to 1.2.0"
git push
```

GitOps 工具（ArgoCD / Flux）检测到 overlay 变更后自动部署。

### 2.2 热修复流程 (Hotfix)

从对应版本 Tag 创建 `hotfix/1.2.1` 分支 → 修复 → 合并回 `main` → 按上述流程发布 `1.2.1`。

---

## 3. Docker 镜像标签策略

| 标签 | 来源 | 用途 |
|------|------|------|
| `1.2.0` | Git Tag `v1.2.0` | 不可变生产标签 |
| `1.2` | 最新 1.2.x | 方便 staging 滚动 |
| `latest` | 最新 main 构建 | 仅限 dev 环境 |
| `sha-abc1234` | Git commit SHA | CI 中间产物追溯 |

生产环境禁止使用 `latest` 标签。

---

## 4. 回滚策略

### 4.1 Kubernetes 回滚

```bash
# 查看历史
kubectl rollout history deployment/tmpl-api -n <ns>

# 回滚到上一版本
kubectl rollout undo deployment/tmpl-api -n <ns>

# 回滚到指定版本
kubectl rollout undo deployment/tmpl-api -n <ns> --to-revision=3
```

### 4.2 Kustomize / GitOps 回滚

通过 Git revert overlay 中的镜像标签变更，ArgoCD/Flux 会自动部署回退版本。

```bash
git revert <commit-hash>
git push
```

### 4.3 数据库回滚注意事项

Flyway 迁移是 forward-only 的，不支持自动回滚。如果新版本包含 schema 变更，回滚应用时：

若迁移仅添加了列或表（向后兼容），旧版本代码可正常运行，无需回滚 schema。若迁移删除了列或修改了类型（不兼容），必须提前准备反向迁移脚本（新版本号），在回滚应用前先执行。

**建议**：所有 schema 变更设计为向后兼容（expand-then-contract 模式），使回滚成为可能。

---

## 5. 发布检查清单

发布前确认以下项目：`mvn clean verify` 全部通过；CHANGELOG.md 已更新；版本号已在 POM 和 Tag 中同步；Docker 镜像构建成功且大小 <= 200MB；OWASP Dependency-Check 无 CVSS >= 7.0 漏洞；Kustomize overlay 中镜像标签已更新；在 staging 环境完成冒烟测试（健康检查、核心 API、Prometheus 端点）。