2026-06-01｜订单关注模块：查询即关注与状态调度

1. 模块开发与功能实现#

今天主要围绕订单交付查询模块中的”订单关注”能力展开开发。该能力的目标是：用户通过订单交付查询输入订单号后，系统自动将该订单加入个人关注列表；后续订单状态发生变化时，系统能够基于关注关系进行状态检测，并为企微推送通知预留能力。

本次已实现的核心业务规则包括：

• 查询即关注：用户输入订单号并完成查询后，自动加入个人关注列表；
• 手动开关：订单结果卡片右上角提供关注按钮，用户可手动关注或取消关注；
• 关注去重：同一用户对同一订单只能关注一次，重复查询时返回”已关注该订单”；
• 多人独立关注：多个用户可以同时关注同一订单，互不影响；
• 手动取消关注：用户取消关注后，将记录标记为 is_manual_unfollow=1；
• 取消后不再自动关注：用户手动取消后，再次查询不会自动重新关注；
• 重新关注：用户可通过按钮或 /resume 接口恢复关注；
• 关注列表查询：支持查询当前用户的所有活跃关注订单；
• 状态终止自动取消：订单到货、签收、取消或作废后，系统可自动将关注状态更新为完成。

该模块补齐了订单交付查询场景下的持续跟踪能力，为后续”订单状态变化后企微通知用户”提供了基础数据和触发条件。

2. 数据库设计与状态模型#

今天完成了订单关注模块的数据表设计，新增 portal_order_follow 表，用于保存用户与订单之间的关注关系。

表中核心字段包括：

• sys_user_id：关注人用户 ID；
• order_number：关注订单号；
• status：关注状态，支持 FOLLOWING、UNFOLLOWED、COMPLETED；
• last_order_status：上一次检测到的订单状态快照；
• last_est_delivery_time：上一次检测到的预计发货时间快照；
• is_manual_unfollow：是否由用户手动取消关注；
• followed_at：关注时间；
• unfollowed_at：取消关注或自动完成时间。

其中，UNIQUE KEY uk_user_order (sys_user_id, order_number) 用于保证同一用户对同一订单只能存在一条关注记录。

本次设计中的关键点是引入 is_manual_unfollow 字段。该字段解决了”查询即关注”和”用户手动取消”之间的冲突：用户手动取消后再次查询同一订单时，系统不会自动恢复关注，只有用户主动点击重新关注时才会将状态恢复为 FOLLOWING。

3. 后端接口与业务逻辑开发#

今天完成了订单关注模块的后端主体开发，新增以下核心文件：

• PortalOrderFollow.java：订单关注实体；
• PortalOrderFollowMapper.java：订单关注 Mapper；
• OrderFollowService.java：订单关注业务逻辑层；
• OrderFollowController.java：订单关注 REST 接口；
• OrderFollowScheduler.java：订单状态变更检测调度器。

本次实现的后端接口包括：

1
POST   /api/portal/order-follow/{orderNumber}
2
DELETE /api/portal/order-follow/{orderNumber}
3
POST   /api/portal/order-follow/{orderNumber}/resume
4
GET    /api/portal/order-follow/{orderNumber}/follow-status
5
GET    /api/portal/order-follow/list?page=1&size=20

核心业务方法包括：

• followOnQuery(auth, orderNumber)：查询即关注，处理去重和手动取消检测；
• unfollow(auth, orderNumber)：用户手动取消关注；
• resume(auth, orderNumber)：用户取消后重新关注；
• getFollowStatus(auth, orderNumber)：查询单个订单关注状态；
• listMyFollows(auth, page, size)：查询当前用户关注列表；
• updateStatusSnapshot(orderNumber, status, time)：更新订单状态快照；
• autoCompleteFollow(orderNumber, reason)：订单到货、签收、取消或作废后自动解除关注；
• listDistinctActiveOrderNumbers()：获取当前活跃关注订单号列表，用于调度器去重检测。

4. 调度器状态检测能力#

今天完成了 OrderFollowScheduler 定时任务开发，用于定期检测已关注订单的状态变化。

调度器配置为：

