前端组件拆分方案

前端组件拆分方案

目标

前端需要同时支持：

1. 研究人员配置项目和 study；
2. 受访者完成 AI 访谈；
3. Agent tool call 驱动交互组件；
4. 研究人员查看结果和 evidence。

对话运行时（assistant-ui + AG-UI）

受访者 Interview 端基于 assistant-ui 构建，通过 AG-UI adapter（@assistant-ui/react-ag-ui）消费后端 LangGraph 经 AG-UI 协议推送的事件（消息流、tool call、human-in-the-loop）。要点：

• 下文的 InteractionRenderer 由 assistant-ui 的 generative UI 驱动：Agent 的 render_interaction tool call → 映射到对应交互组件。
• 受访者端是定制 timeline（message / interaction card / result 混排），禁用 chatbot 式 edit / regenerate / branch。
• 交互组件本体（RadioCardGroup 等）仍为自研，结果走独立的 session submit API（见 02_api_contracts.md）。
• Admin / Study Builder / Results 用常规 React，不套对话框架。

完整选型见 ../03_architecture/05_tech_stack_decision.md。

页面结构

/app
  /dashboard
  /projects
    /[projectId]
      /overview
      /knowledge
      /studies
      /results
  /studies
    /[studyId]
      /builder
      /preview
      /sessions
      /results
      /settings
  /sessions
    /[sessionId]
  /interview
    /[publicSlug]

组件分层

1. Layout Components

components/layout/
  AppShell.tsx
  Sidebar.tsx
  TopNav.tsx
  Breadcrumbs.tsx

2. Study Builder Components

components/study-builder/
  StudyBuilderShell.tsx
  ResearchBriefEditor.tsx
  ObjectivesEditor.tsx
  InterviewGuideEditor.tsx
  AgentConfigEditor.tsx
  ToolSelector.tsx
  OutputSchemaBuilder.tsx
  KnowledgeBaseSelector.tsx
  StudyPreview.tsx
  PublishPanel.tsx

3. Interview Components

components/interview/
  InterviewShell.tsx
  ChatTimeline.tsx
  MessageBubble.tsx
  StreamingMessage.tsx
  Composer.tsx
  InteractionRenderer.tsx
  ProgressIndicator.tsx
  CompletionScreen.tsx

4. Interaction Components

components/interactions/
  InteractionRenderer.tsx
  RadioCardGroup.tsx
  CheckboxCardGroup.tsx
  LikertScale.tsx
  NpsScale.tsx
  RatingScale.tsx
  RankingList.tsx
  MatrixQuestion.tsx
  TextInputCard.tsx
  ModalForm.tsx
  ConceptCard.tsx
  ComparisonCards.tsx
  ConsentPanel.tsx

5. Results Components

components/results/
  SessionsTable.tsx
  SessionDetail.tsx
  TranscriptViewer.tsx
  ToolCallTimeline.tsx
  ExtractedFieldsTable.tsx
  EvidencePanel.tsx
  FieldReviewDialog.tsx
  InsightCard.tsx
  ExportButton.tsx

Interaction Renderer

前端核心是 interaction registry。

const interactionRegistry = {
  single_choice: RadioCardGroup,
  multiple_choice: CheckboxCardGroup,
  likert: LikertScale,
  nps: NpsScale,
  rating: RatingScale,
  ranking: RankingList,
  matrix: MatrixQuestion,
  text_input: TextInputCard,
  modal_form: ModalForm,
  concept_card: ConceptCard,
  comparison: ComparisonCards,
  consent: ConsentPanel,
};

示例：

export function InteractionRenderer({ interaction, onSubmit }) {
  const Component = interactionRegistry[interaction.type];

  if (!Component) {
    return <UnsupportedInteraction interaction={interaction} />;
  }

  return (
    <Component
      interaction={interaction}
      onSubmit={(value, clientContext) =>
        onSubmit({
          interaction_id: interaction.interaction_id,
          type: interaction.type,
          status: "submitted",
          value,
          submitted_at: new Date().toISOString(),
          client_context: clientContext,
        })
      }
      onSkip={() =>
        onSubmit({
          interaction_id: interaction.interaction_id,
          type: interaction.type,
          status: "skipped",
          value: null,
          submitted_at: new Date().toISOString(),
        })
      }
    />
  );
}

组件设计原则

1. 每个 interaction component 只关心展示和采集值。
2. validation 由 schema + 组件共同处理。
3. submit 的 result 格式统一。
4. 组件不直接调用 Agent API，由 InterviewShell 统一提交。
5. 组件要支持 disabled/loading/submitted 状态。
6. 移动端可用。
7. 支持跳过和无障碍访问。

Chat + Interaction Timeline

受访者端不是“消息和表单分离”，而是一个 timeline：

Assistant message
User message
Assistant message
Interaction card
User submitted result
Assistant follow-up

Interaction result 可以展示成轻量摘要：

你选择了：人工整理成本高、输出质量不稳定

Modal 策略

不是所有 interaction 都用 modal。

建议：

• 单选/多选/评分：inline card。
• 排序/矩阵：modal 或 wide card。
• 概念卡片：modal 或 side panel。
• consent：full panel。
• 文件上传：modal。

Study Builder UX

第一版 Study Builder 不必做复杂拖拽 workflow，可以做 stepper：

1. Brief
2. Objectives
3. Guide
4. Agent
5. Tools
6. Output
7. Publish

每步都可以保存草稿。

Results UX

核心是可信度：

• 字段值；
• confidence；
• evidence 数；
• status；
• review 操作。

点击 evidence 时，右侧 panel 展示：

• quote；
• session metadata；
• transcript 上下文；
• tool selection；
• extracted rationale。

推荐实现顺序

1. ChatTimeline + MessageBubble。
2. InteractionRenderer。
3. RadioCardGroup。
4. CheckboxCardGroup。
5. LikertScale。
6. RankingList。
7. SessionDetail + TranscriptViewer。
8. ExtractedFieldsTable + EvidencePanel。
9. StudyBuilder minimal editor。

前端风险

风险	缓解
组件类型过多	MVP 只做 4 个
schema 不稳定	固定 schema_version
modal 打断访谈	默认 inline，复杂组件才 modal
状态难同步	所有交互提交统一走 session API
streaming/tool event 混乱	定义标准 StreamEvent union