实习日报｜2026-05-26#

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

今天主要完成了 AI 智能助手数据埋点能力的开发。整体实现思路是：不在主流程中直接写入统计数据，而是通过事件驱动方式采集用户行为，再由异步监听器完成持久化，尽量减少对现有业务链路的影响。

本次埋点开发主要覆盖以下事件类型：

• MODULE_ACCESS：模块访问事件，用于统计不同功能模块的访问量、覆盖率、日活 / 周活和使用频率排行；
• TO_HUMAN_ESCALATION：转人工事件，用于统计自助查询转人工率和自助查询解决率；
• ORDER_FOLLOW / ORDER_UNFOLLOW：订单关注事件，目前订单关注功能尚未上线，本次完成字段和事件类型预留。

在代码实现上，新增了 AiInstrumentationEvent 事件对象，并采用 Java record + 静态工厂方法的方式定义不同事件类型。通过 ApplicationEventPublisher 在业务入口处发布事件，再由 AiInstrumentationEventListener 监听事件并异步落库。

异步写入部分采用 @EventListener + CompletableFuture.runAsync 的方式处理，写入失败时不阻塞主业务流程。这种设计能够保证埋点能力和业务主链路解耦，降低埋点写入异常对用户使用体验的影响。

2. 数据库与持久化能力实现#

今天完成了埋点数据表设计和持久化链路开发。核心新增表为：

• ai_instrumentation_event

该表用于统一存储模块访问、转人工和后续订单关注等事件。表中通过 event_type 区分事件类型，通过 channel 区分访问来源，并记录员工、部门、模块、订单、会话、客户端信息和事件时间等字段。

表结构中也为后续扩展预留了 extra_info 字段，用于保存 JSON 扩展信息，避免后续新增事件时频繁扩展表字段。同时，针对事件类型、员工、模块和渠道维度建立了索引，支撑后续 Dashboard 查询和统计聚合。

除新建埋点表外，本次也补齐了供应风险预警相关业务表字段，包括：

• portal_supply_risk_alert：补充部门和关联订单字段；
• portal_supply_risk_notification：补充推送状态字段；
• portal_supply_risk_feedback：补充反馈查看时间字段。

这些字段用于支撑风险预警发起覆盖率、推送成功率、查看率、销售反馈查看及时率和督办闭环率等指标统计。

3. 多入口埋点接入#

今天将模块访问和转人工埋点接入到多个 AI 智能助手入口中，覆盖 Web、企微和 ERP 对话等使用场景。

模块访问事件主要接入以下入口：

• Web 门户 Agent 调用入口；
• 企微机器人长连接入口；
• ERP AI 对话入口；
• ERP 智能体调用入口；
• AI Agent invoke 相关入口。

在这些入口中，当用户命中具体业务 Skill 且不是 general-chat 或 fallback 类型时，系统会发布 MODULE_ACCESS 事件，并记录对应模块编码、渠道、员工标识和访问时间等信息。

转人工事件主要接入“提交给人工”相关反馈入口。当用户在 AI 回复后主动提交人工协助请求，并成功提交反馈时，系统会发布 TO_HUMAN_ESCALATION 事件，用于后续计算转人工率和自助查询解决率。

4. Dashboard 统计查询能力开发#

今天还完成了 Dashboard 统计查询层的开发，围绕 /api/erp/ai/dashboard 提供多类统计接口。

本次新增或整理的统计能力包括：

• 总览统计：总访问量、去重用户、去重模块、转人工次数、转人工率；
• 模块使用排行：按访问次数统计各模块使用频率；
• 活跃用户统计：支持 DAU、WAU 和每日明细；
• 转人工率统计：支持整体转人工率和按模块统计；
• 供应风险统计：覆盖预警发起、推送、查看、反馈、状态分布和闭环情况；
• 人工反馈统计：覆盖诉求发起量、业务关联、处理及时率和闭环率；
• 渠道分布统计：统计 WEB、WECOM、ERP_AI_CHAT 等渠道访问量。

