Results & Review

1. 目标 & 范围

1.1 目标

Results & Review 模块是 AgentSurvey 闭环的最后一公里：研究人员在访谈完成后，通过结构化界面判断哪些字段可信、哪些需要人工介入，并最终导出可用于决策的数据集。

核心目标：

让研究人员一眼看出哪些字段可信、哪些需要 review，而不必逐条翻阅原始对话。
提供从「字段结论」到「原始证据 → 对话 turn」的完整回链，支撑研究可信度与可审计性。
支持人工修正并保留 review history，确保修正过程本身可追溯。
提供结构化导出，对接下游分析工具。

1.2 范围

MVP（P0）包含：

Sessions 列表（状态、质量得分、关键指标）
Session 详情（transcript viewer、tool call timeline、extracted fields 表）
Extracted Fields 表（跨 session 视图，含 value / confidence / status / evidence 数）
Evidence Panel（点击字段 → quote / session metadata / transcript 上下文 / tool selection，可跳转原始 turn）
人工 review / 修正字段值（保留 review history，extracted_by 记为 human）
过滤（按 field_name / status / min_confidence / session_id）
导出（JSON / CSV，异步任务，可选含 transcript / evidence）

不在本模块范围（P1+）：

跨 session StudyInsight 聚合（见 00_overview.md 非目标）
批量自动修正
结果可视化图表
团队协作审批流

字段与证据数据定义见 06_extraction_evidence。

2. 用户故事

作为研究人员，我希望在一个列表页看到本 study 所有 sessions 及其状态和质量得分，以便快速判断哪些 session 值得深入查看。

作为研究人员，我希望在 session 详情页同时看到完整 transcript、tool call 记录和抽取字段，以便理解 Agent 的推理过程和字段来源。

作为研究人员，我希望在 Extracted Fields 表中看到每个字段的 confidence 和 status（颜色编码），以便一眼识别需要 review 的字段，而不必逐条阅读对话。

作为研究人员，我希望点击某个字段后，在侧边 Evidence Panel 看到支持该字段的原始 quote 和工具选择，并能跳转到对应 transcript turn，以便核实字段准确性。

作为研究人员，我希望直接在界面修改字段值并留下 review note，以便人工修正低质量抽取结果，同时保留审计记录。

作为研究人员，我希望按字段名、status、最低 confidence、session 过滤字段表，以便批量处理同类问题。

作为研究人员，我希望以 JSON 或 CSV 格式导出结果，可选包含 transcript 和 evidence，以便对接 Notion、Google Sheets、统计工具等下游流程。

3. 功能需求

Sessions 列表

FR-07-1 P0 Sessions 列表视图

显示当前 study 下所有 sessions，每行包含：session_id（截断显示）、status（created / active / completed / abandoned）、quality_score（0–1，来自 sessions.quality_score）、started_at、completed_at、field_coverage（已填字段数 / 必填字段总数）、evidence_coverage（有证据字段数 / 已填字段数）。

验收要点：

列表按 started_at 倒序排列，默认展示最近 50 条，支持分页。
status 用颜色 tag 区分（completed = 绿，abandoned = 灰，active = 蓝）。
quality_score 以进度条或数值显示，低于 0.6 时标红。

FR-07-2 P0 Sessions 列表过滤与搜索

支持按 status、quality_score 区间、started_at 日期范围过滤 sessions。

验收要点：

过滤条件变更后列表实时更新，无需手动刷新页面。
同时勾选多个 status 值时取并集。

Session 详情

FR-07-3 P0 Session 详情页三栏布局

Session 详情页包含三个区域：左侧 Transcript Viewer、中部 Tool Call Timeline、右侧 Extracted Fields 表（或 Evidence Panel）。页面路由为 /studies/[studyId]/sessions/[sessionId]。

验收要点：

三栏布局在 1280px 以上宽度正常展示；1024px 以下切换为 tab 切换模式。
页面加载使用 GET /api/sessions/{session_id}，一次性取 transcript + tool_calls + extracted_fields（见 02_api_contracts）。

FR-07-4 P0 Transcript Viewer

按 turn_index 升序渲染 transcript_turns，区分 role（assistant / user）气泡样式。

验收要点：

