决策证据链 · LightAIP · frontend-intro-v5

1. 页面概览

「决策证据链」是 AIP 的决策支持页面（V5 Stage 2 B2-2，action/web/src/views/DecisionPage.vue）。用户输入决策问题（可指定数据源名），后端同步执行 5 步证据链：问题拆解 → 三路检索 → 证据核验 → 答案生成 → 引用溯源，一次返回 markdown 答案、5 步执行记录与引用列表。页面为三栏布局：左栏提问与历史，中栏 5 步进度与答案，右栏引用面板。一句话总结：本页是「带证据链的问答」，每个结论都能溯源到知识文档、实体或结构化查询证据。

2. 访问入口

2.1 路由与菜单

路由 path: /decision、name: Decision、meta 标题「决策证据链」、requiresAuth；顶部导航栏菜单「决策分析」（title 提示「决策证据链（检索/核验/引用溯源）」）。源码 action/web/src/views/DecisionPage.vue。

2.2 认证与权限

需要登录（aip_token）；普通登录用户即可访问。

2.3 端口与 API 前缀

AIP 后端 18080；客户端 action/web/src/api/decisionApi.js 复用 aipClient，baseURL /aip-api/v1。

2.4 URL 持久化（`?id=`）

选中的答案 id 会写入路由 query ?id=<trace_id>（router.replace，不污染浏览器历史），刷新后可经 GET /decision/answers/:id 恢复；该 URL 可直接分享/加书签回放某次证据链。

3. 界面布局

三栏网格（左 300px / 中弹性 / 右 300px，窄屏自动折行）：

┌───────────────┬───────────────────────────┬────────────────┐
│ AIP · 决策证据链               [刷新历史]     │                │
│ ┌ 提问 ───────┐│ ┌ 5 步证据链进度 ─────┐   ││ ┌ 引用 ───────┐ │
│ │ [textarea]  ││ │ 1 问题拆解 完成     │   ││ │ [1] 知识/RAG│ │
│ │ [数据源名]   ││ │ 2 三路检索 完成     │   ││ │ 标题/uri    │ │
│ │ [提问]      ││ │ 3 证据核验 降级     │   ││ │ [展开片段]   │ │
│ └────────────┘││ │ 4 答案生成 完成     │   ││ └────────────┘ │
│ ┌ 最近提问 ───┐│ │ 5 引用溯源 完成     │   ││                │
│ │ 历史条目列表 ││ │ trace_id: xxx      │   ││                │
│ └────────────┘││ └────────────────────┘   ││                │
│               ││ ┌ 答案 ──────────────┐   ││                │
│               ││ │ markdown 渲染正文   │   ││                │
│               ││ └────────────────────┘   ││                │
└───────────────┴───────────────────────────┴────────────────┘

左栏「提问」卡片：问题文本域 + 数据源名输入 + 提问按钮 + 同步执行提示；「最近提问」卡片列出历史条目。
中栏「5 步证据链进度」卡片：每步名称/状态徽标/耗时（latency_ms），点击步骤行可展开该步 detail 明细；下方显示 trace_id。
中栏「答案」卡片：markdown 渲染的答案正文；失败时显示错误注记。
右栏「引用」卡片：引用条目（序号/来源标签/标题/uri），点击展开 snippet。

4. 交互元素

控件	位置	含义与作用
文本域「提问」	左栏	决策问题，必填；支持 Ctrl+Enter 提交；placeholder 示例「当前差旅报销标准是多少？与上季度相比有何变化？」
输入框「数据源名」	左栏	可选；为空时后端回退演示默认源 `aip_demo_warehouse`（归因见下），只有「未指定且无默认源」才跳过结构化查询（NLQ）通道
按钮「提问」	左栏	同步执行 5 步链；asking 时文案「证据链执行中...」并禁用；开始即清空 URL `?id`，成功后写入新 id
按钮「刷新历史」	页头	重新拉取最近 20 条历史
历史条目	左栏「最近提问」	点击回放该次答案（`loadDetail`），并把该条 id 写入 URL `?id=`
步骤行	中栏「5 步证据链进度」	点击展开/收起该步 `detail` 明细（retrieve 步为三路检索友好摘要；其余为中文键值对，`sub_questions` 渲染为有序列表，无明细显示「无明细」）
引用条目	右栏「引用」	点击展开/收起 snippet 片段

次要：步骤行内状态徽标与耗时列（完成/跳过/降级/执行中）、retrieve 步内的数据源归因徽标（请求指定 / 回退默认源 / 未指定且无默认源）。

5. 后端关联

5.1 API 客户端

action/web/src/api/decisionApi.js（复用 aipClient）；askDecision 请求单独 timeout: 300000（5 分钟，多步 LLM）；统一响应体 {code, message, data}，code 非 0 抛错。

