refactor: 重写 Git hooks 体系，委托已有检查、新增模板与 LFS 校验

pre-commit 代码检查改为委托 _backend-lint / _versionctl-lint / _frontend-check，新增 LFS 指针校验；commit-msg 新增多行空行格式校验和模板注释忽略，移除 CJK/Python 字符集检测；新增 prepare-commit-msg 提交信息模板；hooks-install 增加 source 文件存在性校验；前端 check 补入 tsc -b 类型检查并修复暴露的类型错误
2026-05-06 13:44:28 +08:00
parent 5513f0c13d
commit c04a13bf8a
13 changed files with 443 additions and 111 deletions
--- a/openspec/specs/frontend-lint-rules/spec.md
+++ b/openspec/specs/frontend-lint-rules/spec.md
@@ -49,13 +49,14 @@ TBD - 定义前端 ESLint 规则配置、构建集成 lint 检查、以及自定

 ### Requirement: 构建集成 lint 检查

-前端 SHALL 在 `build` 命令中集成 ESLint 检查和 Prettier 格式检查。
+前端 SHALL 在 `build` 命令中集成 TypeScript 类型检查、ESLint 检查和 Prettier 格式检查。

-#### Scenario: 构建时执行 lint 和格式检查
+#### Scenario: 构建时执行类型检查、lint 和格式检查

 - **WHEN** 执行 `bun run build`
- **THEN** 构建 SHALL 依次执行 `tsc -b`、`bun run check`、`vite build`
- **THEN** `bun run check` SHALL 执行 `bun run lint && bun run format:check`
+- **THEN** 构建 SHALL 依次执行 `bun run check`、`vite build`
+- **THEN** `bun run check` SHALL 依次执行 `bun run typecheck`、`bun run lint`、`bun run format:check`
+- **THEN** 若 `tsc -b` 报告类型错误，构建 SHALL 中断
 - **THEN** 若 `eslint .` 报告任何错误，构建 SHALL 中断
 - **THEN** 若 `prettier --check .` 报告任何格式问题，构建 SHALL 中断

@@ -77,8 +78,13 @@ TBD - 定义前端 ESLint 规则配置、构建集成 lint 检查、以及自定
 #### Scenario: 统一检查命令

 - **WHEN** 执行 `bun run check`
- **THEN** SHALL 运行 `bun run lint && bun run format:check`
- **THEN** lint 错误和格式问题 SHALL 都被检查
+- **THEN** SHALL 依次运行 `bun run typecheck`、`bun run lint`、`bun run format:check`
+- **THEN** 类型错误、lint 错误和格式问题 SHALL 都被检查
+
+#### Scenario: 单独执行类型检查
+
+- **WHEN** 执行 `bun run typecheck`
+- **THEN** SHALL 运行 `tsc -b`

 #### Scenario: 统一修复命令

--- a/openspec/specs/git-hooks/spec.md
+++ b/openspec/specs/git-hooks/spec.md
@@ -8,12 +8,33 @@

 ### Requirement: pre-commit hook 快速检查

-pre-commit hook SHALL 在 `git commit` 执行前对 staged files 进行快速检查，仅检查本次提交涉及的文件。
+pre-commit hook SHALL 在 `git commit` 执行前对 staged files 进行快速检查。非代码检查（冲突标记、大文件告警、LFS 指针）SHALL 在 `_hooks-pre-commit` 中直接实现；代码检查（Go 后端、Go versionctl、前端）SHALL 根据 staged 文件类型有条件地委托给已有 Makefile target（`_backend-lint`、`_versionctl-lint`、`_frontend-check`），不再内联独立的 lint 命令。

-#### Scenario: 无 Go 和前端文件变更时跳过
+#### Scenario: 无 Go 和前端文件变更时跳过代码检查

 - **WHEN** staged files 中既无 `.go` 文件也无 `.ts`/`.tsx`/`.scss` 文件
