LLM 数据分析与智能报表 — 操作手册

适用版本：llm-report-app 部署包（最新）。线上示例：https://report.arbre.top（端口 8980）。
管理界面支持中文。涉及删除/写入数据库的操作均为真实生效，请先备份或谨慎确认。

功能总览
首次访问与登录权限
载入数据（文件 / 演示 / openGauss）
CSV 导入建表与外键（写入数据库）
大模型设置（供应商 / 思考型模型）
智能分析（提问 / 自动分析 / 规则与 LLM 模式）
结果管理与报表画布（多数据集混排 / 导出）
多表关联与键组（两两关联 / 大规模互相关联）
数据钻取（下钻明细 / 跨表直达 / 联合钻取演示）
表管理（直接管理数据库既有表）
数据与配置的删除、持久化与备份
常见问题（FAQ）
目录结构与自测
实验室文档比对 / 核查 / 整改（模块，/compare.html 等）
数据库维护与清理机制（⑥ 清理建议 / 安全删除）

1. 功能总览

数据接入：CSV / TSV / Excel(.xls/.xlsx) 上传、内置演示数据、openGauss/PostgreSQL 数据库只读载入、CSV 批量导入建表（支持主键与外键）。
分析：自然语言提问（LLM 模式）或“一键自动分析”（规则模式兜底）；柱/折/面积/饼图；图表类型、堆叠、双轴、对数轴、数值标签可切换；AI 解读。
结果：分析卡片按来源数据集分组保留，切换数据集不清空；可把多张表的图表汇入同一份“报表画布”并导出离线 HTML 报告或明细 CSV。
关联与钻取：
两两关联（A 表某列 ↔ B 表某列）；
键组（N 张表共享同一逻辑键，一键全互联，组内任意两表直达钻取）；
图表/明细行点击下钻原始记录，再沿关联/键组多跳直达；内置“联合钻取演示”页。
表管理：与数据载入无关，直接连接并管理数据库中既有表（改名/列改名/表格化逐行增删改/删除保护）。
运维：登录会话、大模型与数据库连接配置、上传文件、关联与键组全部持久化到数据卷，重启容器不丢失；删除数据可随时清理。

2. 首次访问与登录权限

浏览器打开 http://<服务器IP>:8980（或 https://report.arbre.top）。
顶部右侧 🔑 登录：输入管理员账号密码。
默认账号：arber，默认密码：Czq147258。
可通过环境变量覆盖：ADMIN_USER、ADMIN_PASS。
登录状态持久保持（约 7 天，重启服务不丢）。
权限划分：
管理员：上传文件、模型设置、数据库数据源、CSV 导入建表、表管理、删除数据、建立/修改关联与键组。
游客：查看/分析已有数据集与演示数据、浏览关联与键组、使用图表与报表功能（使用管理员配置的大模型）；不能上传/配置/删改。

3. 载入数据

3.1 上传文件（管理员）

点顶部 ⬆ 上传数据，选 CSV / TSV / TXT / Excel。
第一行视为表头，自动识别列类型（数值/时间/文本），自动去空列、重名列补序号。
可多表反复上传：左栏“已载入数据集”会显示所有表的胶囊，点击即可切换当前分析表（结果会按表分组保留）。
上传的文件会保存到服务端数据卷（重启不丢），可在侧栏 ✕ 删除。

3.2 演示数据

点顶部 演示数据：生成内置 600 条海关实验室检测样例，无需配置即可体验分析/钻取。

3.3 openGauss 数据库数据源（管理员）

点顶部 🗄 数据库数据源：
填主机/端口/库名/用户/密码（默认已带 127.0.0.1/webapp/webuser，可在服务器端用 DB_HOST/DB_PORT/DB_USER/DB_PASS/DB_NAME 覆盖）；
点 ① 测试连接 → ② 连接并列出表/视图；
勾选表（可多选）或写只读 SELECT，设置行数上限 → 载入。
成功的连接会保存为管理员默认连接，之后“表管理 / CSV 建表”可免重复填写、直接使用。
数据库载入的表会以 openGauss·表名 形式出现在“已载入数据集”，可参与分析与关联钻取。