每条 turn 显示 turn_index、role、content、created_at。
Evidence Panel 跳转时，目标 turn 高亮并自动滚动到可见区域。
content_json 存在时（如 interaction result 摘要）渲染结构化展示，否则渲染纯文本。

FR-07-5 P0 Tool Call Timeline

在独立区域按时间顺序列出本 session 的 tool_calls，显示 tool_name、status、started_at、completed_at（耗时）。

验收要点：

可展开单条 tool call 查看 tool_input 和 tool_output（JSON pretty-print）。
status 异常（error）的条目标红，并显示 error 字段内容。
Tool call 条目点击后，Transcript Viewer 跳转到关联的 turn_id。

Extracted Fields 表

FR-07-6 P0 字段表核心列

ExtractedFieldsTable 展示以下列：field_name（schema label）、value（截断，hover 展示全文）、confidence（0–1 数值 + 颜色条）、status（draft / accepted / rejected / needs_review）、evidence 数（关联 evidence_refs 条数）、extracted_by（agent / post_processor / human）、操作（Edit / Accept / Reject）。

验收要点：

confidence < confidence_threshold（字段 schema 配置）时，整行背景标黄。
status = needs_review 时，整行背景标橙，顶部显示”待 review 字段数”badge。
evidence 数 = 0 且 evidence_required = true 时，evidence 列显示警告图标。
extracted_by = human 时显示”已人工修正”标签。

FR-07-7 P0 字段表过滤

支持按 field_name（下拉多选）、status（多选）、min_confidence（滑块或数值输入）、session_id（单选）过滤字段表。

验收要点：

过滤参数映射到 GET /api/studies/{study_id}/extracted-fields 的 query params（field_name / status / min_confidence / session_id）。
切换过滤条件时 URL query string 同步更新，支持浏览器前进/后退。
清除所有过滤的”重置”按钮始终可见。

FR-07-8 P0 字段表排序

支持按 confidence（升序/降序）、status、field_name 排序。

验收要点：

默认排序：status（needs_review 优先）→ confidence 升序，使最需关注的字段置顶。
列头点击切换排序，再次点击切换方向，第三次恢复默认。

Evidence Panel

FR-07-9 P0 Evidence Panel 触发与布局

点击字段表任意行，右侧滑出或替换 Evidence Panel，显示该字段的所有 evidence_refs。

验收要点：

Panel 打开时，字段表对应行保持高亮选中状态。
Panel 宽度约 400px，可拖拽调整；在窄屏切换为全屏模态框。
同时展示字段元信息：field_name / value / confidence / reasoning_summary（若有）。

FR-07-10 P0 Evidence 条目展示

每条 evidence_ref 显示：evidence_type（user_quote / tool_selection / system_observation）、strength（strong / medium / weak，颜色区分）、quote（带块引用样式）、session_id（可点击跳转）、关联 turn_id 或 tool_call_id。

验收要点：

strength = strong 绿色标签，medium 黄色，weak 灰色。
evidence_type = user_quote 时显示引号样式块；tool_selection 时显示工具图标和选项摘要。
多条 evidence 按 strength 降序排列（strong 在上）。

FR-07-11 P0 Evidence 跳转原始 turn

点击 evidence 条目的”查看原文”，Transcript Viewer 跳转至对应 turn_id 并高亮该 turn。若当前在 Study-level 字段表（跨 session 视图），跳转前先导航到对应 session 详情页。

验收要点：

跳转后目标 turn 位于视口中部，背景高亮持续 3 秒后消退。
若 turn_id 为空（仅 tool_call_id），跳转到 Tool Call Timeline 对应条目。
跳转逻辑通过 anchor hash 或受控 scroll 实现，不触发整页重载。

人工 Review 与修正

FR-07-12 P0 快速接受 / 拒绝字段

字段表每行提供 Accept（✓）和 Reject（✗）操作按钮，点击后调用 PATCH /api/extracted-fields/{field_id}，将 status 更新为 accepted 或 rejected，extracted_by 保持原值不变。

验收要点：

操作后字段行 status 即时更新，无需刷新页面。
批量操作：勾选多行后支持”批量接受”或”批量拒绝”，单次最多 50 条。
操作结果在操作栏显示成功/失败反馈（toast），失败时保留原状态。

FR-07-13 P0 修正字段值（Field Review Dialog）

