dsh-data-cleaning-agent 0.9.13 → 0.9.15

package/lib/workflow.js

@@ -13,6 +13,7 @@ import {
   normalizeFieldSelection,
   normalizeWorkflowDraft,
   normalizeWorkflowOrigin,
+  requiresQcc,
   validateMappings,
 } from './workflow-contract.js';
 
@@ -106,6 +107,30 @@ function sanitizeArtifact(value = {}, timestamp) {
   };
 }
 
+function sanitizeArtifacts(input, timestamp) {
+  const incoming = Array.isArray(input.artifacts) ? input.artifacts : [input.artifact];
+  const artifacts = incoming.filter(Boolean).map((artifact) => sanitizeArtifact(artifact, timestamp));
+  if (!artifacts.length || artifacts.some((artifact) => !artifact.id)) {
+    throw new WorkflowError('DC_WORKFLOW_ARTIFACT_REQUIRED', '至少需要一个 Host 制品引用。', 400);
+  }
+  return artifacts;
+}
+
+function safeMatchSummary(value) {
+  const summary = safeSummary(value, ['total', 'exact', 'candidate', 'confirmed', 'unresolved', 'failed', 'reviewRequired']);
+  assertSummaryTotal(summary, ['exact', 'candidate', 'confirmed', 'unresolved', 'failed'], 'DC_WORKFLOW_MATCH_SUMMARY');
+  if (summary.reviewRequired > summary.candidate) {
+    throw new WorkflowError('DC_WORKFLOW_MATCH_SUMMARY', '待核验数量不能超过候选数量。', 400);
+  }
+  return summary;
+}
+
+function safeEnrichmentSummary(value) {
+  const summary = safeSummary(value, ['total', 'completed', 'unchanged', 'failed', 'reviewRequired', 'callsUsed']);
+  assertSummaryTotal(summary, ['completed', 'unchanged', 'failed', 'reviewRequired'], 'DC_WORKFLOW_ENRICH_SUMMARY');
+  return summary;
+}
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -271,7 +296,7 @@ export class DataCleaningWorkflowStore {
         mappings,
         matchRules: input.matchRules ?? record.matchRules,
       });
-      return { ...draft, state: 'rules_confirmed', stage: 'match', error: null };
+      return { ...draft, state: 'rules_confirmed', stage: 'rules', error: null };
     });
   }
 
