797 lines
25 KiB
Markdown
797 lines
25 KiB
Markdown
# SSA-Pro 前端 UI 改进开发计划 - V8 双屏版
|
||
|
||
> **文档版本：** v1.1
|
||
> **创建日期：** 2026-02-20
|
||
> **最后更新：** 2026-02-20（根据审查反馈更新）
|
||
> **预计工时：** 3-4 天（前端）
|
||
> **依赖文档：**
|
||
> - `03-UI设计/产品原型图V8双屏版.html`
|
||
> - `03-UI设计/SSA-Pro UX方案对比与技术选型报告.md`
|
||
> - `docs/03-业务模块/AIA-AI智能问答/00-模块当前状态与开发指南.md`
|
||
> - `frontend-v2/src/shared/components/Chat/README.md`（流式响应能力）
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 1.1 背景
|
||
|
||
当前 SSA 前端已实现基础功能（Phase 1 完成 85%），但 UI/UX 存在以下问题：
|
||
|
||
| 问题 | 影响 |
|
||
|------|------|
|
||
| 单列布局 | 统计结果（表格、图表）展示空间狭窄 |
|
||
| 对话被结果顶开 | 用户无法同时查看计划和结果 |
|
||
| 缺乏专业感 | 不像 RStudio/SPSS 等专业统计软件 |
|
||
| 交互割裂 | 数据上传、分析、结果分散在不同卡片 |
|
||
|
||
### 1.2 目标
|
||
|
||
采用 **V8 双屏工作台** 架构（类似 Claude Artifacts），实现：
|
||
|
||
1. **左右分屏**：左侧对话控制 + 右侧工作区（60%+ 空间）
|
||
2. **上下文保持**：对话和结果独立展示，互不干扰
|
||
3. **专业信任感**：类似 RStudio 的布局，提升医生信任
|
||
4. **完整流程可视化**：SAP → 执行日志 → 结果报告
|
||
|
||
---
|
||
|
||
## 2. 架构设计
|
||
|
||
### 2.1 整体布局
|
||
|
||
```
|
||
┌────────┬─────────────────────────┬──────────────────────────────────────┐
|
||
│ 64px │ 400-450px │ 剩余空间 │
|
||
│ │ │ │
|
||
│ 全局 │ 对话控制区 │ 工作区 (Artifacts) │
|
||
│ 导航 │ (ChatPane) │ (ArtifactPane) │
|
||
│ │ │ │
|
||
│ ┌───┐ │ ┌─────────────────────┐ │ ┌─────────────────────────────────┐ │
|
||
│ │新建│ │ │ AI 欢迎语 │ │ │ 视图标题 + 操作按钮 │ │
|
||
│ └───┘ │ │ 用户消息 │ │ └─────────────────────────────────┘ │
|
||
│ ┌───┐ │ │ AI 回复 + 交互卡片 │ │ ┌─────────────────────────────────┐ │
|
||
│ │历史│ │ │ 数据挂载确认 │ │ │ │ │
|
||
│ └───┘ │ │ 执行状态提示 │ │ │ 动态内容区域 │ │
|
||
│ ┌───┐ │ └─────────────────────┘ │ │ - SAP 文档 │ │
|
||
│ │设置│ │ │ │ - 执行日志 │ │
|
||
│ └───┘ │ ┌─────────────────────┐ │ │ - 结果报告（表格 + 图表） │ │
|
||
│ │ │ 📎 数据挂载区 │ │ │ │ │
|
||
│ │ │ ────────────────── │ │ └─────────────────────────────────┘ │
|
||
│ │ │ 输入框 + 发送按钮 │ │ │
|
||
│ │ └─────────────────────┘ │ │
|
||
└────────┴─────────────────────────┴──────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 右侧工作区三种视图
|
||
|
||
| 视图 | 触发条件 | 内容 |
|
||
|------|---------|------|
|
||
| **empty** | 初始状态 | 空状态提示（图标 + 文案） |
|
||
| **sap** | 生成 SAP 后 | 研究目的、推荐方法、统计护栏 |
|
||
| **execution** | 执行分析时 | 实时日志（护栏检查、自动降级） |
|
||
| **result** | 执行完成后 | AI 解读、三线表、图表、R 代码 |
|
||
|
||
### 2.3 状态管理设计
|
||
|
||
```typescript
|
||
// stores/ssaStore.ts 扩展
|
||
interface SSAWorkspaceState {
|
||
// 现有状态
|
||
mode: SSAMode;
|
||
currentSession: SSASession | null;
|
||
currentPlan: AnalysisPlan | null;
|
||
executionResult: ExecutionResult | null;
|
||
traceSteps: TraceStep[];
|
||
|
||
// 🆕 新增：右侧面板状态
|
||
activePane: 'empty' | 'sap' | 'execution' | 'result';
|
||
currentArtifact: {
|
||
type: 'sap' | 'trace' | 'result';
|
||
data: any;
|
||
} | null;
|
||
|
||
// 🆕 新增：数据挂载状态
|
||
mountedFile: {
|
||
name: string;
|
||
size: number;
|
||
rowCount: number;
|
||
} | null;
|
||
|
||
// 🆕 新增：动作
|
||
setActivePane: (pane: 'empty' | 'sap' | 'execution' | 'result') => void;
|
||
setArtifact: (artifact: { type: string; data: any } | null) => void;
|
||
setMountedFile: (file: { name: string; size: number; rowCount: number } | null) => void;
|
||
|
||
// 🆕 新增：历史记录状态恢复（审查反馈 - 盲区二）
|
||
hydrateFromHistory: (session: SSASession) => void;
|
||
}
|
||
```
|
||
|
||
**历史记录状态恢复逻辑**：
|
||
|
||
```typescript
|
||
// hydrateFromHistory 实现
|
||
hydrateFromHistory: (session: SSASession) => {
|
||
// 根据 session 状态恢复右侧面板
|
||
if (session.executionResult) {
|
||
set({
|
||
activePane: 'result',
|
||
currentArtifact: { type: 'result', data: session.executionResult }
|
||
});
|
||
} else if (session.currentPlan) {
|
||
set({
|
||
activePane: 'sap',
|
||
currentArtifact: { type: 'sap', data: session.currentPlan }
|
||
});
|
||
} else {
|
||
set({ activePane: 'empty', currentArtifact: null });
|
||
}
|
||
|
||
// 恢复数据挂载状态
|
||
if (session.dataSchema) {
|
||
set({
|
||
mountedFile: {
|
||
name: session.title,
|
||
size: 0,
|
||
rowCount: session.dataSchema.rowCount,
|
||
}
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 组件复用分析
|
||
|
||
### 3.1 可复用的 AIA 组件
|
||
|
||
| 组件 | 来源路径 | 复用程度 | 改造需求 |
|
||
|------|---------|----------|----------|
|
||
| **ResizableSplitPane** | `aia/protocol-agent/components/` | 🟢 100% | 直接复用 |
|
||
| **AIStreamChat** | `shared/components/Chat/` | 🟢 90% | 定制欢迎语 |
|
||
| **ThinkingBlock** | `shared/components/Chat/` | 🟢 100% | 直接复用 |
|
||
| **ViewSwitcher** | `aia/protocol-agent/components/` | 🟡 70% | 修改视图选项 |
|
||
| **MarkdownContent** | `aia/protocol-agent/components/` | 🟢 100% | SAP 文档渲染 |
|
||
|
||
### 3.2 SSA 现有组件保留/改造
|
||
|
||
| 组件 | 当前路径 | 处理方式 | 说明 |
|
||
|------|---------|---------|------|
|
||
| **ModeSwitch** | `ssa/components/` | ⏸️ 暂时移除 | V8 聚焦智能分析模式 |
|
||
| **PlanCard** | `ssa/components/` | 🔄 改造 | 移入 ChatPane 作为交互卡片 |
|
||
| **ExecutionTrace** | `ssa/components/` | 🔄 改造 | 移入 ArtifactPane |
|
||
| **ResultCard** | `ssa/components/` | 🔄 重构 | 拆分为独立组件 |
|
||
| **APATable** | `ssa/components/` | ✅ 保留 | 三线表核心组件 |
|
||
|
||
### 3.3 需要新开发的组件
|
||
|
||
| 组件 | 说明 | 预估工时 |
|
||
|------|------|----------|
|
||
| **SSAWorkspace** | 双屏布局主页面 | 4h |
|
||
| **GlobalNav** | 左侧全局导航栏 | 2h |
|
||
| **ChatPane** | 左侧对话控制区 | 3h |
|
||
| **DataMountZone** | 数据挂载区（嵌入式） | 2h |
|
||
| **ArtifactPane** | 右侧工作区容器 | 2h |
|
||
| **SAPViewer** | SAP 文档视图 | 3h |
|
||
| **ExecutionViewer** | 执行日志视图 | 2h |
|
||
| **ResultViewer** | 结果报告视图 | 4h |
|
||
| **SciTable** | 三线表组件（科学格式） | 2h |
|
||
| **ChartViewer** | 图表展示组件 | 2h |
|
||
| **CodeModal** | R 代码预览模态框 | 1h |
|
||
|
||
---
|
||
|
||
## 4. 详细开发任务
|
||
|
||
### 4.1 Day 1: 架构搭建 + 组件下沉
|
||
|
||
| 任务 | 预估 | 说明 |
|
||
|------|------|------|
|
||
| 下沉 `ResizableSplitPane` 到 shared | 1h | 提取为系统级 Common 组件 |
|
||
| 创建 `SSAWorkspace` 骨架 | 2h | 双屏布局 + 状态联动 |
|
||
| 改造 `ssaStore.ts` | 1.5h | 新增 activePane、artifact 状态 |
|
||
| 创建 `GlobalNav` 组件 | 1.5h | 新建/历史/设置图标 |
|
||
| 样式文件创建 | 1h | `ssa-workspace.css` |
|
||
|
||
**Day 1 交付物：**
|
||
- [ ] 双屏布局可拖拽
|
||
- [ ] 左侧空白区域 + 右侧空白区域
|
||
- [ ] 全局状态管理就绪
|
||
|
||
### 4.2 Day 2: 左侧对话区 + 流式联动
|
||
|
||
| 任务 | 预估 | 说明 |
|
||
|------|------|------|
|
||
| 创建 `ChatPane` 组件 | 2h | 消息列表 + 输入区 |
|
||
| 创建 `DataMountZone` 组件 | 2h | 嵌入式数据挂载 |
|
||
| 改造 `PlanCard` 为交互卡片 | 1.5h | 点击触发右侧 SAP 展示 |
|
||
| 集成 `AIStreamChat` | 1.5h | 咨询模式对话 |
|
||
| 🆕 实现流式 Artifact 标记解析 | 2h | **审查反馈 - 盲区一** |
|
||
| 左侧区域样式精调 | 1h | 参考原型图 |
|
||
|
||
**Day 2 交付物：**
|
||
- [ ] 数据上传 → 挂载区显示文件信息
|
||
- [ ] 输入分析需求 → 生成 SAP
|
||
- [ ] 点击 SAP 卡片 → 右侧展示详情
|
||
- [ ] 🆕 AI 流式输出中解析 Artifact 标记，自动切换右侧面板
|
||
|
||
### 4.3 Day 3: 右侧工作区
|
||
|
||
| 任务 | 预估 | 说明 |
|
||
|------|------|------|
|
||
| 创建 `ArtifactPane` 容器 | 1h | 动态视图切换 |
|
||
| 创建 `SAPViewer` 组件 | 2.5h | 研究目的、推荐方法、护栏 |
|
||
| 创建 `ExecutionViewer` 组件 | 2h | 实时日志 + 动画 |
|
||
| 创建 `SciTable` 组件 | 2h | 三线表科学格式 |
|
||
| 创建 `ChartViewer` 组件 | 1.5h | Base64 图片展示 |
|
||
|
||
**Day 3 交付物：**
|
||
- [ ] SAP 文档视图完整
|
||
- [ ] 执行日志实时展示
|
||
- [ ] 三线表科学格式
|
||
|
||
### 4.4 Day 4: 结果展示 + 联调
|
||
|
||
| 任务 | 预估 | 说明 |
|
||
|------|------|------|
|
||
| 创建 `ResultViewer` 组件 | 2.5h | AI 解读 + 表格 + 图表 |
|
||
| 创建 `CodeModal` 组件 | 1h | R 代码预览模态框 |
|
||
| 下载功能完善 | 1.5h | 代码下载 + 报告下载 |
|
||
| 端到端联调测试 | 2h | 完整流程验证 |
|
||
| UI 样式精调 | 1h | 对齐原型图 |
|
||
|
||
**Day 4 交付物：**
|
||
- [ ] 结果报告完整展示
|
||
- [ ] R 代码一键下载
|
||
- [ ] 端到端流程通过
|
||
|
||
---
|
||
|
||
## 5. 组件详细设计
|
||
|
||
### 5.1 ResizableSplitPane（复用）
|
||
|
||
直接从 `aia/protocol-agent/components/ResizableSplitPane.tsx` 复制到 `shared/components/Layout/`。
|
||
|
||
```typescript
|
||
// 使用方式
|
||
<ResizableSplitPane
|
||
defaultLeftRatio={35} // 左侧 35%
|
||
minLeftRatio={25}
|
||
maxLeftRatio={50}
|
||
enableDrag={true}
|
||
storageKey="ssa-split-ratio"
|
||
leftPanel={<ChatPane />}
|
||
rightPanel={<ArtifactPane />}
|
||
/>
|
||
```
|
||
|
||
### 5.2 SSAWorkspace（主页面）
|
||
|
||
```tsx
|
||
// modules/ssa/SSAWorkspace.tsx
|
||
const SSAWorkspace: React.FC = () => {
|
||
const { activePane, setActivePane } = useSSAStore();
|
||
|
||
return (
|
||
<div className="ssa-workspace">
|
||
{/* 全局导航 */}
|
||
<GlobalNav />
|
||
|
||
{/* 主工作区 */}
|
||
<main className="ssa-main">
|
||
<ResizableSplitPane
|
||
leftPanel={<ChatPane />}
|
||
rightPanel={<ArtifactPane activePane={activePane} />}
|
||
defaultLeftRatio={35}
|
||
/>
|
||
</main>
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
### 5.3 GlobalNav（全局导航）
|
||
|
||
```tsx
|
||
// modules/ssa/components/GlobalNav.tsx
|
||
const GlobalNav: React.FC = () => {
|
||
return (
|
||
<nav className="ssa-global-nav">
|
||
<div className="nav-logo">
|
||
<BarChart3 size={24} />
|
||
</div>
|
||
<div className="nav-actions">
|
||
<button title="新建分析"><Plus /></button>
|
||
<button title="历史记录"><History /></button>
|
||
<button title="配置中心"><Settings /></button>
|
||
</div>
|
||
</nav>
|
||
);
|
||
};
|
||
```
|
||
|
||
### 5.4 ChatPane（对话控制区）
|
||
|
||
```tsx
|
||
// modules/ssa/components/ChatPane.tsx
|
||
const ChatPane: React.FC = () => {
|
||
const { mountedFile, setMountedFile } = useSSAStore();
|
||
|
||
return (
|
||
<div className="ssa-chat-pane">
|
||
{/* 头部 */}
|
||
<header className="chat-header">
|
||
<span className="session-title">新的统计分析</span>
|
||
<StatusBadge status="ready" />
|
||
</header>
|
||
|
||
{/* 消息列表 */}
|
||
<div className="chat-messages">
|
||
{/* AI 欢迎语 */}
|
||
{/* 用户消息 */}
|
||
{/* AI 回复 + 交互卡片 */}
|
||
</div>
|
||
|
||
{/* 输入区 */}
|
||
<div className="chat-input-area">
|
||
{/* 数据挂载区 */}
|
||
{mountedFile && <DataMountZone file={mountedFile} />}
|
||
|
||
{/* 输入框 */}
|
||
<div className="input-container">
|
||
<UploadButton />
|
||
<TextArea placeholder="描述您的分析需求..." />
|
||
<SendButton />
|
||
</div>
|
||
</div>
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
### 5.5 DataMountZone（数据挂载区）
|
||
|
||
```tsx
|
||
// modules/ssa/components/DataMountZone.tsx
|
||
interface DataMountZoneProps {
|
||
file: { name: string; size: number; rowCount: number };
|
||
onRemove: () => void;
|
||
}
|
||
|
||
const DataMountZone: React.FC<DataMountZoneProps> = ({ file, onRemove }) => {
|
||
return (
|
||
<div className="data-mount-zone">
|
||
<FileIcon type="csv" />
|
||
<div className="file-info">
|
||
<span className="file-name">{file.name}</span>
|
||
<span className="file-meta">{file.rowCount} rows • {formatFileSize(file.size)}</span>
|
||
</div>
|
||
<button className="remove-btn" onClick={onRemove}>
|
||
<X size={14} />
|
||
</button>
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
### 5.6 ArtifactPane（工作区容器）
|
||
|
||
```tsx
|
||
// modules/ssa/components/ArtifactPane.tsx
|
||
interface ArtifactPaneProps {
|
||
activePane: 'empty' | 'sap' | 'execution' | 'result';
|
||
}
|
||
|
||
const ArtifactPane: React.FC<ArtifactPaneProps> = ({ activePane }) => {
|
||
const { currentArtifact } = useSSAStore();
|
||
|
||
// 空状态
|
||
if (activePane === 'empty') {
|
||
return (
|
||
<div className="artifact-empty">
|
||
<Layers size={64} />
|
||
<p>分析方案、执行过程与图表将在这里展示</p>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
return (
|
||
<div className="artifact-pane">
|
||
{/* 头部 */}
|
||
<header className="artifact-header">
|
||
<ArtifactIcon type={activePane} />
|
||
<h2>{getArtifactTitle(activePane)}</h2>
|
||
<div className="artifact-actions">
|
||
{activePane === 'result' && <CodeButton />}
|
||
<DownloadButton />
|
||
</div>
|
||
</header>
|
||
|
||
{/* 内容区 */}
|
||
<div className="artifact-content">
|
||
{activePane === 'sap' && <SAPViewer data={currentArtifact?.data} />}
|
||
{activePane === 'execution' && <ExecutionViewer />}
|
||
{activePane === 'result' && <ResultViewer data={currentArtifact?.data} />}
|
||
</div>
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
### 5.7 SciTable（三线表）
|
||
|
||
```tsx
|
||
// modules/ssa/components/SciTable.tsx
|
||
interface SciTableProps {
|
||
headers: string[];
|
||
rows: (string | number)[][];
|
||
caption?: string;
|
||
}
|
||
|
||
const SciTable: React.FC<SciTableProps> = ({ headers, rows, caption }) => {
|
||
return (
|
||
<div className="sci-table-container">
|
||
{caption && <caption>{caption}</caption>}
|
||
<table className="sci-table">
|
||
<thead>
|
||
<tr>
|
||
{headers.map((h, i) => <th key={i}>{h}</th>)}
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
{rows.map((row, i) => (
|
||
<tr key={i}>
|
||
{row.map((cell, j) => <td key={j}>{cell}</td>)}
|
||
</tr>
|
||
))}
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
**三线表样式（科学格式）：**
|
||
|
||
```css
|
||
.sci-table {
|
||
width: 100%;
|
||
border-collapse: collapse;
|
||
font-size: 0.875rem;
|
||
}
|
||
|
||
.sci-table th {
|
||
border-top: 2px solid #1e293b;
|
||
border-bottom: 1px solid #1e293b;
|
||
padding: 10px 12px;
|
||
text-align: left;
|
||
font-weight: 600;
|
||
}
|
||
|
||
.sci-table td {
|
||
border-bottom: 1px solid #e2e8f0;
|
||
padding: 10px 12px;
|
||
}
|
||
|
||
.sci-table tr:last-child td {
|
||
border-bottom: 2px solid #1e293b;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 与后端对接
|
||
|
||
### 6.1 现有 API（无需修改）
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `POST /api/v1/ssa/sessions` | 创建会话（上传数据） |
|
||
| `POST /api/v1/ssa/sessions/:id/plan` | 生成分析计划 |
|
||
| `POST /api/v1/ssa/sessions/:id/execute` | 执行分析 |
|
||
| `GET /api/v1/ssa/sessions/:id/code` | 下载 R 代码 |
|
||
|
||
### 6.2 返回数据结构适配
|
||
|
||
```typescript
|
||
// 执行结果返回结构（后端已实现）
|
||
interface ExecutionResult {
|
||
success: boolean;
|
||
tool_code: string;
|
||
method_used: string;
|
||
|
||
// 表格数据（用于 SciTable）
|
||
result_table: {
|
||
headers: string[];
|
||
rows: (string | number)[][];
|
||
};
|
||
|
||
// 图表数据（用于 ChartViewer）
|
||
plots?: {
|
||
type: 'boxplot' | 'histogram' | 'scatter';
|
||
data: string; // Base64
|
||
}[];
|
||
|
||
// AI 解读
|
||
interpretation: string;
|
||
|
||
// R 代码
|
||
reproducible_code: string;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6.3 🆕 流式响应与数据流技术方案（审查反馈 - 盲区一、四）
|
||
|
||
### 已有能力
|
||
|
||
| 能力 | 位置 | 状态 |
|
||
|------|------|------|
|
||
| **useAIStream Hook** | `shared/components/Chat/hooks/useAIStream.ts` | ✅ 已实现 |
|
||
| **StreamingService** | `backend/src/common/streaming/` | ✅ 已实现 |
|
||
| **traceSteps 状态管理** | `ssaStore.ts` | ✅ 已实现 |
|
||
|
||
### 流式 Artifact 标记解析
|
||
|
||
AI 在对话流中输出结构化标记，前端实时解析并触发右侧面板切换：
|
||
|
||
```typescript
|
||
// AI 输出示例
|
||
"我已为您生成分析方案：<Artifact type='sap' id='plan-001' />"
|
||
|
||
// useAIStream 扩展：解析 Artifact 标记
|
||
const handleChunk = (chunk: string) => {
|
||
// 正常内容追加
|
||
setContent(prev => prev + chunk);
|
||
|
||
// 检测 Artifact 标记
|
||
const artifactMatch = chunk.match(/<Artifact type='(\w+)' id='([^']+)' \/>/);
|
||
if (artifactMatch) {
|
||
const [_, type, id] = artifactMatch;
|
||
ssaStore.setActivePane(type as 'sap' | 'execution' | 'result');
|
||
ssaStore.loadArtifact(type, id);
|
||
}
|
||
};
|
||
```
|
||
|
||
### 执行日志数据流方案
|
||
|
||
| 方案 | 说明 | MVP 采用 |
|
||
|------|------|---------|
|
||
| **方案 A** | 对话流内嵌执行状态（复用 useAIStream） | ✅ 推荐 |
|
||
| **方案 B** | 独立 SSE 端点 | Phase 2 |
|
||
| **方案 C** | 同步返回 + 伪进度 | 备选 |
|
||
|
||
**推荐方案 A 示例**：
|
||
|
||
```
|
||
// AI 对话流中输出执行状态
|
||
data: {"choices":[{"delta":{"content":"🔍 正在检验正态性..."}}]}
|
||
data: {"choices":[{"delta":{"content":"✅ Shapiro-Wilk p=0.32，符合正态分布"}}]}
|
||
data: {"choices":[{"delta":{"content":"📊 正在执行独立样本 T 检验..."}}]}
|
||
data: {"choices":[{"delta":{"content":"<Artifact type='result' id='xxx' />"}}]}
|
||
```
|
||
|
||
**优势**：直接复用 `AIStreamChat` 组件和 `useAIStream` Hook，无需额外开发 SSE 端点。
|
||
|
||
---
|
||
|
||
## 7. 样式规范
|
||
|
||
### 7.1 颜色方案
|
||
|
||
```css
|
||
:root {
|
||
/* 主色 */
|
||
--ssa-primary: #4F46E5; /* Indigo */
|
||
--ssa-primary-light: #EEF2FF;
|
||
|
||
/* 状态色 */
|
||
--ssa-success: #22C55E;
|
||
--ssa-warning: #F59E0B;
|
||
--ssa-error: #EF4444;
|
||
|
||
/* 中性色 */
|
||
--ssa-bg: #F1F5F9;
|
||
--ssa-card: #FFFFFF;
|
||
--ssa-border: #E2E8F0;
|
||
--ssa-text: #334155;
|
||
--ssa-text-secondary: #64748B;
|
||
}
|
||
```
|
||
|
||
### 7.2 间距规范
|
||
|
||
```css
|
||
--spacing-xs: 4px;
|
||
--spacing-sm: 8px;
|
||
--spacing-md: 16px;
|
||
--spacing-lg: 24px;
|
||
--spacing-xl: 32px;
|
||
```
|
||
|
||
### 7.3 动画规范
|
||
|
||
```css
|
||
/* 淡入 */
|
||
.fade-in {
|
||
animation: fadeIn 0.4s ease-out forwards;
|
||
}
|
||
|
||
/* 滑入 */
|
||
.slide-up {
|
||
animation: slideUp 0.4s cubic-bezier(0.16, 1, 0.3, 1) forwards;
|
||
}
|
||
|
||
/* 弹出 */
|
||
.pop-in {
|
||
animation: popIn 0.3s cubic-bezier(0.16, 1, 0.3, 1) forwards;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 验收标准
|
||
|
||
### 8.1 功能验收
|
||
|
||
| 功能 | 验收标准 |
|
||
|------|---------|
|
||
| 双屏布局 | 左右面板可拖拽调整，比例记忆 |
|
||
| 数据上传 | 上传后在挂载区显示文件信息 |
|
||
| SAP 生成 | 点击卡片在右侧展示完整 SAP |
|
||
| 执行日志 | 实时展示护栏检查、自动降级 |
|
||
| 结果展示 | AI 解读 + 三线表 + 图表 |
|
||
| 代码下载 | 点击按钮下载 .R 文件 |
|
||
|
||
### 8.2 UI 验收
|
||
|
||
- [ ] 100% 还原 V8 原型图布局
|
||
- [ ] 三线表符合科学论文格式
|
||
- [ ] 动画流畅（60fps）
|
||
- [ ] 响应式（1280px+ 宽屏）
|
||
|
||
### 8.3 性能验收
|
||
|
||
- [ ] 首屏加载 < 2s
|
||
- [ ] 拖拽无卡顿
|
||
- [ ] 大表格（1000行）渲染 < 500ms
|
||
|
||
---
|
||
|
||
## 9. 风险与应对
|
||
|
||
| 风险 | 概率 | 应对策略 |
|
||
|------|------|---------|
|
||
| ResizableSplitPane 复用不兼容 | 低 | 预留 1h 调试时间 |
|
||
| 三线表样式与原型有差异 | 中 | 参考科学论文格式，与设计师沟通 |
|
||
| 大数据量表格性能问题 | 中 | 使用虚拟滚动（react-window） |
|
||
| 后端返回数据结构不一致 | 低 | 已确认现有 API 结构 |
|
||
|
||
### 9.1 🆕 Phase 2 延后任务（审查反馈 - 盲区三）
|
||
|
||
**响应式降级策略**：MVP 阶段聚焦 PC 端宽屏（1280px+），小屏幕降级方案延后至 Phase 2。
|
||
|
||
| 屏幕宽度 | MVP 处理 | Phase 2 计划 |
|
||
|---------|---------|-------------|
|
||
| ≥ 1280px | ✅ 正常双屏 | - |
|
||
| 1024-1280px | ⚠️ 可用但略挤 | 调整比例 |
|
||
| < 1024px | ❌ 不支持 | Drawer/Modal 降级 |
|
||
|
||
**Phase 2 降级方案预留设计**：
|
||
|
||
```css
|
||
@media (max-width: 1024px) {
|
||
.ssa-workspace {
|
||
.artifact-pane { display: none; }
|
||
.chat-pane { width: 100%; }
|
||
}
|
||
|
||
.artifact-drawer {
|
||
position: fixed;
|
||
right: 0;
|
||
width: 90vw;
|
||
height: 100vh;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 相关文档
|
||
|
||
| 文档 | 路径 |
|
||
|------|------|
|
||
| 产品原型图 V8 | `03-UI设计/产品原型图V8双屏版.html` |
|
||
| UX 对比报告 | `03-UI设计/SSA-Pro UX方案对比与技术选型报告.md` |
|
||
| AIA 组件文档 | `docs/03-业务模块/AIA-AI智能问答/00-模块当前状态与开发指南.md` |
|
||
| Chat 组件文档 | `frontend-v2/src/shared/components/Chat/README.md` |
|
||
| 任务清单 | `04-开发计划/01-任务清单与进度追踪.md` |
|
||
| 🆕 审查报告 | `06-开发记录/SSA-Pro 前端 UI 改进计划审查报告.md` |
|
||
| 🆕 审查回应 | `06-开发记录/SSA-Pro 前端UI改进计划-审查回应.md` |
|
||
|
||
---
|
||
|
||
## 11. 附录：文件结构（V11 最终版）
|
||
|
||
```
|
||
frontend-v2/src/modules/ssa/
|
||
├── index.tsx # 模块入口
|
||
├── SSAWorkspace.tsx # V11 主工作区（全屏 Gemini 风格）
|
||
├── components/
|
||
│ ├── SSASidebar.tsx # 左侧抽屉栏（可展开/收起）
|
||
│ ├── SSAChatPane.tsx # 中间对话区
|
||
│ ├── SSAWorkspacePane.tsx # 右侧工作区（SAP/执行/结果视图）
|
||
│ ├── SSACodeModal.tsx # R 代码模态框
|
||
│ ├── SSAToast.tsx # Toast 通知
|
||
│ ├── TypeWriter.tsx # 打字机效果组件
|
||
│ └── index.ts # 组件导出
|
||
├── stores/
|
||
│ └── ssaStore.ts # Zustand 状态管理
|
||
├── hooks/
|
||
│ ├── useAnalysis.ts # 分析相关 API 调用
|
||
│ ├── useArtifactParser.ts # 流式 Artifact 标记解析
|
||
│ └── index.ts
|
||
├── styles/
|
||
│ └── ssa-workspace.css # V11 完整样式（~1900 行）
|
||
└── types/
|
||
└── index.ts # 类型定义
|
||
```
|
||
|
||
## 12. 端到端测试清单
|
||
|
||
### 12.1 基本功能测试
|
||
|
||
| 序号 | 测试项 | 预期结果 | 状态 |
|
||
|------|--------|---------|------|
|
||
| 1 | 打开 SSA 模块 | 全屏显示，左侧收起的抽屉栏，中间欢迎消息 | ⬜ |
|
||
| 2 | 点击汉堡菜单 | 左侧抽屉栏展开，显示 Logo、新建按钮、历史记录 | ⬜ |
|
||
| 3 | 点击回形针上传数据 | 显示上传进度，成功后显示文件信息 | ⬜ |
|
||
| 4 | 输入分析查询并发送 | 显示 AI 响应，右侧工作区自动打开 SAP 视图 | ⬜ |
|
||
| 5 | 点击"开始执行分析" | 切换到执行视图，显示实时日志 | ⬜ |
|
||
| 6 | 执行完成 | 切换到结果视图，显示统计表格、图表、AI 解读 | ⬜ |
|
||
| 7 | 点击"查看代码" | 弹出代码模态框，显示 R 代码 | ⬜ |
|
||
| 8 | 点击"下载 .R 文件" | 下载真实的分析代码文件 | ⬜ |
|
||
| 9 | 点击"导出报告" | 下载 HTML 格式的分析报告 | ⬜ |
|
||
| 10 | 按 Esc 键 | 关闭代码模态框/工作区 | ⬜ |
|
||
| 11 | 按 Ctrl+B | 切换左侧抽屉栏 | ⬜ |
|
||
| 12 | 按 Ctrl+N | 新建分析（重置状态） | ⬜ |
|
||
| 13 | 点击返回按钮 | 返回上一页 | ⬜ |
|
||
|
||
### 12.2 错误处理测试
|
||
|
||
| 序号 | 测试项 | 预期结果 | 状态 |
|
||
|------|--------|---------|------|
|
||
| 1 | 上传无效文件格式 | 显示错误提示卡片 | ⬜ |
|
||
| 2 | R 服务不可用时执行 | 显示执行失败视图，可点击重试 | ⬜ |
|
||
| 3 | 网络断开时操作 | 显示错误 Toast | ⬜ |
|
||
|
||
### 12.3 UI/UX 测试
|
||
|
||
| 序号 | 测试项 | 预期结果 | 状态 |
|
||
|------|--------|---------|------|
|
||
| 1 | 对话区滚动 | 内容可滚动，输入框不遮挡按钮 | ⬜ |
|
||
| 2 | AI 消息打字机效果 | 文字逐字显示，带闪烁光标 | ⬜ |
|
||
| 3 | 动态引擎状态 | 根据状态显示 Ready/Processing/Running | ⬜ |
|
||
| 4 | 历史记录加载 | 展开抽屉时加载历史，显示加载状态 | ⬜ |
|
||
|
||
---
|
||
|
||
## 13. 版本更新记录
|
||
|
||
| 版本 | 日期 | 更新内容 |
|
||
|------|------|---------|
|
||
| v1.0 | 2026-02-20 | 初始版本 |
|
||
| v1.1 | 2026-02-20 | 根据审查反馈更新：<br>• 盲区一：新增流式 Artifact 标记解析任务<br>• 盲区二：补充 hydrateFromHistory 状态恢复逻辑<br>• 盲区三：风险章节注明响应式降级延后至 Phase 2<br>• 盲区四：新增 6.3 节，说明流式响应技术方案 |
|
||
| v2.0 | 2026-02-20 | **V11 升级：**<br>• 全屏 Gemini 风格布局<br>• 删除 22 个旧版组件<br>• 新增 6 个 V11 核心组件<br>• 完善报告/代码导出功能<br>• 实现流式 Artifact 标记解析框架<br>• 更新文件结构和测试清单 |
|
||
|
||
---
|
||
|
||
**文档维护者：** SSA 开发团队
|
||
**最后更新：** 2026-02-20
|
||
**审查状态：** ✅ 已通过（2026-02-20）
|