2026-06-02｜企微推送接入与订单关注模块完善

1. 企微应用消息推送能力接入#

今天在订单关注模块中补齐了企微应用消息推送能力。订单关注模块的业务目标是：用户关注某个订单后，当订单预计发货时间变化、订单已发货或订单已到货时，系统能够主动向关注者推送企微通知。

项目中原本存在 AI 机器人 WebSocket 通信方式，但该方式更适合对话式交互，主动推送依赖用户先与机器人产生过消息交互。订单关注通知属于服务端主动触发的批量通知场景，因此今天最终选择接入 企业微信应用消息 HTTP API。

该方案的优势是：不依赖用户是否先向机器人发过消息，适合服务端主动通知，可通过企业微信 userid 直接发送消息，并且与订单关注调度器的定时检测机制天然匹配。

本次新增 WecomAppPushService，用于统一封装企微应用消息推送能力，包括 access_token 获取、缓存、刷新和文本消息发送。为了避免 token 边界过期问题，服务中对 access_token 进行内存缓存，并在过期前提前刷新。

2. 订单关注调度器接入推送链路#

今天对 OrderFollowScheduler 进行了改造，使其不仅能检测关注订单状态变化，还能在状态变化时调用企微推送服务。

当前调度器执行链路如下：

1
OrderFollowScheduler 定时执行
2
  → 查询 portal_order_follow 中 status=FOLLOWING 的关注记录
3
  → 按订单号去重
4
  → 查询 OMS 最新订单状态
5
  → 对比上次状态和预计发货时间快照
6
  → 若预计发货时间变更，推送企微提醒
7
  → 若订单已发货，推送企微提醒
8
  → 若订单已到货，推送企微提醒并自动完成关注

在推送内容上，今天设计了三类基础消息模板：预计发货时间变更通知、订单已发货通知、订单已到货通知。当前消息类型采用 text 文本消息，保证企微应用消息兼容性较好，也便于后续快速迭代模板内容。

3. 用户身份映射改造#

今天在开发过程中明确并解决了用户身份映射问题。系统中存在两个容易混淆的用户标识：

• sys_user_id：门户系统用户主键；
• wecom_user_id：企微 userid，实际使用中对应员工工号。

原有 portal_order_follow.sys_user_id 存储的是门户系统用户 ID，不能直接作为企微推送的 touser 参数。为了避免推送时使用错误身份标识，今天在 portal_order_follow 表中新增 wecom_user_id 字段。

关注订单时，系统会从认证上下文中提取 sysUserId 和 employeeCode。后续调度器推送时，直接读取关注记录中的 wecom_user_id 作为企微应用消息的接收人，避免每次推送再做跨表映射，也降低推送链路复杂度。

4. 调度器查询 OMS 权限问题修复#

今天排查到调度器在查询 OMS 订单状态时，最初会出现”无产品行”或查询结果为空的问题。进一步排查发现，根因不是 OMS 数据不存在，也不是 SQL 本身错误，而是 OrderDeliveryService.queryOrder() 需要 viewer 凭证参与权限校验。

原调度器调用查询订单时传入的 viewer 信息为空，导致权限校验拦截后返回空产品行，调度器误判为订单无产品信息。

修复方式是：调度器先根据订单号查询活跃关注记录，从关注记录中取出关注人的 sysUserId 和 wecomUserId，调用 OrderDeliveryService.queryOrder() 时将这两个字段作为 viewer 凭证传入。对于本地测试中 CRM 权限链无法通过的情况，则通过测试授权表临时增加全量查看权限。

修复后，调度器能够正常查询订单状态，为后续状态变更检测和企微推送提供基础数据。

5. RestTemplate Content-Type 问题修复#

今天排查企微推送失败时，发现虽然推送参数和 userid 都正确，但企微接口返回了 JSON 格式错误和 invalid message type 相关错误。

进一步对比 Java 和 Python 请求后，确认根因是 Java 代码中使用 RestTemplate.postForObject(url, jsonString, Map.class) 直接传入字符串，Spring 默认使用 StringHttpMessageConverter，导致请求 Content-Type 为 text/plain，而企微接口要求 application/json。

修复方式是改用 HttpEntity 显式指定请求头：

1
HttpHeaders headers = new HttpHeaders();
2
headers.setContentType(MediaType.APPLICATION_JSON);
3
HttpEntity<String> entity = new HttpEntity<>(jsonBody, headers);
4
restTemplate.postForObject(url, entity, Map.class);

修复后，请求以 application/json 发送，企微接口能够正常解析消息体，推送成功。

该问题也让我进一步认识到：在调用第三方 HTTP API 时，不能只关注请求体内容，还需要特别关注 Content-Type、编码格式和 HTTP message converter 行为。

6. 前端关注入口完善#

