FA 一键诊断 总体设计 v1.8
前置阅读：
相关设计文档：
FA_一键诊断_Ideal_Scenario_Mock数据.md— 理想场景演示数据（5 维数据交叉分析示例）FA_一键诊断_类别标签配置管理_PRD.md— 标签配置管理后台（docs/02_设计/60_管理后台/）FA_一键诊断_Dify编排功能设计.md— Dify Workflow 详细设计FA_一键诊断_前端PRD.md— 前端页面与交互设计FA_一键诊断_知识库自动沉淀Agent.md— 闭环工单沉淀(建设中) Agent
版本记录：
- v1.0 (2026-06-17)：初稿
- v1.1 (2026-06-17)：修正打标链路（LLM 始终在链路而非"兜底"）；7套Prompt合并为1套+Jinja2安全提示；新增QA/FA知识库分离设计
- v1.2 (2026-06-17)：去除关键词匹配，改为纯 LLM 打标；管理后台移除关键词维护功能
- v1.3 (2026-06-17)：去除非故障过滤 Code Node；2.1 数据流改为 Mermaid；confidence 改为 0~1 小数；component 候选列表注入 llm_description 增强分类判断
- v1.4 (2026-06-17)：新增 §5 IOT 数据注入预留节点；去除历史工单重打标功能
- v1.5 (2026-06-22)：§5 从"预留"扩展为「多维数据上下文注入」——IOT 运行记录+告警 + Asset 报修/巡检/保养/零件 5 维数据；新增 device_id 解析逻辑
- v1.6 (2026-06-22)：重写 §2 整体架构——系统交互架构图 + 数据存储 + 工作流引擎集成；删除 §2.2 核心流程 Mermaid（已在 Dify 编排文档）
- v1.7 (2026-06-22)：§2.1 系统交互架构恢复工单系统入口；§3.3、§6.1 删除 Prompt 模板，改为文字说明 + 引用 Dify 编排文档
- v1.8 (2026-06-23)：§3.1 system 类型从"7个固化值"改为"可配置（默认7个）"；§3.3 LLM 打标输入输出中 system 描述同步更新
1. 产品定位
工单受理人在工单详情页点击 「一键诊断」 → 系统基于工单内容自动打标 → 检索对应设备知识库 → LLM 生成排障建议报告。
产品边界：
- 诊断建议仅供参考，不替代人工判断
- 首次上线仅覆盖有知识库挂载的设备类型（详见标注建议 65 份 ✅ 文档）
- 无知识库覆盖的故障类型，由 LLM 通用常识兜底
2. 整体架构
2.1 系统交互架构
2.2 数据存储
诊断结果作为工单操作流水存储，与「接单」「转派」「结单」同属工单域。
work_order_operations
├── id 自增
├── work_order_id FK → 工单
├── action_type "diagnosis" | "accept" | "transfer" | "close"
├── action_payload JSON（diagnosis 时存入 classification + report_summary + references + has_iot_data + has_asset_history）
├── operator_id 操作人（diagnosis 时为 "AI"）
├── created_at理由：诊断是工单生命周期中的一次操作——与接单/转派/结单同类实体，没有独立于工单之外的查询场景。
2.3 工作流引擎集成（待调研）
工单系统基于工作流引擎，后续计划提供「一键诊断」组件拖入流程，实施人员配置字段映射。具体方案需与工单 PM 联合确认。
3. 分类打标
3.1 二维标签体系
| 维度 | 名称 | 类型 | 说明 |
|---|---|---|---|
| category | 设备类别 | 可配置（默认 7 个） | 从 category_config 表获取（默认：建筑结构 / 电气 / 弱电智能化 / 给排水 / 暖通空调 / 消防安防 / 专用设备），支持增删改 |
| tag | 诊断标签 | ~40 个可配置 | 门、窗、灯具、马桶、闸机、UPS、精密空调... |
| symptom | 故障现象 | LLM 自动抽取 | 漏水、堵塞、不亮、异响、开裂、不通电... |
3.2 识别策略：纯 LLM 打标
不做关键词预匹配。LLM 一次调用完成 category + tag + symptom 三个维度的输出。
理由：LLM 始终在链路（symptom 必须 LLM 出），追加关键词预填不省调用、不省 token，只增加维护负担和多命中冲突处理逻辑。
3.3 LLM 打标
LLM 一次调用完成三维输出（设备系统、设备组件、故障现象），同时输出 0~1 置信度。
输入：工单描述原文 + category 候选值（从 category_config 表获取）+ tag 候选列表（约 40 个，带 LLM 增强描述）
输出：
category：从候选 category 列表中选 1 个tag：从候选列表中选最匹配的名称（无匹配时可输出新名称）symptom：短语概括故障现象（如"不亮""漏水""堵塞""异响"）confidence：0~1 小数。≥0.8 高置信，0.5~0.8 中，<0.5 低
详细 Prompt 模板见 Dify 编排功能设计 §2.3。
3.4 配置存储
tag 候选列表存储在管理后台配置表中，通过 API 下发到 Dify LLM Node 的 变量。无关键词配置项。
3.5 配置变更与历史数据
修改 tag 列表后，仅影响新提交的工单打标。暂不支持对历史工单重新打标（token 消耗过大），历史数据重打标方案将在后续 Dify 编排阶段另行设计。
4. 知识库架构
4.1 QA 知识库与 FA 诊断知识库分离
决策：独立部署，通过 Dify 创建两个独立知识库。
| QA 知识库 | FA 诊断知识库 | |
|---|---|---|
| 核心分类字段 | business_domain（空间运营/行政服务...） | system（电气/给排水/暖通...） |
| 文档类型 | 制度规范、培训材料、FAQ、楼宇介绍 | 设备手册、故障码表、通讯协议 |
| 权限 | 全员 + 访客 | 仅运维人员 |
| 检索触发 | 用户自然语言提问 | 工单打标 → Metadata Filter |
分离原因：
- 两类文档语义空间几乎无重叠——同一份文档不大可能同时是 QA 和 FA 的场景
- 元数据 schema 完全不同——合并意味着每份文档必有一半字段为 null
- 检索精度——FA 诊断的 Metadata Filter 依赖
system/component字段，QA 文档没有这些字段，混在一起反而增加噪声
4.2 Metadata Filter
{
"operator": "and",
"conditions": [
{"field": "system", "operator": "eq", "value": "$SYSTEM"},
{"field": "component", "operator": "eq", "value": "$COMPONENT"},
]
}当工单描述中提取到设备品牌/型号时，追加过滤条件：
{"field": "equipment_brand", "operator": "eq", "value": "$BRAND"},
{"field": "equipment_model", "operator": "eq", "value": "$MODEL"}4.3 降级策略
| 场景 | 策略 |
|---|---|
| component 命中、知识库有对应文档 | 正常 RAG 检索 |
| component 命中、知识库无对应文档 | 跳过知识库检索，LLM 常识生成 |
| component 未命中（LLM 打标 low confidence） | 不做 Metadata Filter，纯向量检索 Top-3 |
| system 命中但 component 模糊 | 仅按 system 过滤，向量检索 Top-5 |
5. 多维数据上下文注入
诊断 LLM 的上下文不限于工单描述 + 知识库。基于资产详情页的多维数据结构，一键诊断同时注入 2 类来源 × 5 个数据维度，用于交叉验证定位根因。
5.1 数据维度总览
| 来源 | 数据维度 | 资产详情页 Tab | 注入条件 | Mock Case 中的诊断价值 |
|---|---|---|---|---|
| IOT | ① 运行记录（物模型属性实时值） | Tab 2 — 运行记录 | device_id 不为空 | 回风温度 30.5°C vs 冷水阀 18.5% → 矛盾信号定位水侧问题 |
| IOT | ② 告警记录（规格引擎规则触发） | Tab 3 — 告警记录 | device_id 不为空 | 无告警但设备异常 → IOT 告警规则的盲区证据 |
| Asset | ③ 历史报修工单 | Tab 4 — 报修 | asset_id 不为空 | 15 个月前更换过冷水阀执行器 → 间歇性故障复用模式 |
| Asset | ④ 历史巡检记录 | Tab 5 — 巡检 | asset_id 不为空 | 6/5 巡检结论"正常" → 故障是近期发生的 |
| Asset | ⑤ 历史保养记录 + 零配件更换 | Tab 6+8 — 保养/零件 | asset_id 不为空 | 3 个月前保养测试"正常" → 执行器间歇性卡涩推断 |
核心设计理念：没有一条信息单独看是有价值的——30.5°C 不报警、18.5% 不报警、"3 个月前正常"不触发任何动作。但五条信息交叉的那一刻，根因浮现。这是"脑手合一"差异化壁垒的具体体现。
5.2 device_id 解析
工单系统可能传入 asset_id（人工报修场景）或 device_id（报警转工单场景），也可能同时传入。一键诊断内部统一处理映射关系：
N4c device_id 解析:
输入 device_id → 直接用，跳过解析
无 device_id + 有 asset_id → 调资产系统接口查 asset.device_id
├── 有映射 → device_id = 映射值
└── 无映射 → device_id = null（该资产无物联接入）
无 device_id + 无 asset_id → device_id = null5.3 IOT 数据内容
运行记录：物模型实时点位值，含属性名称、值、单位、参考范围。示例：
| 属性 | 值 | 参考范围 | 诊断用途 |
|---|---|---|---|
| 回风温度 | 30.5°C | — | 与设定值对比，判断制冷效果 |
| 冷水阀阀位反馈 | 18.5% | 夏季 60~80% | 阀位异常 → 水侧问题 |
| 风机运行状态 | 运行 | — | 排除风侧问题 |
告警记录：物联中台规格引擎提前配置的规则触发类报警（近 30 天）。即使无告警，该信息本身也有价值——说明故障点不在 IOT 告警规则覆盖范围内。
5.4 Asset 历史数据内容
| 维度 | 数据源 | 字段 | 诊断用途 |
|---|---|---|---|
| 历史报修 | 报修工单表 | 工单编号、故障描述、结单时间 | 同设备历史故障模式聚类 |
| 历史巡检 | 巡检工单表 | 日期、结论 | 确认故障时间窗口（巡检正常 ≠ 当前正常） |
| 历史保养 | 保养工单表 | 日期、内容、结论 | 排查近期保养操作是否相关 |
| 零配件更换 | 零件更换表 | 日期、零件名称、关联工单 | 复用零件是否存在二次故障 |
5.5 Prompt 注入
Dify N6 Prompt 中注入两段可选上下文：（IOT 实时值 + 告警）和 （报修/巡检/保养/零件）。均通过 Jinja2 {% if %} 条件注入。详见 Dify 编排功能设计。
6. LLM 诊断生成
6.1 诊断报告生成
1 套 Prompt 模板，按设备系统动态注入安全提示。综合以下上下文输入生成诊断报告：
输入上下文：
- 工单描述 + 分类标签（设备系统/设备组件/故障现象）
- 知识库检索结果（RAG chunk 列表，可选）
- IOT 实时数据（物模型点位值 + 告警记录，可选）
- 资产历史记录（报修/巡检/保养/零件，可选）
输出：
- Markdown 格式的诊断建议报告
- 包含可能原因（按可能性排序）、排查步骤（按优先级）、交叉分析、参考文档引用
- 结尾注明：本建议仅供参考，如有疑难请升级处理
详细 Prompt 模板（含安全提示 Jinja2 条件注入、IOT/资产历史循环渲染）见 Dify 编排功能设计 §2.8。
6.2 降级兜底
当 system/component 均为 null 且知识库检索无结果时，LLM 基于通用常识生成诊断——这对于 TOP6 高频故障（门窗、灯具、漏水等）已足够。
6.3 symptom 的数据分析价值
全量工单打完 system + component + symptom 标签后，可支撑：
| 分析场景 | 说明 |
|---|---|
| 高频症状趋势 | 按时间/季节/项目统计 symptom 分布，发现周期性规律 |
| 症状-组件关联矩阵 | 哪些组件最容易出现哪种症状，辅助 component 关键词扩充 |
| 新项目冷启动 | 无历史工单时，用存量 symptom 聚类反向建议 component 列表 |
7. 动态知识库：闭环工单沉淀（P2 规划）
闭环工单按 system + component + symptom 聚合，LLM 提取各分类的常见处理方案，以一份知识库文档维护。非逐工单存档。
定时拉取 → 按 classification 分组 → 每组 LLM 聚合处理方案 → Upsert 知识库8. 实验数据参考
基于 2188 条传统物业维修工单分析：
| 指标 | 数值 |
|---|---|
| TOP15 故障分类覆盖率 | 86% |
| TOP6 高频故障占比 | 67% |
| 未分类长尾 | ~12%（可收敛至 5-8%） |
| 有诊断价值的知识库文档 | 65 份 |
| 建议暂不导入文档 | 17 份（保修卡/合格证） |
| 可选导入平台类文档 | 10 份 |
9. 文档索引
| 文档 | 路径 | 说明 |
|---|---|---|
| 总体设计 | FA_一键诊断_总体设计.md（本文） | v1.8 — 架构、流程、多维上下文注入 |
| 元数据标签体系 | FA_一键诊断_知识库元数据标签体系设计.md | v1.0 — L1/L2/L3 字段定义 + Skill Prompt |
| 文档标注建议 | 知识库文档元数据标注建议.md | 92 份运维文档的 system/component 标注结果 |
| 类别 & 标签管理后台 PRD | FA_一键诊断_类别标签配置管理_PRD.md（docs/02_设计/60_管理后台/） | v4.0 — 标签配置管理后台（命名重构：System→类别, Component→标签） |
| Dify 编排功能设计 | FA_一键诊断_Dify编排功能设计.md | v2.0 — Workflow 详细节点设计（含 device_id 解析 + 多维数据注入） |
| 前端 PRD | FA_一键诊断_前端PRD.md | v1.1 — 一键诊断页面与交互 |
| 知识库自动沉淀 Agent | FA_一键诊断_知识库自动沉淀Agent.md | v2.0 — 闭环工单沉淀方案 |
文档版本：v1.8创建日期：2026-06-17最后更新：2026-06-23 *作者：强哥 *