聚全用户手册

Appearance

数据查询与指标配置 ​

Campus

AI 数据助手是按环境启用的能力。本篇涉及的数据查询、AI 指标、场景指标、查询日志、AI 模型配置等页面，是否出现、出现在哪个一级菜单下，均以实际下发的客户环境为准。

适用角色 ​

  • 系统管理员 / 运维人员：维护数据查询、AI 模型配置。
  • 指标管理员：维护 AI 指标目录、场景与指标的关联。
  • 数据运营 / 客服排查人员：查看 AI 查询日志、排查失败问题。

页面上的新增、编辑、删除、启停按钮受权限控制，无权限时按钮不显示或不可点，以实际分配的角色为准。

功能说明 ​

这组页面围绕「让 AI 助手能查到、查准校园运营数据」展开，分工如下：

  • 数据查询：登记一条命名的 SQL 查询，随时点开预览它的执行结果，用于快速验证一段查询逻辑。
  • AI 指标：维护 AI 助手可识别的指标目录，包括指标名称、常见问题、说明、排序和启停，是决定「AI 能不能命中某个问题」的核心配置。
  • AI 场景指标：把指标挂到具体场景（如领导助手、学生事务、考勤、ERP）下，控制某个场景里能查哪些指标、哪些是必选。
  • AI 查询日志：记录每一次 AI 问答的问题、命中指标、结果、耗时和回复摘要，用于排查失败或异常查询。
  • AI 模型配置：登记可用的 AI 模型服务（名称、模型、接口地址、密钥、是否本地服务）。

其中 AI 指标、场景指标、参数 JSON、执行配置属于高风险运维配置，改动会直接影响 AI 助手的命中率和查询结果，应由熟悉数据口径的管理员操作。

操作入口 ​

text
数据查询 / AI 指标 / AI 场景指标 / AI 查询日志 / AI 模型配置
（各页所在一级菜单以实际下发的客户环境为准，通常归在系统管理下）

截图待补：数据查询列表与结果预览、AI 指标维护页、场景指标弹窗、查询日志详情、AI 模型配置表单。

一、数据查询 ​

登记 SQL 查询并预览结果。

新增查询 ​

  1. 进入「数据查询」，点击工具栏「新增」（无 store 权限时按钮不可用）。
  2. 在弹窗中填写：
    • 查询名称（必填，为空提示「查询名称不能为空」）。
    • SQL（必填，多行文本框，为空提示「查询SQL不能为空」）。
    • 状态（必填）：正常 / 停用。
    • 备注（选填）。
  3. 点击提交保存。

查看查询结果 ​

  • 在列表行点击「查看结果」，弹出标题为「预览查询结果 + 查询名称」的窗口。
  • 结果以 JSON 树形展示，默认展开若干层，支持复制。看完点「关闭」即可。

列表与维护 ​

  • 列表顶部可按「查询名称」关键字筛选。
  • 列表展示：查询名称、SQL、状态、创建时间、备注、创建人。
  • 行操作：查看结果、编辑（需 update 权限）、删除（需 delete 权限）。

SQL 会真实执行以返回预览结果，请只登记只读、口径明确的查询语句，避免写入或高开销的语句。删除查询前确认没有其他用途依赖它。

二、AI 指标维护 ​

维护 AI 助手可查询的指标目录、常见问题和展示信息。此页面偏运维配置，普通用户不应随意修改。

页面顶部有固定提示：推荐只维护「指标名称、排序、常见问题、指标说明、启停状态」；不要随意修改指标编码、参数 JSON、场景、执行方式或执行配置。如果需要新增查询条件，应先确认后端处理逻辑与维度解析均已支持。

维护的影响面用标签概括：

  • 常见问题：可维护
  • 启停指标：需确认影响
  • 参数 JSON：谨慎修改
  • 新增指标：先补测试

筛选与列表 ​

筛选条件：指标编码、指标名称、业务分类（学生事务 / 考勤 / ERP）、执行方式（代码型 / 配置型）、状态（全部 / 启用 / 停用）。点「查询」筛选，点「重置」清空。

列表展示：指标编码、指标名称、分类、执行方式、结果类型、单位、排序、命中次数、状态、说明。

  • 状态：有 metricStatus 权限时显示为开关，可直接启停；无权限时只读展示启用 / 停用标签。
  • 行操作：编辑（需 metricEdit 权限）、详情（需 metricDetail 权限）。

编辑指标 ​

点击行「编辑」打开弹窗，弹窗顶部提示：常见问题会影响前端推荐问题，参数 JSON 会影响 AI 是否能正确传参，停用指标会让对应问题不再可查。

可编辑字段：

  • 指标编码：只读，不可修改。
  • 指标名称（必填，为空提示「指标名称不能为空」）。
  • 业务分类、所属场景：文本填写。
  • 结果类型：数量 / 金额 / 比例 / 列表。
  • 单位、排序（0–9999）。
  • 状态：启用 / 停用。
  • 权限说明、支持角色（JSON 数组文本，例如 ["ROLE_ADMIN"]）。
  • 必填参数 / 可选参数（JSON 数组文本，例如 ["date"]、["schoolId"]）。
  • 常见问题：多行文本，每行一个问题，保存时自动去重后写入。
  • 指标说明、备注。

点「保存」提交，成功提示「保存成功」。

启停指标 ​

在列表用状态开关切换时会二次确认：

  • 启用：提示「启用后该指标可能重新进入 AI 助手候选目录和常见问题」。
  • 停用：提示「停用后该指标将不会被 AI 助手查询，相关常见问题也可能不再展示」。

确认后生效；若取消或失败，状态回退到原值。

指标详情 ​