4. CSV 导入建表与外键（写入数据库，管理员）

点顶部 💾 CSV导入建表：
选择一个或多个 CSV（一文件建一表），自动解析；
编辑每列：列名、类型、是否主键；可 一键蛇形列名（中文自动转拼音，如“样品名称”→sample_name）或 用中文原表头命名；
勾选“若表已存在则重建”可覆盖旧表；勾选“跳过主键为空的行”；
点 写入当前表 / 全部写入。
⑤外键关联（可选）：选子表/子表列、主表/主表列与删除策略（禁止删/级联删/置空）→ 添加外键。
规则提醒：重复主键不允许（会拒绝）；删除被外键引用的表会被拒绝，保证数据完整。

5. 大模型设置

点顶部 ⚙ 模型设置（管理员）：
① 选择供应商：硅基流动 SiliconFlow、DeepSeek 官方、阿里云百炼、OpenAI、自定义（OpenAI 兼容）。
② API 地址：自动带出，可改。
③ API Key：只需填写这一项，其余自动补全。
④ 模型：选供应商后为下拉选择（可直接选）；含“思考型/Reasoner”模型（如 DeepSeek-R1）会标注“思考型”，耗时较长属正常；自定义供应商在文本框输入模型名。
点 测试连接 验证，保存后全站共用（游客也用此模型）。
配置按账号持久化到服务端数据卷：重启容器不丢失；游客看不到密钥。

6. 智能分析

在中间提问框输入自然语言，例：
“按送检部门统计送检量 Top10，画柱状图”
“看看受理量随月份的变化趋势”
“各领域的样品平均检测时长是多少？”
右上角可指定图表类型（自动/柱/折/面积/饼）。
点 ▶ 开始分析：
已配置大模型：LLM 规划→执行→AI 解读；方案不合理会自动纠错，最多反问两轮确认口径。
未配置大模型：自动进入规则模式，只能识别“带字段名”的简单问题；此时建议点 ✨ 一键自动分析。
图表卡片功能：切换图表类型/堆叠/双轴/对数轴/数值标签；💡 AI 解读；下载明细 CSV；删除。
分析结果按数据集分组显示在中间结果区：切换数据集不会消失，可跨表把图表加入同一份报告。

7. 结果管理与报表画布

每张卡片右上角 ＋加入报表 即按顺序排入右侧“报表画布”；可上下移动、移除、清空。
画布支持多数据集图表混排（来自不同表的分组结果都可加入）。
AI 生成总结：让大模型为整份报表写总体结论与分节点评（需已配置模型）。
导出 HTML 报告：生成可离线打开、自带图表的 HTML。
卡片自身也可 下载明细 CSV（聚合表）。
“结果分组”说明：中间结果区顶部出现 📁 数据集名（N 项） 分组头，组头旁“切到该表”可快速回到该数据集的上下文；清空结果 会连同报表画布一起清空（有确认）。

8. 多表关联与键组

目标：让“图表的某个统计值/原始行”能跳到另一张表的相关记录，形成多表互相关联。

8.1 概念

两两关联：A表.列A ↔ B表.列B，外键语义。
键组：把 N 张表的键列声明为“同一逻辑键”，组内任意两表都视为可直接互钻，不需要逐对建边。适合大规模（星型/网状）关联。

8.2 入口

顶部 🔗 表关联（管理员可增删改；游客可查看）。

8.3 建立两两关联

选数据集 A/A 列、数据集 B/B 列 → 建立关联；
或点 ✨ 自动推荐：按列名/取值重叠度列出候选，点击即建。

8.4 键组：手动方式

在“键组”区下拉选 ＋新建键组… → 输入名称 → 点 新建键组；
选中键组后，用“添加成员（数据集+键列）”逐表加入（≥2 张表即生效，先建空组也能逐步加）；
可 改名 / 删除该组。