今天对订单关注模块的前端交互进行了进一步完善，将原来的消息铃铛入口调整为星星图标，并将面板内容从通用消息提醒改为”我的关注订单”列表。

本次前端改造包括：

• 将页面右上角消息铃铛替换为星星图标；
• 将抽屉标题调整为”我的关注”；
• 星星面板中展示当前用户关注订单列表；
• 星星角标实时显示关注订单数量；
• 点击关注列表中的订单，可以打开订单查询结果卡片；
• 与订单卡片右上角关注按钮联动，保证关注状态与角标数量同步。

7. 开发测试端点和调试能力补充#

为了更高效地验证企微推送和调度器行为，今天新增了开发测试端点 OrderFollowTestController，用于在 dev 环境下手动触发调度器、模拟状态变化和验证推送链路。

同时在安全配置中放行 dev 测试端点，方便本地联调。通过这些调试入口，可以在不等待 2 小时定时任务自然执行的情况下，快速验证预计发货时间变化、订单状态变更为已发货、订单状态变更为已到货、已到货后自动取消关注，以及双用户同时关注同一订单时的推送效果。

8. 其他问题排查与修复#

今天在联调过程中还处理了多个附带问题。

• Gradle 构建缓存问题：修改 Java 代码后，普通编译可能显示 UP-TO-DATE，导致服务重启后修复不生效。排查后确认与 Gradle daemon 构建缓存有关，后续通过 --rerun-tasks 或清理构建目录强制重新编译解决。
• MCP jar 未构建问题：排查过程中发现 MCP 子模块 jar 未构建时，会导致部分 Agent 能力返回空 content。通过构建 mcp-stdio Shadow jar 并移除跳过 MCP 的启动 profile 解决。
• 订单输入建议数据源不一致：本地测试时，订单交付查询表单的订单号建议接口使用 SCM 数据源，而订单交付明细查询依赖 productsys 快照库。最终采用快照库中实际存在且具备完整产品行的订单号进行测试。
• admin-web 登录 localStorage key 不匹配：dev 登录页写入的 token key 与 admin-web 前端读取的 key 不一致，导致登录后仍走 OAuth。修复后将登录页 token 写入统一 key，保证本地登录链路正常。

9. 测试验证结果#

今天完成了订单关注与企微推送的多项测试验证。

单元和接口测试覆盖：查询即关注、重复关注去重、关注数量统计、取消关注、手动取消后不自动关注、重新关注、关注状态查询、检查是否存在硬编码用户或 TODO。

企微推送集成测试覆盖两名测试用户，并验证以下场景：预计发货时间变更推送、已发货推送、已到货推送、已到货后关注记录自动变为 COMPLETED。

最终验证结果显示，两名测试用户均能收到发货时间变更、已发货、已到货消息，订单到货后关注状态也能自动完成。

1. 调度器查询订单状态返回空产品行#

• 问题：调度器调用 OMS 查询订单时传入 viewer 参数为空，被订单交付权限校验拦截，导致 products 为空。
• 处理：从关注记录中读取 sysUserId 和 wecomUserId，作为 viewer 凭证传入订单查询服务。
• 结果：调度器能够正常查询 OMS 订单状态。

2. CRM 权限链校验影响本地测试#

• 问题：测试用户不一定在测试订单的 CRM 业绩链中，会被权限校验拦截。
• 处理：在测试环境中通过查看全部订单交付数据授权表为测试用户增加权限。
• 结果：测试环境可顺利验证订单关注和企微推送逻辑。

3. 企微接口返回 invalid message type#

• 问题：Java 后端调用企微接口时，接口返回 JSON 格式错误和 invalid message type。
• 处理：定位到 RestTemplate 直接发送 String 时默认 Content-Type 为 text/plain，改用 HttpEntity 显式设置 application/json。
• 结果：企微接口成功接收消息，推送链路打通。

4. Gradle 构建缓存导致修复未生效#

• 问题：修改代码后编译显示 UP-TO-DATE，服务重启后问题仍存在。
• 处理：使用 --rerun-tasks 或清理构建缓存后重新编译。
• 结果：修复代码能够正确生效。

5. MCP jar 未构建导致嵌入式表单异常#

• 问题：MCP 子模块 jar 不存在，导致部分 Agent 返回空 content。
• 处理：构建 mcp-stdio Shadow jar，并调整启动 profile。
• 结果：嵌入式表单能力恢复正常。

6. 订单建议接口与明细查询数据源不一致#

• 问题：前端订单输入建议与订单明细查询使用的数据源不同。
• 处理：使用 productsys 快照库中实际存在且具备完整产品行的订单号进行测试。
• 结果：避免因测试数据不一致影响功能验证。

7. admin-web 登录 token key 不一致#

• 问题：本地 dev 登录页写入的 token key 与 admin-web 读取的 key 不一致。
• 处理：统一写入 localStorage.admin_portal_jwt。
• 结果：本地登录链路恢复正常。