实习日报｜2026-05-29#

1. 迭代第一期需求梳理#

今天首先与产品经理对 AI 智能助手迭代计划进行了需求梳理，重点理解第一期 9 天内需要优先推进的功能范围。通过沟通，我对本轮迭代的业务目标、优先级和各模块间关系有了更清晰的认识。

第一期需求主要包括以下方向：

1. 订单交付查询模块
   当前只支持销售设备订单查询，测试设备订单暂不支持，后续需要支持测试设备或借测设备的查询能力。

2. 供应风险预警模块
   这是本期重点之一，包含两个核心方向：

   • 供应链发起某个订单预警后，只推送给涉及该订单的销售人员，而不是推送给全部 sales 角色用户；
   • 通过红点提醒机制，让销售、供应链和合同履行角色能够看到是否存在未查看或未反馈的风险预警。

3. 交付文件查询模块
   需要解决纯软销售单在智能助手中查不到文件的问题，使其和技术支持平台一样支持查询和下载交付文件。

4. 关注功能上线
   订单交付查询模块需要支持查询某个订单后自动关注，后续发货信息变更时通过企微通知用户。

5. 供应能力查询模块
   需要关注价格审批单号查询结果数量显示不准确的问题，等待 CPQ 接口改造完成后接入。

6. 手机端页面图标调整
   需要配合移动端页面对部分图标展示进行优化。

通过这次需求梳理，我明确了今天优先落地的开发任务是供应风险预警的精准推送能力，即从原来的“推送给所有销售”改为“只推送给该订单涉及的销售”。

2. 供应风险预警精准推送需求理解#

本次开发前，供应链发起供应风险预警后，系统会将预警推送给全部拥有 sales 角色的用户。这种方式存在明显问题：

• 不相关销售会收到无关预警，信息噪声较大；
• 真正涉及该订单的销售可能被大量通知淹没；
• 合同履行经理无法精确判断该订单到底推送给了谁、谁已经反馈、谁还未反馈；
• 供应链人员和合同履行人员无法准确跟进预警闭环情况。

产品需求希望实现的是：供应链发起某个订单的风险预警后，系统根据订单号找到涉及该订单的销售人员，只向这些相关销售推送预警，并让他们填写反馈。

例如，订单 A 涉及 5 个销售，供应链发起 A 订单预警后，系统只应向这 5 个销售推送，而不是向所有销售角色用户推送。

因此，本次开发的核心不是单纯改推送接口，而是解决“订单号如何映射到相关销售人员”的问题。

3. 数据映射链路设计#

为实现精准推送，今天梳理并实现了从订单号到销售用户的完整映射链路。

整体链路如下：

1
orderId（订单号）
2
  → Oracle EBS cux.cux_om_option_tl.processor（处理人 / 销售姓名）
3
  → SCM sys_user.code（按工号精确匹配）
4
  → SCM sys_user.name（按姓名模糊回退）
5
  → SCM sys_user.user_id
6
  → portal_user_role 过滤 sales 角色
7
  → portal_supply_risk_notification 写入推送记录

该链路涉及三个数据源：

1. Oracle EBS 生产库，只读查询
   通过 cux.cux_om_option_tl 表，根据订单号查询订单涉及的 processor。

2. MySQL SCM 用户表
   通过 processor 去匹配系统用户，优先按工号精确匹配，无法匹配时按姓名进行模糊回退。

3. MySQL Portal 业务库
   通过 portal_user_role 过滤 sales 角色，最终将推送记录写入 portal_supply_risk_notification。

这种设计既能利用现有订单与处理人关系，也能避免直接依赖前端传入销售人员列表，降低人为选择错误的风险。

4. 代码开发与核心逻辑实现#

今天主要修改了供应风险预警的推送链路，核心代码改动集中在 Mapper、XML SQL 和业务 Service 三部分。

主要改动包括：

• 在 ErpMiscMapper.java 中新增 selectDistinctProcessorsByOrderNumber 接口方法；
• 在 ErpMiscMapper.xml 中新增根据订单号查询 distinct processor 的 SQL；
• 在 PortalSupplyRiskService.java 中新增 resolveOrderSalesUserIds 方法；
• 修改 createAndPublish 预警发布逻辑，将原来的全量销售推送改为按订单精准推送。

新增 SQL 的核心逻辑是：

1
SELECT DISTINCT TRIM(t.processor) AS processor
2
FROM cux.cux_om_option_tl t
3
WHERE TO_CHAR(t.order_number) = #{orderNumber}
4
  AND t.processor IS NOT NULL
5
  AND TRIM(t.processor) IS NOT NULL

resolveOrderSalesUserIds 方法的主要处理步骤包括：

1. 如果 orderId 为空或空白，则返回空列表，不进行推送；
2. 根据订单号查询 Oracle EBS 中的 distinct processor；
3. 对每个 processor，优先按 code 精确匹配 SCM 用户；
4. 如果精确匹配失败，再按 name 进行模糊回退；
5. 如果仍无法匹配用户，则跳过并记录警告日志；
6. 匹配到用户后，再过滤其是否拥有 sales 角色；
7. 最终返回去重后的 sales userId 列表。

原逻辑中，系统通过 listSalesSysUserIds() 获取全部销售用户进行推送；改造后，系统改为通过 resolveOrderSalesUserIds(req.getOrderId()) 获取订单相关销售，实现精准推送。

