Non-functional Requirements
非功能需求（Non-functional Requirements）
本模块为贯穿全平台的非功能需求，适用于所有功能模块（01–09）及后端服务。编号格式
NFR-10-<n>；验收标准均可测试。交叉引用采用文件名形式。非功能需求不重复 00_overview 中已表述的产品目标与架构原则。
1. 性能与并发
背景：平台需同时支持多个 study 的受访者并发访谈，以及研究人员在结果页的实时查看。
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-01 | 受访者端首帧 TTFB（首字节）≤ 800 ms（P95，排除模型推理延迟） | P0 |
| NFR-10-02 | Agent 流式消息首 token 到达前端 ≤ 2 s（P95，GPT-4o 级模型，非 local） | P0 |
| NFR-10-03 | 交互组件（Interaction）渲染后受访者提交的处理往返 ≤ 1 s（P95） | P0 |
| NFR-10-04 | MVP 单体部署支持 ≥ 50 路并发 session，无单会话状态泄漏 | P0 |
| NFR-10-05 | 结构化抽取（post-session extraction）在 session 结束后 ≤ 30 s 完成（P95，transcript ≤ 200 turn） | P0 |
| NFR-10-06 | Results 页面初始加载（含 field list + evidence preview）≤ 2 s（P95，单 study ≤ 500 sessions） | P1 |
验收方式：用 k6 / Locust 打 50 并发场景，采集 P50/P95/P99；模型延迟作为 excluded variable 单独记录。
2. 安全与隐私
背景：访谈内容可能涉及公司内部信息、个人隐私及高敏场景。完整分析见 02_security_privacy。
2.1 同意（Consent）
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-07 | 受访者进入访谈前必须完成 Consent 步骤，明确告知：调研目的、AI 主持事实、对话是否录制、是否可匿名、如何退出 | P0 |
| NFR-10-08 | Consent 可配置为 required（不同意则无法继续）或 optional；Consent 结果持久化到 session 记录 | P0 |
验收：自动化测试模拟跳过 Consent 直接进入访谈，期望返回 403 或强制跳转至 Consent 页。
2.2 PII 标记与脱敏
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-09 | transcript 存储时同时保留 raw 版本与 redacted 版本；PII spans（name / email / phone / company / account_id / health_info）以结构化字段标记 | P0 |
| NFR-10-10 | 研究人员查看 transcript 时，可切换 raw / redacted 视图；导出时默认使用 redacted 版本（可选 raw） | P1 |
验收：注入包含 email 与姓名的 transcript，调用 PII 检测接口，期望返回包含对应 span 的结构化标记。
2.3 数据隔离
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-11 | 所有数据库查询必须携带 workspace_id scope；缺失 scope 的查询在 ORM / Query builder 层拒绝执行 | P0 |
| NFR-10-12 | KB retrieval 限定在当前 study/project 边界内，不得跨 workspace 泄露 | P0 |
| NFR-10-13 | Public session（受访者端）API 与 Admin API 物理分离（不同路由前缀 / 中间件），public session 无法调用任何 Admin API | P0 |
验收：集成测试中以受访者 token 调用 Admin 端点，期望 401/403；以 workspace A 的 token 查询 workspace B 数据，期望空集或 403。
2.4 Public Link 安全
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-14 | study public_slug 使用加密随机字符串（≥ 128 bits entropy），不可枚举；支持过期时间、最大 session 数、allowed domains 配置 | P0 |
| NFR-10-15 | public link 端点接入 rate limit（≤ 20 req/min per IP）防刷；screening 不通过时提前结束并返回中性提示 | P0 |
验收：暴力枚举测试（连续请求 1000 个随机 slug）期望命中率 < 0.01%；超速请求期望 429 响应。
2.5 Audit Log
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-16 | 以下操作必须写入 audit log（workspace_id / actor_id / action / resource_type / resource_id / before / after / created_at）：config 变更、study 发布/下线、session 访问、导出、手动修正、model config 变更、KB 变更、tool enable/disable | P0 |
| NFR-10-17 | audit log 为 append-only，不可通过业务 API 删除；保留期不少于 90 天（可配置） | P0 |
验收：执行导出操作后查询 audit log，期望存在对应记录且 actor_id 非空。
2.6 Prompt / Agent 安全
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-18 | Agent system prompt 必须包含：声明 AI 身份、单次一问、允许跳过敏感问题、不泄露 study 配置细节、不输出诊断/法律/财务高风险建议 | P0 |
| NFR-10-19 | Model API key 仅在后端 Model Gateway（LiteLLM）持有，不得出现在任何前端响应、日志或 AG-UI 事件中 | P0 |
| NFR-10-20 | Tool call input 在执行前经 JSON Schema validation；high-risk tool（外部 webhook / CRM write）须记录 audit 且可配置需 approval | P0 |
验收：前端网络请求抓包，确认无 API key 字段；向 Agent 发送注入尝试（“忽略前面的指令”），期望 Agent 输出仍符合 safety 规则。
2.7 Model Provider 透明度
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-21 | 每个 study 的 provider 配置页面显示：provider 名称、数据是否发送第三方、是否启用 provider 侧日志、retention policy | P1 |
3. 可观测性
背景：可观测性栈采用 LangSmith + OpenTelemetry，详见 05_tech_stack_decision。
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-22 | 每次 LLM 调用通过 LangChain callbacks 上报到 LangSmith，覆盖：prompt、completion、model、latency_ms、token_usage（prompt/completion/total）、cost | P0 |
| NFR-10-23 | 每次 Agent decision（AgentDecisionLog，见 02_agent_harness）写入持久化存储，字段包含：session_id / phase / selected_action / rationale / model / prompt_version_id / latency_ms / token_usage | P0 |
| NFR-10-24 | OpenTelemetry trace 覆盖：API 请求、LangGraph node 执行、tool call、extraction job；trace 可与 LangSmith run 关联（通过 trace_id） | P0 |
| NFR-10-25 | 系统提供 Quality Dashboard（见 01_evaluation_metrics），实时显示：completion rate / objective coverage / field coverage / evidence coverage / manual correction rate / review queue size | P1 |
| NFR-10-26 | 异常（LLM timeout / tool error / extraction failure）触发结构化告警日志（level=ERROR，含 session_id / error_type / stack）；告警可对接外部监控（PagerDuty / Slack webhook，可配置） | P1 |
验收：完成一次访谈后，在 LangSmith 中查询对应 run，期望 token_usage 非零；在 OTel 后端查询 trace，期望各 span 完整。
4. 可审计与可重放
背景：可审计/可重放是平台核心差异化，架构设计基础见 01_system_architecture 的「Event Log」与「配置版本化」章节。
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-27 | Session event log 为 append-only，覆盖完整生命周期事件：session.created / participant.message.created / agent.message.started / agent.message.delta / agent.message.completed / tool.call.created / tool.call.completed / interaction.rendered / interaction.submitted / extraction.started / extraction.completed / session.completed | P0 |
| NFR-10-28 | 每个 session 在启动时快照并绑定全量配置版本（study_config_version_id / agent_config_version_id / output_schema_version_id / kb_version_ids / enabled_tool_version_ids / model_config_version_id），后续配置变更不影响进行中及历史 session | P0 |
| NFR-10-29 | 基于 LangGraph PostgresSaver checkpointer，session 可从任意 checkpoint 重放（time-travel）；研究人员可在 Results 页查看完整 transcript 与 decision log 回溯 | P0 |
| NFR-10-30 | Extraction 可对已完成的 session transcript 重跑（re-extract），使用新版 output schema，生成新版字段集；历史版本字段保留对比 | P0 |
| NFR-10-31 | AgentDecisionLog 中每条 decision 关联 prompt_version_id，支持”为什么当时这样问”的因果追溯 | P0 |
验收：选取任意已完成 session，调用 replay API，期望重放事件序列与原始 event log 一致；修改 output schema 后触发 re-extract，期望新字段集存在且旧版字段集保留。
5. 国际化（i18n）
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-32 | 受访者端 Interview UI 文案（按钮、提示、错误信息、Consent 页）支持多语言，默认语言可在 study 配置中指定；MVP 支持中文（zh-CN）与英文（en） | P0 |
| NFR-10-33 | Admin Console（研究人员端）界面语言跟随用户 locale 设置；MVP 支持中英文切换 | P1 |
| NFR-10-34 | Agent 访谈语言由 study 配置的 interview_language 字段控制，该字段注入 system prompt，Agent 以指定语言与受访者交流 | P0 |
| NFR-10-35 | 所有 i18n 字符串通过 key-value 资源文件管理（前端使用 next-intl 或等效方案），不允许硬编码界面文案 | P1 |
验收：将 study interview_language 设为 en，访谈中受访者发中文，期望 Agent 回复英文；切换 locale 到 zh-CN，期望 Admin UI 所有静态文案变为中文。
6. 无障碍（a11y）
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-36 | 受访者端 Interview UI 与所有 Interaction 组件（RadioCardGroup / LikertScale / RankingList / MultiSelectGroup）满足 WCAG 2.1 AA 标准 | P0 |
| NFR-10-37 | 所有交互组件支持键盘导航（Tab / Arrow keys / Enter / Space）；焦点顺序合理，不出现焦点陷阱 | P0 |
| NFR-10-38 | 图片、图标类元素提供 alt 文本；颜色对比度 ≥ 4.5:1（正文）/ 3:1（大字及 UI 组件边框） | P1 |
| NFR-10-39 | 受访者端在移动端（iOS Safari / Android Chrome）可正常完成完整访谈；移动端完成率基线目标 ≥ 80% | P0 |
验收：使用 axe-core（@axe-core/react）自动扫描受访者端，期望 0 critical / 0 serious 违规；使用 VoiceOver（macOS）手动测试 Likert 组件导航，期望可正常选项切换。
7. 可靠性与容错
背景：LangGraph checkpointer 与 durable execution 是可靠性的基础，参见 02_agent_harness 和 05_tech_stack_decision。
| 编号 | 需求 | 优先级 |
|---|---|---|
| NFR-10-40 | Agent Harness 基于 LangGraph PostgresSaver checkpointer 实现 durable execution：worker 崩溃或部署重启后，session 从最近 checkpoint 自动恢复，受访者刷新页面可继续访谈 | P0 |
| NFR-10-41 | LLM 调用支持自动重试（最多 3 次，指数退避）与 provider fallback（通过 LiteLLM 配置）；单次 LLM 调用失败不导致 session 终止 | P0 |
| NFR-10-42 | Extraction job（post-session / re-extract）运行在异步 worker（Arq / Celery）中；job 失败后支持手动重触发，不影响 session transcript 完整性 | P0 |
| NFR-10-43 | AG-UI SSE 连接中断时，前端自动重连（最多 5 次，退避策略），重连后从最近 agent message delta 续传；连接中断不丢失已提交的受访者回答 | P0 |
| NFR-10-44 | MVP 目标服务可用性 ≥ 99%（月统计），不含计划维护窗口；数据库定时备份，RPO ≤ 1 h | P1 |
| NFR-10-45 | 运行时不依赖全局单例（每个 session 拥有独立 LangGraph graph instance），不同 session 之间状态严格隔离，单 session 故障不级联 | P0 |
验收：模拟 worker 进程在访谈进行中强制 kill，重启后受访者重新连接，期望 session 从中断前最近 turn 继续；注入 LLM 超时（mock），期望重试后成功且 session 正常继续。
关联文档
- 安全与隐私完整分析：06_ops/02_security_privacy
- 质量指标与可观测：06_ops/01_evaluation_metrics
- 系统架构与 Event Log：03_architecture/01_system_architecture
- Agent Harness 与 Decision Log：03_architecture/02_agent_harness
- 技术选型（LangSmith / LangGraph / AG-UI）：03_architecture/05_tech_stack_decision