- **THEN** pre-commit hook SHALL 直接通过，不运行任何 linter
+- **THEN** pre-commit hook SHALL 跳过代码检查委托，仅执行非代码检查
+
+#### Scenario: Go 文件变更时委托后端 lint
+
+- **WHEN** staged files 中包含 `backend/*.go` 文件
+- **THEN** pre-commit hook SHALL 委托 `_backend-lint` target 进行 Go 代码检查
+- **THEN** `_backend-lint` SHALL 复用 `backend/.golangci.yml` 配置
+- **THEN** 若 lint 报告任何错误，commit SHALL 被阻止
+
+#### Scenario: versionctl Go 文件变更时委托 versionctl lint
+
+- **WHEN** staged files 中包含 `versionctl/*.go` 文件
+- **THEN** pre-commit hook SHALL 委托 `_versionctl-lint` target 进行 Go 代码检查
+- **THEN** `_versionctl-lint` SHALL 复用 `versionctl/.golangci.yml` 配置
+- **THEN** 若 lint 报告任何错误，commit SHALL 被阻止
+
+#### Scenario: 前端文件变更时委托前端检查
+
+- **WHEN** staged files 中包含 `.ts`、`.tsx` 或 `.scss` 文件
+- **THEN** pre-commit hook SHALL 委托 `_frontend-check` target 进行前端代码检查
+- **THEN** `_frontend-check` SHALL 运行 `bun run check`（包含 `tsc -b` TypeScript 类型检查、ESLint 和 Prettier 格式检查）
+- **THEN** 若检查报告任何错误，commit SHALL 被阻止

 #### Scenario: 冲突标记检测

@@ -21,37 +42,26 @@ pre-commit hook SHALL 在 `git commit` 执行前对 staged files 进行快速检
 - **THEN** pre-commit hook SHALL 报告错误并列出包含冲突的文件名
 - **THEN** commit SHALL 被阻止

-#### Scenario: Go 文件 lint 检查
-
- **WHEN** staged files 中包含 `.go` 文件
- **THEN** pre-commit hook SHALL 对 staged `.go` 文件运行 `golangci-lint run`（复用 `backend/.golangci.yml` 配置）
- **THEN** 若 lint 报告任何错误，commit SHALL 被阻止
-
-#### Scenario: 前端文件 lint 检查
-
- **WHEN** staged files 中包含 `.ts` 或 `.tsx` 文件
- **THEN** pre-commit hook SHALL 对 staged 前端文件运行 ESLint（复用 `frontend/eslint.config.js` 配置）
- **THEN** 若 ESLint 报告任何错误，commit SHALL 被阻止
-
-#### Scenario: 前端文件格式检查
-
- **WHEN** staged files 中包含 `.ts`、`.tsx` 或 `.scss` 文件
- **THEN** pre-commit hook SHALL 对 staged 前端文件运行 Prettier 格式检查（复用 `frontend/.prettierrc` 配置）
- **THEN** 若存在格式不符合规范的文件，commit SHALL 被阻止
-
 #### Scenario: 大文件告警

 - **WHEN** staged files 中存在超过 500KB 的文本文件
 - **THEN** pre-commit hook SHALL 输出警告信息（不阻止提交），提示检查是否误提交

+#### Scenario: LFS 指针校验
+
+- **WHEN** staged files 匹配 `.gitattributes` 中 `filter=lfs` 的路径模式
+- **THEN** pre-commit hook SHALL 检查 staged 内容是否为 LFS 指针格式（`version https://git-lfs.github.com/spec/v1`）
+- **THEN** 若内容不是 LFS 指针格式，commit SHALL 被阻止，并提示安装 git-lfs
+- **THEN** 若 staged files 不匹配任何 `filter=lfs` 路径模式，SHALL 跳过此检查
+
 #### Scenario: commit 被阻止时显示修复提示

 - **WHEN** pre-commit hook 检查失败
- **THEN** hook SHALL 输出明确的修复提示（如 `bun run fix`、手动解决冲突标记等）
+- **THEN** hook SHALL 输出明确的修复提示（如 `make lint` 修复代码问题、手动解决冲突标记等）

 ### Requirement: commit-msg hook 校验提交信息格式

