feat(route): 扩展 QueueMode 支持批处理模式并新增通道路由列表查询接口

[muverystrong]

关联 Issue

Closes #649

变更摘要

1. QueueMode 扩展（api/spi/.../QueueMode.java）：将 PULL(1) 重命名为 SINGLE(1)，新增 BATCH(4)、SINGLE_ROUTE(3)、BATCH_ROUTE(6)，改用位掩码（SINGLE_BIT=1, ROUTE_BIT=2, BATCH_BIT=4）实现模式组合，增加 supportsBatch()、toWorkerMode()、toWorkerModeOrThrow() 方法，并校验 SINGLE 与 BATCH 不可共存。

2. ChannelRouter 重构（api/server/.../ChannelRouter.java）：从 route() 抽取 listAvailableChannels()，返回按优先级/可见性排序的完整通道列表；route() 取首个结果，行为与原逻辑等价。

3. 新增路由查询接口（api/server/.../RouteController.java）：POST /v1/route/list 接受 apikey/endpoint/model/queueMode，验证 apikey 后返回 List<RouteResult>，供外部调度系统感知可用通道。

4. SDK 同步（api/sdk/.../OpenapiClient.java）：新增 listAvailableChannels() 封装对新接口的调用。

5. ChannelService / ModelService：listAllWorkerChannels() 查询条件更新为新 QueueMode 枚举值；listActives() 与 fetchTerminalModelName() 缓存注解暂时注释，待验证后恢复。

6. 版本号：1.2.74 → 1.2.75。

验证证据

• route() 重构前后行为等价：原 pickMaxPriority(filteredChannels).get(0) 与新 listAvailableChannels().get(0) 排序逻辑一致
• QueueMode 位运算：SINGLE=001、ROUTE=010、BATCH=100，互斥校验防止非法组合
• 需重点确认：listActives() 与 fetchTerminalModelName() 禁用缓存后的生产性能影响

上线说明

• QueueMode.PULL 重命名为 SINGLE，外部若有直接引用枚举名需同步更新
• 新增 POST /v1/route/list 接口，无数据库变更

回退说明

回退至版本 1.2.74 可恢复原行为；使用新 QueueMode 枚举值的通道配置需同步回滚。

[szl97]

@claude 检查提交的代码，使用中文回复

[szl97]

Claude finished @szl97's task —— View job

---

代码审查完成 ✅

正在对 PR #650 进行代码审查，主要变更包括 QueueMode 扩展和新增通道路由列表查询接口。

任务清单

• 分析 QueueMode 枚举变更和位运算实现
• 审查 ChannelRouter 重构逻辑
• 检查新增 RouteController 接口实现
• 验证 SDK 客户端集成
• 评估缓存禁用对性能的影响
• 检查版本号更新和依赖关系
• 提供综合代码审查反馈

---

📋 代码审查结果

✅ 设计良好的方面

1. QueueMode 位运算设计：使用位掩码（SINGLE_BIT=1, ROUTE_BIT=2, BATCH_BIT=4）实现模式组合，设计清晰且扩展性良好
2. ChannelRouter 重构：成功从 route() 抽取了 listAvailableChannels() 方法，逻辑分离合理
3. API 接口设计：新增的 POST /v1/route/list 接口参数和返回结果设计一致，便于外部调度系统使用
4. 向后兼容性：虽然 PULL 重命名为 SINGLE，但通过 QueueMode.of() 方法保持了数值兼容性

⚠️ 需要关注的问题

1. 缓存禁用的性能风险（api/server/src/main/java/com/ke/bella/openapi/service/ModelService.java:265，api/server/src/main/java/com/ke/bella/openapi/service/ChannelService.java:177）

   // @Cached(name = modelTerminalCacheKey, key = "#modelName")  // 被注释掉
   public String fetchTerminalModelName(String modelName) {
   
   // @Cached(name = channelCacheKey, key = "#entityType + ':' + #entityCode")  // 被注释掉  
   public List<ChannelDB> listActives(String entityType, String entityCode) {

   影响：这两个方法在高频路由场景下会造成显著的数据库查询压力，建议尽快验证后恢复缓存

2. QueueMode 验证逻辑（api/spi/src/main/java/com/ke/bella/queue/QueueMode.java:79）

   return !(hasSingle && hasBatch);  // SINGLE 和 BATCH 互斥校验

   建议：考虑在异常信息中明确说明互斥原因，便于调试

3. ChannelRouter 中的重复逻辑（api/server/src/main/java/com/ke/bella/openapi/protocol/ChannelRouter.java:234-281）

   • 新的 route() 和 listAvailableChannels() 方法与原有路由逻辑部分重复
   • 建议统一使用新的方法，减少代码重复

🔧 具体改进建议

1. QueueMode.isValid() 错误信息优化：

   // 当前实现
   return !(hasSingle && hasBatch);
   
   // 建议改进
   if (hasSingle && hasBatch) {
       throw new IllegalArgumentException("SINGLE 和 BATCH 模式不能同时存在，当前值：" + code);
   }

2. ChannelRouter.listAvailableChannels() 空值处理：

   // 当前 256 行
   if(CollectionUtils.isEmpty(channels)) {
       return null;  // 建议返回空集合而非 null
   }

3. RouteController 异常处理：
   当 listAvailableChannels() 返回空集合时，建议返回明确的错误信息而非空列表

📊 业务逻辑验证

1. 路由等价性：✅ 验证通过

   • 原逻辑：pickMaxPriority(filteredChannels).get(0)
   • 新逻辑：listAvailableChannels().get(0)
   • 排序规则一致，行为等价

2. 队列模式支持：✅ 设计合理

   • SINGLE(1)、ROUTE(2)、BATCH(4) 的位运算组合逻辑正确
   • listAllWorkerChannels() 正确更新为新的枚举值

3. 版本升级：✅ 版本号从 1.2.74 升至 1.2.75，所有模块版本保持一致

🚀 上线建议

1. 优先级 HIGH：尽快恢复 fetchTerminalModelName() 和 listActives() 的缓存配置
2. 监控重点：关注新接口的响应时间和数据库查询频次
3. 回滚准备：确保外部系统调用新 QueueMode 枚举时的兼容性测试

📝 总体评价

代码整体设计良好，逻辑清晰，向后兼容性处理得当。主要风险在于缓存禁用可能带来的性能影响，建议在生产环境部署前优先解决缓存问题。新增的路由列表查询功能为外部调度系统提供了良好的支持。

建议状态：建议合并，但需先处理缓存配置问题

---