triplestone
d83b5fd5d1
确定性注释审查 harness（cmr），程序决定审什么、agent 负责推理： - 轻量状态机提取注释（Java/TS/JS/Vue/SQL/YAML/Shell/Python），过程性模式分级 P0/P1/P2/INFO - 分层规则（CLI/项目/用户/内置）、全库 scan 与 Git 增量 diff（工作区/分支/提交） - 悬空引用两级判定：确认失效 P0（附近似候选与查找依据）与待核实 P1（外部路径/构建产物/跨仓裸文件名） - testdata/corpus 56 条人工判定样例库 + 记分卡回归门禁；npm test 30/30
6.9 KiB
6.9 KiB
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