Stev_Wang
c90a036f82
背景：远端自建 Gitea 未部署 Actions runner，推送后线上 CI 无法执行；原规范仍要求「推送后确认 CI」，容易误以为需等待远端流水线。 改动： - AGENTS §6/§7：CI 只本地执行，推送前必须 pnpm ci:local 或本地门禁全绿，禁止等待/依赖远端 CI。 - 06-测试与CI规范 V1.1：新增「本地 CI 流水线（远端不跑 CI）」强制规则；集成/契约运行时机改为推送前本地。 - 01-Git规范 / 07-CodeReview：删除「推送后确认 CI」，改为本地门禁后推送。 - README：明确远端无 runner，ci.yml 仅本地参考/手动触发。 - .gitea/workflows/ci.yml：去掉 push 触发，仅保留 workflow_dispatch，避免推送停留在 queued。 影响面：仅规范与工作流配置，不影响代码/数据。 验证：pnpm format:check / lint 通过；pnpm ci:local 全部门禁通过（237.2s，4 e2e 冒烟 passed，8 个门控用例按环境变量跳过）。
6.5 KiB
6.5 KiB
01 · Git 规范
| 项 | 内容 |
|---|---|
| 文档版本 | V1.1（2026-11-02） |
| 依据 | 技术架构 §4.6（CI/CD）、§10.1（仓库结构） |
| 适用范围 | 全仓库（代码、文档、配置、迁移） |
| 强制级别 | 强制 |
1 分支模型
采用 仅 main 直推：仓库只保留 main 一条分支，不建 develop、release、feat/*、docs/* 等任何本地或远程分支。
| 类型 | 名称 | 用途 | 生命周期 |
|---|---|---|---|
| 主干 | main |
唯一长期分支，始终可发布 | 永久 |
规则：
GIT-01所有提交直接基于最新main；提交前先git pull --ff-only，避免落后。GIT-02禁止创建并推送任何非main分支；确需本地验证时可临时创建，但不得推送，完成后立即删除。GIT-03允许直接 pushmain；推送前必须通过本地门禁（format:check、lint、typecheck、test，完整链路用pnpm ci:local）。远端 Gitea 未部署 runner，线上 CI 不可用，推送后不等待远端 CI。GIT-04禁止 force pushmain；禁止 Merge commit；main必须保持线性。
2 提交信息（Conventional Commits 1.0）
<type>(<scope>): <中文简述>
<body：中文，说明为什么改 + 影响面 / 回滚方式>
<footer：BREAKING CHANGE / Refs: R-xx / Closes #12>
type |
用途 |
|---|---|
feat |
新功能 |
fix |
缺陷修复 |
docs |
文档 |
style |
仅格式（不影响逻辑） |
refactor |
重构（不改行为） |
perf |
性能 |
test |
测试 |
build |
构建 / 依赖 |
ci |
CI / 脚本 |
chore |
杂项 |
revert |
回滚 |
规则：
GIT-05提交信息（subject+ 正文）一律使用中文；type/scope保留英文小写。subject用祈使句（「新增 …」而非「新增了 …」「新增的 …」），≤ 50 个汉字且整行 ≤ 72 字符，不加句末标点（英文.与中文。均禁止）。GIT-06scope必填，取值见GIT-01。GIT-07正文说明「为什么」与「影响面 / 回滚方式」；纯重命名类可仅一行 subject。GIT-08破坏性变更：type后加!且 footer 写BREAKING CHANGE: <说明与迁移方式>。GIT-09关联业务规则写Refs: R-04；关联 issue 写Closes #123。GIT-10一个提交只做一件事；禁止在功能提交里顺带格式化无关文件。GIT-11禁止WIP、fix bug、update等无信息量信息；禁止--no-verify绕过钩子。
示例：
feat(media): 图片批次支持按规格矩阵展开任务项
批量生产原先按「模板 × 商品图」展开，导致同素材多规格重复建素材，
违反 PRD R-25「素材为主对象、规格为属性」。改为展开到 task_item，
规格作为属性写入 material_specs。
影响面：production_tasks 新增 spec_key 列（expand 迁移，兼容旧数据）。
回滚方式：关闭 FEATURE_MATRIX_SPEC 开关，旧路径仍可用。
Refs: R-25
2.1 中文书写与中英混排（GIT-21 ~ GIT-23）
GIT-21中文与英文 / 数字之间加一个空格（新增 PRD V1.6、导出 50 张图）；标点用中文全角；代码、命令、文件名、版本号、错误码用反引号包裹并保留原文。GIT-22术语沿用 PRD 附录 C 术语表，禁止自造同义词（「素材规格」不写「素材尺寸」，「要素卡」不写「简报卡」）。GIT-23禁止 Chinglish 与无信息缩写：不写add 功能 for batch、opt、tmp、misc、update；type/scope之外的英文只能是专有名词、标识符或引用编号。
2.2 commitlint 配置要点
中文提交信息有三个坑，必须在 commitlint.config.mjs 中显式处理，否则校验形同无效：
export default {
extends: ['@commitlint/config-conventional'],
rules: {
'subject-case': [0], // 中文无大小写概念，关闭该规则
'header-max-length': [2, 'always', 72], // 按字符计，中文每个字计 1
'subject-full-stop': [2, 'never', '。'], // 拦截中文句号
'subject-empty': [2, 'never'],
},
};
对应的 husky
commit-msg钩子见 03-格式化与Lint §4。
3 提交、推送与 Review
GIT-12直接推送到main的提交即主干提交，提交信息按 §2 执行。GIT-13禁止 Merge commit 等分支合并方式；一次提交只做一件事，main保持线性。GIT-14单个提交变更 ≤ 400 行（含测试，不含 lock 与生成代码）；里程碑批次超出须在提交说明注明原因与拆分计划。GIT-15禁止 force pushmain；已推送提交不回改写，修复一律用新提交前向修复。GIT-16Review 要求见 07-CodeReview与PR规范：高风险变更推送前完成双人走查，普通变更至少自查并在推送后 24 小时内走查。
4 Tag 与发布
| 项 | 规则 |
|---|---|
| 版本号 | 语义化 v<主>.<次>.<补> |
| 打 Tag 时机 | 生产发布前，由发布负责人在 main 打 annotated tag |
| 里程碑 Tag | m0 / m1 / m2…（对应 PRD 分期），仅标记不进版本链 |
| 发布记录 | 每个 Tag 必须写变更摘要（可复用提交标题集合） |
| 回滚 | 回滚用新 Tag（v1.2.1 回滚 v1.2.0 内容），禁止删除已发布 Tag |
5 大文件与二进制
GIT-17禁止入库 > 10 MB 的二进制（PSD 模板、成片、视频、字体包），一律走对象存储；确需入库（如开源字体）用 Git LFS 并在提交说明。GIT-18禁止入库：.env*、密钥、证书私钥、构建产物、node_modules/、日志、项目参考/。GIT-19pnpm-lock.yaml必须提交且与package.json同步；禁止手工编辑 lock 文件。GIT-20误提交敏感信息：立即轮换密钥 → 用git filter-repo清理历史 → 全员重新 clone → 记录复盘。
6 检查清单（提交前 / 推送前）
- 提交基于最新
main，已同步远端 - 提交信息为中文且符合 Conventional Commits（含
scope），subject 无句末标点 - 提交粒度单一，无无关文件
- 无
.env/ 密钥 / 大文件 - 提交说明含背景 / 影响面 / 回滚方式 / 验证证据
- 本地门禁全绿（必要时
pnpm ci:local），已 pushmain；远端无 CI，无需等待