点击字段行的”Edit”或双击 value 单元格，弹出 FieldReviewDialog，展示：当前 value、confidence、reasoning_summary、所有 evidence；提供 value 编辑区域（类型与 schema field type 匹配）和 review_note 文本框。

验收要点：

提交修正调用 PATCH /api/extracted-fields/{field_id}，body 含 value（新值）、status（固定为 accepted）、review_note，后端将 extracted_by 更新为 human。
Dialog 展示字段 schema 约束（type、enum 选项、required），value 输入需通过前端格式校验才可提交。
修正成功后 Dialog 关闭，字段行显示”已人工修正”标签，confidence 列显示”—“（人工值无置信度）。

FR-07-14 P0 Review History

每个字段支持查看完整的 review history：历次 value 变更、status 变更、review_note、操作者、updated_at。

验收要点：

Review history 在 FieldReviewDialog 底部折叠区展示，默认收起。
History 数据来自后端 audit log，展示顺序为时间倒序。
至少保留最近 10 条历史记录。

导出

FR-07-15 P0 发起导出任务

点击”Export”按钮，弹出导出配置面板，选项包括：format（JSON / CSV）、include_transcript（是/否）、include_evidence（是/否）、session_ids（可选，不填则导出全部）。确认后调用 POST /api/studies/{study_id}/exports。

验收要点：

调用成功后返回 { export_id, status: "processing" }，界面显示”导出任务已创建”。
CSV 格式选项不可同时勾选 include_transcript（transcript 为非结构化文本，不适合 CSV 展平），界面灰化并提示。
导出面板需展示”预计文件大小”提示（基于 session 数估算）。

FR-07-16 P0 导出任务状态与下载

导出任务异步执行，完成后在界面提供下载链接，并记录到 exports 表。

验收要点：

界面每 5 秒轮询导出任务状态，status = completed 后展示”下载”按钮，failed 时展示错误原因。
导出文件命名格式：{study_name}_{export_id}_{format}.{ext}。
JSON 导出结构包含 sessions[]、每个 session 的 extracted_fields[]，以及（若勾选）transcript[] 和 evidence_refs[]。

4. 关键流程

4.1 研究人员 review 单个 session

进入 /studies/{studyId}/sessions
→ 查看 Sessions 列表，识别 quality_score 低 / status = abandoned 的 session
→ 点击行，进入 Session 详情页
→ 查看 Extracted Fields 表，识别 status = needs_review 或 confidence 低的字段
→ 点击字段行，打开 Evidence Panel
→ 核查 quote 与 transcript turn（点击"查看原文"跳转）
→ 在字段行点击 Accept / Reject，或打开 FieldReviewDialog 修正值
→ 修正完成，字段 status 更新，reviewed 计数增加

4.2 研究人员批量 review 字段（跨 session）

进入 /studies/{studyId}/results（Study-level extracted fields 视图）
→ 过滤：status = needs_review + field_name = "main_pain_point"
→ 逐条查看 Evidence Panel（证据不足则 Reject，证据充分则 Accept）
→ 或勾选多行 → 批量 Accept
→ 导出 JSON（include_evidence = true）

4.3 查看完整证据链（审计路径）

字段值 → Evidence Panel（EvidenceRef）→ 点击"查看原文"
→ Transcript Viewer 高亮 turn_id（transcript_turns.id）
→ 或 Tool Call Timeline 高亮 tool_call_id（tool_calls.id）

数据链路：extracted_fields → evidence_refs（extracted_field_id / turn_id / tool_call_id）→ transcript_turns / tool_calls（见 03_data_model）。

5. 数据

本模块主要读写以下表（详见 03_data_model）：

表	主要用途
`sessions`	列表视图：`status`、`quality_score`、`started_at`、`completed_at`
`transcript_turns`	Transcript Viewer：按 `session_id` + `turn_index` 升序渲染
`tool_calls`	Tool Call Timeline：`tool_name` / `tool_input` / `tool_output` / `status`
`extracted_fields`	字段表：`value` / `confidence` / `status` / `extracted_by`；人工修正后写回
`evidence_refs`	Evidence Panel：关联 `extracted_field_id`，含 `quote` / `strength` / `turn_id` / `tool_call_id`
`exports`	记录导出任务 `status` 和下载地址

