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

Comment Review Spec (scan)

• repo: C:\Development\Code\zhywgl\zhywgl-front
• rules: project (C:\Development\Code\zhywgl\zhywgl-front.commentreview\rule.json)
• files: 363 | comments: 3442 | candidates: 13
• severity: P0=3 P1=9 P2=1 INFO=0

Comment Rule Group 1: project / src/api/**

Applies to:

• src\api\perfeval\mutualEvaluation\deptTypes.ts

Content

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

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

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

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

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

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

api 层注释要求

• 接口函数注释对应后端业务动作；类型定义靠 TS 类型自解释，不重复注释字段
• 与后端字段含义有出入时（枚举值、单位、时区）必须注释

Comment Rule Group 2: system / **

Applies to:

• src\lang\en_US.ts
• src\lang\zh_CN.ts
• src\layout\components\Settings\index.vue
• src\store\modules\permission.ts
• src\types\vue-office.d.ts
• test\common\role-baseline.ts

Content

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

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

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

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

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

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

Comment Rule Group 3: 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 4: project / src/views/**/*.vue

Applies to:

• src\views\login.vue
• src\views\perfeval\distribution\form.vue
• src\views\perfeval\mutualEvaluation\personalForm.vue

Content

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

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

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

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

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

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

页面/组件注释要求

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

Candidates

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

• 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) 构建产物
• test\common\role-baseline.ts:1-7 [悬空引用：test.config.json 不存在] E2E 环境角色基线。必须在 test.config.json 中显式配置 roleKeys， 不根据当前角色是否“看起来够用”放行。返回错误文案；null 表示通过。 双胞胎副本：zhywgl-e2e/test/common/role-baseline.ts（E2E health 前置使用） 与本文件内容保持一致，…
  • 挂接: export function roleBaselineError(roles: string[] | undefined, expectedRoleKeys?: string[]

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

• src\lang\en_US.ts:4-4 [新旧对比/历史因果叙述] 兼容旧版静态路由 key（避免 meta.title 使用 dashboard/document 时无法命中翻译）
• src\lang\zh_CN.ts:4-4 [新旧对比/历史因果叙述] 兼容旧版静态路由 key（避免 meta.title 使用 dashboard/document 时无法命中翻译）
• src\layout\components\Settings\index.vue:158-158 [新旧对比/历史因果叙述] 默认锁定浅色，不再跟随操作系统的 prefers-color-scheme
• src\utils\notification.ts:45-45 [新旧对比/历史因果叙述] 兼容旧版浏览器，避免静默报错阻塞
• src\utils\notification.ts:86-86 [新旧对比/历史因果叙述] 极少数浏览器（如旧版 360）不支持 Promise 形式，降级尝试回调版
• src\views\login.vue:171-172 [新旧对比/历史因果叙述] 后端已关闭多租户，不再请求租户列表接口 initTenantList();
• src\views\perfeval\distribution\form.vue:301-301 [新旧对比/历史因果叙述] 提交前拦截：所有部门负责人行必须齐备（后端不再对负责人做阻断校验）
  • 挂接: const collectLeaderBlockers = (): string[] => {
• src\views\perfeval\mutualEvaluation\personalForm.vue:659-660 [新旧对比/历史因果叙述] 评分已由 approvalScore 接口写入数据库，流程变量不再携带评分（服务端任务事件不回写评分）； 分管领导办理人由流程定义 SpEL #initiatorDeptId（服务端流程启动时写入）解析，不透传客户端 deptId
• src\views\perfeval\mutualEvaluation\personalForm.vue:731-731 [新旧对比/历史因果叙述] 查询对象由后端固定为当前登录用户及其部门，前端不再传身份参数

低危（疑似业务日期，判别后改写） — 1 处

• src\api\perfeval\mutualEvaluation\deptTypes.ts:116-116 [仅日期/版本（可能是业务生效日，需判别）] 考核月份快捷搜索，格式 YYYY-MM，如 2026-08

Pattern Distribution

• old_new: 9
• dangling_ref: 3
• date: 1