其中，模块访问和转人工指标直接查询新增的 ai_instrumentation_event 表；供应风险和人工反馈指标主要复用已有业务表进行统计查询。这样既满足业务指标统计需求，也避免重复采集已经存在于业务表中的数据。

5. 技术方案与交付文档沉淀#

今天整理并沉淀了完整的数据埋点技术方案和交付文档。技术方案中明确了本期建设边界：优先实现全模块通用访问和转人工行为事件采集，并补齐全量统计查询层；供应风险预警和人工反馈数据优先从已有业务表查询；订单关注行为由于功能尚未开发，本期只做事件和字段预留。

交付文档中整理了以下内容：

• 功能概述；
• 技术方案核心；
• 数据库变更；
• 新建文件清单；
• 修改文件清单；
• 事件采集覆盖范围；
• Dashboard API 列表；
• PDF 需求对照；
• 业务统计口径映射；
• 部署步骤和验证方式。

这部分文档可以作为后续 MR、测试验收、数据库执行和业务沟通的交付材料。

6. 测试验证与验收支持#

今天还根据开发内容整理了测试文档，覆盖登录、模块访问事件触发、转人工事件触发、Dashboard API 验证、PDF 指标对照和数据库确认等环节。

测试文档中设计了以下验证路径：

• 通过开发登录页进入门户角色；
• 点击底栏不同功能按钮，触发 MODULE_ACCESS 事件；
• 在 AI 回复中点击“提交给人工”，触发 TO_HUMAN_ESCALATION 事件；
• 使用浏览器 Console 调用 Dashboard API，验证总览、模块排行、活跃用户、转人工率、供应风险统计、人工反馈统计和渠道分布；
• 使用 SQL 查询埋点表和供应风险相关表，确认事件写入和字段变更情况。

通过这份测试文档，测试人员可以按步骤验证埋点事件是否正常产生、统计接口是否能返回有效数据，以及业务方关注的 KPI 是否具备对应统计口径。

1. 业务需求紧急，需要快速覆盖核心指标#

• 问题：业务方对 AI 智能助手数据埋点需求较急，需要尽快提供模块使用、转人工、供应风险和人工反馈等指标统计能力。
• 处理：将需求拆分为“事件采集”和“统计查询”两部分，本期优先实现全模块访问、转人工行为采集，以及可直接基于已有业务表统计的指标。
• 结果：核心指标具备了统计基础，能够支撑业务侧进行使用情况、转人工情况和风险预警相关分析。

2. 不同业务指标的数据来源不一致#

• 问题：PDF 需求中包含模块访问、转人工、风险预警、销售反馈、诉求闭环等多类指标，如果全部通过新埋点表采集，会导致重复采集和业务侵入较大。
• 处理：采用分层数据来源策略：模块访问和转人工写入新埋点表；供应风险和人工反馈优先查询已有业务表；订单关注功能暂未上线，仅做字段和事件预留。
• 结果：既满足统计口径需求，又降低了对现有业务流程的改造成本。

3. 埋点不能影响主业务流程#

• 问题：如果埋点写库失败或耗时过长，可能影响用户正常调用 AI 助手。
• 处理：采用事件发布 + 异步监听的方式落库，埋点写入失败时静默丢弃并记录调试日志，不阻塞主流程。
• 结果：埋点能力与主业务流程解耦，提升了系统稳定性。

4. 部分需求依赖尚未上线的业务功能#

• 问题：订单关注使用率依赖订单关注功能，但该功能当前尚未开发。
• 处理：在埋点表和事件类型中预留 ORDER_FOLLOW / ORDER_UNFOLLOW，并预留 order_id、order_status 等字段。
• 结果：当前不阻塞本期交付，后续订单关注功能上线时只需在对应 toggle 方法中发布事件即可接入统计。