项目概述
本项目面向桥梁养护、检测与技术管理场景，是一个融合桥梁档案、检测报告、规范文档、知识图谱和大语言模型的智能业务系统。系统采用前后端分离架构，以 SQLite 保存结构化业务数据，以 Neo4j 保存桥梁领域实体关系，以 LangChain 统一接入 OpenAI 兼容的大语言模型端点，并通过 GraphRAG 将知识图谱、桥梁档案、检测报告和来源文档联合用于问答生成。
系统的目标不是替代专业检测结论，而是帮助检测人员、养护人员和管理人员快速定位规范依据、汇总历史检测信息、分析桥梁构件与病害之间的关系，并形成可追溯的辅助回答和巡检计划。涉及结构安全、技术状况等级和处治方案的结果，仍须由具备相应资质的专业人员复核。
当前版本已完成桥梁领域数据模型和界面的整体改造，具备可运行的前端页面、REST API、SQLite 初始化数据、Neo4j 图谱服务、LangChain 模型路由、真实短信服务接入及自动化测试。首次启动会初始化 13 张业务表，并写入 2 个演示用户、5 座桥梁、6 份检测报告、9 份测试文档和演示问答数据。
核心创新点
桥梁领域知识建模：使用 18 类节点和 20 类关系描述桥梁、桥型、构件、材料、规范、检测步骤、设备、指标、方法、病害风险等知识。
GraphRAG 联合检索：根据问题抽取关键词和实体，同时检索图谱路径、桥梁档案、检测报告和来源文档，将结果组织为带来源标识的结构化上下文。
可追溯回答：问答消息保存关键词、实际使用的模型、桥梁/报告/文档检索结果和图谱快照；来源文档仅展示相关摘要或片段，可进一步打开详情核验。
LangChain 模型路由：文本模型和视觉模型分开管理，按启用状态及调用顺序依次尝试；支持 GLM、Qwen、魔搭社区等 OpenAI 兼容端点。
模型安全管理：API Key 加密保存且接口不回显；管理员可新增、编辑、启停、测试端点，并通过上移/下移按钮调整持久化调用顺序。
语义化三元组抽取：使用 LLM 和 Pydantic 结构化输出提取三元组，严格限制节点与关系类型；失败时采用桥梁领域规则兜底，不再按照实体出现顺序构造链式关系。
图谱构建过程可视化：全量、增量和单文档建图均采用进程内异步任务，页面实时展示解析、LangChain 路由、LLM 抽取、结构校验、规则兜底和 Neo4j 写入进度。
图数据库降级能力：Neo4j 不可用时明确返回降级状态，并使用 SQLite 中的三元组提供基础图谱查询和可视化，避免页面无反馈。
多模态辅助分析：桥梁现场图片通过 LangChain 视觉模型辅助识别裂缝、支座、桥面、墩台和缆索等可见问题；图片地址随消息持久化，切换会话后仍可恢复。
业务闭环：桥梁档案、检测报告、规范文档、图谱构建、智能问答、巡检计划、问答导出、统计大屏和数据库后台形成完整的数据使用链路。
应用场景
用户端功能
账号认证：支持账号密码登录、注册、手机短信验证码登录和短信验证后重置密码。
个人中心：支持查看和修改个人资料、修改密码及上传头像；头像上传成功后同步更新个人中心、导航栏和本地登录状态。
智能问答：支持桥梁规范、检测方法、指标、设备、病害和历史报告等自然语言查询，以及连续多轮对话。
图片问答：支持上传桥梁或检测现场图片进行辅助识别，聊天区展示原始所选图片并持久化保存。
会话管理：支持创建、切换、重命名、清空和删除会话；可调用 LLM 生成标题，在弹窗中查看生成进度并编辑确认后保存。
检索依据查看：右侧检索结果按桥梁档案、检测报告、来源文档、图谱和关键词分组展示；条目可点击弹窗查看详情。
问答历史：支持回看问题、回答、关键词、检索证据、知识图谱快照和模型信息。
导出功能：支持将完整会话导出为 DOCX 文档。
管理端功能
控制台与数据大屏：展示用户、文档、桥梁、报告、会话、消息、节点、关系和建图任务等指标，以及桥型、报告等级、检测类型、文档类型、节点类型、关系类型和系统活跃趋势图表。
用户管理：支持用户查询、新增、编辑、启用/禁用、角色调整和删除；普通用户无法访问管理员接口。
模型管理：分别维护文本与视觉端点，支持密钥只写、连接测试、启停、编辑、删除和调用顺序调整；连接失败时给出针对 Base URL、认证、模型标识、频率限制等问题的可读提示。
文档管理：支持目录树、文件上传、MD5 去重、关键词筛选、内容查看、下载、编辑、删除和 LLM 摘要；左侧目录和右侧内容区可独立滚动。
知识图谱管理：支持单文档、增量和全量构建，查询构建任务进度、成功/失败数量和错误明细，并查看三元组的来源片段及置信度。
知识图谱可视化：支持节点/关系类型过滤、关键词搜索、1—3 跳邻居、力导向/环形布局、连接度统计和节点详情；不同节点类型采用稳定的独立颜色。
桥梁档案管理：维护桥梁编号、名称、桥型、材料、结构体系、路线路段、跨径参数、位置、建成日期、相关规范、说明和图片。
检测报告管理：维护报告编号、关联桥梁、检测日期与类型、路段、点位、人员、设备、方法、指标、费用、等级、结论、建议和多张现场图片。
巡检计划：从桥梁详情汇总历史报告，由 LangChain 生成检查范围、频次、重点构件、方法设备、人员安排、风险控制和规范依据；可保存为知识文档并导出 DOCX。
SQLite 管理后台：通过导航栏头像左侧的“管理后台”按钮进入，仅开放 13 张业务表的白名单查询和受控删除；密码、模型密钥等敏感列不在通用接口中返回。
核心技术功能
实体与关键词提取：从问题中识别桥梁、桥型、规范、桥位部位、指标、设备、检测方法和病害风险等实体。
图谱路径检索：以实体或关键词作为种子检索 1—3 跳邻居，返回节点、关系、类型、连接度和来源信息。
多源证据检索：联合查询 Neo4j/SQLite 图谱、桥梁档案、检测报告和知识文档，并对传入 LLM 的文本长度进行控制。
受约束回答生成：提示词要求模型仅依据检索证据回答，不得虚构规范编号、条款或现场测量结果；证据不足时必须明确说明。
流式响应：/api/chat/stream 使用 Server-Sent Events 依次返回检索结果、生成文本片段和完成事件。
结构化三元组提取：通过 LangChain ChatOpenAI 与 Pydantic 模型约束 <头实体, 关系, 尾实体>，并保留源文档、原文片段和置信度。
语义中心构图：围绕“桥梁/桥型—构件/材料/规范”“检测步骤/方法—设备/指标”“病害—部位/检测方法”等中心建立辐射关系，避免所有节点首尾相连成单链。
端点故障切换：按照模型类型和管理员配置的优先顺序调用端点；端点异常时记录状态和错误并尝试下一个可用端点。
安全与权限：使用 JWT 鉴权、管理员装饰器、密码哈希、模型密钥加密、上传类型与大小校验以及 SQLite 表白名单控制。
短信安全控制：验证码有效期 5 分钟、同号码 60 秒发送冷却、每小时最多 10 次且使用后立即失效；重置密码使用短时一次性重置票据。
技术架构
整体架构设计
┌──────────────────────────────┐
│ 浏览器 / 响应式管理工作台 │
│ Vue 3 + TypeScript + Element │
│ http://127.0.0.1:3000 │
└──────────────┬───────────────┘
│ REST / JWT / SSE / 文件上传下载
┌──────────────▼───────────────┐
│ Flask API（Python 3.11+） │
│ http://127.0.0.1:5010 │
│ 认证、业务服务、GraphRAG、任务 │
└───────┬────────┬────────┬────┘
│ │ │
┌───────▼───┐ ┌──▼──────┐ ┌▼────────────────────┐
│ SQLite │ │ Neo4j │ │ LangChain 模型路由 │
│ 13张业务表 │ │ 18类节点 │ │ GLM / Qwen / 魔搭等 │
│ 三元组降级 │ │ 20类关系 │ │ OpenAI 兼容端点 │
└───────┬───┘ └─────────┘ └──────────┬──────────┘
│ │
┌───────▼────────────────┐ ┌────────▼────────────┐
│ 本地文件存储 │ │ 阿里云市场短信接口 │
│ 文档/头像/桥梁/报告/聊天 │ │ 登录与密码重置验证码 │
└────────────────────────┘ └─────────────────────┘
主要数据流如下：
管理员上传 TXT、DOCX、PDF 或 XLSX 文档，后端提取正文、计算 MD5 并保存文档元数据。
建图任务对正文分片，优先通过 LangChain 调用文本 LLM 提取结构化三元组；模型不可用或结构校验失败时使用桥梁领域规则兜底。
三元组首先写入 SQLite，并在 Neo4j 可用时同步写入图数据库；每条关系保存来源文档 ID、原文片段和置信度。
用户提问后，系统提取关键词和实体，检索图谱、桥梁档案、检测报告和来源文档，再将受控上下文交给 LangChain 生成回答。
问题、图片、回答、关键词、检索结果、图谱快照和模型标识写入 SQLite，用于会话恢复、详情展示与 DOCX 导出。
技术栈详解
前端技术栈
Vue 3.5 + Composition API：实现单页管理工作台和响应式交互。
TypeScript：定义用户、文档、桥梁、报告、模型、图谱及问答数据类型。
Element Plus：提供表单、表格、弹窗、上传、进度条、消息和分页等组件。
Pinia：维护认证和会话状态，并与 localStorage 同步登录用户信息。
Vue Router：承载单页应用入口；各业务模块由工作台统一编排。
Axios：封装统一 API 请求、JWT 请求头和错误处理。
ECharts 5.6：实现知识图谱、统计卡片及数据大屏图表。
Marked：将模型返回的 Markdown 安全渲染为问答内容。
Vite 6：提供开发服务器与生产构建；图谱和大屏组件采用异步加载。
视觉规范：依据 prototype 原型采用深海蓝、监测青和安全橙配色，并适配 1440、1024、768 和 375 像素宽度。
后端技术栈
Flask 2.2：提供 REST API、文件服务、SSE 流式响应及统一错误处理。
SQLite：保存用户、目录、文档、会话、消息、桥梁、报告、三元组、任务、模型、元数据、反馈和短信验证码。
PyJWT + Werkzeug：实现 JWT 登录态与密码哈希校验。
cryptography：加密保存模型 API Key，读取接口仅返回是否已配置密钥。
Flask-CORS：按环境变量配置允许访问的前端来源。
python-docx / pdfplumber / openpyxl：解析 DOCX、PDF、XLSX，并生成问答记录和巡检计划 DOCX。
Requests：调用阿里云市场短信服务；请求采用 Authorization: APPCODE ... 和表单参数协议。
进程内线程池：异步执行建图任务并将进度持久化到 SQLite；当前版本未依赖外部消息队列。
本地文件存储：按 avatars、documents、bridge_images、inspection_images 和 chat_images 分类保存上传内容。
算法服务技术栈
Neo4j 5.x Driver：建立节点唯一性约束，执行节点/关系合并、全文子图查询、1—3 跳邻居查询、统计和文档图谱查询。
LangChain 1.x + langchain-openai：使用 ChatOpenAI(model=..., base_url=...) 统一接入 OpenAI 兼容端点。
Pydantic 2.x：校验实体和三元组结构，限制节点类型、关系类型、置信度和来源片段字段。
文本模型路由：默认模型为 glm-4.7-flash，可增加 Qwen、魔搭社区或其他兼容端点作为主模型或备援。
视觉模型路由：默认模型为 glm-4.6v-flash，通过 LangChain 多模态消息传递 Base64 图片内容。
规则抽取兜底：内置桥梁、桥型、材料、构件、病害、指标、设备、方法、人员和环境词典，并按实体类型匹配合理关系。
SQLite 图谱降级：Neo4j 连接失败时从 graph_triples 重建节点、边、分类和连接度，并在接口中返回 sqlite_fallback 与降级标志。
运行时关键配置位于 backend/.env，可从 backend/.env.example 复制。至少应根据部署环境修改 SECRET_KEY、JWT_SECRET_KEY、MODEL_KEY_SECRET、Neo4j 连接信息、模型 API Key、短信 APPCODE、短信模板 ID 和 CORS 来源。真实密钥不得提交到源码。