-commit-msg hook SHALL 在 `git commit` 输入提交信息后校验格式，确保符合项目规范。提交描述 SHALL 使用中文；版本号、英文专有名词可与中文描述混用。
+commit-msg hook SHALL 在 `git commit` 输入提交信息后校验格式，确保首行符合项目规范。提交描述按项目规范应使用中文，但 hook SHALL NOT 通过 Python/CJK 字符集检测强制判断描述语言，以避免引入新的运行时依赖。

 #### Scenario: 合法格式通过

@@ -63,12 +73,6 @@ commit-msg hook SHALL 在 `git commit` 输入提交信息后校验格式，确
 - **WHEN** 提交信息首行使用的类型不在允许列表中（如 `update: xxx`）
 - **THEN** commit-msg hook SHALL 报告错误，显示允许的类型列表，commit SHALL 被阻止

-#### Scenario: 英文描述被拒绝
-
- **WHEN** 提交信息首行为 `feat: add auth`
- **THEN** commit-msg hook SHALL 报告错误，提示提交描述需使用中文
- **THEN** commit SHALL 被阻止
-
 #### Scenario: 缺少冒号空格被拒绝

 - **WHEN** 提交信息首行为 `feat:xxx`（冒号后无空格）或 `feat xxx`
@@ -89,16 +93,35 @@ commit-msg hook SHALL 在 `git commit` 输入提交信息后校验格式，确
 - **WHEN** commit-msg hook 检查失败
 - **THEN** hook SHALL 输出包含正确格式示例的错误信息（如 `feat: 添加供应商批量管理功能`）

+#### Scenario: 不执行字符集检测
+
+- **WHEN** 提交信息首行格式合法且类型合法，但描述部分不包含 CJK 字符（如 `feat: add hook tests`）
+- **THEN** commit-msg hook SHALL 通过
+- **THEN** hook SHALL NOT 调用 `python3` 或其他额外运行时做 Unicode/CJK 检测
+
+#### Scenario: 多行格式校验
+
+- **WHEN** 提交信息忽略 `#` 注释行后，第三行及之后存在任一非空详细说明行
+- **THEN** commit-msg hook SHALL 检查第二行是否为空行
+- **THEN** 若第二行非空行，commit SHALL 被阻止，提示首行后应空行再写详细描述
+
+#### Scenario: 模板注释不参与校验
+
+- **WHEN** 提交信息文件中包含 prepare-commit-msg 写入的 `#` 注释模板
+- **THEN** commit-msg hook SHALL 忽略这些注释行
+- **THEN** 注释行 SHALL NOT 导致首行格式、多行空行分隔校验失败
+
 ### Requirement: hooks-install 安装命令

 `make hooks-install` SHALL 将 `scripts/git-hooks/` 下的 hook 脚本安装到 `.git/hooks/`，不覆盖 Git LFS 管理的 hook。

-#### Scenario: 安装 pre-commit 和 commit-msg
+#### Scenario: 安装所有 hook 脚本

 - **WHEN** 执行 `make hooks-install`
 - **THEN** `scripts/git-hooks/pre-commit` SHALL 被复制到 `.git/hooks/pre-commit`
 - **THEN** `scripts/git-hooks/commit-msg` SHALL 被复制到 `.git/hooks/commit-msg`
- **THEN** 两个文件 SHALL 被设置为可执行（`chmod +x`）
+- **THEN** `scripts/git-hooks/prepare-commit-msg` SHALL 被复制到 `.git/hooks/prepare-commit-msg`
+- **THEN** 所有复制文件 SHALL 被设置为可执行（`chmod +x`）

 #### Scenario: 不覆盖 LFS 管理的 hook

@@ -113,9 +136,15 @@ commit-msg hook SHALL 在 `git commit` 输入提交信息后校验格式，确
 #### Scenario: hooks-check 验证安装状态

 - **WHEN** 执行 `make hooks-check`