1
首次延迟 1 分钟启动，之后每 2 小时执行一次

调度器核心流程如下：

1
获取所有活跃关注订单号（去重）
2
  → 调用 OrderDeliveryService 查询最新订单状态
3
  → 首次检测时记录初始快照
4
  → 状态变更为已到货 / 已签收时自动完成关注
5
  → 状态变更为取消 / 作废时自动完成关注
6
  → 预计发货时间变化时记录日志并预留企微推送能力
7
  → 订单状态变化时记录日志并预留企微推送能力

当前调度器已完成状态检测和自动完成关注逻辑，企微消息推送模板已预留但尚未正式接入。

5. 前端交互改造#

今天还完成了订单关注模块的前端交互接入，主要修改 src/main/resources/static/app.js。

前端改动包括：

• 在 queryOrderByTid() 调用订单查询成功后，新增 autoFollowOrder(data.tid) 自动关注；
• 在 showOrderResult() 的订单结果卡片标题区域新增关注按钮；
• 新增 autoFollowOrder()、toggleFollowOrder()、updateFollowButtons() 三个函数；
• 根据当前关注状态显示”关注”或”已关注”；
• 点击按钮时根据状态调用关注、取消关注或重新关注接口。

由于订单交付查询结果卡片并不是 Vue / React 组件，而是后端返回 HTML 后由前端拼接字符串渲染，因此本次采用在 showOrderResult() 的 HTML 模板字符串中插入按钮，并通过 setTimeout 绑定事件监听器的方式完成交互接入。

6. 测试验证与问题处理#

今天完成了订单关注模块的 API 测试，共验证 11 项场景，结果均通过。

测试覆盖内容包括：

• 查询即关注；
• 重复查询去重；
• 多个订单同时关注；
• 关注列表查询；
• 单订单关注状态查询；
• 手动取消关注；
• 取消后状态验证；
• 取消后查询不自动关注；
• 重新关注；
• 到货自动完成关注；
• 空订单号校验。

同时完成了调度器验证。日志显示调度器能够正常启动并检测活跃关注订单：

1
[FollowScheduler] 开始状态变更检测
2
[FollowScheduler] 检测 5 个订单
3
[FollowScheduler] 检测完成: 5 订单, 0 变更, 0 自动完成

该结果说明调度器已能正常获取关注订单并执行状态检测流程。

7. 开发难点与解决方案#

1. 后端 HTML 渲染页面不便接入交互组件#

• 问题：订单交付查询结果卡片由后端生成 HTML，前端没有完整组件化结构，无法直接以 Vue / React 方式添加按钮。
• 处理：在 showOrderResult() 拼接 HTML 时直接插入关注按钮，并在渲染后绑定点击事件。
• 结果：在不大规模重构页面的情况下完成了关注按钮接入。

2. 查询即关注与手动取消存在逻辑冲突#

• 问题：如果每次查询都自动关注，用户手动取消后再次查询会被重新关注，违背用户操作预期。
• 处理：新增 is_manual_unfollow 字段，用户手动取消后再次查询不自动关注，只允许通过 /resume 接口主动恢复。
• 结果：实现了查询即关注和手动取消之间的互斥控制。

3. 调度器需要判断订单状态变化#

• 问题：订单系统没有实时推送机制，无法即时感知订单状态变化。
• 处理：通过调度器定时轮询关注订单，并在关注表中保存上次订单状态和预计发货时间快照，用于后续对比。
• 结果：完成了基于轮询和快照比对的状态变化检测机制。

4. 测试环境订单数据存在缺失#

• 问题：本地 productsys 数据较旧，部分订单缺少产品行数据，影响测试。
• 处理：通过 SQL 查找具有完整 JOIN 数据的订单号，并使用这些订单进行验证。
• 结果：解决了测试数据不可用导致的功能验证问题。

5. 测试用户受订单交付权限限制#

• 问题：测试用户不在部分订单业绩链中，订单交付查询会被权限拦截。
• 处理：在查看全部订单交付数据授权表中加入测试用户。
• 结果：绕过测试环境权限限制，保证订单关注功能可以正常验证。