9.8 KiB
数据处理创建流程四步向导设计
日期：2026-07-10
1. 目标
重构 /data-process/create，把当前职责混杂、步骤数量会变化的流程，调整为四个语义稳定、页面内容相互独立的步骤。用户在任一时刻只处理当前任务，同时始终知道所处阶段、前后关系和唯一主操作。
本次设计沿用现有平台视觉语言：浅灰应用背景、单层白色页面画布、靛蓝主色、克制边框与阴影、固定四步进度导航和底部操作栏。不得出现页面白底中再次嵌套整页白色大卡片的双层白底。
2. 固定流程
顶部步骤数量始终为四个，不随结构化或非结构化类型变化：
- 创建任务：填写任务信息、上传源文件并选择处理类型。
- 数据预览：检查系统解析结果；非结构化数据进入切片预览，结构化数据进入记录预览。
- 开始生成：确认摘要、启动生成并查看进度或错误。
- 结果编辑与保存：检查并修改生成结果，通过校验后保存任务。
步骤状态只有 未开始、当前、已完成 三种。用户返回已完成步骤时保留已经填写或编辑的内容，不因切换处理类型而静默清空任务名称、描述和上传文件。
3. 第一步：创建任务
页面只显示创建任务所需内容：
- 任务名称和可选描述。
- 结构化数据、非结构化数据两种处理类型。
- 单文件上传区、文件格式和大小约束。
- 上传后的基础识别结果：文件名、大小、格式、记录数或文本长度、校验状态。
底部操作：取消、保存草稿、唯一主操作 继续：数据预览。
切换处理类型时仅更新后续预览和生成策略；如果已经产生预览结果，需要明确提示预览将重新计算，确认后才清除后续步骤数据。
4. 第二步：数据预览
4.1 页面职责
本页只负责核对源数据与系统预览结果的对应关系，并允许修改不合理的切片或记录内容。不得显示第一步的大量表单、第三步的生成进度或第四步的最终结果表格。
页面顶部仅保留一行来源摘要，例如：
finance_qa.jsonl · 非结构化数据 · 8,560 个切片
4.2 非结构化数据：源文件与切片对照
主体为同一白色画布中的左右分栏，使用竖向分隔线区分，不使用两个浮动大卡片：
-
左侧约 58%：源文件阅读器
- 只读展示完整源文件，支持滚动和行号。
- 当前切片对应的原文使用浅靛蓝背景高亮，并在左边缘显示定位条。
- 顶部提示当前定位，例如
已定位到切片 #002。 - 左侧原文始终保持源文件真实性，修改右侧切片不会直接改写源文件。
-
右侧约 42%：切片内容
- 上方为切片列表，支持按编号或内容搜索、仅查看已修改项。
- 每个切片显示编号、来源行范围、Token 数和修改状态。
- 下方为当前切片的可编辑正文、字符数、Token 数和自动保存状态。
- 提供上一片、下一片和恢复原始内容。
4.3 对照定位交互
右侧切片是主选择源，左侧原文是定位反馈：
- 用户点击右侧切片。
- 系统读取该切片保存的原始来源范围
sourceStart、sourceEnd。 - 左侧阅读器自动滚动到目标范围，并将对应原文高亮。
- 右侧切片进入选中态，左右使用一致的浅靛蓝语义色建立对应关系。
- 用户切换上一片或下一片时执行相同的同步定位。
为了避免跳动，目标范围应滚动到阅读区中部；如果目标已完全可见，则只更新高亮，不重复滚动。
4.4 编辑与来源映射
- 编辑切片正文只改变待生成内容，来源映射仍指向最初的原文范围。
- 编辑后显示
已修改，草稿已自动保存，并允许恢复到系统初始切片内容。 - 修改后的文本与原文不再完全一致时，左侧仍高亮原始来源，右侧显示
内容已调整，避免误解为源文件被改写。 - 手动新增的切片没有原始来源，显示
手动新增，无源文件定位，左侧清除高亮但保留当前位置。 - 删除切片需要二次确认；删除只影响本次处理，不修改源文件。
- 找不到来源范围或范围越界时，右侧显示
无法定位原文，左侧不进行错误滚动，用户仍可编辑该切片。
4.5 结构化数据适配
第二步的整体布局和交互不变，但语义调整为记录对照：
- 左侧展示源文件中的表格行或原始 JSON 记录。
- 右侧展示系统解析后的单条记录及字段值。
- 点击右侧记录，左侧定位并高亮对应源行或 JSON 范围。
这样可以保持四步流程稳定，同时避免对结构化数据使用不准确的“切片”文案。
底部操作：返回：创建任务、保存草稿、唯一主操作 确认预览并继续。
5. 第三步：开始生成
页面只显示：
- 任务名称、数据类型、文件、预览条目数和修改条目数的只读摘要。
- 唯一启动操作
开始生成。 - 启动后的进度、当前阶段、耗时和状态日志。
- 失败时显示错误摘要与
重试；运行中提供停止生成，停止前需要二次确认。
启动前不显示底部“下一步”与页面内“开始生成”两个竞争按钮。生成成功后，唯一主操作切换为 查看生成结果。
6. 第四步：结果编辑与保存
结果不再使用一组原始 JSON 文本框堆叠展示，而采用结构化编辑列表：
- 桌面端左侧为结果条目列表，支持搜索、错误筛选和已修改筛选。
- 桌面端右侧为当前结果的字段编辑区；较窄窗口改为列表在上、编辑区在下。
- 每条结果显示校验状态，错误定位到具体字段。
- 支持上一条、下一条、恢复生成结果。
- 保存前执行完整校验；有阻断错误时禁止保存并聚焦首个错误。
底部操作：返回：开始生成、保存草稿、唯一主操作 保存任务。
7. 状态与数据模型
向导需要维护统一草稿状态：
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. 验收标准
- 结构化和非结构化流程都始终显示四个固定步骤。
- 每一步只包含该阶段必要内容，页面中不存在跨步骤主操作竞争。
- 点击任一有来源映射的右侧切片后，左侧在一次交互内定位并高亮准确原文范围。
- 已完全可见的范围不会产生多余滚动；不可定位时有明确反馈且不破坏编辑。
- 修改切片不会改写左侧源文件，高亮仍指向原始来源。
- 返回前一步再进入时，选中项、编辑内容、滚动上下文和草稿状态可恢复。
- 生成开始前只存在一个明确启动操作；生成成功后才允许进入结果编辑。
- 最终结果保存前执行字段级校验，阻断错误可准确定位。
- 路由切换不出现列表页或灰色背景闪烁，白色页面画布保持连续。
- 页面在常用桌面宽度下无横向溢出，底部操作栏不遮挡主体内容。
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