YG_FT/docs/superpowers/plans/2026-07-10-data-process-create-wizard.md

Data Process Create Wizard Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将 /data-process/create 实现为固定四步向导，并在第二步提供“右侧选择切片、左侧自动定位并高亮原文”的可编辑对照体验。

Architecture: DataProcessCreateView.vue 只负责向导状态、步骤切换和跨步骤数据；每个步骤拆成独立 Vue 组件。源文定位和切片生成由纯 TypeScript 模块负责，第二步组件只消费偏移范围并同步滚动、高亮和编辑状态。现有 Vue 3、Element Plus、SCSS 和 Font Awesome 继续使用，不引入新依赖。

Tech Stack: Vue 3.5、TypeScript 5.7、Vite 6、Element Plus 2.9、SCSS、Node.js 回归脚本、vue-tsc。

Global Constraints

• 顶部固定四步：创建任务、数据预览、开始生成、结果编辑与保存。
• 结构化和非结构化类型不得改变步骤数量。
• 第二步桌面端左侧约 58% 为只读源文件，右侧约 42% 为切片或记录列表及编辑器。
• 点击右侧条目时，左侧必须定位并高亮 sourceStart 到 sourceEnd 的原始范围。
• 编辑切片不得改写源文件；来源映射始终指向初始原文。
• 每一步只能有一个主操作，不得同时出现“下一步”和“开始生成”等竞争动作。
• 页面继续使用现有全局白色页面画布，不新增整页嵌套白卡。
• 不增加第三方依赖。

---

Task 1: 建立四步向导回归测试

Files:

• Create: frontend/scripts/regression-data-process-wizard.mjs
• Modify: frontend/package.json
• Test: frontend/scripts/regression-data-process-wizard.mjs

Interfaces:

• Consumes: Vue SFC 源码、@vue/compiler-sfc、@vue/compiler-dom。

• Produces: npm run test:data-process-wizard，验证固定步骤、组件边界、对照定位标记和底部唯一主操作。

• Step 1: 写入当前实现必然失败的结构回归检查

import assert from 'node:assert/strict'
import { readFile } from 'node:fs/promises'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { parse as parseSfc } from '@vue/compiler-sfc'

const scriptDir = path.dirname(fileURLToPath(import.meta.url))
const viewSource = await readFile(
  path.resolve(scriptDir, '../src/views/data-process/DataProcessCreateView.vue'),
  'utf8',
)
const previewSource = await readFile(
  path.resolve(scriptDir, '../src/views/data-process/create/PreviewCompareStep.vue'),
  'utf8',
)

assert.match(viewSource, /const WIZARD_STEPS = \[/)
for (const title of ['创建任务', '数据预览', '开始生成', '结果编辑与保存']) {
  assert.ok(viewSource.includes(`title: '${title}'`), `缺少固定步骤：${title}`)
}
assert.doesNotMatch(viewSource, /all\.filter|steps\s*=\s*computed/)
assert.match(previewSource, /class="source-viewer"/)
assert.match(previewSource, /class="preview-workspace"/)
assert.match(previewSource, /scrollIntoView/)
assert.match(previewSource, /sourceStart/)
assert.match(previewSource, /sourceEnd/)

const { descriptor } = parseSfc(viewSource)
assert.ok(descriptor.template?.content.includes('TaskSetupStep'))
assert.ok(descriptor.template?.content.includes('PreviewCompareStep'))
assert.ok(descriptor.template?.content.includes('GenerationStep'))
assert.ok(descriptor.template?.content.includes('ResultEditorStep'))

console.log('数据处理四步向导回归检查通过')

• Step 2: 在 package.json 注册命令

{
  "scripts": {
    "test:data-process-wizard": "node scripts/regression-data-process-wizard.mjs"
  }
}

• Step 3: 运行测试并确认失败原因正确

Run: cd frontend && npm run test:data-process-wizard

Expected: FAIL，首先因 PreviewCompareStep.vue 不存在或固定步骤断言不成立而失败。

Task 2: 建立向导类型、草稿状态和来源映射模型

Files:

• Create: frontend/src/views/data-process/create/types.ts
• Create: frontend/src/views/data-process/create/previewModel.ts
• Test: frontend/scripts/regression-data-process-wizard.mjs

Interfaces:

• Consumes: 上传文件解析出的字符串。

• Produces: ProcessType、StepId、PreviewItem、ResultItem、DataProcessDraft；buildPreviewItems(sourceText, processType) 和 sourceLines(sourceText)。

• Step 1: 在回归脚本增加模型文件和关键字段断言

const typesSource = await readFile(
  path.resolve(scriptDir, '../src/views/data-process/create/types.ts'),
  'utf8',
)
const modelSource = await readFile(
  path.resolve(scriptDir, '../src/views/data-process/create/previewModel.ts'),
  'utf8',
)
for (const field of ['sourceStart', 'sourceEnd', 'originalContent', 'editedContent']) {
  assert.ok(typesSource.includes(field), `PreviewItem 缺少字段：${field}`)
}
assert.match(modelSource, /export function buildPreviewItems/)
assert.match(modelSource, /export function sourceLines/)

• Step 2: 定义稳定类型

export type ProcessType = 'structured' | 'unstructured'
export type StepId = 'create' | 'preview' | 'generate' | 'results'

export 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'
}