点「详情」查看只读信息，分两块：

  • 基础信息：指标编码、名称、执行方式、状态、分类、场景、结果类型、单位、命中次数、最近命中时间、常见问题、说明。
  • 执行配置：源表、聚合方式、聚合字段、时间字段、默认过滤、参数映射、权限过滤（JSON 内容原样展示）。

执行配置属于查询实现细节，展示为参考。修改这类配置需确认后端支持，超出「常见问题 / 名称 / 排序 / 说明 / 启停」范围的改动请先在测试环境验证命中效果。

三、AI 场景指标 ​

把指标挂到具体场景下，控制每个场景可查的指标范围。

筛选与列表 ​

筛选条件：场景（下拉，选项来自系统已配置的场景列表）、指标编码、状态（全部 / 启用 / 停用）。

列表展示：场景、指标编码、指标名称、分类、执行方式、结果类型、排序、必选（是 / 否）、状态。

  • 状态：开关，可直接启停，失败自动回退。
  • 行操作：编辑、删除。

添加 / 编辑场景指标 ​

点「添加指标」或行「编辑」打开弹窗：

  • 场景（必填，为空提示「请选择场景」）。从筛选进入时会带入当前筛选的场景。
  • 指标（必填，为空提示「请选择指标」）：下拉只列出已启用的指标，显示为「指标名称（指标编码）」。
  • 排序（0–9999，默认 100）。
  • 是否必选：是 / 否（默认否）。
  • 状态：启用 / 停用（默认启用）。

点「保存」提交，成功提示「保存成功」。

删除 ​

点「删除」会确认「确定删除场景指标「指标名称」吗？」，确认后删除并刷新列表。

「必选」表示该指标在场景中被优先纳入。停用或删除某个场景指标会让该场景不再可查对应指标，变更前请确认对应场景的使用情况。

四、AI 查询日志 ​

只读页面，记录每一次 AI 问答，用于排查。

筛选与列表 ​

筛选条件：用户问题、指标编码、场景（领导助手 / 学生事务 / 考勤助手 / ERP助手）、结果（全部 / 成功 / 失败）、时间区间（按起止日期）。

列表展示：时间、用户问题、命中指标、场景、结果（成功 / 失败）、耗时（毫秒，无则显示 -）、模型、回复摘要。

查看详情 ​

点行「详情」查看，分两块：

  • 基础信息：时间、结果、用户 ID、用户角色、场景、模型、命中指标、耗时、用户问题、会话 ID。
  • 解析与回复：解析参数（JSON）、错误信息（仅失败等有错误时显示）、回复摘要。

排查失败查询时，优先看「结果 = 失败」的记录，结合命中指标、解析参数和错误信息定位是没命中指标、参数没解析对，还是执行阶段报错。

五、AI 模型配置 ​

登记可用的 AI 模型服务。

筛选与列表 ​

筛选条件：AI 名称、状态（全部 / 正常 / 停用）。

列表展示：AI 名称、模型、Api 地址、ApiKey、是否本地服务、状态、备注、创建时间。

新增 / 编辑 ​

点「新增」（需 store 权限）或行「编辑」打开表单：

  • AI 名称（必填）。
  • 模型（必填）。
  • Api 地址（必填）。
  • ApiKey（必填）。
  • 是否本地服务（必填）：是 / 否。
  • 状态（必填）：正常 / 停用。
  • 备注（选填）。

删除需 delete 权限。

ApiKey 属于敏感凭据，配置时注意保密，不要在截图、工单中泄露。切换模型或改动接口地址会影响 AI 助手的实际调用，建议改动后用查询日志确认调用正常。

关键规则与注意事项 ​

  • AI 回答仅基于已配置的指标和当前账号的数据权限，不能替代财务、学籍等正式报表的最终核对。
  • 数据查询的 SQL 会真实执行以生成预览，只登记只读、口径明确的语句。
  • 指标编码在编辑时不可改；参数 JSON、执行配置、场景关联属于高风险字段，改动前需业务负责人确认并完成测试。
  • 停用指标或场景指标会让对应问题不再可查，启停前看清二次确认里的影响说明。
  • 常见问题、支持角色、必填 / 可选参数需按提示的 JSON 数组格式填写，格式错误会影响 AI 传参。
  • ApiKey 等凭据保密，不要输入无业务必要的个人隐私、密码、密钥或敏感材料到 AI 助手。

常见问题 ​

AI 没有命中或没有返回结果 ​

先在「AI 查询日志」找到这条记录，看命中指标和结果。若没命中，检查「AI 指标」里对应指标是否启用、常见问题里是否有相近问法、该指标是否已挂到当前场景（AI 场景指标）。缩小问题范围、写明时间和对象后重试。

AI 数字与报表对不上 ​

先比较统计时间、范围和指标口径。指标详情里的执行配置（源表、聚合方式、时间字段）反映了取数口径，可据此核对；最终以对应业务报表和经确认的业务数据为准。

指标编辑里想改编码，但改不动 ​

指标编码在编辑弹窗中是只读的，属于设计约束。编码是 AI 识别指标的关键标识，不能随意改动；如确需调整，请走后端配置并做测试验证。

保存指标 / 场景指标时提示必填未填 ​

指标名称为必填；场景指标的场景、指标为必选。按提示补全后再保存。常见问题、支持角色、参数等 JSON 文本请按示例格式填写。

数据查询点「查看结果」报错或很慢 ​

结果由 SQL 实时执行返回，语句本身错误或数据量过大都会导致失败或缓慢。请确认 SQL 正确、为只读查询，并避免高开销语句。

版本记录 ​

版本日期修改说明
v1.02026-07-27首次建立
v1.12026-07-27依据前端源码完善内容

聚全信息文档中心

Copyright © 2026 聚全信息