comment-review/reports/zhgl-zhgl-front.md

Comment Review Spec (scan)

• repo: C:\Development\Code\zhgl\zhgl-front
• rules: project (C:\Development\Code\zhgl\zhgl-front.commentreview\rule.json)
• files: 315 | comments: 2873 | candidates: 12
• severity: P0=2 P1=10 P2=0 INFO=0

Comment Rule Group 1: system / **

Applies to:

• src\lang\en_US.ts
• src\lang\zh_CN.ts
• src\store\modules\permission.ts
• src\types\vue-office.d.ts

Content

注释通用质量（内置规则）

注释只回答三问：是什么（作用域/职责）、受何约束（业务规则、前提、坑）、行为是什么（非显然的行为说明）。

禁止（过程叙述，git 提交消息的职责）

• 日期戳、迭代/阶段编号（阶段 3、第二阶段、Phase N）、文档版本号
• 版本演变起点（"v2.1 起…"）→ 改写为当前结构语义
• 实测/性能回忆（"实测 594s 挂死"）、"曾在某环境"类环境记忆
• 提交溯源（commit hash）、来源仓、评审编号引用（R6 修正）
• 历史因果词（曾致/曾被/早期版本误用/迁移期教训/取代原先/反哺）
• 悬空引用：引用仓库中不存在的文档/文件/章节 → 删除引用

豁免（合法保留，勿误杀）

• 引用真实存在的带日期文档，按实际文件名保留（改名会伪造记录）
• 数据/行为事实：动画时长、menu_id、数据版本字段、SQL 日期字面量
• 环境频率现状描述（"偶发超过 15s"支撑超时取值）= 现状约束
• vendor/第三方文件注释不动

Comment Rule Group 2: project / src/utils/**

Applies to:

• src\utils\notification.ts

Content

注释通用质量（内置规则）

注释只回答三问：是什么（作用域/职责）、受何约束（业务规则、前提、坑）、行为是什么（非显然的行为说明）。

禁止（过程叙述，git 提交消息的职责）

• 日期戳、迭代/阶段编号（阶段 3、第二阶段、Phase N）、文档版本号
• 版本演变起点（"v2.1 起…"）→ 改写为当前结构语义
• 实测/性能回忆（"实测 594s 挂死"）、"曾在某环境"类环境记忆
• 提交溯源（commit hash）、来源仓、评审编号引用（R6 修正）
• 历史因果词（曾致/曾被/早期版本误用/迁移期教训/取代原先/反哺）
• 悬空引用：引用仓库中不存在的文档/文件/章节 → 删除引用

豁免（合法保留，勿误杀）

• 引用真实存在的带日期文档，按实际文件名保留（改名会伪造记录）
• 数据/行为事实：动画时长、menu_id、数据版本字段、SQL 日期字面量
• 环境频率现状描述（"偶发超过 15s"支撑超时取值）= 现状约束
• vendor/第三方文件注释不动

工具函数注释要求

• JSDoc 写清输入约束（空值、边界、格式）与副作用；纯函数的显然行为不必注释

Comment Rule Group 3: project / src/views/**/*.vue

Applies to:

• src\views\contract\paymentForm.vue
• src\views\documents\receiveForm.vue
• src\views\documents\sendForm.vue
• src\views\login.vue
• src\views\vehicle\applyList.vue

Content

注释通用质量（内置规则）

注释只回答三问：是什么（作用域/职责）、受何约束（业务规则、前提、坑）、行为是什么（非显然的行为说明）。

禁止（过程叙述，git 提交消息的职责）

• 日期戳、迭代/阶段编号（阶段 3、第二阶段、Phase N）、文档版本号
• 版本演变起点（"v2.1 起…"）→ 改写为当前结构语义
• 实测/性能回忆（"实测 594s 挂死"）、"曾在某环境"类环境记忆
• 提交溯源（commit hash）、来源仓、评审编号引用（R6 修正）
• 历史因果词（曾致/曾被/早期版本误用/迁移期教训/取代原先/反哺）
• 悬空引用：引用仓库中不存在的文档/文件/章节 → 删除引用

豁免（合法保留，勿误杀）

• 引用真实存在的带日期文档，按实际文件名保留（改名会伪造记录）
• 数据/行为事实：动画时长、menu_id、数据版本字段、SQL 日期字面量
• 环境频率现状描述（"偶发超过 15s"支撑超时取值）= 现状约束
• vendor/第三方文件注释不动

页面/组件注释要求

• 组件顶部注释说明页面职责与关键交互约束（权限、状态联动），一段以内
• 复杂表单校验规则、跨组件通信处允许行内注释解释动机

Candidates

高危（纯过程记录，删除候选） — 2 处

• src\store\modules\permission.ts:13-13 [悬空引用：匹配views里面所有的.vue 不存在] 匹配views里面所有的.vue文件
  • 挂接: const modules = import.meta.glob('./../../views/**/*.vue');
• src\types\vue-office.d.ts:3-4 [悬空引用：lib/index.js 不存在] vue-office 纯前端预览组件类型声明 pnpm 跳过了 postinstall 脚本，lib/index.js 未生成，故直接引用 v3(对应 Vue3) 构建产物

中危（混合/演变叙述，拆分改写） — 10 处

• src\lang\en_US.ts:4-4 [新旧对比/历史因果叙述] 兼容旧版静态路由 key（避免 meta.title 使用 dashboard/document 时无法命中翻译）
• src\lang\zh_CN.ts:6-6 [新旧对比/历史因果叙述] 兼容旧版静态路由 key（避免 meta.title 使用 dashboard/document 时无法命中翻译）
• src\utils\notification.ts:45-45 [新旧对比/历史因果叙述] 兼容旧版浏览器，避免静默报错阻塞
• src\utils\notification.ts:86-86 [新旧对比/历史因果叙述] 极少数浏览器（如旧版 360）不支持 Promise 形式，降级尝试回调版
• src\views\contract\paymentForm.vue:715-715 [新旧对比/历史因果叙述] 修改已关联的合同名称即切换到手工模式，原台账字段不再适用。
• src\views\documents\receiveForm.vue:712-712 [新旧对比/历史因果叙述] 旧版据此选择部门承办或副总办理；新版据此决定合并办理节点是否包含副总。
• src\views\documents\receiveForm.vue:717-719 [新旧对比/历史因果叙述] 保存业务数据（草稿/编辑模式）。审批中的业务回写走专用办理接口 （completeCirculateReceive / completeLeaderReviewReceive / completeDeptHandleReceive / approvalSaveAttachmentReceive）， 不再整表单提交。…
  • 挂接: const saveBusinessData = async () => {
• src\views\documents\sendForm.vue:706-707 [新旧对比/历史因果叙述] 保存业务数据（草稿/编辑模式）。审批中的业务回写走专用接口（approvalSaveDocNo/approvalSaveAttachment）， 不再整表单提交。
  • 挂接: const saveBusinessData = async () => {
• src\views\login.vue:188-189 [新旧对比/历史因果叙述] 后端已关闭多租户，不再请求租户列表接口 initTenantList();
• src\views\vehicle\applyList.vue:119-119 [新旧对比/历史因果叙述] 搜索和切换页签会主动刷新；此处不再监听分页变量，避免重复请求。
  • 挂接: const switchTab = (tab: string) => {

Pattern Distribution

• old_new: 10
• dangling_ref: 2
• crud_verb: 1