export interface ResultItem {
  id: string
  instruction: string
  input: string
  output: string
  status: 'valid' | 'modified' | 'invalid'
  error?: string
}

• Step 3: 实现可重复的来源偏移生成

export function buildPreviewItems(sourceText: string, processType: ProcessType): PreviewItem[] {
  const lines = sourceText.split('\n')
  const groupSize = processType === 'structured' ? 1 : 3
  let cursor = 0
  const ranges = lines.map((line, index) => {
    const start = cursor
    cursor += line.length + (index < lines.length - 1 ? 1 : 0)
    return { line, lineNumber: index + 1, start, end: start + line.length }
  })

  const items: PreviewItem[] = []
  for (let index = 0; index < ranges.length; index += groupSize) {
    const group = ranges.slice(index, index + groupSize)
    if (!group.length || group.every((item) => !item.line.trim())) continue
    const content = group.map((item) => item.line).join('\n')
    items.push({
      id: `preview-${items.length + 1}`,
      originalContent: content,
      editedContent: content,
      sourceStart: group[0].start,
      sourceEnd: group[group.length - 1].end,
      sourceStartLine: group[0].lineNumber,
      sourceEndLine: group[group.length - 1].lineNumber,
      tokenCount: Math.max(1, Math.ceil(content.length / 2)),
      status: 'original',
    })
  }
  return items
}

• Step 4: 运行回归检查和类型检查

Run: cd frontend && npm run test:data-process-wizard && npm run type-check

Expected: 回归测试继续因组件未完成而失败；previewModel.ts 和 types.ts 不产生 TypeScript 错误。

Task 3: 实现向导壳层和第一步创建任务

Files:

• Create: frontend/src/views/data-process/create/TaskSetupStep.vue
• Modify: frontend/src/views/data-process/DataProcessCreateView.vue
• Test: frontend/scripts/regression-data-process-wizard.mjs

Interfaces:

• Consumes: ProcessType、Element Plus 表单与上传组件。

• Produces: TaskSetupStep 的 v-model:name、v-model:description、v-model:processType、file-change、remove-file 事件；父页面提供固定 WIZARD_STEPS 和统一底部操作。

• Step 1: 将父页面步骤定义改为不可变四步

const WIZARD_STEPS = [
  { id: 'create', title: '创建任务', desc: '填写任务信息与上传源数据' },
  { id: 'preview', title: '数据预览', desc: '核对源文件与预览内容' },
  { id: 'generate', title: '开始生成', desc: '确认摘要并启动处理' },
  { id: 'results', title: '结果编辑与保存', desc: '检查、修改并保存结果' },
] as const

