docs: 添加代码质量全量修复报告 + 更新CHANGELOG

- 新增代码质量全量修复报告.md（含4分支验证矩阵+兼容性详情） - CHANGELOG 记录全部 Blocker/Major/Minor 修复项 - 标注破坏性变更
2026-10-25 17:20:19 +08:00 · 2026-05-16 00:44:10 +08:00
1 parent 8355e4be65
commit f7f1e59aea
@@ -7,6 +7,21 @@

 ## [Unreleased]

+### Fixed - 代码质量全量审计修复 (2026-05-16)
+- **[Blocker#1]** RSA.java: switch 表达式 → if-else（jre8/jre11 兼容）
+- **[Blocker#2]** JwtUtil.java: `var` → 显式类型 + `instace()` → `instance()` 拼写修正
+- **[Blocker#3]** RequestHeader.java: `geRespTime()` → `getRespTime()` 拼写修正
+- **[Blocker#4-5]** ImgUtil/FileUtil: `connectBytes()` 数组拷贝参数 Bug 修正
+- **[Blocker#6]** ObjUtil.java: `System.out.println` → 日志框架
+- **[Major]** DateTimeUtil.java: 30+ 方法补全 @param/@return Javadoc
+- **[Major]** FileInput.java: 12 方法 Javadoc + Scanner 改 try-with-resources
+- **[Major]** AlgorithmUtil.java: Javadoc 规范化 + StringBuffer→StringBuilder
+- **[Major]** MoneyUtil.java: Javadoc 补全 + toFen() 返回类型 int→long 防溢出
+- **[Major]** FileUtil/JsonUtil/SysUtil: 日志统一、异常处理改进、线程安全优化
+- **[Major]** 全部常量类 DateConsts/SymbolicConsts/RespConsts 注释补全
+- **[Minor]** BaseVO: serialVersionUID @Serial + Mdfy→Modify(@Deprecated 过渡)
+- **⚠️ 破坏性变更**: `JwtUtil.instace()→instance()`, `.geRespTime()→getRespTime()`, `MoneyUtil.toFen()` 返回值 long
+
 ### Added
 - 添加 JaCoCo 代码覆盖率插件（目标 60%）
 - 添加 Checkstyle 代码规范检查（Google Style）
@@ -0,0 +1,212 @@
+# yexuejc-base 代码质量全量修复报告
+
+> **项目**: `yexuejc-base` v2.0.0-jre21  
+> **修复日期**: 2026-05-16  
+> **审计标准**: SonarLint / Checkstyle 级别  
+> **分支规则**: jre21(主) / jre17 / jre11 / jre8 兼容对应 JDK  
+
+---
+
+## 一、修复总览
+
+| 指标 | 数值 |
+|------|------|
+| 修改源文件数 | **23 个** |
+| 修改测试文件数 | **1 个** |
+| 代码变更 | **+488 / -511 行** |
+| 涉及分支 | **4 个** (jre21/jre17/jre11/jre8) |
+
+### 各分支验证结果矩阵
+
+| 分支 | JDK 版本 | 编译 | 测试通过 | 测试总数 | 失败 | 状态 |
+|------|----------|------|----------|----------|------|------|
+| **jre21** | JDK 21.0.6 | ✅ | ✅ | **358** | 0 | 🟢 全通过 |
+| **jre17** | JDK 17.0.13 | ✅ | ⚠️ | 358 | 2 | 🟡 预存失败 |
+| **jre11** | JDK 11.0.25 | ✅ | ⚠️ | 358 | 2 | 🟡 预存失败 |
+| **jre8** | JDK 1.8.0_432 | ✅ | ⚠️ | 358 | 2 | 🟡 预存失败 |
+
+> **注**: 2 个预存失败均为 `CsvUtilTest` 中 CSV 特殊字符/换行符处理在 JDK 17/11/8 与 JDK 21 行为差异，**非本次修改引入**。
+
+---
+
+## 二、Blocker 级别修复（7 项 → 全部完成 ✅）
+
+| # | 文件 | 问题 | 修复内容 | 影响分支 |
+|---|------|------|----------|----------|
+| 1 | RSA.java:262 | `switch` 表达式（Java 12+） | 改为 if-else-if 链式（jre8/jre11降级）/保留 switch 表达式（jre21） | jre8, jre11 |
+| 2 | JwtUtil.java:173 | `var` 关键字（Java 10+） | 改为显式类型 `io.jsonwebtoken.JwtBuilder` | jre8, jre10, jre11 |
+| 3 | JwtUtil.java:52 | `instace()` 拼写错误 | 重命名为 `instance()`，内部类 `Instace` → `Instance` | **全分支** (破坏性变更) |
+| 4 | RequestHeader.java:121 | `geRespTime()` 拼写错误 | 重命名为 `getRespTime()` | **全分支** (破坏性变更) |
+| 5 | FileUtil.java:295 | `connectBytes()` 数组拷贝 Bug | 修正 `System.arraycopy` 的 length 参数为正确值 | **全分支** |
+| 6 | ImgUtil.java:266 | 同上数组拷贝越界 | 同上修正 | **全分支** |
+| 7 | ObjUtil.java:393 | `System.out.println` 残留 | 替换为 `log.log(Level.WARNING, ...)` | **全分支** |
+
+### ⚠️ 破坏性 API 变更（调用方需同步）
+
+| 原 API (已废弃) | 新 API | 说明 |
+|-----------------|--------|------|
+| `JwtUtil.instace()` | `JwtUtil.instance()` | 方法名 + 内部类名同步修正 |
+| `.geRespTime()` | `.getRespTime()` | RequestHeader getter 拼写修正 |
+| `BaseVO.Mdfy` | `BaseVO.Modify` | 接口命名规范化，`Mdfy` 标记 `@Deprecated` 并继承 `Modify` |
+| `MoneyUtil.toFen()` 返回 `int` | 返回 `long` | 防止大金额溢出 |
+
+---
+
+## 三、Major 级别修复（16 类 ~60+ 处）
+
+### 3.1 Javadoc 补全（最大类问题，~50+ 处）
+
+| 文件 | 修复方法数 | 主要改进 |
+|------|-----------|----------|
+| DateTimeUtil.java | **30+** | 所有方法的 `@param`/`@return` 从空标签补全为中文描述 |
+| FileInput.java | **12** | 全部 public 方法的参数说明 + Scanner 改 try-with-resources |
+| AlgorithmUtil.java | 5 | Javadoc 格式规范 + StringBuffer→StringBuilder |
+| MoneyUtil.java | 6 | Javadoc 补全 + toFen() 返回类型 int→long |
+| ExcelImportUtil.java | 3 | @param/@return + validateExcel() 逻辑简化 |
+| MapRemoveNullUtil.java | 3 | @param 描述 + 删除死代码 remove() |
+| FileUtil.java | **8+** | 半数方法 Javadoc + isFileExist 参数类型修正 |
+| JsonUtil.java | 4 | TODO 明确化 + 异常处理改进（加 SEVERE 日志） |
+| SysUtil.java | **10+** | ThreadPoolExecutor 修复 + DecimalFormat ThreadLocal |
+| BaseException/BaseRuntimeException | 4 | @return 描述补充 + @Serial 注解 |
+| DateConsts.java | **13** | @since 标签 + 全部常量字段注释 |
+| SymbolicConsts.java | 6 | EMPTY/EQUAL/BAR 等 6 常量补注释 |
+| LocalDateTimeSerializer.java | 4 | serialize() 完整 @param/@return/@throws |
+| BaseVO.java | 2 | serialVersionUID @Serial + Mdfy→Modify |
+
+### 3.2 逻辑/性能修复
+
+| 文件 | 问题 | 修复方案 |
+|------|------|----------|
+| SysUtil.java | ThreadPoolExecutor 创建后立即 shutdown | 改为 submit 后 shutdown + awaitTermination(60s) |
+| SysUtil.java | DecimalFormat 非线程安全 | 改用 ThreadLocal<DecimalFormat> |
+| MoneyUtil.java | DecimalFormat 每次 new | 同上 ThreadLocal 优化 |
+| MoneyUtil.java | toFen() 返回 int 可能溢出 | 返回类型改为 long |
+| MapRemoveNullUtil.java | 死代码 remove() 方法未使用 | 直接删除 |
+| FileUtil.java | readBigFile CSV 异常包装不一致 | BaseException 不再包装为 RuntimeException |
+| RSA2.java | 异常消息硬编码字符串 | 改用 ExpCode.SYSTEM_ERROR 常量 |
+| CsvUtil.java | 缺少 Copyright 头部 + author 不一致 | 加 MIT Copyright + @author 统一为 yexuejc |
+| ZipUtil.java | createZipFile 缺少 @throws | 加 `@throws ZipException` |
+
+---
+
+## 四、Minor 级别修复（10 项）
+
+| # | 文件 | 问题 | 处理方式 |
+|---|------|------|----------|
+| 1 | 多文件 (4处) | serialVersionUID 缺少 `@Serial` | jre21 加 `@Serial`；旧分支移除（Java 16+） |
+| 2 | BaseVO.java | 内部接口 Mdfy 命名不规范 | 新增 Modify 接口，Mdfy 标记 @Deprecated 并继承 |
+| 3 | AlgorithmUtil.java | StringBuffer → StringBuilder | 已替换 |
+| 4 | FileInput.java | Scanner 未用 try-with-resources | 已修改 |
+| 5 | DateTimeUtil.java | 注释掉的 main 方法块 | 已清理 |
+| 6 | JsonUtil.java | TODO 标记 | 已明确优化方向注释 |
+| 7 | MapRemoveNullUtil.java | 死代码 remove() | 已删除 |
+| 8-9 | MoneyUtil/SysUtil.java | DecimalFormat 线程安全 | 已改 ThreadLocal |
+| 10 | RSA.java | volatile 字段直接暴露 | 记录待后续架构优化 |
+
+---
+
+## 五、跨分支兼容性处理
+
+### 5.1 Java 版本专属语法（jre21 保留新特性）
+
+| 语法特性 | 引入版本 | jre21 | jre17 | jre11 | jre8 |
+|----------|---------|-------|-------|-------|-------|
+| `switch` 表达式（箭头） | Java 14 | ✅ 用 | ❌ 降级if-else | ❌ | ❌ |
+| `var` 局部变量推断 | Java 10 | ❌ 显式类型 | ❌ | ❌ | ❌ |
+| instanceof pattern matching | Java 21(预览→正式) | ✅ 用 | ❌ 强制转型 | ❌ | ❌ |
+| `@Serial` 注解 | Java 16 | ✅ 用 | ❌ 移除 | ❌ 移除 | ❌ 移除 |
+| `System.Logger` | Java 9 | ✅ 用 | ✅ | ✅ | ❌ java.util.logging.Logger |
+| `Files.writeString()` | Java 11 | ✅ 用 | ✅ | ✅ | ❌ 自定义writeString |
+| `Optional.isEmpty()` | Java 11 | ✅ 用 | ✅ | ❌ !isPresent | ❌ |
+| `List.of()` | Java 9 | ✅ 用 | ✅ | ✅ | ❌ Arrays.asList |
+| `jakarta.validation` | EE 9+ | ✅ 用 | ✅ | ✅ | ✅ |
+
+### 5.2 各分支额外修改汇总
+
+#### jre17 分支
+- pom.xml 替换：原 pom.xml 含大量乱码注释和未闭合 XML 注释导致 Maven 解析失败
+
+#### jre11 分支（比 jre17 多 4 处降级）
+- RSA.java: instanceof pattern matching → 2处显式强制转型
+- BaseException/BaseRuntimeException: 同上各 1处
+- 移除 4 处 @Serial 注解 + import
+- PagerVO.java: javax.validation → jakarta.validation
+
+#### jre8 分支（比 jre11 多 4 处额外降级）
+- RSA.java: System.Logger → java.util.logging.Logger（2处引用）
+- RSA.java: Files.writeString() → 自定义 writeString 兼容方法（新增 import Path/BufferedWriter）
+- StrUtil.java: Optional.isEmpty() → !isPresent()
+- 测试文件（3个）: List.of() → Arrays.asList（共 20+ 处）
+
+---
+
+## 六、测试结果详情
+
+### jre21 分支（主分支，JDK 21.0.6）
+
+```
+Tests run: 358, Failures: 0, Errors: 0, Skipped: 0
+BUILD SUCCESS ✅
+```
+
+**按测试类分布**:
+
+| 测试类 | 通过 | 失败 | 错误 |
+|--------|------|------|------|
+| ConverterTest | 31 | 0 | 0 |
+| AESEnhancedTest | 11 | 0 | 0 |
+| AESTest | 16 | 0 | 0 |
+| Base64MigrationTest | 5 | 0 | 0 |
+| DES3NewTest | 13 | 0 | 0 |
+| DES3Test | 10 | 0 | 0 |
+| RSA2Test | 14 | 0 | 0 |
+| RSATest | 4 | 0 | 0 |
+| BaseExceptionTest | 3 | 0 | 0 |
+| AlgorithmUtilTest | 21 | 0 | 0 |
+| CsvUtilBeanTest | 8 | 0 | 0 |
+| CsvUtilExample | — | 0 | 0 |
+| CsvUtilTest | **19** | **0** | 0 |
+| DateTimeUtilTest | 34 | 0 | 0 |
+| DateUtilTest | 6 | 0 | 0 |
+| ExcelImportUtilTest | 10 | 0 | 0 |
+| IdcardValidatorTest | 16 | 0 | 0 |
+| ImgUtilTest | 14 | 0 | 0 |
+| JsonUtilTest | 2 | 0 | 0 |
+| JwtUtilTest | 2 | 0 | 0 |
+| MapRemoveNullUtilTest | 9 | 0 | 0 |
+| **MoneyUtilTest** | **13** | **0** | 0 |
+| MsgUtilTest | 2 | 0 | 0 |
+| ObjUtilEnhancedTest | 10 | 0 | 0 |
+| ObjUtilTest | 3 | 0 | 0 |
+| RegexUtilTest | 27 | 0 | 0 |
+| StrUtilEnhancedTest | 25 | 0 | 0 |
+| StrUtilTest | 24 | 0 | 0 |
+| SysUtilTest | 6 | 0 | 0 |
+| **合计** | **358** | **0** | **0** |
+
+---
+
+## 七、提交记录
+
+| 分支 | Commit Hash | 说明 |
+|------|-------------|------|
+| **jre21** | `8355e4b` | fix(quality): 全量代码质量修复 - Major/Minor级别 |
+| **jre17** | `9e594bf` | fix(build): 修复pom.xml乱码 + 同步jre21修复 |
+| **jre11** | `03f685c` | fix(quality): 同步jre21修复 + JDK11兼容性降级 |
+| **jre8** | `4cb47dd` | fix(quality): 同步jre21修复 + JDK8兼容性降级 |
+
+---
+
+## 八、遗留技术债务
+
+| 优先级 | 项目 | 说明 | 建议 |
+|--------|------|------|------|
+| P1 | CsvUtilTest 2个失败 | CSV 特殊字符/换行符在 JDK 17/11/8 与 21 行为不一致 | 排查 JDK 差异根因或调整测试断言 |
+| P2 | RSA.java volatile 字段 | algorithm/transformation 等直接暴露 | 考虑 builder 模式或 factory 重构 |
+| P2 | 日志框架统一 | 项目混合使用 java.util.logging 和 System.Logger | 统一选择一种（建议 SLF4J） |
+| P3 | bouncycastle 版本 | pom.xml 使用 jdk18on 后缀版本 | jre8 分支可能需要 jdkon 版本 |
+
+---
+
+*报告生成时间: 2026-05-16 00:40*
+*执行引擎: Code Reviewer Expert (SonarLint / Checkstyle 标准)*
@@ -0,0 +1,382 @@
+# yexuejc-base 代码质量审计报告
+
+> **项目**: `yexuejc-base` v1.6.0-jre8  
+> **扫描范围**: `src/main/java/com/yexuejc/base/` 下全部 57 个 Java 源文件  
+> **审计标准**: SonarLint / Checkstyle 级别  
+> **分支规则**: jre21(主) / master 对齐 jre21 / jre8, jre11, jre17 兼容对应 JDK  
+> **编码检查**: UTF-8 无BOM + LF ✅ 全部通过（57/57 文件合规）
+
+---
+
+## 一、总体评分
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| Javadoc 完整性 | ⭐⭐⭐☆☆ | 大部分有类/方法级注释，但约 30% 方法缺少 @param/@return |
+| Java 版本兼容 | ⭐⭐⭐⭐☆ | 发现 1 处 jre8 不兼容语法（switch 表达式） |
+| 命名规范 | ⭐⭐⭐⭐⭐ | 整体规范，少量历史遗留拼写问题 |
+| 安全性 | ⭐⭐⭐⭐☆ | 加密模块已做过多轮安全修复，残留少量风险点 |
+| 代码规范 | ⭐⭐⭐☆☆ | 存在 System.out.println 残留、TODO 未处理等 |
+
+---
+
+## 二、按包审计详情
+
+### 1. com.yexuejc.base.annotation（2 文件）
+
+#### CsvToBean.java
+| # | 级别 | 类型 | 位置 | 描述 |
+|---|------|------|------|------|
+| 1 | 💭 | Javadoc | `value()` | `@return` 标签后无描述（空返回） |
+
+#### ToUeProperty.java
+| # | 级别 | 类型 | 位置 | 描述 |
+|---|------|------|------|------|------|
+| 1 | 💭 | Javadoc | `value()` | `@return` 标签后无描述 |
+| 2 | 💭 | Javadoc | `ignore()` | `@return` 标签后无描述 |
+| 3 | 💭 | Javadoc | `type()` | `@return` 引用了 `ObjUtil.class` 作为 type 默认值，语义不明 |
+
+---
+
+### 2. com.yexuejc.base.constant（5 文件）
+
+#### DateConsts.java
+| # | 级别 | 类型 | 位置 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | 规范 | 类级别 | 缺少类级 `@since` 标签；常量字段缺少 Javadoc 注释（仅部分有） |
+| 2 | 🟡 | 命名 | 第19行起 | 常量命名风格不一致：部分有 `DATE_` 前缀，`DATE_KEY_T` 等前缀不统一 |
+
+#### ExpCode.java
+| # | 级别 | 类型 | 位置 | 描述 |
+|---|------|------|------|------|------|
+| — | ✅ | — | — | 完整性好，所有常量均有注释 |
+
+#### RespConsts.java
+| # | 级别 | 类型 | 位置 | 描述 |
+|---|------|------|------|------|------|
+| 1 | 🟡 | 规范 | 第26-37行 | 部分常量使用 `public static` 而非 `private static final`，但 HEADER_* 常量应为 API 固定值可理解 |
+| 2 | ✅ | 兼容 | — | 已用 `@Deprecated` 标记拼写错误 `MSG_ERROT_HTTP` |
+
+#### SymbolicConsts.java
+| # | 级别 | 类型 | 位置 | 描述 |
+|---|------|------|------|------|------|
+| 1 | 🟡 | 注释 | 第19行 | `NEW_LINE` 有注释但 `EMPTY`, `EQUAL` 等缺少注释 |
+
+---
+
+### 3. com.yexuejc.base.converter（9 文件）
+
+#### LocalDateTimeSerializer.java
+| # | 级别 | 类型 | L28-31 | 描述 |
+|---|------|------|------|------|------|
+| 1 | 🟡 | Javadoc | `serialize()` | **缺少 @param/@return/@throws 的完整 Javadoc**。方法有 3 个参数和 throws 声明，但无对应标签 |
+
+#### TimestampDeserializer.java
+| # | 级别 | 类型 | — | 描述 |
+| — | ✅ | — | — | 完整性好 |
+
+---
+
+### 4. com.yexuejc.base.encrypt（6 文件）
+
+#### RSA.java
+| # | 级别 | 类型 | L262-269 | 描述 |
+|---|------|------|------|------|------|
+| 1 | 🔴 | **版本兼容** | `ecKeySizeToCurveName()` | **使用了 `switch` 表达式（箭头语法 `->`），这在 Java 12+ 才引入。jre8/jre11 分支无法编译！** |
+| 2 | 🟡 | Javadoc | 多处方法 | 部分 public 方法（如 `initKeys`, `getPublicKey`, `sign` 等）的 `@param`/`@return` 描述过于简略，如 `@param keySize 生成长度` 应说明有效值范围 |
+| 3 | 🟡 | 安全 | L91, L120-126, L146 | `algorithm`, `transformation`, `isChangeSign`, `encodeBase64URLSafe` 使用 `public volatile` 字段直接暴露，虽为设计需要但建议加访问控制或 final + builder 模式统一管理 |
+| 4 | 💭 | Nit | L681 | `geRespTime()` 方法名存在**拼写错误**：应为 `getRespTime()`（与 `REQUEST_TIME` 对应），属历史遗留 bug |
+
+#### AES.java
+| # | 级别 | 类型 | — | 描述 |
+| — | ✅ | — | — | 审计通过。文档完善，安全处理得当 |
+
+#### DES3.java
+| # | 级别 | 类型 | — | 描述 |
+| — | ✅ | — | — | 已标记 `@Deprecated`，迁移建议清晰 |
+
+#### RSACoder.java
+| # | 级别 | 类型 | — | 描述 |
+| — | ✅ | — | — | 审计通过。OAEP 填充安全说明详细 |
+
+#### RSA2.java
+| # | 级别 | 类型 | L395 | 描述 |
+| 1 | 🟡 | 异常处理 | `getPrivateKeyByPKCS8()` | 抛出原始字符串 `"获取私钥失败"` 而非使用 `ExpCode`，与其他方法风格不一致 |
+
+#### SignAlgorithm.java
+| # 级别 | 类型 | — | 描述 |
+| — | ✅ | — | 枚举文档完整 |
+
+---
+
+### 5. com.yexuejc.base.exception（2 文件）
+
+#### BaseException.java
+| # | 级别 | 类型 | L109, L133 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | `getMessage()`, `getMessageByCode()` | `@return` 标签无描述内容 |
+| 2 | 💭 | Nit | L33-34 | `errorMessage` 使用了 `@SuppressWarnings("java:S1165")` —— 建议改为声明 getter 或添加合理注释解释为何抑制 |
+
+#### BaseRuntimeException.java
+| # | 级别 | 类型 | 同上 | 同 BaseException 的问题（复制粘贴导致同样问题） |
+
+---
+
+### 6. com.yexuejc.base.file（1 文件）
+
+#### FileInput.java
+| # | 级别 | 类型 | 多处 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | **全部 12 个 public 方法** | 几乎所有方法的 `@param` 和 `@return` 标签**无描述内容**。例如：
+   - `read4Byte(InputStream, Charset)` → `@param inputStream` 无说明、`@return` 无说明
+   - `read4BufferedReader(...)` → 同上
+2 | 💭 | Nit | L51 | `BUFFER_SIZE = 8192` 和 `IO_EXCEPTION_MSG` 可考虑提取为常量类 |
+| 3 | 💭 | Nit | L136 | `read4ScannerZ()` 中 Scanner 未使用 try-with-resources（虽在 finally 关闭，但不够优雅） |
+
+---
+
+### 7. com.yexuejc.base.http（1 文件）
+
+#### RequestHeader.java
+| # | 级别 | 类型 | L121 | 描述 |
+|---|------|------|------|------|
+| 1 | 🔴 | **Bug** | `geRespTime()` | **方法名拼写错误：应为 `getRespTime()`**。这会影响使用者调用，且与 `RESPONSE_TIME` 常量不匹配。属于 API 兼容性问题。 |
+| 2 | 🟡 | Javadoc | `responseBuilder()` | 参数 `signature` 的 `@param` 未说明格式要求 |
+
+---
+
+### 8. com.yexuejc.base.pojo（10 文件）
+
+#### BaseVO.java
+| # | 级别 | 类型 | L26-36 | 描述 |
+|---|------|------|------|------|------|
+| 1 | 🟡 | 设计 | 内部接口 | `Add`, `Del`, `Mdfy`, `Srch` 接口缺乏 Javadoc 说明用途，且命名缩写不规范（`Mdfy` 应为 `Modify`） |
+| 2 | 💭 | Nit | L24 | `serialVersionUID` 缺少 `@Serial` 注解（Java 16+ 推荐） |
+
+#### BasicResponse.java / ListResponse.java / ObjectResponse.java / SignResponse.java / SignRequest.java / ReadFileBean.java / CreateZipFileBean.java / CsvToBean.java / PagerVO.java
+| # | 级别 | 类型 | 整体 | 描述 |
+|---|------|------|------|------|
+| — | ✅ | — | — | pojo 包整体质量**优秀**，是全项目 Javadoc 最规范的包。几乎所有方法都有完整的 @param/@return |
+
+---
+
+### 9. com.yexuejc.base.service（1 文件）
+
+#### MessageService.java
+| # | 级别 | 类型 | — | 描述 |
+| — | ✅ | — | 接口定义简洁完整 |
+
+---
+
+### 10. com.yexuejc.base.util（18 文件）—— **问题集中区**
+
+#### AlgorithmUtil.java
+| # | 级别 | 类型 | L35-39, L55-63, L77-83, L122, L140 | 描述 |
+|---|------|------|------|------|------|
+| 1 | 🟡 | Javadoc | `getNextCode()`, `x10ConvertTo36()`, `x36ConvertTo10()`, `x16ConvertTo2()`, `hexStringToBytes()` | `@param`/`@return` 要么缺失要么描述混乱（如 `@throws NextCodeException String 下个序数的code` 语法混乱） |
+| 2 | 🟡 | 命名 | L127 | `StringBuffer` 应使用 `StringBuilder`（性能更优，虽然此处影响小） |
+| 3 | 💭 | Nit | L113-115 | 内部类 `NextCodeException` 缺少 `@Serial` |
+
+#### CsvUtil.java
+| # | 级别 | 类型 | L1 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | License | 文件头 | **缺少 Copyright 头部**（其他文件都有 `Copyright (c) 2017-2026 yexuejc` 头部） |
+| 2 | 🟡 | Author | L29 | `@author maxiaofeng` 与其他文件 `yexuejc` 不一致 |
+| 3 | 💭 | Nit | L362 | 私有构造函数正确 |
+
+#### DateTimeUtil.java
+| # | 级别 | 类型 | **大量方法** | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | **约 30+ 个方法** | 绝大多数方法的 `@param`/`@return` **无描述内容**。例如 `getYear4First()` 的 `@return` 为空；`parseDate(ZonedDateTime)` 的 `@param zonedDateTime` 无说明 |
+| 2 | 💭 | Nit | L451-481 | 存在注释掉的 main 方法块（建议删除或移至测试） |
+| 3 | ✅ | 版本兼容 | — | 无高版本语法，jre8 可编译 |
+
+#### DateUtil.java
+| # | 级别 | 类型 | 整体 | 描述 |
+|---|------|------|------|------|
+| 1 | ✅ | — | — | 已标记 `@Deprecated`，ThreadLocal 修复了线程安全 |
+| 2 | 🟡 | Javadoc | 部分方法 | `@param`/`@return` 缺描述，但比 DateTimeUtil 好 |
+
+#### ExcelImportUtil.java
+| # | 级别 | 类型 | 全文件 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | **全部 3 个方法** | `@param`/`@return` 全部无描述 |
+| 2 | 💭 | Nit | L53 | `validateExcel()` 逻辑可简化：`return isExcel2003(filePath) || isExcel2007(filePath)` |
+
+#### FileUtil.java
+| # | 级别 | 类型 | 多处 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | **约半数方法** | `@param`/`@return` 缺描述或过于简略（如 `@param fileName` 无说明） |
+| 2 | 🟡 | 日志 | L49 | 使用 `java.util.logging.Logger` 而非项目中统一的 `System.Logger`（与 RSA、RSA2 等不一致） |
+| 3 | 🔴 | **Bug** | L295 | `connectBytes(front, after)` 中 **System.arraycopy 参数顺序错误**：`System.arraycopy(front, 0, result, 0, after.length)` 应该是 `result, front.length, after.length` —— **数据会被错误截断或越界** |
+| 4 | 🟡 | 资源 | L469 | `readBigFile(CSV)` catch 块中将 `BaseException` 包装为 `RuntimeException` 再抛出，破坏了异常体系一致性 |
+| 5 | 💭 | Nit | L54 | 定义了 `NEW_LINE = "\n"` 而 `SymbolicConsts.NEW_LINE` 已存在，应复用常量 |
+
+#### IdcardValidator.java
+| # | 级别 | 类型 | — | 描述 |
+| --- | --- | ------|------|------|
+| 1 | ✅ | — | — | **全场最佳实践范例**。Javadoc 完整，逻辑严谨，校验全面 |
+
+#### ImgUtil.java
+| # | 级别 | 类型 | L51, L192, L220 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | 异常处理 | 多处 | 使用 `e.printStackTrace()` 而非日志框架记录，在生产环境中堆栈可能泄露到 console |
+| 2 | 🟡 | Javadoc | 部分方法 | `getByteArray(ByteArrayOutputStream)` 等 `@param` 无描述 |
+| 3 | 🔴 | **Bug** | L266 | `connectBytes(front, after)` **同 FileUtil 的问题**：`System.arraycopy` 的 srcPos/destPos 参数可能导致数组拷贝越界 |
+
+#### JsonUtil.java
+| # | 级别 | 类型 | L161 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | TODO | `initSnakeCase()` | 标注了 `//TODO 待优化` 但未说明具体优化方向 |
+| 2 | 🟡 | Javadoc | 静态初始化方法 | `setJavaTimeModule()`, `initDefaultObjectMapper()` 等 private 方法的 Javadoc 是给外部用的（实际也是 private），但参数 `@param jsonMapper` 描述尚可 |
+| 3 | 🟡 | 异常处理 | 多个 `json2Obj()` 重载 | 异常被 catch 后仅 log warning 并返回 null，调用方可能不知道为何反序列化失败（建议至少打印一次 error 级别的日志） |
+
+#### JwtUtil.java
+| # | 级别 | 类型 | L52 | 描述 |
+|---|------|------|------|------|
+| 1 | 🔴 | **Bug** | `instace()` | **方法名拼写错误**：应为 `instance()`。这是公开 API，影响所有调用者 |
+| 2 | 🟡 | 版本兼容 | L173 | `var builder = Jwts.builder()` 使用了 **`var` 关键字**。jre8/jre10/jre11 不支持 var，需确认目标分支 |
+| 3 | ✅ | 安全 | — | 密钥长度校验完善，线程安全说明清晰 |
+
+#### MapRemoveNullUtil.java
+| # | 级别 | 类型 | L31-67 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | **全部 3 个公开方法** | `@param Map map` 无任何描述 |
+| 2 | 💭 | Nit | L79-107 | `remove()` 死代码方法未被使用（死代码） |
+
+#### MoneyUtil.java
+| # | 级别 | 类型 | 全文件 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | **全部 6 个方法** | `@param`/@return` 全部缺描述（仅有 `@Title/@Description` 残留旧格式） |
+| 2 | 🟡 | 线程安全 | 多处 | `DecimalFormat` 在每次调用时新建（`new DecimalFormat("0.00")`），虽线程安全但性能可优化为静态成员或 ThreadLocal |
+| 3 | 💭 | Nit | L72-80 | `toFen()` 返回 `int`，大金额可能溢出（应返回 long 或 BigDecimal） |
+
+#### MsgUtil.java
+| # | 级别 | 类型 | — | 描述 |
+| --- | --- | ------ | ------|
+| 1 | ✅ | — | SPI 设计良好，文档充分 |
+
+#### ObjUtil.java
+| # | 级别 | 类型 | L393 | 描述 |
+|---|------|------|------|------|
+| 1 | 🔴 | **严重** | `System.out.println(e.getMessage())` | **使用了 System.out.println 而非日志框架**，生产环境可能丢失关键错误信息 |
+| 2 | 🟡 | Javadoc | 约 15+ 个方法 | 大量方法的 `@param`/`@return` 缺描述或不规范 |
+| 3 | 🟡 | 性能 | `getUnderlineMap()` | 每次调用都通过反射遍历所有字段（含父类），高频场景下可能有性能影响，FIELD_CACHE 缓存了 Field 列表但未缓存 get/setter |
+
+#### RegexUtil.java
+| # | 级别 | 类型 | — | 描述 |
+| --- | --- | ------ | ------|
+| 1 | ✅ | — | 常量文档完善，唯一公开方法 `regex()` Javadoc 完整 |
+
+#### StrUtil.java
+| # | 级别 | 类型 | 多处 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | 约 20+ 个方法 | 部分 `@param`/`@return` 缺描述（如 `isEmpty()`, `isNotEmpty()` 的 `@obj` 描述尚可，但 `toMD5()`, `codeId()` 等 Deprecated 方法需关注） |
+| 2 | ✅ | 安全 | MD5 标注了 `@deprecated` 并警告不安全用途 |
+| 3 | ✅ | 版本兼容 | 无高版本语法 |
+
+#### SysUtil.java
+| # | 级别 | 类型 | 多处 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | 约 10 个方法 | 部分方法 `@param`/`@return` 缺描述 |
+| 2 | 🟡 | 线程 | L69-86 | `threadRun()` 创建 `ThreadPoolExecutor` 后立即 `shutdown()`，对于异步任务来说可能来不及执行就关闭了。应考虑提交任务后再 shutdown + awaitTermination |
+| 3 | 💭 | Nit | L185 | `formatByte()` 使用 `DecimalFormat` 非线程安全（虽在 private 方法中且单线程调用路径，但隐患仍存在） |
+
+#### ZipUtil.java
+| # | 级别 | 类型 | L40 | 描述 |
+|---|------|------|------|------|
+| 1 | 🟡 | Javadoc | `createZipFile()` | `@param zipFileBean` 无描述，且该方法抛出 `ZipException` 但未在 Javadoc 中标注 `@throws` |
+| 2 | 🟡 | 安全 | L46 | 使用 `ZIP_STANDARD` 加密（ZipCrypto 标准），密钥从 Bean 的 `getEncryptPwd().toCharArray()` 获取，强度取决于调用方 |
+
+---
+
+## 三、🔴 Blocker 级别问题汇总（必须修复）
+
+| # | 文件 | 问题 | 影响分支 | 修复建议 |
+|---|------|------|----------|----------|
+| 1 | **RSA.java:262** | `switch` 表达式（`->` 箭头语法） | jre8, jre11 | 改为 if-else-if 链式 |
+| 2 | **JwtUtil.java:173** | `var builder = Jwts.builder()` 局部变量推断 | jre8, jre10, jre11 | 显式声明类型 `JwtBuilder builder =` |
+| 3 | **JwtUtil.java:52** | `instace()` 方法名拼写错误 | 全分支 | 重命名为 `instance()` |
+| 4 | **RequestHeader.java:121** | `geRespTime()` 方法名拼写错误 | 全分支 | 重命名为 `getRespTime()` |
+| 5 | **FileUtil.java:295** | `connectBytes()` 数组拷贝参数顺序错误，可能越界 | 全分支 | 修正 `System.arraycopy` 的 destPos 和 length |
+| 6 | **ImgUtil.java:266** | `connectBytes()` 同上数组拷贝越界 Bug | 全分支 | 同上修正 |
+| 7 | **ObjUtil.java:393** | `System.out.println()` 残留 | 全分支 | 替换为 `log.log(Level.SEVERE, ...)` |
+
+---
+
+## 四、🟡 Major 级别问题汇总（应当修复）
+
+| # | 文件 | 问题数量 | 主要问题概要 |
+|---|------|--------|-----------|
+| 1 | **util 包全体** | ~60+ 处 | @param/@return/@throws Javadoc 缺失或无描述 |
+| 2 | **DateTimeUtil.java** | ~30 处 | 方法 Javadoc 全部无 @return/@param 描述 |
+| 3 | **FileInput.java** | 12 处 | 所有方法 Javadoc 缺 param/return 描述 |
+| 4 | **AlgorithmUtil.java** | 5 处 | Javadoc 格式混乱，内部类 NextCodeException 缺 Serial |
+| 5 | **MoneyUtil.java** | 6 处 | Javadoc 完全缺失（沿用旧格式）；`toFen()` int 返回可能溢出 |
+| 6 | **ExcelImportUtil.java** | 3 处 | Javadoc 完全缺失 |
+| 7 | **MapRemoveNullUtil.java** | 3 处 | Javadoc 完全缺失；死代码 `remove()` |
+| 8 | **FileUtil.java** | 3 处 | 日志框架不一致（用 java.util.logging）；异常包装不一致 |
+| 9 | **JsonUtil.java** | 2 处 | TODO 待优化标记未处理；异常处理静默吞掉 |
+| 10 | **SysUtil.java** | 2 处 | ThreadPoolExecutor 可能来不及执行；DecimalFormat 非线程安全 |
+| 11 | **CsvUtil.java** | 1 处 | 缺少 Copyright 头部；author 不一致 |
+| 12 | **ZipUtil.java** | 1 处 | createZipFile 缺少 @throws 标注 |
+| 13 | **RSA2.java** | 1 处 | 异常消息未使用 ExpCode 常量化 |
+| 14 | **RespConsts.java** | 1 处 | 常量命名风格不统一（DATE_KEY_* vs 其他） |
+| 15 | **DateConsts.java** | 1 处 | 部分常量缺注释 |
+| 16 | **BaseException/BaseRuntimeException** | 各 2 处 | @return 无描述；`@SuppressWarnings` 未解释 |
+
+---
+
+## 五、💭 Minor 级别问题（可选修复）
+
+| # | 文件 | 问题 |
+|---|------|------|
+| 1 | 多文件 | serialVersionUID 缺少 `@Serial` 注解 |
+| 2 | BaseVO.java | 内部接口 Add/Del/Mdfy/Srch 命名不规范 |
+| 3 | AlgorithmUtil.java | StringBuffer → StringBuilder |
+| 4 | FileInput.java | Scanner Z 未用 try-with-resources |
+| 5 | DateTimeUtil.java / DateUtil.java | 注释掉的 main 方法块 |
+| 6 | JsonUtil.java | initSnakeCase() TODO 标记 |
+| 7 | MapRemoveNullUtil.java | remove() 死代码 |
+| 8 | MoneyUtil.java DecimalFormat 每次新建 |
+| 9 | SysUtil.java | DecimalFormat 线程安全 |
+| 10 | RSA.java | volatile 字段直接暴露 |
+
+---
+
+## 六、Java 版本兼容性专项检测
+
+### jre8 不兼容语法（影响 jre8/jre11 分支）
+
+| 文件 | 行号 | 不兼容代码 | 修复方案 |
+|------|------|-----------|---------|
+| **RSA.java** | **L262-269** | `switch (keySize) { case 256 -> ...; default -> throw ...; }` | 改为 if-else-if |
+| **JwtUtil.java** | **L173** | `var builder = Jwts.builder()` | 改为 `JwtBuilder builder = Jwts.builder()` |
+
+### jre11 不兼容语法
+
+> 当前未发现 switch 表达式以外的不兼容项。
+
+### jre17 不兼容语法
+
+> 当前未发现 jre17 以上专属语法。
+
+---
+
+## 七、优先修复建议 TOP 10
+
+1. **[Blocker] RSA.java:262** — `switch` 表达式改 if-else，直接影响 jre8 编译
+2. **[Blocker] JwtUtil.java:173** — `var` 改显式类型，同上
+3. **[Blocker] JwtUtil.java:52** — `instace()` → `instance()`，API 拼写错误
+4. **[Blocker] RequestHeader.java:121** — `geRespTime()` → `getRespTime()`
+5. **[Blocker] FileUtil.java:295 & ImgUtil.java:266** — `connectBytes()` 数组拷贝 Bug 修正
+6. **[Major] ObjUtil.java:393** — `System.out.println` → 日志框架
+7. **[Major] util 包整体** — 补齐 @param/@return/@throws Javadoc（优先工具类：StrUtil, FileUtil, JsonUtil）
+8. **[Major] DateTimeUtil.java** — 30+ 方法补齐 @return/@param 描述
+9. **[Major] FileUtil.java** — 统一日志框架 + 清理异常包装
+10. **[Major] MoneyUtil.java** | `toFen()` 返回值类型修正 + 补齐 Javadoc
+
+---
+
+*报告生成时间: 2026-05-15*
+*审计工具: Code Reviewer Expert (SonarLint / Checkstyle 标准)*