@@ -283,7 +308,7 @@ export class DataCleaningWorkflowStore {
       if (record.state !== 'diagnosed') contractCall(() => assertWorkflowTransition(record.state, 'diagnosed'));
       return {
         state: 'diagnosed',
-        stage: 'match',
+        stage: requiresQcc(record) ? 'match' : 'enrich',
         error: null,
         qualitySummary: safeSummary(input.summary, [
           'total', 'valid', 'missingAnchor', 'duplicates', 'invalidCreditNo', 'invalidPhone', 'emptyFields',
@@ -304,11 +329,7 @@ export class DataCleaningWorkflowStore {
       if (!['rules_confirmed', 'diagnosed', 'matching', 'review_required', 'partial'].includes(record.state)) {
         throw new WorkflowError('DC_WORKFLOW_MATCH_STATE', 'Match summary cannot be recorded in the current state.', 409);
       }
-      const summary = safeSummary(input.summary, ['total', 'exact', 'candidate', 'confirmed', 'unresolved', 'failed', 'reviewRequired']);
-      assertSummaryTotal(summary, ['exact', 'candidate', 'confirmed', 'unresolved', 'failed'], 'DC_WORKFLOW_MATCH_SUMMARY');
-      if (summary.reviewRequired > summary.candidate) {
-        throw new WorkflowError('DC_WORKFLOW_MATCH_SUMMARY', 'Review-required count cannot exceed candidate count.', 400);
-      }
+      const summary = safeMatchSummary(input.summary);
       const nextState = summary.reviewRequired > 0 ? 'review_required' : 'matched';
       if (record.state !== nextState) contractCall(() => assertWorkflowTransition(record.state, nextState));
       return {
@@ -343,9 +364,11 @@ export class DataCleaningWorkflowStore {
       if (!['matched', 'enriching', 'partial', 'authorization_required'].includes(record.state)) {
         throw new WorkflowError('DC_WORKFLOW_ENRICH_STATE', 'Enrichment summary cannot be recorded in the current state.', 409);
       }
-      const summary = safeSummary(input.summary, ['total', 'completed', 'unchanged', 'failed', 'reviewRequired', 'callsUsed']);
-      assertSummaryTotal(summary, ['completed', 'unchanged', 'failed', 'reviewRequired'], 'DC_WORKFLOW_ENRICH_SUMMARY');
+      const summary = safeEnrichmentSummary(input.summary);
       const nextState = summary.failed > 0 || summary.reviewRequired > 0 ? 'partial' : 'export_ready';
+      if (nextState === 'partial' && !record.artifacts.length) {
+        throw new WorkflowError('DC_WORKFLOW_PARTIAL_ARTIFACT_REQUIRED', '部分完成任务必须先生成可下载制品。', 409);
+      }
       if (record.state !== nextState) contractCall(() => assertWorkflowTransition(record.state, nextState));
       return {
         state: nextState,
@@ -385,6 +408,143 @@ export class DataCleaningWorkflowStore {
     });
   }
 
+  async completeLocalDelivery(id, input = {}) {
+    return this.mutate(id, input.expectedRevision, (record) => {
+      if (record.state !== 'diagnosed' || requiresQcc(record)) {
+        throw new WorkflowError('DC_WORKFLOW_LOCAL_EXPORT_STATE', '只有已完成体检的本地任务可以生成结果。', 409);
+      }
+      contractCall(() => assertWorkflowTransition(record.state, 'completed'));
+      const total = integer(input.summary?.total ?? record.source?.rowCount);
+      const summary = {
+        total,
+        completed: integer(input.summary?.completed ?? total),
+        unchanged: integer(input.summary?.unchanged),
+        failed: integer(input.summary?.failed),
+        reviewRequired: 0,
+        callsUsed: 0,
+      };
+      assertSummaryTotal(summary, ['completed', 'unchanged', 'failed'], 'DC_WORKFLOW_ENRICH_SUMMARY');
+      const timestamp = this.nowFn();
+      const artifacts = sanitizeArtifacts(input, timestamp);
+      return {
+        state: 'completed',
+        stage: 'download',
+        enrichmentSummary: summary,
+        artifacts: [...record.artifacts, ...artifacts].slice(-20),
+        error: null,
+        completedAt: timestamp,
+      };
+    });
+  }
+
+  async completeQccDelivery(id, input = {}) {
+    return this.mutate(id, input.expectedRevision, (record) => {
+      if (!['matching', 'review_required'].includes(record.state)) {
+        throw new WorkflowError('DC_WORKFLOW_DELIVERY_STATE', '当前任务不能提交企查查结果。', 409);
+      }
+      const matchSummary = safeMatchSummary(input.matchSummary);
+      if (matchSummary.reviewRequired > 0) {
+        throw new WorkflowError('DC_WORKFLOW_REVIEW_REQUIRED', '请先完成企业主体候选核验。', 409);
+      }
+      const enrichmentSummary = safeEnrichmentSummary(input.enrichmentSummary);
+      const nextState = enrichmentSummary.failed > 0 || enrichmentSummary.reviewRequired > 0 ? 'partial' : 'completed';
+      contractCall(() => assertWorkflowTransition(record.state, nextState));
+      const timestamp = this.nowFn();
+      const artifacts = sanitizeArtifacts(input, timestamp);
+      return {
+        state: nextState,
+        stage: 'download',
+        matchSummary,
+        enrichmentSummary,
+        qccRunId: safeText(input.qccRunId, 160) || record.qccRunId,
+        artifacts: [...record.artifacts, ...artifacts].slice(-20),
+        error: null,
+        completedAt: timestamp,
+      };
+    });
+  }
+
+  async recordRetryReview(id, input = {}) {
+    return this.mutate(id, input.expectedRevision, (record) => {
+      if (record.state !== 'partial') {
+        throw new WorkflowError('DC_WORKFLOW_RETRY_STATE', '只有部分完成任务可以进入重试候选核验。', 409);
+      }
+      const summary = safeMatchSummary(input.summary);
+      if (summary.reviewRequired === 0) {
+        throw new WorkflowError('DC_WORKFLOW_REVIEW_REQUIRED', '重试结果没有待核验企业主体。', 400);
+      }
+      contractCall(() => assertWorkflowTransition(record.state, 'review_required'));
+      return {
+        state: 'review_required',
+        stage: 'match',
+        matchSummary: summary,
+        qccRunId: safeText(input.qccRunId, 160) || record.qccRunId,
+        error: null,
+      };
+    });
+  }
+
+  async completeRetryDelivery(id, input = {}) {
+    return this.mutate(id, input.expectedRevision, (record) => {
+      const recoverableFailure = record.state === 'failed'
+        && record.error?.code === 'DC_DELIVERY_FAILED'
+        && record.qccRunId;
+      if (record.state !== 'partial' && record.state !== 'export_ready' && !recoverableFailure) {
+        throw new WorkflowError('DC_WORKFLOW_RETRY_STATE', '当前任务不能重试结果交付。', 409);
+      }
+      const matchSummary = safeMatchSummary(input.matchSummary ?? record.matchSummary);
+      if (matchSummary.reviewRequired > 0) {
+        throw new WorkflowError('DC_WORKFLOW_REVIEW_REQUIRED', '请先完成企业主体候选核验。', 409);
+      }
+      const enrichmentSummary = safeEnrichmentSummary(input.enrichmentSummary ?? record.enrichmentSummary);
+      const nextState = enrichmentSummary.failed > 0 || enrichmentSummary.reviewRequired > 0 ? 'partial' : 'completed';
+      if (record.state !== nextState) contractCall(() => assertWorkflowTransition(record.state, nextState));
+      const timestamp = this.nowFn();
+      const artifacts = sanitizeArtifacts(input, timestamp);
+      return {
+        state: nextState,
+        stage: 'download',
+        matchSummary,
+        enrichmentSummary,
+        qccRunId: safeText(input.qccRunId, 160) || record.qccRunId,
+        artifacts: [...record.artifacts, ...artifacts].slice(-20),
+        error: null,
+        completedAt: timestamp,
+      };
+    });
+  }
+
+  async recordRetryFailure(id, input = {}) {
+    return this.mutate(id, input.expectedRevision, (record) => {
+      if (record.state !== 'partial') {
+        throw new WorkflowError('DC_WORKFLOW_RETRY_STATE', '只有部分完成任务可以记录重试错误。', 409);
+      }
+      return {
+        state: 'partial',
+        stage: 'download',
+        error: { code: safeText(input.code, 80) || 'DC_RETRY_FAILED' },
+      };
+    });
+  }
+
+  async recordDeliveryFailure(id, input = {}) {
+    return this.mutate(id, input.expectedRevision, (record) => {
+      if (!['matching', 'review_required', 'export_ready'].includes(record.state)) {
+        throw new WorkflowError('DC_WORKFLOW_DELIVERY_STATE', '当前任务不能记录结果交付失败。', 409);
+      }
+      const nextState = record.artifacts.length ? 'partial' : 'failed';
+      if (record.state !== nextState) contractCall(() => assertWorkflowTransition(record.state, nextState));
+      return {
+        state: nextState,
+        stage: 'download',
+        matchSummary: input.matchSummary ? safeMatchSummary(input.matchSummary) : record.matchSummary,
+        enrichmentSummary: input.enrichmentSummary ? safeEnrichmentSummary(input.enrichmentSummary) : record.enrichmentSummary,
+        qccRunId: safeText(input.qccRunId, 160) || record.qccRunId,
+        error: { code: 'DC_DELIVERY_FAILED' },
+      };
+    });
+  }
+
   async recordExport(id, input = {}) {
     return this.mutate(id, input.expectedRevision, (record) => {
       if (!['export_ready', 'partial'].includes(record.state)) {
@@ -392,11 +552,7 @@ export class DataCleaningWorkflowStore {
       }
       contractCall(() => assertWorkflowTransition(record.state, 'completed'));
       const timestamp = this.nowFn();
-      const incoming = Array.isArray(input.artifacts) ? input.artifacts : [input.artifact];
-      const artifacts = incoming.filter(Boolean).map((artifact) => sanitizeArtifact(artifact, timestamp));
-      if (!artifacts.length || artifacts.some((artifact) => !artifact.id)) {
-        throw new WorkflowError('DC_WORKFLOW_ARTIFACT_REQUIRED', 'At least one Host artifact reference is required.', 400);
-      }
+      const artifacts = sanitizeArtifacts(input, timestamp);
       return {
         state: input.preservePartial === true && record.state === 'partial' ? 'partial' : 'completed',
         stage: 'download',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-data-cleaning-agent",
-  "version": "0.9.13",
+  "version": "0.9.15",
   "description": "Data cleaning and data enrichment for CSV/XLSX/JSON enterprise lists in DeepSeek Harness, including spreadsheet cleaning, deduplication, profiling, optional Qichacha MCP and exports.",
   "type": "module",
   "main": "lib/index.js",
@@ -22,6 +22,8 @@
     "docs/USER-GUIDE.md",
     "docs/RELEASE-0.9.11.md",
     "docs/RELEASE-0.9.13.md",
+    "docs/RELEASE-0.9.14.md",
+    "docs/RELEASE-0.9.15.md",
     "docs/UNIFIED-HOME-1.5.4-ADOPTION.md",
     "docs/FIRST-CONTRIBUTION.md",
     "docs/COMPATIBILITY.md",