关键字段依赖：

extracted_fields.schema_version_id 关联 output_schema_versions，用于在 Review Dialog 中展示字段 schema 约束（type、enum 选项、required）。
evidence_refs.extracted_field_id 是字段与证据的核心外键；turn_id 和 tool_call_id 是 Evidence Panel 到 Transcript 跳转的回链键。
sessions.quality_score 由 post-session evaluation job 写入（见 01_evaluation_metrics），Results 模块只读不写。

6. 接口

本模块调用的核心 API（详见 02_api_contracts）：

操作	方法 & 路径	说明
获取 sessions 列表	`GET /api/studies/{study_id}/sessions`	支持 `status` / 日期范围过滤
获取 session 详情	`GET /api/sessions/{session_id}`	返回 `session` + `transcript` + `tool_calls` + `extracted_fields`
获取字段列表（跨 session）	`GET /api/studies/{study_id}/extracted-fields`	query params: `field_name` / `status` / `min_confidence` / `session_id`
修正字段	`PATCH /api/extracted-fields/{field_id}`	body: `value` / `status` / `review_note`；后端更新 `extracted_by = human` 并写 audit log
发起导出	`POST /api/studies/{study_id}/exports`	body: `format` / `include_transcript` / `include_evidence` / `session_ids`
查询导出状态	`GET /api/studies/{study_id}/exports/{export_id}`	返回 `status` / `download_url`

PATCH /api/extracted-fields/{field_id} 必须记录 audit log，保留历次 value、status、review_note 变更（见 api_contracts.md 原则第 4 条）。

7. 验收标准

AC-07-01 打开 Sessions 列表，显示本 study 所有 sessions，每行包含 status（颜色 tag）、quality_score（数值）、field_coverage、evidence_coverage；quality_score < 0.6 的行标红，列表按 started_at 倒序排列。

AC-07-02 Sessions 列表过滤：选择 status = completed，列表仅显示 completed sessions；同时设置 quality_score >= 0.7，列表进一步缩小；清除过滤后恢复全部。

AC-07-03 进入 Session 详情页，三栏（Transcript Viewer / Tool Call Timeline / Extracted Fields）在 1280px 宽度同时可见；窄于 1024px 时切换为 tab 模式，三个 tab 均可正常切换。

AC-07-04 Transcript Viewer 按 turn_index 升序渲染所有 turns，assistant 和 user 气泡样式不同，每条显示时间戳。

AC-07-05 Tool Call Timeline 列出所有 tool_calls，展开一条后显示 tool_input / tool_output JSON；点击该条目，Transcript Viewer 自动滚动并高亮关联 turn_id。

AC-07-06 Extracted Fields 表：confidence < confidence_threshold 的行背景标黄；status = needs_review 的行背景标橙；evidence 数 = 0 且 evidence_required = true 的行 evidence 列显示警告图标；页面顶部显示”待 review: N 条”badge（N = needs_review 条数）。

AC-07-07 字段表过滤：选择 status = needs_review，仅显示对应字段；设置 min_confidence = 0.8，进一步过滤；URL query string 同步更新；浏览器后退后过滤条件复原。

AC-07-08 字段表默认排序：needs_review 行在最上方，同 status 内按 confidence 升序；点击 confidence 列头切换排序方向。

AC-07-09 点击字段行，Evidence Panel 打开，显示所有关联 evidence_refs，按 strength 降序排列（strong 在上），每条显示 evidence_type 图标、strength 颜色标签、quote 块引用。

AC-07-10 在 Evidence Panel 点击某条 evidence 的”查看原文”，Transcript Viewer 自动滚动到对应 turn_id 并高亮该 turn，高亮持续 3 秒后消退；若来源是 tool_call_id，则高亮 Tool Call Timeline 对应条目。

AC-07-11 点击字段行的 Accept 按钮，该行 status 立即更新为 accepted（无需刷新），顶部 badge 计数减 1；点击 Reject 同理，status 更新为 rejected。

AC-07-12 批量操作：勾选 3 行（混合 needs_review 和 draft），点击”批量接受”，3 行全部更新为 accepted，操作栏显示”已接受 3 条”toast。