8.5 键组：一键批量

⚡ 按同名列批量加入：把“当前键列”同名的所有表一次性并入当前键组。
⚡ 一键互联：勾选 ≥2 张表（全选/清空），可选填：
键组名：留空自动命名；
指定键列：留空=自动识别（同名键列优先，其次取值重叠）；填写=只用你指定的字段，所选表都必须含该列，否则会提示缺列的表名。
点 一键互联（建立键组） → 全部选中表自动进同一键组。

8.6 关系图

🌐 查看关系图：圆点=数据集，连线=两两关联；键组成员同色聚簇并带虚线组框与组名；点击任一表节点，高亮其所在的键组与关联，图例给出明细。

9. 数据钻取

图表/聚合卡片带绿色 🔎 可下钻 徽标；点柱子、饼块或“查看明细数据”中的行 → 弹出该聚合格的原始记录明细。
明细弹窗中，每行若可继续跳转，末尾有 → 目标表.列（键组方向为 🔑）按钮：点击即在同一弹窗中显示另一张表按该键值命中的记录，可连续多跳并有“← 返回上级”。
🧭 联合钻取演示（顶栏与报表画布均提供）：
选起始表 → 自动列出可跳方向（关联/键组）胶囊；
点左表任意一行 → 右侧展示其在选中目标表中的命中记录（含命中行数）。
说明：钻取基于分析生成时刻的数据；若数据集被删除或重新分析导致失效，会提示重新分析。

10. 表管理（直接管理数据库既有表）

入口 🗂 表管理（管理员）。与“已载入数据”互相独立：连接后直接列出数据库中既有表，无需先载入。
默认使用管理员保存的数据库连接（或服务器默认 openGauss），打开即可“连接并加载表清单”。
能力：
主键列自动识别（id/编号/单号/…，可改）；
表级：重命名表、删除表（被外键引用会拒绝）；
列级：载入列清单、改列名；
行级：表格化预览——每行可 ✎ 编辑（改后只提交变化列）或 🗑 删除；顶部输入框可可视化新增一行（逐列填写）；“高级”折叠区提供批量删行、条件更新、JSON 新增。
所有行级操作真实写入数据库。

11. 数据与配置的删除、持久化与备份

11.1 删除

删除已载入数据集：左栏数据集胶囊上的 ✕（管理员）。源自上传文件会连同原始文件删除；数据库原始表不受影响（去表管理删除）；相关关联/键组成员自动清理。
清空分析结果：结果区 清空结果。
删除数据库表：表管理 → 删除表（有外键依赖时拒绝）。

11.2 持久化（容器部署）

容器挂载命名卷 llm-report-data:/app/data，其中保存：

state.json：登录会话、大模型与数据库连接配置、上传数据集描述、两两关联、键组；
uploads/：上传文件的原始字节。

重启/重建容器均自动恢复（数据库来源的数据集会按描述重新载入）。

11.3 备份与迁移

# 备份（任选其一）
docker run --rm -v llm-report-data:/data -v "$PWD":/backup alpine tar czf /backup/llm-report-data.tgz -C /data .
# 或直接 docker volume inspect llm-report-data 找到宿主机目录拷贝

# 迁移到新机器：先建同名字卷，再解包
docker volume create llm-report-data
docker run --rm -v llm-report-data:/data -v "$PWD":/backup alpine tar xzf /backup/llm-report-data.tgz -C /data

12. 常见问题（FAQ）