• Step 2: 创建第一步组件，保留现有校验并改为视觉选择块

const props = defineProps<{
  name: string
  description: string
  processType: ProcessType
  file: File | null
  fileCount: number
}>()

const emit = defineEmits<{
  'update:name': [value: string]
  'update:description': [value: string]
  'update:processType': [value: ProcessType]
  'file-change': [file: UploadFile]
  'remove-file': []
}>()

• Step 3: 在父页面统一步骤导航和底部动作文案

const primaryActionLabel = computed(() => ({
  create: '继续：数据预览',
  preview: '确认预览并继续',
  generate: generation.progress === 100 ? '查看生成结果' : '开始生成',
  results: '保存任务',
}[currentStepId.value]))

• Step 4: 运行回归检查和类型检查

Run: cd frontend && npm run test:data-process-wizard && npm run type-check

Expected: 回归测试因后续三个组件缺失而失败；第一步相关代码通过类型检查。

Task 4: 实现左右源文件与切片同步预览

Files:

• Create: frontend/src/views/data-process/create/PreviewCompareStep.vue
• Modify: frontend/src/views/data-process/DataProcessCreateView.vue
• Test: frontend/scripts/regression-data-process-wizard.mjs

Interfaces:

• Consumes: sourceText: string、items: PreviewItem[]、selectedId: string | null、processType: ProcessType。

• Produces: update:selectedId、update:item-content、restore:item；选中条目变化时调用 scrollIntoView({ block: 'center' })。

• Step 1: 增加源文范围与选中态的结构断言

for (const marker of [
  'source-viewer',
  'source-line',
  'is-highlighted',
  'preview-item',
  'preview-editor',
  'scrollIntoView',
]) {
  assert.ok(previewSource.includes(marker), `第二步缺少结构：${marker}`)
}

• Step 2: 通过行偏移判断高亮范围

function isLineHighlighted(lineStart: number, lineEnd: number) {
  if (!selectedItem.value || selectedItem.value.sourceStart == null || selectedItem.value.sourceEnd == null) {
    return false
  }
  return lineEnd >= selectedItem.value.sourceStart
    && lineStart <= selectedItem.value.sourceEnd
}

• Step 3: 选中切片后定位首个高亮行

watch(selectedItem, async (item) => {
  if (!item || item.sourceStart == null) return
  await nextTick()
  sourceViewerRef.value
    ?.querySelector<HTMLElement>(`[data-offset="${item.sourceStart}"]`)
    ?.scrollIntoView({ block: 'center', behavior: 'smooth' })
})

• Step 4: 编辑时只更新 editedContent 和状态

function updateContent(item: PreviewItem, value: string) {
  emit('update:item-content', item.id, value)
}

父组件处理事件时不得修改 sourceText、sourceStart 或 sourceEnd：

function updatePreviewContent(id: string, value: string) {
  const item = draft.previewItems.find((entry) => entry.id === id)
  if (!item) return
  item.editedContent = value
  item.status = value === item.originalContent ? 'original' : 'modified'
  draft.dirty = true
}

• Step 5: 完成搜索、仅看已修改、上一片、下一片和恢复原文

Run: cd frontend && npm run test:data-process-wizard && npm run type-check

Expected: 第二步结构断言通过，类型检查通过；回归测试只因第三、四步组件缺失而失败。

Task 5: 实现生成与结果编辑两个独立步骤

Files:

• Create: frontend/src/views/data-process/create/GenerationStep.vue
• Create: frontend/src/views/data-process/create/ResultEditorStep.vue
• Modify: frontend/src/views/data-process/DataProcessCreateView.vue
• Test: frontend/scripts/regression-data-process-wizard.mjs

Interfaces:

• Consumes: 任务摘要、预览条目、生成状态和结果条目。

• Produces: start、stop、retry、update:result、restore:result、save 事件。

• Step 1: 生成步骤只保留摘要、进度与状态

const emit = defineEmits<{
  start: []
  stop: []
  retry: []
}>()