5. 行为变化与业务效果#

本次改造后，供应风险预警推送行为发生了明显变化：

• 如果填写了 orderId，并且订单涉及 2 个销售，则只推送给这 2 人；
• 如果未填写 orderId，则推送 0 人；
• 如果填写了 orderId，但 processor 无法映射到系统用户，则推送 0 人；
• 如果 processor 能映射到系统用户，但该用户没有 sales 角色，也不会推送。

这相比原来的“推送给全部 56 个 sales 角色用户”更加精准，也更符合业务需求。

该改造带来的价值主要包括：

• 减少无关销售收到预警的干扰；
• 提高相关销售查看和反馈预警的效率；
• 支撑合同履行经理后续进行“已推送人员”和“已反馈人员”的对账；
• 为供应风险预警模块后续红点提醒和闭环统计提供更准确的数据基础。

6. 合同履行经理看板对账支持#

今天也确认了本次精准推送对合同履行经理看板的支持方式。当前已有两个 API 可以完成推送与反馈对账：

• GET /api/portal/supply-risk/alerts/{id}/push-recipients
  用于查看预警已推送人员名单，包括姓名、部门、已读状态等。

• GET /api/portal/supply-risk/alerts/{id}/detail
  用于查看预警反馈记录，包括提交人、处置选择、影响评估等。

通过这两个接口对照，可以判断：

• 这条预警推送给了哪些销售；
• 哪些销售已经查看；
• 哪些销售已经反馈；
• 哪些销售还没有反馈。

这为第一期需求中的合同履行经理看板功能提供了数据基础，也为后续红点提醒逻辑提供了支撑。

7. 单元测试验证#

今天为 PortalSupplyRiskService 补充了单元测试，共覆盖 9 个场景，全部通过。

测试场景包括：

• orderId 为空或空白时返回空；
• 订单无 processor 时返回空；
• processor 按 code 精确匹配；
• processor 按 name 模糊回退；
• processor 无法映射时跳过；
• 映射到用户但没有 sales 角色时过滤；
• 多 processor 场景下去重、映射和角色过滤；
• 数据库异常时返回空；
• processor 含空白时跳过。

这些测试覆盖了精准推送链路中最容易出错的边界条件，保证不同数据情况下不会误推送给无关人员。

8. 端到端测试验证#

除单元测试外，今天还进行了端到端测试，测试数据来自 Oracle PROD 只读库和 MySQL 测试库。

验证结果包括：

• 订单 202501140293 映射到 processor 赵雨，最终匹配到 1 名销售，pushCount=1；
• 订单 202501090279 映射到赵雨和陈龙，最终匹配到 2 人，pushCount=2；
• 不填写 orderId 时，pushCount=0；
• 不存在订单 9999999999 时，pushCount=0；
• processor 无法映射时，pushCount=0。

端到端测试验证了从订单号查询、processor 映射、用户匹配、sales 角色过滤到推送记录生成的完整链路。

9. 安全与数据访问控制#

今天在实现过程中也注意了数据访问安全：

• Oracle PROD 只做 SELECT 查询，不执行任何写操作；
• 测试数据写入仅发生在 MySQL 测试库；
• 推送目标必须经过 portal_user_role 的 sales 角色过滤；
• 对无法匹配的 processor 不进行兜底全量推送，避免误推；
• 对空 orderId 不再默认推送给全部销售，避免无订单关联的风险预警造成大范围通知干扰。

这保证了本次迭代需求在实现精准推送的同时，也避免引入新的误推风险。

1. 原推送逻辑过于粗放#

• 问题：原逻辑通过 listSalesSysUserIds() 获取全部 sales 角色用户进行推送，导致无关销售也会收到供应风险预警。
• 处理：改为根据订单号解析涉及销售，只向订单相关 sales 用户推送。
• 结果：预警推送范围大幅收敛，避免全量推送带来的信息噪声。

2. 订单号到销售用户之间存在跨库映射链路#

• 问题：预警表中只有 orderId，无法直接知道涉及销售，需要从 Oracle EBS 查 processor，再映射到 SCM 用户。
• 处理：新增 Oracle 查询 processor 的 SQL，并通过 SCM 用户 code 精确匹配、name 模糊回退完成用户映射。
• 结果：建立了完整的订单号到销售用户的解析链路。

3. processor 可能无法匹配系统用户#

• 问题：Oracle 中的 processor 可能是姓名、工号或存在脏数据，无法保证一定能匹配到 SCM 用户。
• 处理：设计两级匹配策略，优先按 code 精确匹配，失败后按 name 模糊回退；仍失败则跳过并记录日志。
• 结果：兼顾准确性和容错性，同时避免在无法匹配时错误推送给全部销售。

4. 匹配到用户后仍需角色过滤#

• 问题：即使 processor 能映射到系统用户，该用户也不一定是销售角色。
• 处理：通过 portal_user_role 过滤 sales 角色，只保留具备 sales 角色的 userId。
• 结果：保证供应风险预警只推送给相关销售用户，而不是任意匹配到的系统用户。

5. 空 orderId 的处理策略需要调整#

• 问题：如果未填写 orderId，原逻辑可能仍会走全量 sales 推送，容易造成大范围误通知。
• 处理：新逻辑中 orderId 为空直接返回空列表，推送 0 人。
• 结果：避免没有订单关联时误推送给全部销售。