现象	原因 / 处理
页面看起来没更新	浏览器缓存：Ctrl+F5 强刷
供应商模型无法选择	模型为真实下拉；需先选供应商；若“无法加载供应商目录”请检查网络到 `api.siliconflow.cn` 等
重启容器后登录/数据没了	确认用卷启动（`-v llm-report-data:/app/data` 或 compose 中的 volumes）
提示“下钻数据已失效”	该分析基于旧数据，重新生成对应分析即可
表管理连接失败	在“🗄 数据库数据源”测试连接并保存；或核对服务器 `DB_*` 环境变量
删除表被拒	该表被外键引用（RESTRICT 策略），先删引用关系/子表
LLM 一直反问/报错	检查 API Key、余额、模型名；思考型模型耗时长可等待或换非思考型
比对把表头当内容 / 检测项目取不到	docx 是旧版“拍平”解析：在「🗂 文档」对该文档点重解析后重新运行比对（新上传自动按表解析）
游客不能上传/设置	属预期权限；管理员登录后操作
中文列名	导入建表时“一键蛇形列名”可转拼音英文；仅内存分析可保留中文列名

13. 目录结构与自测

server/      后端（node:http + pg + SheetJS）
  index.js   路由/鉴权/持久化/一键互联
  datasets.js 数据集注册与类型识别
  engine.js  聚合引擎（含下钻行索引）
  analyzer.js 分析编排 + 下钻注册表
  links.js   两两关联
  keygroups.js 键组 + 一键互联自动识别
  store.js   数据卷持久化
public/      前端（原生 HTML/CSS/JS + ECharts）
tests/       e2e 自测脚本
data/        运行期生成：state.json + uploads（容器内挂到 /app/data）

自测（本机先启动服务）：

node tests/e2e.mjs
node tests/e2e-llm.mjs   # 需桩模型即可
node tests/run-all.mjs   # 模块四套回归（sanity/parse/compare/check，需先启动服务）

14. 实验室文档比对 / 核查 / 整改（文档模块）

入口：首页右上「🧭 文档比对 →」，或直接访问 /compare.html、/check.html、/rectify.html。
三个页面与数据分析首页共用同一账号/登录态：任一处登录/退出，其它页面同步；未登录操作会就地弹登录框。

14.1 角色

内置 admin（全部权限）。模块还支持 organizer/reviewer/lab/auditor 角色（由管理员用 POST /api/mod/users 创建，lab 用于“整改页”以被检方身份提交印证材料）。

14.2 文档库（两种独立容器、可互相引用）

库	上传入口	用途
比对文档库（compare）	比对页「新建比对会话」上传原件/报告	一致性比对会话
核查文档库（check）	核查页「⬆ 上传被查文档(核查库)」	符合性核查的被查文档

各自上传到独立保存区（data/mod-uploads/compare/、.../check/），互不串写；
共用：核查“选择被查文档”时按“本核查库 / 🔗共享：比对文档库”分区列出，可勾选引用另一库文档；
支持 docx / pdf / xlsx / xls / txt，上传后自动解析分块；单文件 ≤200MB；
顶部 🗂 文档 可查看/删除已上传文档，并对旧解析的 docx 点 重解析（见 14.7）。

14.3 比对（compare）

「载入演示样例对（合成）」快速体验；或「＋新建比对会话（上传文档）」选原始记录 + 检测报告；
会话生成后「候选关键字」→ 勾选/自定义关键字 → 「确认选择（自动带出要素）」；
「运行比对」→ 差异按要素列成表：要素 / 原始记录 / 检测报告 / 结论 / 差异说明 / 复核；
- 结果取值来自表格单元格（docx/xlsx 按“行 | 单元格”读取），不是表头/标签文字本身（见 14.7）；
- 不一致项的差异说明会给出具体不一致字段，形如 不一致字段[单位]：原始=mg/L，报告=μg/mL、不一致字段[结果]：原始=0.02，报告=0.2；单侧缺失/报告多出项目也会逐项列出；
逐项复核：一致项点「确认一致」；不一致项点「复核差异」，先弹明细核对“不一致字段/原始取值/报告取值/差异说明”，确认后才标记「✅ 已复核」；有“新要素发现”时可选择加入关键字库/仅本次/忽略；
「复核归档」→ 导出差异 CSV / Word；归档会话可删除（仅删任务或连同关联文档一并删除）。

14.4 核查（check）

