# 数据处理创建流程四步向导设计

日期：2026-07-10

## 1. 目标

重构 `/data-process/create`，把当前职责混杂、步骤数量会变化的流程，调整为四个语义稳定、页面内容相互独立的步骤。用户在任一时刻只处理当前任务，同时始终知道所处阶段、前后关系和唯一主操作。

本次设计沿用现有平台视觉语言：浅灰应用背景、单层白色页面画布、靛蓝主色、克制边框与阴影、固定四步进度导航和底部操作栏。不得出现页面白底中再次嵌套整页白色大卡片的双层白底。

## 2. 固定流程

顶部步骤数量始终为四个，不随结构化或非结构化类型变化：

1. **创建任务**：填写任务信息、上传源文件并选择处理类型。
2. **数据预览**：检查系统解析结果；非结构化数据进入切片预览，结构化数据进入记录预览。
3. **开始生成**：确认摘要、启动生成并查看进度或错误。
4. **结果编辑与保存**：检查并修改生成结果，通过校验后保存任务。

步骤状态只有 `未开始`、`当前`、`已完成` 三种。用户返回已完成步骤时保留已经填写或编辑的内容，不因切换处理类型而静默清空任务名称、描述和上传文件。

## 3. 第一步：创建任务

页面只显示创建任务所需内容：

- 任务名称和可选描述。
- 结构化数据、非结构化数据两种处理类型。
- 单文件上传区、文件格式和大小约束。
- 上传后的基础识别结果：文件名、大小、格式、记录数或文本长度、校验状态。

底部操作：`取消`、`保存草稿`、唯一主操作 `继续：数据预览`。

切换处理类型时仅更新后续预览和生成策略；如果已经产生预览结果，需要明确提示预览将重新计算，确认后才清除后续步骤数据。

## 4. 第二步：数据预览

### 4.1 页面职责

本页只负责核对源数据与系统预览结果的对应关系，并允许修改不合理的切片或记录内容。不得显示第一步的大量表单、第三步的生成进度或第四步的最终结果表格。

页面顶部仅保留一行来源摘要，例如：

`finance_qa.jsonl · 非结构化数据 · 8,560 个切片`

### 4.2 非结构化数据：源文件与切片对照

主体为同一白色画布中的左右分栏，使用竖向分隔线区分，不使用两个浮动大卡片：

- **左侧约 58%：源文件阅读器**
  - 只读展示完整源文件，支持滚动和行号。
  - 当前切片对应的原文使用浅靛蓝背景高亮，并在左边缘显示定位条。
  - 顶部提示当前定位，例如 `已定位到切片 #002`。
  - 左侧原文始终保持源文件真实性，修改右侧切片不会直接改写源文件。

- **右侧约 42%：切片内容**
  - 上方为切片列表，支持按编号或内容搜索、仅查看已修改项。
  - 每个切片显示编号、来源行范围、Token 数和修改状态。
  - 下方为当前切片的可编辑正文、字符数、Token 数和自动保存状态。
  - 提供上一片、下一片和恢复原始内容。

### 4.3 对照定位交互

右侧切片是主选择源，左侧原文是定位反馈：

1. 用户点击右侧切片。
2. 系统读取该切片保存的原始来源范围 `sourceStart`、`sourceEnd`。
3. 左侧阅读器自动滚动到目标范围，并将对应原文高亮。
4. 右侧切片进入选中态，左右使用一致的浅靛蓝语义色建立对应关系。
5. 用户切换上一片或下一片时执行相同的同步定位。

为了避免跳动，目标范围应滚动到阅读区中部；如果目标已完全可见，则只更新高亮，不重复滚动。

### 4.4 编辑与来源映射

- 编辑切片正文只改变待生成内容，来源映射仍指向最初的原文范围。
- 编辑后显示 `已修改，草稿已自动保存`，并允许恢复到系统初始切片内容。
- 修改后的文本与原文不再完全一致时，左侧仍高亮原始来源，右侧显示 `内容已调整`，避免误解为源文件被改写。
- 手动新增的切片没有原始来源，显示 `手动新增，无源文件定位`，左侧清除高亮但保留当前位置。
- 删除切片需要二次确认；删除只影响本次处理，不修改源文件。
- 找不到来源范围或范围越界时，右侧显示 `无法定位原文`，左侧不进行错误滚动，用户仍可编辑该切片。

### 4.5 结构化数据适配

第二步的整体布局和交互不变，但语义调整为记录对照：

- 左侧展示源文件中的表格行或原始 JSON 记录。
- 右侧展示系统解析后的单条记录及字段值。
- 点击右侧记录，左侧定位并高亮对应源行或 JSON 范围。

这样可以保持四步流程稳定，同时避免对结构化数据使用不准确的“切片”文案。

底部操作：`返回：创建任务`、`保存草稿`、唯一主操作 `确认预览并继续`。

## 5. 第三步：开始生成

页面只显示：