生成完成前底部唯一主操作为 开始生成；生成进行中为禁用的 正在生成；完成后变为 查看生成结果。

• Step 2: 清理并托管模拟生成计时器

let generationTimer: ReturnType<typeof setInterval> | null = null

function stopGenerationTimer() {
  if (generationTimer) clearInterval(generationTimer)
  generationTimer = null
}

onBeforeUnmount(stopGenerationTimer)

• Step 3: 将预览条目转换为结构化结果字段

function createResults(items: PreviewItem[]): ResultItem[] {
  return items.slice(0, 12).map((item, index) => ({
    id: `result-${index + 1}`,
    instruction: item.editedContent.split('\n')[0] || `数据条目 ${index + 1}`,
    input: '',
    output: item.editedContent.split('\n').slice(1).join('\n') || item.editedContent,
    status: 'valid',
  }))
}

• Step 4: 使用左侧结果列表和右侧字段编辑器替代原始 JSON 文本框

function validateResult(item: ResultItem) {
  item.error = item.instruction.trim() && item.output.trim() ? undefined : '指令和输出不能为空'
  item.status = item.error ? 'invalid' : 'modified'
}

• Step 5: 运行回归、页面表面和类型检查

Run: cd frontend && npm run test:data-process-wizard && npm run test:page-surface && npm run type-check

Expected: 三项检查全部 PASS。

Task 6: 完成视觉实现、响应式和浏览器验收

Files:

• Modify: frontend/src/views/data-process/DataProcessCreateView.vue
• Modify: frontend/src/views/data-process/create/TaskSetupStep.vue
• Modify: frontend/src/views/data-process/create/PreviewCompareStep.vue
• Modify: frontend/src/views/data-process/create/GenerationStep.vue
• Modify: frontend/src/views/data-process/create/ResultEditorStep.vue
• Test: frontend/scripts/regression-data-process-wizard.mjs

Interfaces:

• Consumes: 已完成的四步组件和现有全局页面画布。

• Produces: 与确认修订稿一致的桌面布局，以及 900px 以下的上下布局。

• Step 1: 落实单层页面、固定步骤和底部操作栏样式

.wizard-footer {
  position: sticky;
  bottom: 0;
  display: flex;
  align-items: center;
  justify-content: space-between;
  min-height: 64px;
  background: rgba(255, 255, 255, 0.98);
  border-top: 1px solid #eef0f5;
}

• Step 2: 落实桌面左右对照和 900px 响应式

.preview-workspace {
  display: grid;
  grid-template-columns: minmax(0, 58fr) minmax(380px, 42fr);
}

@media (max-width: 900px) {
  .preview-workspace {
    grid-template-columns: minmax(0, 1fr);
  }
}

• Step 3: 启动页面并逐步验证四步交互

Run: cd frontend && npm run dev -- --host 0.0.0.0 --port 16801

Browser checks at http://localhost:16801/data-process/create:

1. 第一步上传文本并选择非结构化数据。
2. 第二步点击至少三个右侧切片，确认左侧滚动目标和高亮范围变化。
3. 修改一个切片并切换前后条目，确认修改状态和内容保留。
4. 完成生成并进入第四步，修改结果字段并保存。
5. 返回前一步，确认草稿和选中项未丢失。
6. 以 1440×1024 和 900px 窄屏分别截图，确认无横向溢出和底部遮挡。

• Step 4: 执行完整验证

Run: cd frontend && npm run test:data-process-wizard && npm run test:page-surface && npm run type-check && npm run build

Expected: 所有回归脚本、类型检查和生产构建全部 PASS。

Self-Review Result

• 规格中的四步稳定语义由 Tasks 1、3、5 覆盖。
• 左右对照、来源映射、滚动高亮、编辑不改源文件由 Tasks 2、4 覆盖。
• 生成状态、计时器清理、结果字段校验由 Task 5 覆盖。
• 单层白底、响应式、路由转场连续性和最终验收由 Task 6 覆盖。
• 未引入新依赖；计划中所有类型和事件名在前置任务中已有定义。