dsh-data-cleaning-agent 0.9.13 → 0.9.15

package/lib/image-workflow.js

@@ -13,7 +13,13 @@ export function createImageWorkflow({ getWorkflow, execution, commands }) {
     task = await store.recordUpload(task.id, { expectedRevision: task.revision,
       source: { type: 'image', fileName: record.fileName, sizeBytes: record.sizeBytes,
         rowCount: rows.length, columnCount: 1, headers: ['主体标识'] } });
-    task = await store.updateDraft(task.id, { expectedRevision: task.revision, mappings });
+    task = await store.updateDraft(task.id, {
+      expectedRevision: task.revision,
+      mappings,
+      objectives: task.objectives.includes('complete_fields')
+        ? task.objectives
+        : [...task.objectives, 'complete_fields'],
+    });
     if (result.truncated || result.needsReview || rows.length > 100) {
       return { taskId: task.id, deliveryState: 'review_required', artifacts: [],
         reviewReason: rows.length > 100 || result.truncated ? '识别名单超出单批范围，请核验并拆分。' : '识别文本含模糊字符或待确认提示，请核验名单。' };

package/lib/qcc-command.js

@@ -198,6 +198,14 @@ export class QccCommandStore {
     return output;
   }
 
+  hasActiveForTask(taskId) {
+    this.cleanup();
+    const id = String(taskId ?? '');
+    return [...this.commands.values()].some((command) => (
+      command.taskId === id && ['prepared', 'running'].includes(command.state)
+    ));
+  }
+
   async run(commandId, execution) {
     const record = this.require(commandId);
     if (!execution?.agent || !execution?.token) {

package/lib/qcc-runs.js

@@ -191,6 +191,15 @@ export class G5RunStore {
     return this.snapshot(this.requireRun(id));
   }
 
+  capabilities(id) {
+    this.cleanup();
+    const record = this.runs.get(String(id ?? ''));
+    return {
+      liveRunAvailable: Boolean(record),
+      retryableFailuresAvailable: Boolean(record?.errors.some((item) => item.error?.retryable)),
+    };
+  }
+
   snapshot(record) {
     return clone({
       runId: record.id,

package/lib/web.js

@@ -7,13 +7,19 @@
  *  - 上传体大小上限（parseBody）。
  *  - 同步接口返回明细行仅供「已授权同源 UI」下载，不面向模型。
  */
+import { createHash, randomBytes } from 'node:crypto';
 import { parseCsv, parseXlsx, parseJson, detectFormat, toCsv } from './engine.js';
 import { runSync, DataCleaningJobs } from './jobs.js';
 import { QccBridgeError, QccHostBridge } from './qcc.js';
 import { QccCommandStore, registerQccCommandTool, TOOL_QCC_COMMAND } from './qcc-command.js';
 import { fingerprintRequest, G5RunStore } from './qcc-runs.js';
 import { PHASE3_BATCH_LIMITS, Phase3BatchService, Phase3RunStore } from './qcc-phase3-batch.js';
-import { publicWorkflowContract } from './workflow-contract.js';
+import {
+  WORKFLOW_ACTIONS,
+  allowedWorkflowActions,
+  deriveWorkflowFlow,
+  publicWorkflowContract,
+} from './workflow-contract.js';
 import { DataCleaningWorkflowStore, WorkflowError } from './workflow.js';
 import { ArtifactError, WorkflowArtifactStore } from './artifacts.js';
 import { renderArtifactPreview } from './artifact-preview.js';
@@ -141,6 +147,23 @@ function writeImageError(res, error) {
 }
 
 /** 从 JSON 协议解析上传：{ filename, content }。content 为字符串；xlsx 时为 base64。 */
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value === null || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+function sourceVerifier(headers, rows, previous = '') {
+  const match = /^sha256-canonical-rows-v1:([a-f0-9]{32}):[a-f0-9]{64}$/.exec(String(previous));
+  const salt = match?.[1] || randomBytes(16).toString('hex');
+  const canonical = JSON.stringify({
+    headers: (Array.isArray(headers) ? headers : []).map(String),
+    rows: canonicalize(Array.isArray(rows) ? rows : []),
+  });
+  const digest = createHash('sha256').update(salt).update('\0').update(canonical).digest('hex');
+  return `sha256-canonical-rows-v1:${salt}:${digest}`;
+}
+
 async function parseUpload(body) {
   let payload;
   try {
@@ -153,12 +176,20 @@ async function parseUpload(body) {
   const filename = String(payload?.filename ?? 'data.csv');
   const content = payload?.content ?? '';
   const fmt = detectFormat(filename);
+  let parsed;
   if (fmt === 'xlsx') {
     const buf = Buffer.from(String(content), 'base64');
-    return { fmt, ...(await parseXlsx(buf)) };
+    parsed = await parseXlsx(buf);
+  } else if (fmt === 'json') {
+    parsed = parseJson(String(content));
+  } else {
+    parsed = parseCsv(String(content));
   }
-  if (fmt === 'json') return { fmt, ...parseJson(String(content)) };
-  return { fmt, ...parseCsv(String(content)) };
+  return {
+    fmt,
+    ...parsed,
+    checksum: sourceVerifier(parsed.headers, parsed.rows, payload?.previousChecksum),
+  };
 }
 
 const UI_HTML = `<!doctype html>
@@ -307,7 +338,11 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
   const disposers = [];
   const qccBridge = new QccHostBridge({ tools, logger });
   const g5Runs = new G5RunStore();
-  const execution = createWorkflowExecution({ getWorkflow: () => getWorkflow(), artifacts: wctx.fs ? new WorkflowArtifactStore({ fs: wctx.fs }) : null });
+  const execution = createWorkflowExecution({
+    getWorkflow: () => getWorkflow(),
+    artifacts: wctx.fs ? new WorkflowArtifactStore({ fs: wctx.fs }) : null,
+    getRun: (runId) => g5Runs.get(runId),
+  });
   const qccCommands = new QccCommandStore({ bridge: qccBridge, runs: g5Runs, lifecycle: execution });
   const imageIntake = new ImageIntakeStore({ tools,
     continueWorkflow: createImageWorkflow({ getWorkflow: () => getWorkflow(), execution, commands: qccCommands }) });
@@ -353,6 +388,22 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
     return workflowReady;
   };
 
+  const workflowView = (task) => ({
+    ...task,
+    flow: deriveWorkflowFlow(task),
+    runtimeCapabilities: {
+      activeCommand: qccCommands.hasActiveForTask(task.id),
+      ...g5Runs.capabilities(task.qccRunId),
+    },
+  });
+
+  const requireWorkflowAction = (task, action) => {
+    if (!allowedWorkflowActions(task).includes(action)) {
+      const current = deriveWorkflowFlow(task).currentStage;
+      throw new WorkflowError('DC_WORKFLOW_ACTION_LOCKED', `当前任务位于“${current}”，不能执行该操作。`, 409);
+    }
+  };
+
   register('/data-cleaning/', (req, res) => {
     if (!isTrusted(req)) { res.writeHead(403); return res.end('untrusted origin'); }
     res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
@@ -490,7 +541,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           return writeJson(res, 200, {
             ok: true,
             marker: 'data-cleaning-workflow-v2',
-            tasks: await workflow.list(),
+            tasks: (await workflow.list()).map(workflowView),
           });
         }
         if (req.method === 'POST') {
@@ -499,7 +550,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           return writeJson(res, 201, {
             ok: true,
             marker: 'data-cleaning-workflow-v2',
-            task: await workflow.create(payload),
+            task: workflowView(await workflow.create(payload)),
           });
         }
         return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'GET or POST required' });
@@ -511,17 +562,18 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           return writeJson(res, 200, {
             ok: true,
             marker: 'data-cleaning-workflow-v2',
-            task: await workflow.require(taskId),
+            task: workflowView(await workflow.require(taskId)),
           });
         }
         if (req.method === 'PATCH') {
           const body = await readBody(req);
           const payload = body.length ? JSON.parse(body.toString('utf8')) : {};
-          await workflow.assertRequestOrigin(taskId, payload);
+          const current = await workflow.assertRequestOrigin(taskId, payload);
+          requireWorkflowAction(current, WORKFLOW_ACTIONS.EDIT_RULES);
           return writeJson(res, 200, {
             ok: true,
             marker: 'data-cleaning-workflow-v2',
-            task: await workflow.updateDraft(taskId, payload),
+            task: workflowView(await workflow.updateDraft(taskId, payload)),
           });
         }
         return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'GET or PATCH required' });
@@ -540,7 +592,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           return writeJson(res, 200, {
             ok: true,
             marker: 'data-cleaning-artifacts-v1',
-            task: current,
+            task: workflowView(current),
             artifacts: current.artifacts,
           });
         }
@@ -551,32 +603,24 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           if (Number(payload.expectedRevision) !== current.revision) {
             throw new WorkflowError('DC_WORKFLOW_REVISION_CONFLICT', 'Workflow task was updated by another session.', 409);
           }
-          let readyTask = current;
-          if (['rules_confirmed', 'diagnosed'].includes(readyTask.state)) {
-            readyTask = await workflow.prepareLocalExport(taskId, {
-              expectedRevision: readyTask.revision,
-              summary: payload.summary,
-            });
-          }
-          if (!['export_ready', 'partial'].includes(readyTask.state)) {
-            throw new WorkflowError('DC_WORKFLOW_EXPORT_STATE', 'Output is not ready for durable export.', 409);
-          }
+          requireWorkflowAction(current, WORKFLOW_ACTIONS.CREATE_LOCAL_ARTIFACTS);
           const artifacts = await artifactStore.createBundle(taskId, {
             rows: payload.rows,
             headers: payload.headers,
-            fieldSelection: readyTask.fieldSelection,
-            mappings: readyTask.mappings,
+            fieldSelection: current.fieldSelection,
+            mappings: current.mappings,
             exceptionRows: payload.exceptionRows,
-            baseName: payload.baseName || readyTask.title,
+            baseName: payload.baseName || current.title,
           });
-          const completed = await workflow.recordExport(taskId, {
-            expectedRevision: readyTask.revision,
+          const completed = await workflow.completeLocalDelivery(taskId, {
+            expectedRevision: current.revision,
+            summary: payload.summary,
             artifacts,
           });
           return writeJson(res, 201, {
             ok: true,
             marker: 'data-cleaning-artifacts-v1',
-            task: completed,
+            task: workflowView(completed),
             artifacts: completed.artifacts,
           });
         }
@@ -617,27 +661,22 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
       const action = rest[2];
       await workflow.assertRequestOrigin(taskId, payload);
       const actions = {
-        upload: () => workflow.recordUpload(taskId, payload),
-        rules: () => workflow.confirmRules(taskId, payload),
-        quality: () => workflow.recordQuality(taskId, payload),
-        'match-start': () => workflow.startMatch(taskId, payload),
-        match: () => workflow.recordMatch(taskId, payload),
-        'enrich-start': () => workflow.startEnrichment(taskId, payload),
-        enrichment: () => workflow.recordEnrichment(taskId, payload),
-        'local-export-ready': () => workflow.prepareLocalExport(taskId, payload),
-        export: () => workflow.recordExport(taskId, payload),
-        'parse-failed': () => workflow.recordParseFailure(taskId, payload),
-        'authorization-required': () => workflow.requireAuthorization(taskId, payload),
-        fail: () => workflow.recordFailure(taskId, payload),
-        cancel: () => workflow.cancel(taskId, payload),
+        upload: { action: WORKFLOW_ACTIONS.IMPORT_DATA, run: () => workflow.recordUpload(taskId, payload) },
+        rules: { action: WORKFLOW_ACTIONS.CONFIRM_RULES, run: () => workflow.confirmRules(taskId, payload) },
+        quality: { action: WORKFLOW_ACTIONS.RUN_QUALITY, run: () => workflow.recordQuality(taskId, payload) },
+        'retry-delivery': { action: WORKFLOW_ACTIONS.RETRY_DELIVERY, run: async () => (
+          await execution.retryDelivery({ taskId, expectedRevision: payload.expectedRevision })
+        ).task },
       };
       if (!actions[action]) {
         return writeJson(res, 404, { ok: false, code: 'DC_WORKFLOW_ACTION', message: `Unknown workflow action: ${action}` });
       }
+      const current = await workflow.require(taskId);
+      requireWorkflowAction(current, actions[action].action);
       return writeJson(res, 200, {
         ok: true,
         marker: 'data-cleaning-workflow-v2',
-        task: await actions[action](),
+        task: workflowView(await actions[action].run()),
       });
     } catch (error) {
       if (error instanceof SyntaxError) {
@@ -984,7 +1023,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
     if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
     try {
       const body = await readBody(req);
-      const { fmt, headers, rows } = await parseUpload(body);
+      const { fmt, headers, rows, checksum } = await parseUpload(body);
       writeJson(res, 200, {
         ok: true,
         fmt,
@@ -992,6 +1031,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
         rowCount: rows.length,
         preview: rows.slice(0, 5),
         rows,
+        checksum,
       });
     } catch (error) {
       writeJson(res, 400, { ok: false, code: error?.code ?? 'DC_PARSE', message: error instanceof Error ? error.message : String(error) });

package/lib/workflow-contract.js

@@ -10,6 +10,27 @@
 import { QCC_FIELD_CATALOG } from './qcc-field-catalog.js';
 
 export const WORKFLOW_SCHEMA_VERSION = 2;
+export const FLOW_VERSION = 1;
+
+export const WORKFLOW_STAGE_ACCESS = Object.freeze({
+  CURRENT: 'current',
+  READ: 'read',
+  LOCKED: 'locked',
+});
+
+export const WORKFLOW_ACTIONS = Object.freeze({
+  IMPORT_DATA: 'import-data',
+  EDIT_RULES: 'edit-rules',
+  CONFIRM_RULES: 'confirm-rules',
+  RUN_QUALITY: 'run-quality',
+  PREPARE_QCC_COMMAND: 'prepare-qcc-command',
+  RUN_LOCAL_CLEAN: 'run-local-clean',
+  RUN_LOCAL_COMPLETE: 'run-local-complete',
+  CREATE_LOCAL_ARTIFACTS: 'create-local-artifacts',
+  RESOLVE_CANDIDATE: 'resolve-candidate',
+  RETRY_FAILED: 'retry-failed',
+  RETRY_DELIVERY: 'retry-delivery',
+});
 
 export const WORKFLOW_STAGES = Object.freeze([
   Object.freeze({ id: 'upload', label: '上传数据', order: 1 }),
@@ -79,17 +100,17 @@ const STATE_IDS = new Set(WORKFLOW_STATES);
 const TRANSITIONS = Object.freeze({
   draft: ['uploaded', 'parse_failed', 'cancelled'],
   uploaded: ['draft', 'rules_confirmed', 'parse_failed', 'cancelled'],
-  rules_confirmed: ['diagnosed', 'matching', 'matched', 'review_required', 'export_ready', 'authorization_required', 'failed', 'cancelled'],
-  diagnosed: ['matching', 'matched', 'review_required', 'export_ready', 'authorization_required', 'failed', 'cancelled'],
-  matching: ['matched', 'review_required', 'authorization_required', 'partial', 'failed', 'cancelled'],
-  review_required: ['matching', 'matched', 'authorization_required', 'partial', 'failed', 'cancelled'],
+  rules_confirmed: ['diagnosed', 'failed', 'cancelled'],
+  diagnosed: ['matching', 'export_ready', 'completed', 'authorization_required', 'failed', 'cancelled'],
+  matching: ['matched', 'review_required', 'authorization_required', 'partial', 'completed', 'failed', 'cancelled'],
+  review_required: ['matching', 'matched', 'authorization_required', 'partial', 'completed', 'failed', 'cancelled'],
   matched: ['enriching', 'export_ready', 'authorization_required', 'partial', 'failed', 'cancelled'],
   enriching: ['export_ready', 'review_required', 'authorization_required', 'partial', 'failed', 'cancelled'],
-  export_ready: ['enriching', 'completed', 'failed', 'cancelled'],
+  export_ready: ['enriching', 'partial', 'completed', 'failed', 'cancelled'],
   parse_failed: ['draft', 'uploaded', 'cancelled'],
   authorization_required: ['matching', 'enriching', 'failed', 'cancelled'],
-  partial: ['matching', 'review_required', 'enriching', 'export_ready', 'authorization_required', 'completed', 'failed', 'cancelled'],
-  failed: ['draft', 'uploaded', 'rules_confirmed', 'diagnosed', 'matching', 'enriching', 'cancelled'],
+  partial: ['review_required', 'authorization_required', 'completed', 'failed', 'cancelled'],
+  failed: ['partial', 'completed', 'cancelled'],
   completed: [],
   cancelled: [],
 });
@@ -173,6 +194,100 @@ export function normalizeWorkflowDraft(value = {}) {
   };
 }
 
+export function requiresQcc(task) {
+  return Array.isArray(task?.objectives)
+    && task.objectives.some((objective) => ['validate_identity', 'complete_fields'].includes(objective));
+}
+
+function currentStageFor(task) {
+  switch (task?.state) {
+    case 'draft':
+    case 'parse_failed':
+      return 'upload';
+    case 'uploaded':
+    case 'rules_confirmed':
+      return 'rules';
+    case 'diagnosed':
+      return requiresQcc(task) ? 'match' : 'enrich';
+    case 'matching':
+    case 'review_required':
+      return 'match';
+    case 'matched':
+    case 'enriching':
+      return 'enrich';
+    case 'export_ready':
+    case 'partial':
+    case 'completed':
+      return 'download';
+    case 'authorization_required':
+    case 'failed':
+    case 'cancelled':
+      return STAGE_IDS.has(task?.stage) ? task.stage : 'upload';
+    default:
+      return STAGE_IDS.has(task?.stage) ? task.stage : 'upload';
+  }
+}
+
+export function allowedWorkflowActions(task) {
+  const state = task?.state;
+  if (state === 'draft' || state === 'parse_failed') {
+    return [WORKFLOW_ACTIONS.IMPORT_DATA, WORKFLOW_ACTIONS.EDIT_RULES];
+  }
+  if (state === 'uploaded') {
+    return [WORKFLOW_ACTIONS.IMPORT_DATA, WORKFLOW_ACTIONS.EDIT_RULES, WORKFLOW_ACTIONS.CONFIRM_RULES];
+  }
+  if (state === 'rules_confirmed') return [WORKFLOW_ACTIONS.RUN_QUALITY];
+  if (state === 'diagnosed') {
+    return requiresQcc(task)
+      ? [WORKFLOW_ACTIONS.PREPARE_QCC_COMMAND]
+      : [
+          WORKFLOW_ACTIONS.RUN_LOCAL_CLEAN,
+          WORKFLOW_ACTIONS.RUN_LOCAL_COMPLETE,
+          WORKFLOW_ACTIONS.CREATE_LOCAL_ARTIFACTS,
+        ];
+  }
+  if (state === 'review_required') return [WORKFLOW_ACTIONS.RESOLVE_CANDIDATE];
+  if (state === 'export_ready') {
+    return requiresQcc(task)
+      ? [WORKFLOW_ACTIONS.RETRY_DELIVERY]
+      : [WORKFLOW_ACTIONS.CREATE_LOCAL_ARTIFACTS];
+  }
+  if (state === 'partial') {
+    return [
+      WORKFLOW_ACTIONS.RETRY_FAILED,
+      ...(task?.error?.code === 'DC_DELIVERY_FAILED' ? [WORKFLOW_ACTIONS.RETRY_DELIVERY] : []),
+    ];
+  }
+  if (state === 'failed' && task?.error?.code === 'DC_DELIVERY_FAILED' && task?.qccRunId) {
+    return [WORKFLOW_ACTIONS.RETRY_DELIVERY];
+  }
+  return [];
+}
+
+export function deriveWorkflowFlow(task) {
+  const currentStage = currentStageFor(task);
+  const stageAccess = Object.fromEntries(WORKFLOW_STAGES.map(({ id }) => [id, WORKFLOW_STAGE_ACCESS.LOCKED]));
+  stageAccess[currentStage] = WORKFLOW_STAGE_ACCESS.CURRENT;
+
+  const makeReadable = (stage, condition) => {
+    if (condition && stage !== currentStage) stageAccess[stage] = WORKFLOW_STAGE_ACCESS.READ;
+  };
+  makeReadable('upload', Boolean(task?.source));
+  makeReadable('rules', !['draft', 'uploaded', 'parse_failed'].includes(task?.state));
+  makeReadable('match', requiresQcc(task) && Boolean(task?.matchSummary || task?.qccRunId));
+  makeReadable('enrich', Boolean(task?.enrichmentSummary));
+  makeReadable('download', Array.isArray(task?.artifacts) && task.artifacts.length > 0);
+
+  const allowedActions = allowedWorkflowActions(task);
+  return {
+    flowVersion: FLOW_VERSION,
+    currentStage,
+    stageAccess,
+    allowedActions,
+    nextAction: allowedActions[0] ?? null,
+  };
+}
+
 export function canTransition(from, to) {
   if (!STATE_IDS.has(from) || !STATE_IDS.has(to)) return false;
   return TRANSITIONS[from].includes(to);
@@ -187,7 +302,10 @@ export function assertWorkflowTransition(from, to) {
 export function publicWorkflowContract() {
   return {
     schemaVersion: WORKFLOW_SCHEMA_VERSION,
+    flowVersion: FLOW_VERSION,
     stages: WORKFLOW_STAGES,
+    stageAccessModes: Object.values(WORKFLOW_STAGE_ACCESS),
+    actions: Object.values(WORKFLOW_ACTIONS),
     states: WORKFLOW_STATES,
     terminalStates: TERMINAL_WORKFLOW_STATES,
     sourceTypes: SOURCE_TYPES,

package/lib/workflow-execution.js

@@ -1,7 +1,34 @@
 import { WorkflowError } from './workflow.js';
+import { WORKFLOW_ACTIONS, allowedWorkflowActions } from './workflow-contract.js';
+
+function summariesFor(run) {
+  const summary = run.summary || {};
+  const total = Number(summary.totalRows ?? run.rows.length);
+  const reviewRequired = Number(summary.ambiguous ?? 0);
+  return {
+    reviewRequired,
+    matchSummary: {
+      total,
+      exact: Number(summary.enriched || 0) + Number(summary.fieldReview || 0),
+      candidate: reviewRequired,
+      confirmed: 0,
+      unresolved: Number(summary.unresolved || 0) + Number(summary.missingName || 0),
+      failed: Number(summary.failed || 0),
+      reviewRequired,
+    },
+    enrichmentSummary: {
+      total,
+      completed: Number(summary.enriched || 0),
+      unchanged: Number(summary.unresolved || 0) + Number(summary.missingName || 0),
+      failed: Number(summary.failed || 0),
+      reviewRequired: Number(summary.fieldReview || 0),
+      callsUsed: run.audit?.length || 0,
+    },
+  };
+}
 
 // Execution owns finalization: closing a browser must not interrupt result delivery.
-export function createWorkflowExecution({ getWorkflow, artifacts }) {
+export function createWorkflowExecution({ getWorkflow, artifacts, getRun }) {
   const requireStore = async () => {
     const store = await getWorkflow();
     if (!store || !artifacts) throw new WorkflowError('DC_DELIVERY_UNAVAILABLE', 'Host 任务存储或下载服务不可用，请升级 DSH。', 503);
@@ -11,15 +38,22 @@ export function createWorkflowExecution({ getWorkflow, artifacts }) {
     async prepare(payload) {
       const store = await requireStore();
       const task = await store.assertRequestOrigin(payload.taskId, payload);
-      if (!['rules_confirmed', 'diagnosed', 'review_required', 'partial'].includes(task.state)) {
+      const kind = String(payload.kind || 'enrich');
+      const expectedState = kind === 'resolve' ? 'review_required' : kind === 'retry' ? 'partial' : 'diagnosed';
+      if (task.state !== expectedState) {
         throw new WorkflowError('DC_EXECUTION_STATE', '请先在工作台确认规则；进行中或已完成任务不能重复启动。', 409);
       }
-      if (Number(payload.expectedRevision) !== task.revision) throw new WorkflowError('DC_WORKFLOW_REVISION_CONFLICT', '任务已更新，请重新生成说明。', 409);
-      if ((!payload.kind || payload.kind === 'enrich') && !['rules_confirmed', 'diagnosed'].includes(task.state)) {
-        throw new WorkflowError('DC_EXECUTION_STATE', '请通过候选确认或失败重试继续当前任务。', 409);
+      const action = kind === 'resolve'
+        ? WORKFLOW_ACTIONS.RESOLVE_CANDIDATE
+        : kind === 'retry'
+          ? WORKFLOW_ACTIONS.RETRY_FAILED
+          : WORKFLOW_ACTIONS.PREPARE_QCC_COMMAND;
+      if (!allowedWorkflowActions(task).includes(action)) {
+        throw new WorkflowError('DC_WORKFLOW_ACTION_LOCKED', '当前任务状态不允许生成该执行命令。', 409);
       }
-      if (payload.kind && payload.kind !== 'enrich' && payload.runId !== task.qccRunId) throw new WorkflowError('DC_RUN_MISMATCH', '执行结果不属于当前任务。', 409);
-      if (!payload.kind || payload.kind === 'enrich') {
+      if (Number(payload.expectedRevision) !== task.revision) throw new WorkflowError('DC_WORKFLOW_REVISION_CONFLICT', '任务已更新，请重新生成说明。', 409);
+      if (kind !== 'enrich' && payload.runId !== task.qccRunId) throw new WorkflowError('DC_RUN_MISMATCH', '执行结果不属于当前任务。', 409);
+      if (kind === 'enrich') {
         if (!Array.isArray(payload.rows) || payload.rows.length !== task.source?.rowCount) throw new WorkflowError('DC_SOURCE_MISMATCH', '任务名单数量不一致，请重新载入。', 409);
       }
       if (!task.fieldSelection.length) throw new WorkflowError('DC_FIELDS_REQUIRED', '未选择外部补全字段，请使用本地清洗与导出。', 400);
@@ -35,7 +69,9 @@ export function createWorkflowExecution({ getWorkflow, artifacts }) {
       const store = await requireStore();
       const task = await store.require(record.taskId);
       if (task.revision !== record.input.workflowRevision) throw new WorkflowError('DC_WORKFLOW_REVISION_CONFLICT', '说明已失效，请返回工作台重新生成；未执行查询。', 409);
-      await store.startMatch(task.id, { expectedRevision: task.revision });
+      if (record.kind !== 'retry') {
+        await store.startMatch(task.id, { expectedRevision: task.revision });
+      }
       record.workflowStarted = true;
     },
     async failed(record, error) {
@@ -43,6 +79,22 @@ export function createWorkflowExecution({ getWorkflow, artifacts }) {
       const store = await requireStore();
       const task = await store.require(record.taskId);
       if (['completed', 'cancelled', 'failed'].includes(task.state)) return;
+      if (record.kind === 'retry' && task.state === 'partial') {
+        await store.recordRetryFailure(task.id, {
+          expectedRevision: task.revision,
+          code: record.deliveryDraft ? 'DC_DELIVERY_FAILED' : error.code,
+        });
+        return;
+      }
+      if (record.deliveryDraft) {
+        await store.recordDeliveryFailure(task.id, {
+          expectedRevision: task.revision,
+          qccRunId: record.deliveryDraft.qccRunId,
+          matchSummary: record.deliveryDraft.matchSummary,
+          enrichmentSummary: record.deliveryDraft.enrichmentSummary,
+        });
+        return;
+      }
       if (['QCC_AUTH_REQUIRED', 'QCC_NOT_CONNECTED', 'QCC_TOOL_UNAVAILABLE'].includes(error.code)) {
         await store.requireAuthorization(task.id, { expectedRevision: task.revision });
       } else {
@@ -53,22 +105,71 @@ export function createWorkflowExecution({ getWorkflow, artifacts }) {
       if (!record.input.workflowOwned) return;
       const store = await requireStore();
       let task = await store.require(record.taskId);
-      const s = run.summary || {};
-      const total = Number(s.totalRows ?? run.rows.length);
-      const review = Number(s.ambiguous ?? 0);
-      task = await store.recordMatch(task.id, { expectedRevision: task.revision, qccRunId: run.runId,
-        summary: { total, exact: Number(s.enriched || 0) + Number(s.fieldReview || 0), candidate: review,
-          unresolved: Number(s.unresolved || 0) + Number(s.missingName || 0), failed: Number(s.failed || 0), reviewRequired: review } });
-      if (review) return { state: task.state, artifacts: [], taskId: task.id };
-      task = await store.startEnrichment(task.id, { expectedRevision: task.revision });
-      task = await store.recordEnrichment(task.id, { expectedRevision: task.revision, qccRunId: run.runId,
-        summary: { total, completed: Number(s.enriched || 0), unchanged: Number(s.unresolved || 0) + Number(s.missingName || 0),
-          failed: Number(s.failed || 0), reviewRequired: Number(s.fieldReview || 0), callsUsed: run.audit?.length || 0 } });
+      const summaries = summariesFor(run);
+      if (summaries.reviewRequired) {
+        task = record.kind === 'retry'
+          ? await store.recordRetryReview(task.id, {
+              expectedRevision: task.revision,
+              qccRunId: run.runId,
+              summary: summaries.matchSummary,
+            })
+          : await store.recordMatch(task.id, {
+              expectedRevision: task.revision,
+              qccRunId: run.runId,
+              summary: summaries.matchSummary,
+            });
+        return { state: task.state, artifacts: task.artifacts, taskId: task.id };
+      }
+      record.deliveryDraft = { ...summaries, qccRunId: run.runId };
       const bundle = await artifacts.createBundle(task.id, { rows: run.rows, headers: task.source?.headers || run.headers,
         mappings: task.mappings, fieldSelection: task.fieldSelection,
         baseName: (task.source?.fileName || task.title).replace(/\.[^.]+$/, '') + '-清洗补全结果' });
-      task = await store.recordExport(task.id, { expectedRevision: task.revision, artifacts: bundle, preservePartial: true });
+      task = record.kind === 'retry'
+        ? await store.completeRetryDelivery(task.id, {
+            expectedRevision: task.revision,
+            qccRunId: run.runId,
+            matchSummary: summaries.matchSummary,
+            enrichmentSummary: summaries.enrichmentSummary,
+            artifacts: bundle,
+          })
+        : await store.completeQccDelivery(task.id, {
+            expectedRevision: task.revision,
+            qccRunId: run.runId,
+            matchSummary: summaries.matchSummary,
+            enrichmentSummary: summaries.enrichmentSummary,
+            artifacts: bundle,
+          });
       return { state: task.state, artifacts: task.artifacts, taskId: task.id };
     },
+    async retryDelivery(payload) {
+      const store = await requireStore();
+      const task = await store.require(payload.taskId);
+      if (Number(payload.expectedRevision) !== task.revision) {
+        throw new WorkflowError('DC_WORKFLOW_REVISION_CONFLICT', '任务已更新，请刷新后重试交付。', 409);
+      }
+      if (!task.qccRunId || typeof getRun !== 'function') {
+        throw new WorkflowError('DC_DELIVERY_RUNTIME_EXPIRED', '企查查运行结果已失效，无法仅重试文件交付。', 409);
+      }
+      const run = getRun(task.qccRunId);
+      const summaries = summariesFor(run);
+      if (summaries.reviewRequired) {
+        throw new WorkflowError('DC_WORKFLOW_REVIEW_REQUIRED', '请先完成企业主体候选核验。', 409);
+      }
+      const bundle = await artifacts.createBundle(task.id, {
+        rows: run.rows,
+        headers: task.source?.headers || run.headers,
+        mappings: task.mappings,
+        fieldSelection: task.fieldSelection,
+        baseName: (task.source?.fileName || task.title).replace(/\.[^.]+$/, '') + '-清洗补全结果',
+      });
+      const completed = await store.completeRetryDelivery(task.id, {
+        expectedRevision: task.revision,
+        qccRunId: run.runId,
+        matchSummary: summaries.matchSummary,
+        enrichmentSummary: summaries.enrichmentSummary,
+        artifacts: bundle,
+      });
+      return { task: completed, artifacts: completed.artifacts };
+    },
   };
 }