AC-07-13 打开 Field Review Dialog，显示当前 value、confidence、reasoning_summary、所有 evidence 列表；修改 value 为新值，填写 review_note，提交后字段行 value 更新、显示”已人工修正”标签、confidence 列显示”—“；Dialog 展示 Schema 约束（如 enum 选项），非法值无法提交。

AC-07-14 打开 Field Review Dialog 的 Review History 区域，展示至少两条历史记录，每条包含时间、操作者、旧值、新值、review_note，顺序为时间倒序。

AC-07-15 发起 CSV 导出（include_evidence = true）：界面显示”导出任务已创建”；5 秒内轮询到 status = completed（或在测试环境 mock 完成），出现”下载”按钮；下载文件名符合 {study_name}_{export_id}_csv.csv 格式。

AC-07-16 勾选 CSV 格式后，include_transcript 复选框灰化不可勾选，并显示提示文案；切换到 JSON 格式后，include_transcript 复选框恢复可用。

AC-07-17 JSON 导出文件（include_evidence = true）结构验证：顶层含 sessions[]；每个 session 含 extracted_fields[]；每个 field 含 evidence_refs[]；所有 extracted_field_id 在 evidence_refs 中可关联。

8. 边界 & 非目标

不做跨 session 的 StudyInsight 聚合视图（P1）。字段表的 session 维度是必选过滤，不自动合并多 session 同名字段。
不做结果图表与可视化（如 confidence 分布直方图、字段完成率饼图），这些在 P1 Quality Dashboard 中实现（见 01_evaluation_metrics）。
不做团队协作审批流（如指派 reviewer、评论、审批状态流转）。
不做Export 文件在平台内预览，只提供下载链接。
不做自动批量修正（如”将所有 confidence < 0.5 的字段批量 reject”的规则引擎）。
sessions.quality_score 由 evaluation job 写入，Results 模块只读，不提供手动修改入口。
Transcript Viewer 只读，不支持研究人员编辑 transcript 内容。

9. 依赖 & 风险

9.1 依赖

依赖	说明
06_extraction_evidence	`extracted_fields` 和 `evidence_refs` 数据由抽取流程生成，Results 模块消费；字段的 `status = needs_review` 由抽取规则设置
04_interview_runtime	`transcript_turns` 和 `tool_calls` 由访谈运行时写入，Results 模块只读
03_data_model	`extracted_fields` / `evidence_refs` / `sessions` / `transcript_turns` / `tool_calls` 表结构
02_api_contracts	`GET /api/sessions/{id}`、`PATCH /api/extracted-fields/{id}`、`POST /api/studies/{id}/exports` 等接口
01_evaluation_metrics	`sessions.quality_score`、`field_coverage`、`evidence_coverage` 由 post-session evaluation job 写入
03_frontend_components	`SessionsTable` / `SessionDetail` / `TranscriptViewer` / `ToolCallTimeline` / `ExtractedFieldsTable` / `EvidencePanel` / `FieldReviewDialog` / `ExportButton` 组件规范

9.2 风险

风险	影响	缓解措施
Session 数据量大（transcript 数千 turns）导致详情页加载慢	研究人员等待时间长，体验差	`GET /api/sessions/{id}` 响应分页（transcript 默认加载前 100 turns，滚动时懒加载）；`tool_calls` 按需展开
`evidence_refs` 与 `transcript_turns` 的 `turn_id` 对应关系在重跑抽取后可能失效	证据跳转到错误 turn	重跑抽取时必须用新的 `evidence_id`，禁止复用旧 `evidence_id`；前端跳转前校验 `turn_id` 是否存在于当前 session
人工修正与 agent 抽取并发（重跑抽取覆盖人工值）	人工修正丢失	`extracted_by = human` 的字段在重跑抽取时跳过；若强制重跑需在 UI 中显式确认并记录 audit log
Export 大文件（多 sessions + transcript + evidence）导致超时	导出失败，研究人员无法获取数据	导出强制异步任务（`exports` 表）；前端轮询状态；后端限制单次导出最多 200 sessions，超出提示分批导出
字段 schema 版本迭代后旧字段无法正确渲染枚举选项	Review Dialog 显示异常	`extracted_fields.schema_version_id` 关联 `output_schema_versions`，Review Dialog 按该版本加载 enum 选项，不用最新 schema