195 lines
9.8 KiB
Markdown
195 lines
9.8 KiB
Markdown
# 数据处理创建流程四步向导设计
|
||
|
||
日期：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`
|