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

Comment Review Spec (scan)

• repo: C:\Development\Code\zhywgl\zhywgl-server
• rules: project (C:\Development\Code\zhywgl\zhywgl-server.commentreview\rule.json)
• files: 1119 | comments: 9581 | candidates: 42
• severity: P0=4 P1=24 P2=14 INFO=0

Comment Rule Group 1: system / **

Applies to:

• script\bin\ts.sh
• script\workflow\validate-handlers.sh
• script\workflow\validate-releases.sh
• zhywgl-admin\src\main\resources\application.yml
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java
• zhywgl-common\zhywgl-common-mybatis\src\main\java\com\zhywgl\common\mybatis\aspect\DataPermissionPointcut.java
• zhywgl-common\zhywgl-common-sensitive\src\test\java\com\zhywgl\common\sensitive\core\SensitiveStrategyTest.java
• zhywgl-common\zhywgl-common-social\src\main\java\me\zhyd\oauth\request\AuthDingTalkV2Request.java

Content

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

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

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

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

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

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

Comment Rule Group 2: project / script/sql/**

Applies to:

• script\sql\release\1.0.0\01_system.sql
• script\sql\release\1.0.0\02_workflow.sql
• script\sql\release\1.0.0\03_seal.sql
• script\sql\release\1.0.0\04_supplies.sql
• script\sql\release\1.0.0\05_vehicle.sql
• script\sql\release\1.0.0\06_vacation.sql
• script\sql\release\1.0.0\07_schema_history.sql
• script\sql\release\1.0.0\08_perfeval.sql
• script\sql\release\1.0.0\09_agenda_party.sql
• script\sql\release\1.0.0\10_attendance.sql
• script\sql\release\1.0.0\11_duty.sql
• script\sql\validate_sql.sh

Content

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

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

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

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

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

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

SQL 脚本注释要求

• 表/字段 COMMENT 表达业务含义；状态类字段注明取值映射
• 脚本头部 banner 只保留当前用途说明，不留创建/修改历程

Comment Rule Group 3: project / /controller//*.java

Applies to:

• zhywgl-modules\zhywgl-demo\src\main\java\com\zhywgl\demo\controller\TestBatchController.java

Content

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

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

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

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

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

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

Controller 层注释要求

• 接口注释描述业务动作与权限语义（谁能做什么），与 @SaCheckPermission 一致
• 不写调用方式、参数示例等前端细节（那是接口文档的职责）

Comment Rule Group 4: project / /service//*.java

Applies to:

• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\AgendaPartyServiceImplTest.java
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\AttendanceServiceImplTest.java
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\PerfDistributionServiceImplTest.java
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\PerfevalMutualEvaluationDeptServiceImplTest.java
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\PerfevalMutualEvaluationPersonalServiceImplTest.java
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\PerfevalSummaryReviewServiceImplTest.java
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\VacationApplyServiceImplTest.java
• zhywgl-modules\zhywgl-system\src\main\java\com\zhywgl\system\service\impl\SysSchemaHistoryServiceImpl.java

Content

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

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

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

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

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

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

Service 层注释要求

• 方法注释表达业务约束与动机（事务边界理由、状态机规则、并发前提），不复述方法名
• 类级 Javadoc 说明领域职责与边界，一段以内
• 复杂算法处允许行内注释解释非显然的分支条件

Candidates

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

• script\bin\ts.sh:1-2 [悬空引用：./ry.sh 不存在] !/bin/sh ./ry.sh start 启动 stop 停止 restart 重启 status 状态
• script\sql\release\1.0.0\01_system.sql:1250-1251 [悬空引用：04_seal.sql 不存在] 业务选择器目录按钮（用户/部门/岗位，12040-12042）：15 个基线角色全量绑定 （印章选择按钮 12043 的绑定随 04_seal.sql）
• script\sql\release\1.0.0\02_workflow.sql:1-3 [悬空引用：warm-flow-all.sql 不存在] ---------------------------- 0、warm-flow-all.sql ----------------------------
• script\sql\release\1.0.0\10_attendance.sql:157-161 [悬空引用：attendanceConfig.ts 不存在] ============================================================ D. 字典：attendance_mark 考勤标记 dictValue 与前端 attendanceConfig.ts 的映射注释对齐（休=3/病=5/事=6/婚=9/丧=10/ 产=11/陪=…

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

• script\sql\release\1.0.0\04_supplies.sql:1-12 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 物品管理基线 数据库：达梦 DM；默认模式：ZHYWGL 内容：7 张业务表（物品库、库存流水、物品申领×2、物品采购×2、出库记录）、…
• script\sql\release\1.0.0\05_vehicle.sql:1-10 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 车辆管理基线 数据库：达梦 DM；默认模式：ZHYWGL 内容：8 张业务表、6 个业务字典及菜单/按钮权限 范围：车辆、司机、用车申请…
• script\sql\release\1.0.0\06_vacation.sql:1-7 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 休假管理模块 数据库：达梦 DM；默认模式：ZHYWGL 适用范围：按本目录 MANIFEST 顺序初始化全新空库 内容：休假申请表、假…
• script\sql\release\1.0.0\07_schema_history.sql:1-10 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 数据库发布历史基线 数据库：达梦 DM；默认模式：ZHYWGL 内容：数据库发布历史表、索引及系统管理菜单/按钮权限 范围：人工执行结果…
• script\sql\release\1.0.0\08_perfeval.sql:1-6 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 绩效考核基线 数据库：达梦 DM；默认模式：ZHYWGL 内容：自评互评、考核标准、汇总审核、绩效基础数据（基数/岗位系数）、绩效分配 …
• script\sql\release\1.0.0\08_perfeval.sql:689-698 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 绩效基础数据基线 数据库：达梦 DM；默认模式：ZHYWGL 内容：2 张业务表（绩效基础数据、绩效岗位系数）、基数初始值及菜单/按钮权…
• script\sql\release\1.0.0\08_perfeval.sql:821-825 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 绩效分配基线 数据库：达梦 DM；默认模式：ZHYWGL 内容：绩效分配主表、部门/人员业务明细及菜单权限 ==============…
• script\sql\release\1.0.0\09_agenda_party.sql:1-8 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 党委会议题呈报 数据库：达梦 DM；默认模式：ZHYWGL 适用范围：按本目录 MANIFEST 顺序初始化全新空库 内容：议题呈报表 …
• script\sql\release\1.0.0\10_attendance.sql:1-7 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 考勤管理模块 数据库：达梦 DM；默认模式：ZHYWGL 适用范围：按本目录 MANIFEST 顺序初始化全新空库 内容：考勤填报表、考…
• script\sql\release\1.0.0\11_duty.sql:1-8 [版本号+过程信号（多为库特性说明，判别）] ============================================================================= ZHYWGL 1.0.0 职务基线 数据库：达梦 DM；默认模式：ZHYWGL 内容：2 张业务表（职务、用户职务关联）及菜单/按钮权限 约束： 1. 仅用于新环…
• script\sql\validate_sql.sh:1-10 [新旧对比/历史因果叙述] !/usr/bin/env bash ============================================================================= 达梦数据库 (DM) SQL 基线规范与完整性校验脚本 用法: ./validate_sql.sh # 校验当前版本（根 po…
• zhywgl-admin\src\main\resources\application.yml:60-61 [新旧对比/历史因果叙述] 从 springboot 3.5 开始 spring自带线程池 不再需要 AsyncConfig与ThreadPoolConfig 可直接注入线程池使用
• zhywgl-common\zhywgl-common-mybatis\src\main\java\com\zhywgl\common\mybatis\aspect\DataPermissionPointcut.java:21-22 [新旧对比/历史因果叙述] 优先匹配方法 数据权限注解不对继承生效，所以检查当前方法是否有注解即可，不再往上匹配父类或接口
  • 挂接: if (method.isAnnotationPresent(DataPermission.class)) {
• zhywgl-common\zhywgl-common-sensitive\src\test\java\com\zhywgl\common\sensitive\core\SensitiveStrategyTest.java:58-60 [新旧对比/历史因果叙述] 邮箱：本地部分被掩码，域名保留，且不再是原文。
• zhywgl-common\zhywgl-common-social\src\main\java\me\zhyd\oauth\request\AuthDingTalkV2Request.java:21-26 [新旧对比/历史因果叙述] 新版钉钉二维码登录 @author yadong.zhang (yadong.zhang0415(a)gmail.com) @since 1.16.7
  • 挂接: public class AuthDingTalkV2Request extends AuthDefaultRequest {
• zhywgl-modules\zhywgl-demo\src\main\java\com\zhywgl\demo\controller\TestBatchController.java:33-37 [版本号+过程信号（多为库特性说明，判别）] 新增批量方法 可完美替代 saveBatch 秒级插入上万数据 (对mysql负荷较大)

  3.5.0 版本 增加 rewriteBatchedStatements=true 批处理参数 使 MP 原生批处理可以达到同样的速度

• zhywgl-modules\zhywgl-demo\src\main\java\com\zhywgl\demo\controller\TestBatchController.java:52-56 [版本号+过程信号（多为库特性说明，判别）] 新增或更新 可完美替代 saveOrUpdateBatch 高性能

  3.5.0 版本 增加 rewriteBatchedStatements=true 批处理参数 使 MP 原生批处理可以达到同样的速度

• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\AgendaPartyServiceImplTest.java:48-54 [阶段/迭代编号] 党委会议题数据权限契约测试（第二阶段统一边界）。

  列表/详情走 Mapper scoped 查询；详情在数据范围外按「业务 ID + DWHYT 流程编码」放行流程参与人； 草稿、退回、撤销、作废仅发起人本人可见，流程参与人不豁免； 拒绝时统一文案「数据不存在或无权访问」，且不得继续查询名称、流程历史与手签章。…

  • 挂接: @ExtendWith(MockitoExtension.class)
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\AttendanceServiceImplTest.java:53-60 [阶段/迭代编号] 考勤数据权限契约测试（第二阶段统一边界）。

  列表/详情/导出走 Mapper scoped 查询（create_by + 业务 dept_id）； 详情在数据范围外按「业务 ID + KQGL 流程编码」放行流程参与人； 草稿、退回、撤销、作废仅发起人本人可见； 详情返回流程历史与按明细人员解析的手签章投影，拒…

  • 挂接: @ExtendWith(MockitoExtension.class)
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\PerfDistributionServiceImplTest.java:53-58 [阶段/迭代编号] 绩效分配数据权限契约测试（数据范围 ∪ 流程参与人并集，第二阶段统一边界收口）。

  并集分页：候选 id 全量取、scoped id 与参与人 id 求并、最终分页 ignore 二次过滤； 列表与详情统一「草稿/退回/撤销/作废仅发起人可见」；不存在与无权统一文案。

  • 挂接: @ExtendWith(MockitoExtension.class)
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\PerfevalMutualEvaluationDeptServiceImplTest.java:46-51 [阶段/迭代编号] 部门互评数据权限契约测试（第二阶段统一边界）。

  列表/导出走 Mapper scoped 查询；详情数据范围外按 ZPHPBM 流程参与人放行； 草稿、退回、撤销、作废仅发起人本人可见；拒绝时不得查询明细、名称与流程历史。

  • 挂接: @ExtendWith(MockitoExtension.class)
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\PerfevalMutualEvaluationPersonalServiceImplTest.java:52-58 [阶段/迭代编号] 个人自评互评数据权限契约测试（第二阶段统一边界）。

  列表/导出走 Mapper scoped 查询；详情数据范围外按 ZPHPGR 流程参与人放行； 草稿、退回、撤销、作废仅发起人本人可见； 审批打分必须携带任务 ID 且任务须绑定当前办理人、本业务单与部门负责人审批节点。

  • 挂接: @ExtendWith(MockitoExtension.class)
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\PerfevalSummaryReviewServiceImplTest.java:48-54 [阶段/迭代编号] 汇总审核数据权限契约测试（第二阶段统一边界）。

  列表/导出走 Mapper scoped 查询；详情数据范围外按 HZSH 流程参与人放行； 草稿、退回、撤销、作废仅发起人本人可见； 审批模式保存以任务 ID 判定并校验归属，客户端单独声称的 nodeCode 不得跳过所有权校验。

  • 挂接: @ExtendWith(MockitoExtension.class)
• zhywgl-modules\zhywgl-oa\src\test\java\com\zhywgl\oa\service\impl\VacationApplyServiceImplTest.java:50-56 [阶段/迭代编号] 休假数据权限契约测试（第二阶段统一边界）。

  列表/详情/导出走 Mapper scoped 查询（create_by + 业务 dept_id）； 详情在数据范围外按「业务 ID + 三种休假流程编码」放行流程参与人（按申请类型逐码判定）； 草稿、退回、撤销、作废仅发起人本人可见；详情返回流程历史与按流程办理人…

  • 挂接: @ExtendWith(MockitoExtension.class)

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

• script\sql\release\1.0.0\03_seal.sql:1-4 [仅日期/版本（可能是业务生效日，需判别）] ZHYWGL 1.0.0 印章基础功能 本脚本依次初始化印章管理和用印申请。 字典 ID: seal_type=104, seal_status=105, data=1032-1039 本文件只用于新环境初始化，不得在已有业务库重复执行。
• script\sql\release\1.0.0\08_perfeval.sql:341-342 [仅日期/版本（可能是业务生效日，需判别）] ZHYWGL 1.0.0 考核标准：考核标准表及菜单权限。 本文件只用于新环境初始化，不得在已有业务库重复执行。
• script\sql\validate_sql.sh:241-242 [仅日期/版本（可能是业务生效日，需判别）] 3.1 seed/ 目录不得存在：组织数据在 release/1.0.0/01_system.sql AA 段、 职务字典在 11_duty.sql C 段、岗位系数在 08_perfeval.sql
• script\workflow\validate-handlers.sh:1-7 [仅日期/版本（可能是业务生效日，需判别）] !/usr/bin/env bash 仓库级静态一致性检查（构建期，不查询任何数据库）： 1. 流程 JSON 中的 post: 必须在 release/1.0.0/01_system.sql AA 段（组织岗位）中存在、启用且至少绑定一名用户； 2. role: 必须在 01_system.sql 角…
• script\workflow\validate-releases.sh:75-75 [仅日期/版本（可能是业务生效日，需判别）] 1.0.0 之外的增量版本走更严格的语义与工程契约校验
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java:43-45 [仅日期/版本（可能是业务生效日，需判别）] 例例如，2023年7月可以表示为 "2023-07"
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java:68-70 [仅日期/版本（可能是业务生效日，需判别）] 例例如，2023年7月可以表示为 "2023/07"
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java:88-90 [仅日期/版本（可能是业务生效日，需判别）] 例例如，2023年7月可以表示为 "2023.07"
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java:108-110 [仅日期/版本（可能是业务生效日，需判别）] 例如，2023年7月可以表示为 "202307"
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java:113-115 [仅日期/版本（可能是业务生效日，需判别）] 例如，2023年7月22日可以表示为 "20230722"
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java:118-120 [仅日期/版本（可能是业务生效日，需判别）] 例如，2023年7月22日下午3点可以表示为 "2023072215"
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java:123-125 [仅日期/版本（可能是业务生效日，需判别）] 例如，2023年7月22日下午3点30分可以表示为 "202307221530"
• zhywgl-common\zhywgl-common-core\src\main\java\com\zhywgl\common\core\enums\FormatsType.java:128-130 [仅日期/版本（可能是业务生效日，需判别）] 例如，2023年7月22日下午3点30分45秒可以表示为 "20230722153045"
• zhywgl-modules\zhywgl-system\src\main\java\com\zhywgl\system\service\impl\SysSchemaHistoryServiceImpl.java:28-30 [仅日期/版本（可能是业务生效日，需判别）] 1.1.0 服务端发布白名单。登记只证明人工确认，白名单用于防止脚本名或校验值被随意伪造。

Pattern Distribution

• version: 18
• separator_line: 11
• date: 8
• phase_no: 7
• crud_verb: 6
• old_new: 5
• dangling_ref: 4