- 任务名称、数据类型、文件、预览条目数和修改条目数的只读摘要。
- 唯一启动操作 `开始生成`。
- 启动后的进度、当前阶段、耗时和状态日志。
- 失败时显示错误摘要与 `重试`；运行中提供 `停止生成`，停止前需要二次确认。

启动前不显示底部“下一步”与页面内“开始生成”两个竞争按钮。生成成功后，唯一主操作切换为 `查看生成结果`。

## 6. 第四步：结果编辑与保存

结果不再使用一组原始 JSON 文本框堆叠展示，而采用结构化编辑列表：

- 桌面端左侧为结果条目列表，支持搜索、错误筛选和已修改筛选。
- 桌面端右侧为当前结果的字段编辑区；较窄窗口改为列表在上、编辑区在下。
- 每条结果显示校验状态，错误定位到具体字段。
- 支持上一条、下一条、恢复生成结果。
- 保存前执行完整校验；有阻断错误时禁止保存并聚焦首个错误。

底部操作：`返回：开始生成`、`保存草稿`、唯一主操作 `保存任务`。

## 7. 状态与数据模型

向导需要维护统一草稿状态：

```ts
interface DataProcessDraft {
  task: TaskInfo
  sourceFile: SourceFileMeta
  processingType: 'structured' | 'unstructured'
  previewItems: PreviewItem[]
  selectedPreviewId: string | null
  generation: GenerationState
  results: ResultItem[]
  currentStep: 1 | 2 | 3 | 4
  dirty: boolean
}

interface PreviewItem {
  id: string
  originalContent: string
  editedContent: string
  sourceStart: number | null
  sourceEnd: number | null
  sourceStartLine: number | null
  sourceEndLine: number | null
  tokenCount: number
  status: 'original' | 'modified' | 'manual' | 'invalid'
}
```

源文件位置以字符偏移作为定位依据，行号用于展示。这样即使原文存在长行或不同换行符，也能稳定高亮准确范围。

## 8. 页面组件边界

- `DataProcessWizardShell`：固定四步导航、页面标题和底部操作栏。
- `TaskSetupStep`：任务信息、类型和文件上传。
- `PreviewStep`：数据预览容器，按处理类型选择预览器。
- `SourceViewer`：源文件渲染、滚动定位和范围高亮。
- `PreviewItemList`：切片或记录列表、搜索与选择。
- `PreviewItemEditor`：当前条目编辑、状态和恢复。
- `GenerationStep`：启动、进度、失败与重试。
- `ResultReviewStep`：生成结果列表、字段编辑和保存校验。

`SourceViewer` 不感知切片列表内部逻辑，只接收选中范围；`PreviewItemList` 不直接操纵滚动，只上报选中项。同步行为由 `PreviewStep` 统一协调。

## 9. 异常与离开保护

- 上传失败、解析失败、预览生成失败分别提供明确原因和重试入口。
- 预览数据加载时显示骨架或局部加载状态，不能让整个白色画布闪烁或短暂回退到列表页。
- 刷新、返回列表或关闭页面前，如果存在未持久化修改，必须提示保存草稿或放弃更改。
- 自动保存失败时保留本地编辑内容，并显示可重试状态。
- 生成过程中禁止无提示切换处理类型或替换源文件。

## 10. 响应式与可访问性

- 桌面端左右对照为默认布局，分栏宽度允许拖动但设置最小宽度。
- 较窄窗口下改为上下布局：源文件在上，切片在下；选中切片后仍自动定位高亮。
- 选中、高亮、修改和错误状态不能只依赖颜色，还需文字、图标或边缘标记。
- 键盘支持上下切换切片、聚焦编辑器、保存草稿；滚动定位后不抢走编辑器焦点。

## 11. 验收标准

1. 结构化和非结构化流程都始终显示四个固定步骤。
2. 每一步只包含该阶段必要内容，页面中不存在跨步骤主操作竞争。
3. 点击任一有来源映射的右侧切片后，左侧在一次交互内定位并高亮准确原文范围。
4. 已完全可见的范围不会产生多余滚动；不可定位时有明确反馈且不破坏编辑。
5. 修改切片不会改写左侧源文件，高亮仍指向原始来源。
6. 返回前一步再进入时，选中项、编辑内容、滚动上下文和草稿状态可恢复。
7. 生成开始前只存在一个明确启动操作；生成成功后才允许进入结果编辑。
8. 最终结果保存前执行字段级校验，阻断错误可准确定位。
9. 路由切换不出现列表页或灰色背景闪烁，白色页面画布保持连续。
10. 页面在常用桌面宽度下无横向溢出，底部操作栏不遮挡主体内容。

## 12. 视觉参考

- 当前流程截图：`docs/superpowers/specs/assets/data-process-create-audit/01-create-task.png`
- 当前动态步骤截图：`docs/superpowers/specs/assets/data-process-create-audit/02-unstructured-step-change.png`
- 最终左右对照修订稿：`/Users/caoxiaozhu/.codex/generated_images/019f4981-cb06-79f0-b387-1d685e74ceea/exec-c72de596-4c50-405b-8987-43d122e02b86.png`
