气象灾害预警：定时任务 + 钉钉群聊卡片投递

公司要实时关注广东气象局发布的灾害预警（台风、暴雨、高温……），第一时间推送到钉钉群。SmartOA 实现：定时任务扫描广东气象局预警数据 → 解析预警级别 → 钉钉互动卡片投递到群聊，卡片带详情链接和级别图标。这篇记录模块从联调到上线的完整过程，包括两个典型的「数据语义」坑。

一、整体链路

二、数据源与接口切换

广东气象局的预警接口有两个版本，联调中发现老接口（ActiveYJ）数据不全，切换到新接口：

• 初版接的接口预警数据字段不完整（缺图标 media_id）
• 切换 ActiveYJ 接口后数据完整，但图标不是 URL 而是 media_id（钉钉素材 ID）
• media_id 需要先调钉钉上传素材接口换取，卡片才能显示图标

// 图标处理：media_id 需先上传素材换取
public String getLevelIcon(String levelCode) {
    if (mediaIdCache.containsKey(levelCode)) {
        return mediaIdCache.get(levelCode);       // 缓存，避免重复上传
    }
    String mediaId = dingTalkService.uploadMedia(iconFile(levelCode));
    mediaIdCache.put(levelCode, mediaId);
    return mediaId;
}

图标全量补全：4 色通用图标（蓝=预警、黄=较重、橙=严重、红=特别严重），titleimg 统一换通用图标。

三、坑 1：预警级别编码映射错误——橙色显示蓝色

上线后第一条台风预警，橙色预警却显示蓝色图标。排查：

• 气象局接口返回的级别是数字编码（如 2=蓝色、3=黄色、4=橙色、5=红色）
• 我按「自己以为的编码」写了映射表（2=橙色），完全对不上

// 修复：按真实数据反推的映射表
private static final Map<Integer, Level> LEVEL_MAP = Map.of(
    2, Level.BLUE,     // 实测 2 → 蓝色
    3, Level.YELLOW,   // 实测 3 → 黄色
    4, Level.ORANGE,   // 实测 4 → 橙色
    5, Level.RED       // 实测 5 → 红色
);

四、坑 2：市级过滤——子串匹配误伤

需求：只推送本公司所在城市（如惠州）的预警。初版用子串匹配：预警标题包含「惠州」就推送。结果：

• 「惠州市大亚湾区」的预警被误伤——大亚湾不是市区，但标题包含「惠州」子串
• 预警区域字段是多级行政区划，子串匹配把「惠阳」「惠东」也带进来

修复：从子串匹配改为精确匹配市级行政区划代码/名称：

// ❌ 子串匹配：'惠州市大亚湾区'.contains('惠州') → 误推送
if (title.contains(cityName)) { push(); }

// ✅ 精确匹配：预警区域字段按行政区划解析，只认市级本身
if (region.equals(cityName) || region.startsWith(cityName + "市")) {
    if (isSubRegion(region)) return;   // 区/县级别不推
    push();
}

五、坑 3：预警解除要「降级」而不是「静默」

预警解除后，气象局会发一条解除记录（级别 0 或特殊编码）。初版逻辑是「无新预警就不推」，结果群里台风过境后没有任何「解除」通知，员工不知道警报已撤。修复：

• 解除记录单独识别，推送「已解除」卡片（蓝色图标 + 解除文案）
• 解除图标改蓝色（fix: 解除预警图标改蓝色）

六、定时任务配置：SmartJob 复用

定时任务复用项目现有的 SmartJob 调度体系（不单独开发），前端在 /#/job/list 管理：

执行记录导出 Excel 功能一并补齐（定时任务执行记录增加导出），便于事后核对「为什么没推」。

七、踩坑清单（可直接复用）

1. 枚举语义别猜：外部接口编码映射先拉真实数据反推，再写代码
2. 区域过滤用精确匹配：contains 子串匹配会误伤子区域
3. 解除也是事件：状态变化要推送「解除」，不能静默
4. media_id 缓存：钉钉素材上传接口有频率限制，必须缓存
5. 定时任务复用 SmartJob：别重复造调度轮子，执行记录可导出