- **THEN** 命令 SHALL 检查 `.git/hooks/pre-commit` 和 `.git/hooks/commit-msg` 是否存在且可执行
+- **THEN** 命令 SHALL 检查 `.git/hooks/pre-commit`、`.git/hooks/commit-msg`、`.git/hooks/prepare-commit-msg` 是否存在且可执行
 - **THEN** SHALL 输出每个 hook 的安装状态

+#### Scenario: 安装前验证 source 文件存在
+
+- **WHEN** 执行 `make hooks-install`
+- **THEN** 命令 SHALL 在复制前验证每个 source 文件（`scripts/git-hooks/<hook-name>`）是否存在
+- **THEN** 若 source 文件不存在，命令 SHALL 报告错误并返回非零退出码
+
 ### Requirement: hooks-test 回归测试命令

 `make hooks-test` SHALL 运行仓库内 hook 回归测试，覆盖 commit-msg 格式校验和 pre-commit staged-file 检查，不污染真实 git index。
@@ -146,19 +175,19 @@ pre-commit 和 commit-msg hook 脚本 SHALL 可在 macOS 和 Windows（Git Bash

 ### Requirement: pre-commit 核心逻辑在 Makefile 中复用

-pre-commit hook 的检查逻辑 SHALL 通过 Makefile target 调用项目已有工具链，不重复实现 hook 框架逻辑。commit-msg hook SHALL 在脚本内直接完成格式校验。
+pre-commit hook 的检查逻辑 SHALL 通过 Makefile target 调用项目已有工具链，不重复实现。非代码检查（冲突标记、大文件、LFS 指针）SHALL 在 `_hooks-pre-commit` 中直接实现；代码检查 SHALL 委托 `_backend-lint`、`_versionctl-lint`、`_frontend-check` target。

-#### Scenario: Go lint 复用后端配置
+#### Scenario: Go lint 委托后端 lint target

 - **WHEN** pre-commit 需要检查 Go 文件
- **THEN** SHALL 调用 Makefile 逻辑，在 `backend/` 目录对 staged `.go` 文件运行 `go tool golangci-lint run`
- **THEN** SHALL 复用 `backend/.golangci.yml` 中的 lint 配置
+- **THEN** SHALL 委托 `_backend-lint` 或 `_versionctl-lint` target（根据文件路径 `backend/` vs `versionctl/`）
+- **THEN** SHALL NOT 在 `_hooks-pre-commit` 中内联 `golangci-lint` 命令

-#### Scenario: 前端 lint 使用 staged 文件参数
+#### Scenario: 前端检查委托前端 check target

 - **WHEN** pre-commit 需要检查前端文件
- **THEN** SHALL 调用 Makefile 逻辑，在 `frontend/` 目录对 staged 前端文件运行 ESLint 和 Prettier 的文件参数模式
- **THEN** SHALL NOT 在 pre-commit 阶段运行全量 `bun run check`
+- **THEN** SHALL 委托 `_frontend-check` target
+- **THEN** SHALL NOT 在 `_hooks-pre-commit` 中内联 `eslint` 或 `prettier` 命令

 #### Scenario: 终端直接调试