5.2 端点表

方法	路径	请求体/参数	页面触发点	成功响应 data
POST	`/decision/answer`	`{question, data_source}`	提问	`{answer, steps, citations}`
GET	`/decision/answers`	`limit=20`	加载历史	`{answers, total}`
GET	`/decision/answers/:id`	—	历史回放	`{answer, steps, citations}`

5.3 关键机制

5 步链：decompose（问题拆解）→ retrieve（三路检索 + 融合去重）→ verify（证据核验 support/refute/irrelevant）→ synthesize（生成 markdown 答案）→ cite（引用溯源）。步骤状态：ok 完成、degraded 降级、skipped 跳过，每步带 latency_ms。
三路检索：rag（知识/RAG 多路召回）、entity（实体通道，直查 aie_entities）、nlq（结构化查询通道）。数据源语义（报告 63 口径）：data_source 显式指定优先；为空时回退注入的默认源 aip_demo_warehouse（defaultDS）；仅「未指定且无默认源」才跳过并标 skipped_no_datasource。归因来源写入 detail.nlq_datasource_source：request（请求显式指定）/ default（回退默认源）/ none（未指定且无默认源），使「回退查询」与「用户显式指定该源」在步骤明细与审计事件中可区分、可审计。后端 resolveDataSource（products/aip/decision/service.go:116-124）、retrieveAll（:418-448）。
步骤明细（StepRecord.detail）：每步 detail（map[string]any，json:"detail,omitempty"，products/aip/decision/models.go:107-117）随响应返回，前端按中文键名渲染可展开明细。各步实际键：decompose→sub_questions（子问题字符串数组）/llm_ok；retrieve→rag/entity/nlq（各为 "skipped"/"skipped_no_datasource"/"failed"/命中行数）、rag_error/entity_error/nlq_error（后端 errDetailMax=300 截断）、nlq_datasource（实际使用的源名）、nlq_datasource_source（归因）、candidates（候选证据数）、fused（融合后证据数）、note；verify→llm_ok/llm_retries/unverified/supported/dropped/note；synthesize→llm_ok/evidence_used/answer_chars；cite→citations。
降级约定：单步失败一律降级继续（verify 失败按 support 处理并标注未核验；synthesize 失败降级为证据摘要 markdown；某路检索失败跳过不阻塞）。
审计留痕：答案 ID 即 trace_id，与 ai_decision 审计轨迹 ref_id 一致，可在 Admin「AI 决策审计」按 trace_id 回放；数据落表 ad_answers / ad_citations（服务 AutoMigrate 建表）。

6. 权限与安全

三个端点均挂 protected 登录组（JWT 鉴权）。
答案 markdown 在浏览器端先 marked 解析，再经 DOMPurify.sanitize 清洗后才以 v-html 输出，防 XSS。
引用与步骤均只读展示；历史按登录用户 created_by 归属记录。

7. 常见问题与排错

提问后长时间无响应：原因是同步多步 LLM，通常需数秒至数十秒（客户端超时 300s）。处理：耐心等待；超时后提示「决策链执行失败」，确认 AIP 后端 18080 与 LLM 网关（/api/v1/llm）可用。
步骤显示「降级」或某步跳过：原因是对应通道依赖未注入（无 RAG 索引、无实体数据，或未指定数据源且无默认源）。处理：属设计行为，答案仍会生成；数据源名留空时后端会回退默认源 aip_demo_warehouse（步骤明细「归因」标注来源），需要指定其它源时在提问框填写；需要完整三路检索时先建知识库/实体。展开「三路检索」步骤可查看各路命中/跳过/失败与数据源归因。
答案区提示「暂无答案」：原因是尚未提问且未选择历史。处理：在左栏提问，或点击「最近提问」中的历史条目。
历史加载失败/刷新历史报错：原因是 GET /decision/answers 失败（后端未启动、token 失效 401）。处理：确认 18080 启动与 token 有效；Network 查看具体状态码。

8. 已知缺陷与边界

三路检索任一依赖（rag/entities/nlq）未注入则对应通道跳过并标注，不报错；LLM 为 nil 时全链降级。
已选中的证据链经 URL ?id= 持久化，刷新可恢复（GET /decision/answers/:id 早已支持）；仅「进行中」的同步链不可续（后端为同步接口，无任务化/断点续传，属后端契约边界）。
数据源名为空时回退默认源 aip_demo_warehouse 并在步骤明细标注归因（request/default/none），不再一律「跳过」。
历史列表为轻量摘要（不含 steps/citations 正文），完整回放需再请求详情接口。
markdown 渲染覆盖标题/列表/引用/表格/行内代码等常用元素，复杂排版有限。