「＋新建检查要求」输入条款（规则识别“应包含/不得出现/数量应一致”等）或载入演示要求；
「生成实施计划」→「确认计划」；
「运行核查」：先在本页上传被查文档（核查库）或引用比对库文档，勾选后逐项核查（LLM 判定 + 证据原文校验，未配模型自动规则模式）；
结果审核（确认/改判）→「问题归集」→「签发整改清单」→ 到「整改」页闭环；
导出：核查报告 CSV / Word、问题整改清单 CSV / Word。

14.5 整改（rectify）

管理员/审核角色：查看整改任务、复核通过或退回；
lab 角色：登录后「我的整改」提交印证材料 → 管理员复核，形成闭环。
全部关键操作写入审计（GET /api/mod/audit）。

14.6 模块库与配置

业务表 mod_*（22+ 张）存于模块库：默认回落 DB_*（webapp/webuser）；启动自动幂等建表（账本 mod_schema_migrations），数据库不可达自动降级 JSON 存储。
状态：/api/mod/health（storage: pg|file、db.status）。建表失败可 POST /api/mod/db/migrate 重试。

14.7 表格读取与重解析（docx/xlsx 取数模型）

docx 解析为“行 | 单元格”结构（如 样品 | 检测项目 | 检测结果 | 单位 | 限量要求），要素取值按所在表格定位，而不是把表头/标签文字当作内容：
表头列 → 数据列：找到含要素名的表头单元格后，取同列其下所有数据行（如“检测项目”列 → 铅、砷…）；
纵向“标签：内容”：如 检测项目 | 铅(Pb)、砷(As)，取同行右侧单元格；
检测项目清单：自动定位项目名 / 结果 / 单位三列逐行生成 名称+结果+单位；报告缺项、多出项、结果或单位不一致都会被逐项指出。
旧版用拍平方式解析的 docx 没有表格结构：请在「🗂 文档」中对相应文档点 重解析，完成后重新运行比对，要素才能按单元格正确取数（新上传的 docx/xlsx 自动按表格解析，无需重解析）。
解析校验：结果行会显示“差异说明/原始/报告”三栏，便于人工核对取数是否正确；仍不准确时，可用上传界面重新上传或联系维护人员导出解析块定位。

15. 数据库维护与清理机制

15.1 推荐做法

mod_*（模块）与业务大表（如 30 万行业务表）不在自动建议内；
清理建议只给出「非模块表 + 空表」；有数据的大表需你人工判断后再删（“🗂 表管理 → 删除表”带外键保护）。

15.2 页面入口（表管理 → ⑥ 库清理建议）

「🗂 表管理」（管理员）→ 打开「⑥ 库清理建议」→「🔍 扫描并列出可清理项」；
列表按：系统/模块、空/行数、大小、是否被引用、标签（空表/疑似测试）展示；**系统 mod_* 表不可勾选**；
「☑ 全选建议项」后点「🗑 删除勾选表」：服务端自动先删子表再删父表；若仍被其它未勾选表引用会自动拦截并说明，不会误删；
删除后自动刷新表清单与数据源下拉。

15.3 接口（管理员）

POST /api/db/cleanup/list（conn 可选，缺省回落 webapp/webuser）：返回每张表 name/rows(bytes)/isSystem/empty/testLike/children/canSuggest/tags。
POST /api/db/cleanup/drop（{tables:[…]}）：按外键依赖安全删除，返回 {dropped, blocked}。

15.4 手工删除大表（如需）

先备份（pg_dump -t 表名），再到“🗂 表管理 → 选择表 → 删除表（被引用会拒绝）”；或 DROP TABLE ... CASCADE 前确认没有业务依赖。

15.5 后台自动清理（可选，供定时任务）

可 cron 每天调用接口扫描并记录，但默认不自动删除；需要自动删“空表+N 天前的测试表”策略时请先人工确认规则后接入。

本文档随 llm-report-app 自动生成；如需最新版请以应用内置“手册”为准。