AiDOPWarehouse/.cursor/rules/version-bump-on-commit.mdc

---
description: 发版必升号；提交改动到前端/后端代码时须递增对应端版本号
alwaysApply: true
---

# 版本号：发版与前后端代码提交

## 发版必升号

凡视为**发版**（打 tag、上预发/生产、对外交付构建物），发布所依据的提交中**必须**已更新版本号，且与变更说明一致；禁止「已部署仍沿用旧号」。

## Git 提交：只在改动对应端代码/配置时升号

凡执行 `git commit` 时，应根据**本次提交实际纳入的文件**决定是否递增版本号，而不是根据整段会话历史、工作区曾经改过什么、或后续计划要提交什么来判断。

1. **改动前端代码/配置**：必须在同一提交中递增 `Web/package.json` 的 `version`（SemVer：**只升 patch** 末位，如 `2.4.33` → `2.4.34`；minor/major 仅在明确里程碑发版时由负责人决定）。构建时 `__NEXT_VERSION__` 来自该字段，无需另改 `vite.config.ts`。
2. **改动后端代码/配置**：必须在同一提交中递增 `server/Admin.NET.Web.Entry/Admin.NET.Web.Entry.csproj` 中的 `<Version>`、`<AssemblyVersion>`、`<FileVersion>`（**三处保持同号**，patch +1，如 `1.0.0` → `1.0.1`）。
3. **同时改动前端与后端**：前端、后端版本号都必须在同一提交中分别 patch +1。
4. **仅改文档、规则、会议纪要、说明类 Markdown、非运行脚本说明等不影响前后端运行产物的内容**：**不递增**前端或后端版本号。

### 提交范围与版本号示例

- 本次 commit **只包含后端代码/配置**：只递增后端版本号，不递增 `Web/package.json`。
- 本次 commit **只包含前端代码/配置**：只递增前端版本号，不递增后端 `.csproj`。
- 本次 commit **同时包含前端和后端代码/配置**：前端、后端版本号都递增。
- 工作区里前后端都改过，但用户要求**只提交其中一端**：只按实际提交端递增版本号。
- 本次 commit 只包含文档、规则或说明文件：不递增前后端版本号。

### 影响范围判定

一般按路径与运行影响判断：

- 前端：`Web/` 下会进入前端构建或影响前端运行的源码、配置、依赖、静态资源等。
- 后端：`server/` 下会进入后端构建或影响后端运行的源码、配置、依赖、启动参数、数据库初始化配置等。
- 文档/规则：`doc/`、`.cursor/rules/`、`AGENTS.md` 等仅说明协作或方案的文件，默认不升号。
- 若改动虽在文档/脚本目录，但会被部署流程执行并影响运行行为，应按其实际影响端升号。

### 锁文件

若项目使用 `package-lock.json` / `pnpm-lock.yaml` 且会因版本或依赖变更而更新，版本提交中应包含与 `package.json` 一致的锁文件变更。

### 提交说明

若本次提交包含版本递增，建议在 commit message 中带一句版本，例如：`chore: bump version Web 2.4.34 / server 1.0.1` 或与功能说明合并。纯文档/规则提交无需写版本信息。

## AI / 协作者执行时注意

在准备帮用户**提交或收尾 PR** 时：应先判断本次实际要纳入提交的文件是否影响前端或后端运行产物，再主动提醒或代为完成对应端版本号递增。不要因为会话中曾经改过某端、工作区里存在未纳入提交的某端改动、或纯文档/规则提交而递增无关端版本号。