wang259797/lingxi
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(docs): 调整分支策略为仅 main 直推
ci / 质量门禁 (push) Canceled after 0s
Details

Browse Source 
背景：用户确认仓库只保留 main，不再创建任何远程分支或走 PR 合并。

改动：
- 01-Git规范 V1.1：仅 main 直推，禁止非 main 分支推送、force push 与 Merge commit；
- AGENTS V1.1：变更流程改为直接提交并推送 main；
- 07-CodeReview：PR 模板改为提交说明，合并流程改为推送与推送后观察；
- 03/06/工程规范 README 同步去除 PR 措辞；
- CI 仅保留 push main 与 workflow_dispatch 触发。

影响面：仅流程与文档，无代码/数据/接口变更。
回滚方式：git revert 本提交即可恢复旧流程。
验证：format:check、lint、typecheck 全绿（10/10）。
This commit is contained in:
Stev_Wang committed 2026-11-02 17:40:01 +08:00
1 parent 046dad463e
commit dd01b89214
7 files changed
+74 -81
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.gitea/workflows/ci.yml
+2 -2
View File
@@ -2,8 +2,8 @@ name: ci
on: on:
push: push:
branches: [main, 'feat/**'] branches: [main]
pull_request: workflow_dispatch:
concurrency: concurrency:
group: ci-${{ github.ref }} group: ci-${{ github.ref }}
AGENTS.md
+11 -11
View File
@@ -7,7 +7,7 @@
| --- | --- | | --- | --- |
| 适用对象 | 前端 / 后端 / 测试 / 运维 / AI 工程 / 产品（技术边界） | | 适用对象 | 前端 / 后端 / 测试 / 运维 / AI 工程 / 产品（技术边界） |
| 适用产物 | 代码、配置、脚本、迁移、文档、Prompts | | 适用产物 | 代码、配置、脚本、迁移、文档、Prompts |
| 文档版本 | V1.0（2026-11-02） | | 文档版本 | V1.1（2026-11-02） |
| 事实基线 | PRD `V1.6`、技术架构 `V0.4` | | 事实基线 | PRD `V1.6`、技术架构 `V0.4` |
--- ---
@@ -79,7 +79,7 @@
| 质量 | Vitest · Testcontainers · Playwright · k6 · oasdiff | | 质量 | Vitest · Testcontainers · Playwright · k6 · oasdiff |
| 观测 | Pino · OpenTelemetry | | 观测 | Pino · OpenTelemetry |
> 版本升级单独 PR + 修订记录，**禁止顺手升级**。新增运行时依赖需在 PR 说明必要性（影响面 + 替代方案）。 > 版本升级单独提交 + 修订记录，**禁止顺手升级**。新增运行时依赖需在提交说明必要性（影响面 + 替代方案）。
--- ---
@@ -122,21 +122,21 @@ docs/ PRD / 技术架构 / 立项建议 / 工程规范
--- ---
## 7　变更流程（提测 / 合并前必须全绿） ## 7　变更流程（推送前必须全绿）
1. 从 `main` 拉短分支 → 小步提交（**Conventional Commits，提交信息与 PR 标题一律用中文**，`type` / `scope` 保留英文）。 1. 基于最新 `main` 直接提交，小步 commit（**Conventional Commits，提交信息一律用中文**，`type` / `scope` 保留英文）。
2. 本地门禁：`pnpm lint && pnpm typecheck && pnpm test`。 2. 本地门禁：`pnpm format:check && pnpm lint && pnpm typecheck && pnpm test`。
3. PR 描述必含：**背景 / 改动 / 影响面 / 回滚方式 / 验证证据**；迁移、权限、AI、导出类变更须**双人 Review**。 3. 提交说明必含：**背景 / 改动 / 影响面 / 回滚方式 / 验证证据**；迁移、权限、AI、导出类变更须在推送前完成双人走查。
4. CI 全绿 + Review 通过 → **Squash Merge**；禁止 force push `main`。 4. 直接 `git push origin main`；禁止 force push `main`，禁止 Merge commit；推送后立即确认 CI，失败按前向修复处理。
5. 发布：staging 验证 → 生产灰度；**迁移先行、代码后行**。 5. 发布：staging 验证 → 生产灰度；**迁移先行、代码后行**。
细则：[Git 规范](docs/工程规范/01-Git规范.md) · [Code Review 与 PR](docs/工程规范/07-CodeReview与PR规范.md) · [测试与 CI](docs/工程规范/06-测试与CI规范.md) 细则：[Git 规范](docs/工程规范/01-Git规范.md) · [Code Review](docs/工程规范/07-CodeReview与PR规范.md) · [测试与 CI](docs/工程规范/06-测试与CI规范.md)
--- ---
## 8　文档规范（摘要） ## 8　文档规范（摘要）
- 文档与代码**同 PR** 更新；只改文档也要走 PR。 - 文档与代码**同一次提交或相邻提交**更新；只改文档也直接提交到 `main`。
- 新业务规则先进 PRD 并编号（`R-xx`），再进代码。 - 新业务规则先进 PRD 并编号（`R-xx`），再进代码。
- 文档版本 `V<主>.<次>`：主版本 = 业务口径不兼容；次版本 = 增量补充。 - 文档版本 `V<主>.<次>`：主版本 = 业务口径不兼容；次版本 = 增量补充。
- 索引三处必须同步：根 `README.md`、`docs/工程规范/README.md`、本文件 §9。 - 索引三处必须同步：根 `README.md`、`docs/工程规范/README.md`、本文件 §9。
@@ -148,13 +148,13 @@ docs/ PRD / 技术架构 / 立项建议 / 工程规范
| 主题 | 文档 | 一句话 | | 主题 | 文档 | 一句话 |
| --- | --- | --- | | --- | --- | --- |
| Git / 分支 / 提交 | [01-Git规范](docs/工程规范/01-Git规范.md) | 主干 + 短分支，Conventional Commits（**提交信息用中文**），Squash 合并 | | Git / 分支 / 提交 | [01-Git规范](docs/工程规范/01-Git规范.md) | 仅 `main` 直推，Conventional Commits（**提交信息用中文**），禁止 Merge commit |
| 代码风格 | [02-代码风格](docs/工程规范/02-代码风格.md) | 命名、类型、错误处理、异步、React 约定 | | 代码风格 | [02-代码风格](docs/工程规范/02-代码风格.md) | 命名、类型、错误处理、异步、React 约定 |
| 格式化与 Lint | [03-格式化与Lint](docs/工程规范/03-格式化与Lint.md) | Prettier + ESLint 9 flat，钩子与 CI 门禁 | | 格式化与 Lint | [03-格式化与Lint](docs/工程规范/03-格式化与Lint.md) | Prettier + ESLint 9 flat，钩子与 CI 门禁 |
| API 与路由 | [04-API与路由规范](docs/工程规范/04-API与路由规范.md) | REST /api/v1、错误码、鉴权链、任务协议 | | API 与路由 | [04-API与路由规范](docs/工程规范/04-API与路由规范.md) | REST /api/v1、错误码、鉴权链、任务协议 |
| 数据库 | [05-数据库规范](docs/工程规范/05-数据库规范.md) | ULID、customer_id、游标分页、expand/contract | | 数据库 | [05-数据库规范](docs/工程规范/05-数据库规范.md) | ULID、customer_id、游标分页、expand/contract |
| 测试与 CI | [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md) | 分层测试、权限三态、覆盖率只升不降 | | 测试与 CI | [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md) | 分层测试、权限三态、覆盖率只升不降 |
| Code Review | [07-CodeReview与PR规范](docs/工程规范/07-CodeReview与PR规范.md) | PR 模板、双人场景、DoD、合并后观察 | | Code Review | [07-CodeReview与PR规范](docs/工程规范/07-CodeReview与PR规范.md) | 提交说明、双人场景、DoD、推送后观察 |
| 日志与可观测 | [08-日志与可观测性规范](docs/工程规范/08-日志与可观测性规范.md) | Pino 字段、trace_id、审计与日志分离、告警 | | 日志与可观测 | [08-日志与可观测性规范](docs/工程规范/08-日志与可观测性规范.md) | Pino 字段、trace_id、审计与日志分离、告警 |
| 环境变量与密钥 | [09-环境变量与密钥规范](docs/工程规范/09-环境变量与密钥规范.md) | `.env.example` 入库、启动校验、轮换与泄露处置 | | 环境变量与密钥 | [09-环境变量与密钥规范](docs/工程规范/09-环境变量与密钥规范.md) | `.env.example` 入库、启动校验、轮换与泄露处置 |
| 资产命名与图层 | [10-资产命名与PSD图层规范](docs/工程规范/10-资产命名与PSD图层规范.md) | 命名占位符、PSD 图层前缀、规格矩阵、低质量标记 | | 资产命名与图层 | [10-资产命名与PSD图层规范](docs/工程规范/10-资产命名与PSD图层规范.md) | 命名占位符、PSD 图层前缀、规格矩阵、低质量标记 |
docs/工程规范/01-Git规范.md
+21 -30
View File
@@ -2,7 +2,7 @@
| 项 | 内容 | | 项 | 内容 |
| --- | --- | | --- | --- |
| 文档版本 | V1.0（2026-11-02） | | 文档版本 | V1.1（2026-11-02） |
| 依据 | 技术架构 §4.6（CI/CD）、§10.1（仓库结构） | | 依据 | 技术架构 §4.6（CI/CD）、§10.1（仓库结构） |
| 适用范围 | 全仓库（代码、文档、配置、迁移） | | 适用范围 | 全仓库（代码、文档、配置、迁移） |
| 强制级别 | 强制 | | 强制级别 | 强制 |
@@ -11,25 +11,18 @@
## 1　分支模型 ## 1　分支模型
采用 **trunk-based（主干 + 短生命周期分支）**，不建 `develop`、不建长期 `release` 分支。 采用 **仅 main 直推**：仓库只保留 `main` 一条分支，不建 `develop`、`release`、`feat/*`、`docs/*` 等任何本地或远程分支。
| 类型 | 命名 | 用途 | 生命周期 | | 类型 | 名称 | 用途 | 生命周期 |
| --- | --- | --- | --- | | ---- | ------ | ------------------------ | -------- |
| 主干 | `main` | 始终可发布 | 永久 | | 主干 | `main` | 唯一长期分支，始终可发布 | 永久 |
| 功能 | `feat/<scope>-<简述>` | 新功能 | ≤ 5 天，超过须拆分 |
| 修复 | `fix/<scope>-<简述>` | 缺陷修复 | ≤ 2 天 |
| 文档 | `docs/<简述>` | 仅文档 | ≤ 1 天 |
| 重构 | `refactor/<scope>-<简述>` | 行为不变的结构调整 | ≤ 3 天 |
| 其他 | `chore/` `test/` `perf/` `build/` `ci/` | 对应类型 | ≤ 2 天 |
规则： 规则：
- `GIT-01` 分支名全小写 kebab-case，≤ 50 字符，**不含中文**；`scope` 用模块或包名（`api` / `web` / `worker` / `media` / `db` / `ci` / `docs`）。 - `GIT-01` 所有提交直接基于最新 `main`；提交前先 `git pull --ff-only`，避免落后。
- `GIT-02` 分支必须从最新 `main` 拉出，合并前 rebase 到 `main` 最新。 - `GIT-02` 禁止创建并推送任何非 `main` 分支；确需本地验证时可临时创建，但不得推送，完成后立即删除。
- `GIT-03` 禁止直接 push `main`；分支保护开启：必须 PR + CI 绿 + ≥1 批准。 - `GIT-03` 允许直接 push `main`；推送前必须通过本地门禁（`format:check`、`lint`、`typecheck`、`test`），推送后立即确认 CI。
- `GIT-04` 合并后立即删除远端分支。 - `GIT-04` 禁止 force push `main`；禁止 Merge commit；`main` 必须保持线性。
---
## 2　提交信息（Conventional Commits 1.0） ## 2　提交信息（Conventional Commits 1.0）
@@ -105,15 +98,13 @@ export default {
--- ---
## 3　PR 与合并 ## 3　提交、推送与 Review
- `GIT-12` PR 标题遵循提交规范（Squash 后即主干提交信息）。 - `GIT-12` 直接推送到 `main` 的提交即主干提交，提交信息按 §2 执行。
- `GIT-13` 合并方式统一 **Squash Merge**，保持 `main` 线性；禁止 Merge commit。 - `GIT-13` 禁止 Merge commit 等分支合并方式；一次提交只做一件事，`main` 保持线性。
- `GIT-14` 单个 PR 变更 ≤ 400 行（含测试，不含 lock 文件与生成代码）；超出须拆分并在描述说明依赖关系。 - `GIT-14` 单个提交变更 ≤ 400 行（含测试，不含 lock 与生成代码）；里程碑批次超出须在提交说明注明原因与拆分计划。
- `GIT-15` 禁止 force push `main` / 已有人 Review 的公共分支；个人分支允许 `--force-with-lease`。 - `GIT-15` 禁止 force push `main`；已推送提交不回改写，修复一律用新提交前向修复。
- `GIT-16` PR 描述模板与双人 Review 场景见 [07-CodeReview与PR规范](07-CodeReview与PR规范.md)。 - `GIT-16` Review 要求见 [07-CodeReview与PR规范](07-CodeReview与PR规范.md)：高风险变更推送前完成双人走查，普通变更至少自查并在推送后 24 小时内走查。
---
## 4　Tag 与发布 ## 4　Tag 与发布
@@ -122,25 +113,25 @@ export default {
| 版本号 | 语义化 `v<主>.<次>.<补>` | | 版本号 | 语义化 `v<主>.<次>.<补>` |
| 打 Tag 时机 | 生产发布前，由发布负责人在 `main` 打 annotated tag | | 打 Tag 时机 | 生产发布前，由发布负责人在 `main` 打 annotated tag |
| 里程碑 Tag | `m0` / `m1` / `m2`…（对应 PRD 分期），仅标记不进版本链 | | 里程碑 Tag | `m0` / `m1` / `m2`…（对应 PRD 分期），仅标记不进版本链 |
| 发布记录 | 每个 Tag 必须写变更摘要（可复用 PR 标题集合） | | 发布记录 | 每个 Tag 必须写变更摘要（可复用提交标题集合） |
| 回滚 | 回滚用新 Tag（`v1.2.1` 回滚 `v1.2.0` 内容），**禁止删除已发布 Tag** | | 回滚 | 回滚用新 Tag（`v1.2.1` 回滚 `v1.2.0` 内容），**禁止删除已发布 Tag** |
--- ---
## 5　大文件与二进制 ## 5　大文件与二进制
- `GIT-17` 禁止入库 > 10 MB 的二进制（PSD 模板、成片、视频、字体包），一律走对象存储；确需入库（如开源字体）用 **Git LFS** 并在 PR 说明。 - `GIT-17` 禁止入库 > 10 MB 的二进制（PSD 模板、成片、视频、字体包），一律走对象存储；确需入库（如开源字体）用 **Git LFS** 并在提交说明。
- `GIT-18` 禁止入库：`.env*`、密钥、证书私钥、构建产物、`node_modules/`、日志、`项目参考/`。 - `GIT-18` 禁止入库：`.env*`、密钥、证书私钥、构建产物、`node_modules/`、日志、`项目参考/`。
- `GIT-19` `pnpm-lock.yaml` 必须提交且与 `package.json` 同步；**禁止**手工编辑 lock 文件。 - `GIT-19` `pnpm-lock.yaml` 必须提交且与 `package.json` 同步；**禁止**手工编辑 lock 文件。
- `GIT-20` 误提交敏感信息：立即轮换密钥 → 用 `git filter-repo` 清理历史 → 全员重新 clone → 记录复盘。 - `GIT-20` 误提交敏感信息：立即轮换密钥 → 用 `git filter-repo` 清理历史 → 全员重新 clone → 记录复盘。
--- ---
## 6　检查清单（提交前 / 合并前） ## 6　检查清单（提交前 / 推送前）
- [ ] 分支名符合 `GIT-01`，从最新 `main` 拉出 - [ ] 提交基于最新 `main`，已同步远端
- [ ] 提交信息为**中文**且符合 Conventional Commits（含 `scope`），subject 无句末标点 - [ ] 提交信息为**中文**且符合 Conventional Commits（含 `scope`），subject 无句末标点
- [ ] 提交粒度单一，无无关文件 - [ ] 提交粒度单一，无无关文件
- [ ] 无 `.env` / 密钥 / 大文件 - [ ] 无 `.env` / 密钥 / 大文件
- [ ] PR 描述含背景 / 影响面 / 回滚方式 / 验证证据 - [ ] 提交说明含背景 / 影响面 / 回滚方式 / 验证证据
- [ ] CI 全绿，Review 通过，Squash 合并 - [ ] 本地门禁全绿，已 push `main` 并确认 CI
docs/工程规范/03-格式化与Lint.md
+5 -5
View File
@@ -34,7 +34,7 @@
- `FMT-01` 只允许一个 Prettier 版本、一个根配置；子包**不得**覆盖。 - `FMT-01` 只允许一个 Prettier 版本、一个根配置；子包**不得**覆盖。
- `FMT-02` 禁止在文件中写 `prettier-ignore`，除非是生成代码或大段 markdown 表格，并注明原因。 - `FMT-02` 禁止在文件中写 `prettier-ignore`，除非是生成代码或大段 markdown 表格，并注明原因。
- `FMT-03` CI 执行 `pnpm format:check`，失败即阻断。 - `FMT-03` CI 执行 `pnpm format:check`，失败即阻断。
- `FMT-04` 禁止把格式化产生的无关改动混进功能 PR（会产生冲突与 Review 噪音）。 - `FMT-04` 禁止把格式化产生的无关改动混进功能提交（会产生冲突与 Review 噪音）。
--- ---
@@ -95,7 +95,7 @@ element-plus naive-ui @mui/* @chakra-ui/*
| `pre-push` | husky | 跑 `pnpm typecheck`（本地拦截类型错误，避免浪费 CI） | | `pre-push` | husky | 跑 `pnpm typecheck`（本地拦截类型错误，避免浪费 CI） |
- `FMT-08` `lint-staged` 只处理暂存文件，**禁止**在钩子里跑全量 lint / 全量测试（太慢会诱发 `--no-verify`）。 - `FMT-08` `lint-staged` 只处理暂存文件，**禁止**在钩子里跑全量 lint / 全量测试（太慢会诱发 `--no-verify`）。
- `FMT-09` 禁止 `git commit --no-verify`；如确因钩子故障，须在 PR 描述说明并附 CI 结果。 - `FMT-09` 禁止 `git commit --no-verify`；如确因钩子故障，须在提交说明中说明并附 CI 结果。
--- ---
@@ -113,7 +113,7 @@ element-plus naive-ui @mui/* @chakra-ui/*
| 安全 | 依赖审计 + 镜像高危漏洞 | 阻断（高危 0） | | 安全 | 依赖审计 + 镜像高危漏洞 | 阻断（高危 0） |
- `FMT-10` CI 与本地必须使用**同一份配置**，禁止 CI 单独放宽规则。 - `FMT-10` CI 与本地必须使用**同一份配置**，禁止 CI 单独放宽规则。
- `FMT-11` 覆盖率基线只升不降；下调须在 PR 说明理由并由技术负责人批准。 - `FMT-11` 覆盖率基线只升不降；下调须在提交说明说明理由并由技术负责人批准。
--- ---
@@ -122,12 +122,12 @@ element-plus naive-ui @mui/* @chakra-ui/*
| 场景 | 做法 | | 场景 | 做法 |
| --- | --- | | --- | --- |
| 生成代码（Prisma Client、OpenAPI 类型） | 在 `eslint.config.mjs` 中按路径 `ignores`，禁止在生成文件内加注释 | | 生成代码（Prisma Client、OpenAPI 类型） | 在 `eslint.config.mjs` 中按路径 `ignores`，禁止在生成文件内加注释 |
| 第三方类型缺陷 | 文件级 `/* eslint-disable rule -- 原因 */`，必须写原因并在 PR 说明 | | 第三方类型缺陷 | 文件级 `/* eslint-disable rule -- 原因 */`，必须写原因并在提交说明说明 |
| 单行特殊语法 | 行内 `// eslint-disable-next-line rule -- 原因` | | 单行特殊语法 | 行内 `// eslint-disable-next-line rule -- 原因` |
| 全文件 disable | **禁止**；确需则改为局部 disable 或调整规则配置 | | 全文件 disable | **禁止**；确需则改为局部 disable 或调整规则配置 |
- `FMT-12` 任何 `eslint-disable` 都必须写明原因与到期处理方式（升级依赖 / 提 issue）。 - `FMT-12` 任何 `eslint-disable` 都必须写明原因与到期处理方式（升级依赖 / 提 issue）。
- `FMT-13` 规则调整（新增 / 降级 / 关闭）必须单独 PR，说明影响文件数与整改计划。 - `FMT-13` 规则调整（新增 / 降级 / 关闭）必须单独提交，说明影响文件数与整改计划。
--- ---
docs/工程规范/06-测试与CI规范.md
+5 -5
View File
@@ -14,8 +14,8 @@
| 层级 | 工具 | 范围 | 运行时机 | | 层级 | 工具 | 范围 | 运行时机 |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| 单元 | Vitest | Service、工具函数、状态机、命名 / 表单引擎 | 每次提交（CI + 本地） | | 单元 | Vitest | Service、工具函数、状态机、命名 / 表单引擎 | 每次提交（CI + 本地） |
| 集成 | Vitest + Testcontainers（PG 18 / Redis 7.4 / MinIO） | Repository、队列、迁移、事务 | 每次 PR（CI） | | 集成 | Vitest + Testcontainers（PG 18 / Redis 7.4 / MinIO） | Repository、队列、迁移、事务 | 每次 push `main`（CI） |
| 契约 | OpenAPI + `oasdiff` | 接口兼容性 | 每次 PR | | 契约 | OpenAPI + `oasdiff` | 接口兼容性 | 每次 push `main` |
| E2E | Playwright | 主链路（登录 → 生成 → 预览 → 勾选 → 导出） | 主干 + 发布前 | | E2E | Playwright | 主链路（登录 → 生成 → 预览 → 勾选 → 导出） | 主干 + 发布前 |
| 性能 | k6 | 列表 / 任务提交 / SSE | 发布前（仅 staging） | | 性能 | k6 | 列表 / 任务提交 / SSE | 发布前（仅 staging） |
| 视觉回归 | 图片像素比对 | PSD 合成产物 | 改动 `packages/render` 时 | | 视觉回归 | 图片像素比对 | PSD 合成产物 | 改动 `packages/render` 时 |
@@ -61,7 +61,7 @@ install --frozen-lockfile
→ format:check → lint --max-warnings=0 → typecheck → format:check → lint --max-warnings=0 → typecheck
→ unit test（coverage）→ build → unit test（coverage）→ build
→ integration（Testcontainers）→ openapi:diff → integration（Testcontainers）→ openapi:diff
→ e2e（main / 发布分支）→ 镜像构建 + 漏洞扫描 → e2e（main）→ 镜像构建 + 漏洞扫描
``` ```
| 阶段 | 阻断条件 | | 阶段 | 阻断条件 |
@@ -76,7 +76,7 @@ install --frozen-lockfile
| 安全 | 高危漏洞 > 0 | | 安全 | 高危漏洞 > 0 |
- `TST-20` 流水线并行化按包拆分（Turborepo），但门禁结论必须在聚合 job 上判定。 - `TST-20` 流水线并行化按包拆分（Turborepo），但门禁结论必须在聚合 job 上判定。
- `TST-21` 禁止通过 `--passWithNoTests`、跳过集成测试等方式「修绿」；豁免须技术负责人批准并留 PR 记录。 - `TST-21` 禁止通过 `--passWithNoTests`、跳过集成测试等方式「修绿」；豁免须技术负责人批准并留提交说明记录。
- `TST-22` flaky 测试 24 小时内修复或移除并登记，**禁止**重试 3 次掩盖。 - `TST-22` flaky 测试 24 小时内修复或移除并登记，**禁止**重试 3 次掩盖。
--- ---
@@ -89,7 +89,7 @@ install --frozen-lockfile
| 其他 `FEATURE_*` | 按里程碑临时开关，上线稳定后删除 | | 其他 `FEATURE_*` | 按里程碑临时开关，上线稳定后删除 |
- `TST-23` 未完成功能必须藏在开关后，**禁止**半成品直接可见。 - `TST-23` 未完成功能必须藏在开关后，**禁止**半成品直接可见。
- `TST-24` 开关必须有默认值、有 owner、有清理期限（写进 PR 或配置注释）。 - `TST-24` 开关必须有默认值、有 owner、有清理期限（写进提交说明或配置注释）。
- `TST-25` 开关组合不得导致数据不一致（关闭后已产生的数据仍可读）。 - `TST-25` 开关组合不得导致数据不一致（关闭后已产生的数据仍可读）。
--- ---
docs/工程规范/07-CodeReview与PR规范.md
+25 -23
View File
@@ -1,15 +1,17 @@
# 07 · Code Review 与 PR 规范 # 07 · Code Review 规范（main 直推）
| 项 | 内容 | | 项 | 内容 |
| --- | --- | | --- | --- |
| 文档版本 | V1.0（2026-11-02） | | 文档版本 | V1.1（2026-11-02） |
| 依据 | 技术架构 §10.1（工程约定）、§4.6（CI/CD） | | 依据 | 技术架构 §10.1（工程约定）、§4.6（CI/CD） |
| 适用范围 | 所有进入 `main` 的变更 | | 适用范围 | 所有直接推送到 `main` 的提交 |
| 强制级别 | 强制 | | 强制级别 | 强制 |
--- ---
## 1　PR 描述模板（缺项即打回） ## 1　提交说明模板（缺项不推送）
> 仓库仅保留 `main`，不再创建 PR。将下列模板写入提交说明正文（`git commit -m "type(scope): 标题" -m "背景…"`），Review 基于待推送的本地 diff 完成。
```markdown ```markdown
## 背景 ## 背景
@@ -32,15 +34,17 @@
- 迁移在 staging 的执行结果 - 迁移在 staging 的执行结果
``` ```
- `PR-01` 标题遵循 Conventional Commits 且**用中文**（Squash 时以 PR 标题为准，`scope` 保留英文，写法见 [01](01-Git规范.md) §2）。 - `CR-01` 提交标题遵循 Conventional Commits 且**用中文**（`scope` 保留英文，写法见 [01](01-Git规范.md) §2）。
- `PR-02` 变更 ≤ 400 行（不含 lock / 生成代码）；超出拆分为多个 PR 并在描述写依赖顺序。 - `CR-02` 单次提交变更 ≤ 400 行（不含 lock / 生成代码）；超出拆为多个提交，并在说明写依赖顺序。
- `PR-03` 禁止在功能 PR 中混入无关重构、格式化、依赖升级。 - `CR-03` 禁止在功能提交中混入无关重构、格式化、依赖升级。
- `PR-04` Draft PR 可用于早期讨论，但**不得**在 CI 未绿时请求 Review。 - `CR-04` 本地门禁未全绿**不得**推送；高风险变更未完成走查不得推送。
--- ---
## 2　Review 分工 ## 2　Review 分工
> 无远程分支，Review 对象为待推送的本地提交（`git diff origin/main...HEAD`）；高风险变更须在推送前完成双人走查。
| 变更类型 | 要求 | | 变更类型 | 要求 |
| --- | --- | | --- | --- |
| 普通业务代码 | ≥ 1 名同模块 Owner | | 普通业务代码 | ≥ 1 名同模块 Owner |
@@ -51,9 +55,9 @@
| 发布配置 / CI / 基础设施 | **2 人**（含运维） | | 发布配置 / CI / 基础设施 | **2 人**（含运维） |
| 仅文档 | 1 人（可为作者同组） | | 仅文档 | 1 人（可为作者同组） |
- `PR-05` 作者不得自我批准；禁止「LGTM」式无内容批准。 - `CR-05` 作者不得自我批准；禁止「LGTM」式无内容批准。
- `PR-06` 首轮 Review 时效 24 小时内；作者负责推动，超过 48 小时升级到模块负责人。 - `CR-06` 推送前 Review 时效 24 小时内；紧急变更允许推送后 24 小时内补走查，须在提交说明记录。
- `PR-07` Review 意见分「必须改（blocking）/ 建议（non-blocking）」，作者逐条回复；未解决不得合并。 - `CR-07` Review 意见分「必须改（blocking）/ 建议（non-blocking）」，作者逐条回复；blocking 未解决不得推送。
--- ---
@@ -93,11 +97,11 @@
--- ---
## 4　DoD（合并即完成的定义） ## 4　DoD（推送即完成的定义）
同时满足才可合并： 同时满足才可推送：
1. CI 全绿（含契约与集成），无豁免。 1. 本地门禁全绿；推送后 CI 全绿（含契约与集成），无豁免。
2. Review 通过，blocking 意见全部解决。 2. Review 通过，blocking 意见全部解决。
3. 文档同步：PRD 规则编号、技术架构、OpenAPI、本目录细则（如涉及）。 3. 文档同步：PRD 规则编号、技术架构、OpenAPI、本目录细则（如涉及）。
4. 迁移可回滚，或在描述说明为何不可回滚与前向修复方案。 4. 迁移可回滚，或在描述说明为何不可回滚与前向修复方案。
@@ -106,20 +110,18 @@
--- ---
## 5　合并与合并后 ## 5　推送与推送后
- `PR-08` 统一 **Squash Merge**，提交信息用 PR 标题 + 描述要点。 - `CR-08` 推送前完成本地门禁（`format:check` / `lint` / `typecheck` / `test`）；推送即进入主干，不再有 Squash 合并环节。
- `PR-09` 合并后删除分支；关注 CI 与错误率 15 分钟。 - `CR-09` 直接 `git push origin main`；禁止 force push、禁止 Merge commit；推送后 15 分钟内确认 CI 与错误率。
- `PR-10` 合并后发现缺陷：优先前向修复；影响面大则按回滚预案执行，并补一次复盘（写 `docs/releases/` 或 issue）。 - `CR-10` 推送后发现缺陷：优先以新提交前向修复；影响面大时按回滚预案执行（回滚也用新提交，不回写历史），并补一次复盘（写 `docs/releases/` 或 issue）。
- `PR-11` 禁止「合并后再补测试 / 再补文档」作为常态；确因紧急修复，须 24 小时内补齐并在 PR 记录追踪链接。 - `CR-11` 禁止「先推后补测试 / 补文档」作为常态；紧急修复须 24 小时内以新提交补齐，并在提交说明记录。
--- ## 6　反模式（走查直接打回）
## 6　反模式（Review 直接打回）
| 反模式 | 原因 | | 反模式 | 原因 |
| --- | --- | | --- | --- |
| 巨型 PR（> 800 行） | 无法有效 Review，缺陷率高 | | 巨型提交（> 800 行） | 无法有效 Review，缺陷率高 |
| 「顺手」重构无关模块 | 混淆影响面，增加回滚难度 | | 「顺手」重构无关模块 | 混淆影响面，增加回滚难度 |
| 用 `any` / `@ts-ignore` 绕过类型 | 把问题推到运行时 | | 用 `any` / `@ts-ignore` 绕过类型 | 把问题推到运行时 |
| 在 Controller 写业务规则 | 破坏分层，无法复用与测试 | | 在 Controller 写业务规则 | 破坏分层，无法复用与测试 |
docs/工程规范/README.md
+5 -5
View File
@@ -5,13 +5,13 @@
| 编号 | 文档 | 覆盖范围 | 强制级别 | | 编号 | 文档 | 覆盖范围 | 强制级别 |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| 01 | [Git 规范](01-Git规范.md) | 分支模型、提交信息、合并与发布、Tag、大文件 | 强制 | | 01 | [Git 规范](01-Git规范.md) | main 直推、提交信息、推送与发布、Tag、大文件 | 强制 |
| 02 | [代码风格](02-代码风格.md) | 命名、类型、错误处理、异步、React、注释、导入顺序 | 强制 | | 02 | [代码风格](02-代码风格.md) | 命名、类型、错误处理、异步、React、注释、导入顺序 | 强制 |
| 03 | [格式化与 Lint](03-格式化与Lint.md) | Prettier / ESLint 配置、钩子、CI 门禁、豁免流程 | 强制 | | 03 | [格式化与 Lint](03-格式化与Lint.md) | Prettier / ESLint 配置、钩子、CI 门禁、豁免流程 | 强制 |
| 04 | [API 与路由规范](04-API与路由规范.md) | REST、版本、错误码、鉴权链、任务协议、上传下载、前端路由 | 强制 | | 04 | [API 与路由规范](04-API与路由规范.md) | REST、版本、错误码、鉴权链、任务协议、上传下载、前端路由 | 强制 |
| 05 | [数据库规范](05-数据库规范.md) | 命名、主键、客户隔离、索引、迁移、事务、保留期 | 强制 | | 05 | [数据库规范](05-数据库规范.md) | 命名、主键、客户隔离、索引、迁移、事务、保留期 | 强制 |
| 06 | [测试与 CI 规范](06-测试与CI规范.md) | 分层测试、必测清单、门禁、发布与回滚 | 强制 | | 06 | [测试与 CI 规范](06-测试与CI规范.md) | 分层测试、必测清单、门禁、发布与回滚 | 强制 |
| 07 | [Code Review 与 PR 规范](07-CodeReview与PR规范.md) | PR 模板、双人场景、Review 清单、DoD | 强制 | | 07 | [Code Review 规范](07-CodeReview与PR规范.md) | 提交说明、双人场景、Review 清单、DoD | 强制 |
| 08 | [日志与可观测性规范](08-日志与可观测性规范.md) | 日志字段、trace、审计、指标、告警 | 强制 | | 08 | [日志与可观测性规范](08-日志与可观测性规范.md) | 日志字段、trace、审计、指标、告警 | 强制 |
| 09 | [环境变量与密钥规范](09-环境变量与密钥规范.md) | env 命名、校验、密钥管理、轮换、泄露处置 | 强制 | | 09 | [环境变量与密钥规范](09-环境变量与密钥规范.md) | env 命名、校验、密钥管理、轮换、泄露处置 | 强制 |
| 10 | [资产命名与 PSD 图层规范](10-资产命名与PSD图层规范.md) | 资产归属、命名占位符、图层前缀、规格矩阵、低质量标记 | 强制 | | 10 | [资产命名与 PSD 图层规范](10-资产命名与PSD图层规范.md) | 资产归属、命名占位符、图层前缀、规格矩阵、低质量标记 | 强制 |
@@ -20,13 +20,13 @@
| 项 | 约定 | | 项 | 约定 |
| --- | --- | | --- | --- |
| 编写语言 | 中文说明 + 英文标识符 / 命令 / 路径；**Git 提交信息与 PR 标题也用中文**（见 [01](01-Git规范.md) §2） | | 编写语言 | 中文说明 + 英文标识符 / 命令 / 路径；**Git 提交信息也用中文**（见 [01](01-Git规范.md) §2） |
| 结构 | 作用与边界 → 规则（表格 / 编号）→ 检查清单 → 违规示例 | | 结构 | 作用与边界 → 规则（表格 / 编号）→ 检查清单 → 违规示例 |
| 变更 | 修改规则须单独 PR，说明「为什么改」+「存量代码如何处理」 | | 变更 | 修改规则须单独提交，说明「为什么改」+「存量代码如何处理」 |
| 版本 | `V<主>.<次>`；主版本 = 破坏性（存量代码需整改），次版本 = 补充 | | 版本 | `V<主>.<次>`；主版本 = 破坏性（存量代码需整改），次版本 = 补充 |
| 冲突 | 与本目录细则冲突时以技术架构为准；技术架构未覆盖以 PRD 为准 | | 冲突 | 与本目录细则冲突时以技术架构为准；技术架构未覆盖以 PRD 为准 |
| 有效性 | 规则必须可被检查（lint / CI / review 清单 / 脚本），否则降为「建议」 | | 有效性 | 规则必须可被检查（lint / CI / review 清单 / 脚本），否则降为「建议」 |
| 废止 | 删除规则必须在 PR 描述里写清理计划，禁止直接删条目 | | 废止 | 删除规则必须在提交说明里写清理计划，禁止直接删条目 |
## 与总纲的关系 ## 与总纲的关系