# 版本号规范 (Versioning)

> 适用：七虎AI PaaS 平台 (qihuaiflow) 全部发布物（源码、Docker 镜像、线上环境）。
> 生效版本：`v2026.07.18.1`（取代旧 `-recover` 标签体系）。

---

## 1. 版本号格式

```
vYYYY.MM.DD.N
```

| 段 | 含义 | 示例 |
|----|------|------|
| `YYYY` | 年（4 位） | 2026 |
| `MM` | 月（2 位，补零） | 07 |
| `DD` | 日（2 位，补零） | 18 |
| `N` | **当日**递增序号，从 `1` 开始，同日多次发布顺延 | 1, 2, 3 … |

- 同一天第 1 次发布 = `v2026.07.18.1`，第 2 次 = `v2026.07.18.2`。
- 跨天序号**重置**：次日第 1 次发布 = `v2026.07.19.1`。
- 序号不与全局总发布数绑定，只跟"当天第几次"有关，便于人类快速判断发布日期与顺序。

## 2. 环境标签 (prod / test)

每个版本必须标注环境，用于正式版与测试版的环境切割：

- **`prod`** — 正式版，面向最终用户，质量门禁（测试全绿 + 备份完成）必须达标。
- **`test`** — 测试版 / 灰度 / 预发布，允许未完全冻结，但同样需要镜像备份。

环境信息记录在 `VERSION` 文件的 `ENV=` 字段，并写入 git tag 注解与镜像 metadata。

## 3. 三类发布物的对应关系

一次发布同时产生三个相互关联的制品：

| 制品 | 命名 | 工具 |
|------|------|------|
| Git 标签 | `v2026.07.18.1`（注解含 `env=prod`） | `git tag -a` |
| Docker 镜像 | `qihu-aiflow:v2026.07.18.1` | `docker tag` / `docker commit` |
| 运行态快照（回滚点） | `qihu-aiflow:backup-YYYYMMDD-NNN` | `scripts/backup_before_deploy.py` |

> **关键纪律**：`backup-*` 是部署**前**对当前健康运行态的快照（防线）；`v*` 镜像/标签是部署**后**的发布物（成果）。两者不是一个东西。

## 4. 发布流程（SOP）

每次部署严格遵守以下步骤：

```bash
# 0. 在改任何代码之前，先打部署前镜像备份（强制）
python scripts/backup_before_deploy.py --env prod --note "发布 v2026.07.18.1 前快照"

# 1. 在容器中完成代码修改
#    （编辑 /app/... → 必要时 npm run build → docker restart）

# 2. 把容器内最新源码 docker cp 回宿主仓库
docker cp qihu-aiflow:/app /www/wwwroot/qihuaiflow   # 仅后端；前端 dist 同理

# 3. 更新 VERSION 文件（VERSION / ENV / DATE / BACKUP_IMAGE）

# 4. 提交并打标签
cd /www/wwwroot/qihuaiflow
git add -A
git commit -m "release: v2026.07.18.1 (prod) — <一句话变更摘要>"
git tag -a v2026.07.18.1 -m "prod | Phase0 工程纪律止血：备份SOP + 版本规范 + 测试基建"
git push origin main
git push origin v2026.07.18.1

# 5. 固化发布镜像（可选但推荐，便于回滚到有版本号的镜像）
docker commit qihu-aiflow qihu-aiflow:v2026.07.18.1
```

## 5. 回滚流程

若发布后发现问题：

```bash
# 方案 A：回滚到部署前快照（最快，不依赖源码）
docker tag qihu-aiflow:backup-20260718-001 qihu-aiflow:with-deps
docker restart qihu-aiflow

# 方案 B：回滚到某个历史发布镜像
docker tag qihu-aiflow:v2026.07.18.1 qihu-aiflow:with-deps
docker restart qihu-aiflow

# 方案 C：源码回滚
git checkout v2026.07.18.1
docker cp /www/wwwroot/qihuaiflow/app qihu-aiflow:/app
docker restart qihu-aiflow
```

## 6. VERSION 文件维护

- 仓库根目录 `VERSION` 为机器 + 人共读的清单，必须包含 `VERSION=` / `ENV=` / `DATE=` / `BASE_IMAGE=` / `BACKUP_IMAGE=` 五个字段。
- 每次发布更新 `VERSION` 与 `DATE`，并在"本版本变更"小节追加一行摘要。
- `BACKUP_IMAGE` 必须填写本次发布前实际生成的 `backup-*` 标签，作为可审计的回滚点。

## 7. 旧标签处理

- 旧 `-recover` 系列标签（`v2026.07.12-recover` 等）**保留不删**，仅停止使用，避免丢失历史快照索引。
- 旧镜像标签 `AIFlow v2.0.1` / `v2026.07.14` / `v2026.07.14-nav` 视为历史资产，新发布不再沿用该命名。