--- a/openspec/specs/prepare-commit-msg-hook/spec.md
+++ b/openspec/specs/prepare-commit-msg-hook/spec.md
@@ -0,0 +1,57 @@
+# prepare-commit-msg-hook
+
+## Purpose
+
+定义 prepare-commit-msg Git hook，在 `git commit` 编辑器打开时为开发者提供提交信息模板。
+
+## Requirements
+
+### Requirement: prepare-commit-msg hook 提供提交信息模板
+
+prepare-commit-msg hook SHALL 在 `git commit` 打开编辑器时，将规范格式的提交信息模板预填充到提交信息文件中，辅助开发者编写符合项目规范的多行提交信息。
+
+#### Scenario: 模板预填充到提交信息文件
+
+- **WHEN** `git commit` 被执行且编辑器打开提交信息文件
+- **THEN** prepare-commit-msg hook SHALL 在提交信息文件中写入模板内容
+- **THEN** 模板 SHALL 包含注释行（以 `#` 开头）引导开发者填写规范格式
+
+#### Scenario: 模板包含格式引导
+
+- **WHEN** 模板被写入提交信息文件
+- **THEN** 模板 SHALL 包含首行格式提示：`# <类型>: <简短中文描述>`
+- **THEN** 模板 SHALL 包含空行占位符
+- **THEN** 模板 SHALL 包含详细描述区：`# <详细说明>`
+- **THEN** 模板 SHALL 列出可用类型：`feat / fix / refactor / docs / style / test / chore`
+- **THEN** 模板 SHALL 包含示例：`feat: 添加供应商批量管理功能`
+
+#### Scenario: 注释行不被提交
+
+- **WHEN** 用户在编辑器中基于模板填写提交信息并保存
+- **THEN** 以 `#` 开头的模板注释行 SHALL 被 Git 作为注释过滤，不会成为提交信息的一部分
+
+#### Scenario: 已有提交信息时跳过
+
+- **WHEN** 提交信息文件已包含非注释内容（如 `-m` 参数指定、`git commit --amend`、merge commit、cherry-pick）
+- **THEN** prepare-commit-msg hook SHALL NOT 覆盖已有内容，直接退出
+
+#### Scenario: Git 默认注释不阻止模板写入
+
+- **WHEN** 提交信息文件只包含空行或 Git 默认生成的 `#` 注释行
+- **THEN** prepare-commit-msg hook SHALL 将其视为没有已有提交信息
+- **THEN** hook SHALL 在文件顶部写入模板，并保留 Git 原有注释内容
+
+### Requirement: 通过 hooks-install 安装
+
+prepare-commit-msg hook SHALL 随 `make hooks-install` 一起安装到 `.git/hooks/`。
+
+#### Scenario: 安装 prepare-commit-msg
+
+- **WHEN** 执行 `make hooks-install`
+- **THEN** `scripts/git-hooks/prepare-commit-msg` SHALL 被复制到 `.git/hooks/prepare-commit-msg`
+- **THEN** 该文件 SHALL 被设置为可执行（`chmod +x`）
+
+#### Scenario: hooks-check 验证安装状态
+
+- **WHEN** 执行 `make hooks-check`
+- **THEN** 命令 SHALL 检查 `.git/hooks/prepare-commit-msg` 是否存在且可执行
--- a/openspec/specs/prettier-formatting/spec.md
+++ b/openspec/specs/prettier-formatting/spec.md
@@ -189,7 +189,8 @@

 - `format = "prettier --write ."` — 格式化所有文件
 - `format:check = "prettier --check ."` — 检查文件格式
- `check = "bun run lint && bun run format:check"` — 检查 lint 和格式
+- `typecheck = "tsc -b"` — TypeScript 类型检查
+- `check = "bun run typecheck && bun run lint && bun run format:check"` — 检查类型、lint 和格式
 - `fix = "bun run lint:fix && bun run format"` — 修复 lint 问题并格式化

 #### Scenario: 运行格式化命令
@@ -207,8 +208,14 @@
 #### Scenario: 运行统一检查命令

 - **WHEN** 执行 `bun run check`
- **THEN** SHALL 运行 `bun run lint && bun run format:check`
- **THEN** lint 错误和格式问题 SHALL 都被检查
+- **THEN** SHALL 依次运行 `bun run typecheck`、`bun run lint`、`bun run format:check`
+- **THEN** TypeScript 类型错误、lint 错误和格式问题 SHALL 都被检查
+
+#### Scenario: 运行类型检查命令
+
+- **WHEN** 执行 `bun run typecheck`
+- **THEN** SHALL 运行 `tsc -b`
+- **THEN** TypeScript 类型错误 SHALL 报告错误

 #### Scenario: 运行统一修复命令