v2.0.2（20260731）

IMPORTANT

本节对应 v2.0.1 之后的发布代码。

1. 升级范围

本次待发布变化集中在 Java LTS 兼容、后端与前端依赖、WebSocket 消息契约、滑块验证码和 AI 协作支持：

• 后端支持使用 Java 21 或 Java 25 构建与运行，但产物继续保持 Java 21 字节码基线。
• Spring Boot、Jackson、MyBatis-Flex、数据库驱动及前端工具链集中升级。
• WebSocket 消息数据改为跨服务可反序列化的通用对象结构。
• 滑块验证码改为服务端计时，并为每次获取生成独立 requestId。
• 新增项目知识入口、标准 Skill、JSON Schema 和只读 MCP。

本范围没有新增 Liquibase changeSet，不需要数据库表结构或初始化数据迁移。

2. Java 21 / 25 LTS 兼容策略

当前默认和最低基线仍是 Java 21，Java 25 作为兼容运行时：

场景	Java 21	Java 25
本地 Maven 构建	默认支持	支持
运行项目 JAR	支持	支持
编译产物	Java 21 字节码	仍为 Java 21 字节码
官方 MySQL 镜像	registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-admin:latest	registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-admin:latest-jdk25
官方 PostgreSQL 镜像	registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-admin:latest-postgresql	registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-admin:latest-postgresql-jdk25
官方 WebSocket 镜像	registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-websocket:latest	registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-websocket:latest-jdk25

可直接执行以下命令下载对应镜像：

# Admin MySQL
docker pull registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-admin:latest
docker pull registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-admin:latest-jdk25

# Admin PostgreSQL
docker pull registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-admin:latest-postgresql
docker pull registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-admin:latest-postgresql-jdk25

# WebSocket
docker pull registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-websocket:latest
docker pull registry.cn-beijing.aliyuncs.com/sz-dev/sz-service-websocket:latest-jdk25

根 POM 使用 maven.compiler.release=21。因此使用 Java 25 执行 Maven 时，也不能在主线代码中使用 Java 22—25 专属 API、语法或 preview feature。

WARNING

不要把现有服务器的 latest 或 latest-postgresql 理解为 Java 25 镜像。这两个历史标签继续使用 Java 21；只有显式带 -jdk25 的标签使用 Java 25 运行时。

双版本兼容政策计划执行至 2026-08-31。计划自 2026-09-01 起提升 Java 25 默认与最低基线，但日期到达本身不会改变仓库配置；必须等待独立迁移变更、验证和正式发布公告。

3. 后端依赖升级

依赖	v2.0.1	当前待发布
Spring Boot	4.0.6	4.1.0
Jackson	3.1.3	3.2.1
MyBatis-Flex	1.11.7	1.11.8
MyBatis Spring	4.0.0	4.1.0
MySQL Connector/J	9.4.0	9.7.0
PostgreSQL JDBC Driver	42.7.5	42.7.13
HikariCP	7.0.2	7.1.0
yauaa	7.32.0	8.1.1

二开项目如果覆盖了 Spring Boot BOM、Jackson、MyBatis-Flex、数据库驱动或 Maven Compiler Plugin 版本，应先移除无必要的覆盖，再检查自定义 starter、TypeHandler、序列化配置和数据库连接。

建议分别使用 Java 21、Java 25 执行以下验证：

mvn clean verify -DskipTests=false -DskipITs=false -Pmysql
mvn clean verify -DskipTests=false -DskipITs=false -Ppostgresql
bash .github/scripts/check-java-class-version.sh 65

4. WebSocket 消息契约

后台发送 MESSAGE 频道消息时，不再把 PayloadBody 业务 DTO 直接放入跨服务消息，而是转换为通用对象：

{
  "channel": "MESSAGE",
  "data": {
    "title": "消息标题",
    "content": "消息内容"
  }
}

官方前端同时兼容对象和历史 JSON 字符串。二开客户端如果仍固定执行 JSON.parse(data)，需要改为：

const notice = typeof data === 'string' ? JSON.parse(data) : data || {};

升级后至少回归后台发送消息、前端实时通知、未读数刷新、消息列表刷新和 WebSocket 独立服务重启后的消息转发。

5. 滑块验证码契约

验证码校验耗时不再信任客户端 startTime，由后端保存验证码生成时间并计算。前端校验参数调整为：

type CaptchaVerifyImageParams = {
  requestId: string;
  moveEncrypted: string;
  iv: string;
};

每次调用 /captcha/get 都会返回新的 requestId。自定义前端必须使用当前图片对应的 requestId，刷新验证码后不得继续提交旧标识。

升级后至少回归：

1. 正常拖动验证成功。
2. 连续获取两次验证码，两个挑战按各自 requestId 独立验证，校验数据互不覆盖。
3. 已完成校验的 requestId 无法重复使用；缺失 IV 返回参数缺失，非法密文、AES-GCM 解密失败和错误位移返回验证码验证失败。
4. 同一 IP + User-Agent 的验证码获取频率仍受原有限流配置控制。

6. 安全白名单配置

router.whitelist 现在默认初始化为空集合。生产环境未配置该字段时，服务不再因拦截器注册空指针而启动失败。

这项容错不等于自动添加公共接口。已有环境应继续核对登录、验证码、OpenAPI、静态资源等需要匿名访问的路径；缺少必要白名单仍会导致请求被认证链拦截。

7. 前端依赖升级

依赖	v2.0.1	当前待发布
Axios	1.16.1	1.18.0
Vite	7.3.3	7.3.5
TypeScript	5.2.2	5.9.3
vue-tsc	2.2.12	3.3.8
ESLint	9.39.4	10.8.0
VueUse	14.3.0	14.4.0
Jodit	4.12.2	4.12.26

升级时保留 pnpm-lock.yaml 和 pnpm.overrides，不要只复制 package.json 后重新解析依赖。推荐执行：

corepack prepare pnpm@10.17.1 --activate
pnpm install --frozen-lockfile
pnpm run type-check
pnpm run build

二开项目如有自定义 ESLint 配置、Vue 宏类型、Vite 插件或 vue-tsc 检查规则，应单独回归，不要通过关闭类型检查或删除规则制造构建通过。

返回升级索引