dsh-data-cleaning-agent 0.5.3 → 0.6.1

package/lib/web.js

@@ -10,8 +10,12 @@
 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 { DataCleaningWorkflowStore, WorkflowError } from './workflow.js';
+import { ArtifactError, WorkflowArtifactStore } from './artifacts.js';
 
 const MAX_BODY = 16 * 1024 * 1024; // 16 MiB 上传上限（MVP）
 
@@ -65,7 +69,7 @@ function requirePaidConfirmation(payload) {
 }
 
 function qccHttpStatus(code) {
-  if (code === 'QCC_RUN_NOT_FOUND') return 404;
+  if (code === 'QCC_RUN_NOT_FOUND' || code === 'QCC_COMMAND_NOT_FOUND') return 404;
   if (code === 'QCC_AUTH_REQUIRED') return 401;
   if (code === 'QCC_PERMISSION_DENIED') return 403;
   if (code === 'QCC_QUOTA_EXHAUSTED') return 402;
@@ -76,6 +80,8 @@ function qccHttpStatus(code) {
     || code === 'QCC_TOOL_UNAVAILABLE'
     || code === 'QCC_UPSTREAM_UNAVAILABLE'
     || code === 'QCC_IDEMPOTENCY_CAPACITY'
+    || code === 'QCC_COMMAND_CAPACITY'
+    || code === 'QCC_AGENT_COMMAND_UNAVAILABLE'
   ) return 503;
   if (
     code === 'QCC_CONFIRM_REQUIRED'
@@ -86,6 +92,7 @@ function qccHttpStatus(code) {
     || code === 'QCC_OPERATION_IN_PROGRESS'
     || code === 'QCC_RETRY_NOT_FAILED'
     || code === 'QCC_RETRY_NOT_ALLOWED'
+    || code === 'QCC_AGENT_EXECUTION_REQUIRED'
   ) return 409;
   return 400;
 }
@@ -98,6 +105,20 @@ function writeQccError(res, error) {
   writeJson(res, qccHttpStatus(code), { ok: false, ...payload });
 }
 
+function writeWorkflowError(res, error) {
+  if (error instanceof ArtifactError) {
+    return writeJson(res, error.status, { ok: false, code: error.code, message: error.message });
+  }
+  if (error instanceof WorkflowError) {
+    return writeJson(res, error.status, { ok: false, code: error.code, message: error.message });
+  }
+  return writeJson(res, 500, {
+    ok: false,
+    code: 'DC_WORKFLOW_INTERNAL',
+    message: 'Workflow request failed.',
+  });
+}
+
 /** 从 JSON 协议解析上传：{ filename, content }。content 为字符串；xlsx 时为 base64。 */
 async function parseUpload(body) {
   let payload;
@@ -265,11 +286,21 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
   const disposers = [];
   const qccBridge = new QccHostBridge({ tools, logger });
   const g5Runs = new G5RunStore();
+  const qccCommands = new QccCommandStore({ bridge: qccBridge, runs: g5Runs });
+  if (typeof tools?.register === 'function') {
+    disposers.push(registerQccCommandTool(tools, qccCommands));
+    report.qccCommandToolRegistered = true;
+  } else {
+    report.qccCommandToolRegistered = false;
+  }
   const phase3Service = new Phase3BatchService(qccBridge);
   const phase3Runs = new Phase3RunStore();
   report.qccBridgeMounted = true;
   let state = null; // DataCleaningJobs，惰性初始化
   let stateReady = null;
+  let workflow = null; // v2 工作流元数据，惰性初始化
+  let workflowReady = null;
+  const artifactStore = wctx.fs ? new WorkflowArtifactStore({ fs: wctx.fs }) : null;
 
   const register = (path, handler) => {
     disposers.push(server.register({ kind: 'prefix', path, handler }));
@@ -286,6 +317,15 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
     return null;
   };
 
+  const getWorkflow = () => {
+    if (!wctx.storageDomain) return null;
+    if (!workflowReady) {
+      workflow = new DataCleaningWorkflowStore({ storageDomain: wctx.storageDomain, logger });
+      workflowReady = workflow.init();
+    }
+    return workflowReady;
+  };
+
   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' });
@@ -304,11 +344,193 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
         skillListed: null,
         jobs: Boolean(wctx.jobs),
         storageDomain: Boolean(wctx.storageDomain),
+        workflowV2: Boolean(wctx.storageDomain),
+        durableArtifacts: Boolean(artifactStore),
+        artifactBinaryStrategy: artifactStore ? 'xlsx-base64-over-writeText' : 'unavailable',
         qccBridge: qccBridge.capabilities(),
       },
     });
   });
 
+  register('/data-cleaning/api/workflow/contract', (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'GET') {
+      return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'GET required' });
+    }
+    writeJson(res, 200, {
+      ok: true,
+      marker: 'data-cleaning-workflow-v2',
+      contract: publicWorkflowContract(),
+      executesTools: false,
+      paidCalls: false,
+    });
+  });
+
+  register('/data-cleaning/api/workflow/tasks', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    try {
+      const ready = getWorkflow();
+      if (!ready) {
+        return writeJson(res, 503, {
+          ok: false,
+          code: 'DC_WORKFLOW_UNAVAILABLE',
+          message: 'storageDomain unavailable in this composition',
+        });
+      }
+      await ready;
+      const pathname = new URL(req.url ?? '/data-cleaning/api/workflow/tasks', 'http://127.0.0.1').pathname;
+      const segments = pathname.split('/').filter(Boolean);
+      const tasksIndex = segments.indexOf('tasks');
+      const rest = tasksIndex >= 0 ? segments.slice(tasksIndex + 1) : [];
+
+      if (rest.length === 0) {
+        if (req.method === 'GET') {
+          return writeJson(res, 200, {
+            ok: true,
+            marker: 'data-cleaning-workflow-v2',
+            tasks: await workflow.list(),
+          });
+        }
+        if (req.method === 'POST') {
+          const body = await readBody(req);
+          const payload = body.length ? JSON.parse(body.toString('utf8')) : {};
+          return writeJson(res, 201, {
+            ok: true,
+            marker: 'data-cleaning-workflow-v2',
+            task: await workflow.create(payload),
+          });
+        }
+        return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'GET or POST required' });
+      }
+
+      const taskId = decodeURIComponent(rest[0]);
+      if (rest.length === 1) {
+        if (req.method === 'GET') {
+          return writeJson(res, 200, {
+            ok: true,
+            marker: 'data-cleaning-workflow-v2',
+            task: await workflow.require(taskId),
+          });
+        }
+        if (req.method === 'PATCH') {
+          const body = await readBody(req);
+          const payload = body.length ? JSON.parse(body.toString('utf8')) : {};
+          return writeJson(res, 200, {
+            ok: true,
+            marker: 'data-cleaning-workflow-v2',
+            task: await workflow.updateDraft(taskId, payload),
+          });
+        }
+        return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'GET or PATCH required' });
+      }
+
+      if (rest[1] === 'artifacts') {
+        if (!artifactStore) {
+          return writeJson(res, 503, {
+            ok: false,
+            code: 'DC_ARTIFACT_UNAVAILABLE',
+            message: 'DSH fs service unavailable in this composition.',
+          });
+        }
+        const current = await workflow.require(taskId);
+        if (rest.length === 2 && req.method === 'GET') {
+          return writeJson(res, 200, {
+            ok: true,
+            marker: 'data-cleaning-artifacts-v1',
+            task: current,
+            artifacts: current.artifacts,
+          });
+        }
+        if (rest.length === 2 && req.method === 'POST') {
+          const body = await readBody(req);
+          const payload = body.length ? JSON.parse(body.toString('utf8')) : {};
+          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);
+          }
+          const artifacts = await artifactStore.createBundle(taskId, {
+            rows: payload.rows,
+            headers: payload.headers,
+            exceptionRows: payload.exceptionRows,
+            baseName: payload.baseName || readyTask.title,
+          });
+          const completed = await workflow.recordExport(taskId, {
+            expectedRevision: readyTask.revision,
+            artifacts,
+          });
+          return writeJson(res, 201, {
+            ok: true,
+            marker: 'data-cleaning-artifacts-v1',
+            task: completed,
+            artifacts: completed.artifacts,
+          });
+        }
+        if (rest.length === 3 && req.method === 'GET') {
+          const artifactId = decodeURIComponent(rest[2]);
+          const artifact = current.artifacts.find((item) => item.id === artifactId);
+          if (!artifact) throw new ArtifactError('DC_ARTIFACT_NOT_FOUND', 'Artifact not found for this task.', 404);
+          const bytes = await artifactStore.read(taskId, artifact);
+          const fallback = artifact.format === 'xlsx' ? 'export.xlsx' : 'export.csv';
+          const asciiName = String(artifact.fileName || fallback).replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_');
+          res.writeHead(200, {
+            'content-type': artifact.mediaType || 'application/octet-stream',
+            'content-length': String(bytes.length),
+            'content-disposition': `attachment; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(artifact.fileName || fallback)}`,
+            'cache-control': 'no-store',
+            'x-content-type-options': 'nosniff',
+            'referrer-policy': 'no-referrer',
+          });
+          return res.end(bytes);
+        }
+        return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'Artifact route requires GET or POST.' });
+      }
+
+      if (rest.length !== 3 || rest[1] !== 'actions' || req.method !== 'POST') {
+        return writeJson(res, 404, { ok: false, code: 'DC_WORKFLOW_ROUTE', message: 'Workflow route not found.' });
+      }
+      const body = await readBody(req);
+      const payload = body.length ? JSON.parse(body.toString('utf8')) : {};
+      const action = rest[2];
+      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),
+      };
+      if (!actions[action]) {
+        return writeJson(res, 404, { ok: false, code: 'DC_WORKFLOW_ACTION', message: `Unknown workflow action: ${action}` });
+      }
+      return writeJson(res, 200, {
+        ok: true,
+        marker: 'data-cleaning-workflow-v2',
+        task: await actions[action](),
+      });
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return writeJson(res, 400, { ok: false, code: 'DC_BAD_JSON', message: 'Request body must be valid JSON.' });
+      }
+      return writeWorkflowError(res, error);
+    }
+  });
+
   register('/data-cleaning/api/g5/capabilities', (req, res) => {
     if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
     writeJson(res, 200, {
@@ -320,10 +542,52 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
       idempotencyRequired: true,
       candidateResume: true,
       manualRetry: true,
+      agentCommandTool: TOOL_QCC_COMMAND,
+      agentCommandToolRegistered: report.qccCommandToolRegistered,
+      agentOwnedExecutionRequired: true,
       runPersistence: 'host-memory',
     });
   });
 
+  register('/data-cleaning/api/g5/commands', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    try {
+      const pathname = new URL(req.url ?? '/data-cleaning/api/g5/commands', 'http://127.0.0.1').pathname;
+      const segments = pathname.split('/').filter(Boolean);
+      const commandsIndex = segments.indexOf('commands');
+      const rest = commandsIndex >= 0 ? segments.slice(commandsIndex + 1) : [];
+      if (rest.length === 0 && req.method === 'POST') {
+        if (!report.qccCommandToolRegistered) {
+          throw new QccBridgeError(
+            'QCC_AGENT_COMMAND_UNAVAILABLE',
+            'The current DSH Host does not expose the Agent command registration API.',
+          );
+        }
+        const payload = JSON.parse((await readBody(req)).toString('utf8'));
+        requirePaidConfirmation(payload);
+        return writeJson(res, 201, {
+          ok: true,
+          marker: 'g5-agent-command',
+          paidCalls: false,
+          command: qccCommands.prepare(payload),
+        });
+      }
+      if (rest.length === 1 && req.method === 'GET') {
+        return writeJson(res, 200, {
+          ok: true,
+          marker: 'g5-agent-command',
+          command: qccCommands.status(decodeURIComponent(rest[0])),
+        });
+      }
+      return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST a command or GET one command id' });
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return writeJson(res, 400, { ok: false, code: 'DC_BAD_JSON', message: 'Request body must be valid JSON.' });
+      }
+      return writeQccError(res, error);
+    }
+  });
+
   register('/data-cleaning/api/phase2/capabilities', (req, res) => {
     if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
     if (req.method !== 'GET') {
@@ -633,6 +897,8 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
         kind,
         summary: result.summary,
         rowCount: result.rows.length,
+        headers: headers.length ? headers : result.rows[0] ? Object.keys(result.rows[0]) : [],
+        rows: result.rows,
         csv,
         downloadName: kind === 'clean' ? 'cleaned.csv' : kind === 'complete' ? 'completed.csv' : null,
       });
@@ -687,6 +953,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
 
   return () => {
     if (state) { state.dispose().catch(() => {}); }
+    if (workflow) { workflow.dispose().catch(() => {}); }
     for (const dispose of disposers) dispose();
   };
 }

package/lib/workflow-contract.js

@@ -0,0 +1,263 @@
+/**
+ * 数据清洗补全智能体 v2 工作流契约。
+ *
+ * 设计原则：
+ *  - 业务主流程固定为五步；质量体检与任务历史是横向能力。
+ *  - 匹配结果只表达状态与可审计依据，不生成无法验证的“置信度”。
+ *  - 历史、人员、招投标三域不属于当前版本字段目录。
+ */
+
+export const WORKFLOW_SCHEMA_VERSION = 2;
+
+export const WORKFLOW_STAGES = Object.freeze([
+  Object.freeze({ id: 'upload', label: '上传数据', order: 1 }),
+  Object.freeze({ id: 'rules', label: '规则确认', order: 2 }),
+  Object.freeze({ id: 'match', label: '数据匹配', order: 3 }),
+  Object.freeze({ id: 'enrich', label: '清洗补全', order: 4 }),
+  Object.freeze({ id: 'download', label: '下载数据', order: 5 }),
+]);
+
+export const WORKFLOW_STATES = Object.freeze([
+  'draft',
+  'uploaded',
+  'rules_confirmed',
+  'diagnosed',
+  'matching',
+  'review_required',
+  'matched',
+  'enriching',
+  'export_ready',
+  'completed',
+  'parse_failed',
+  'authorization_required',
+  'partial',
+  'failed',
+  'cancelled',
+]);
+
+export const TERMINAL_WORKFLOW_STATES = Object.freeze(['completed', 'cancelled']);
+
+export const SOURCE_TYPES = Object.freeze(['text', 'csv', 'xlsx', 'json', 'image']);
+
+export const MATCH_STATUSES = Object.freeze([
+  'exact',
+  'candidate',
+  'confirmed',
+  'unresolved',
+  'failed',
+]);
+
+export const MATCH_ANCHORS = Object.freeze(['company_name', 'credit_no', 'reg_no']);
+
+export const FIELD_CATALOG = Object.freeze([
+  Object.freeze({
+    id: 'identity',
+    label: '基础工商信息',
+    fields: Object.freeze([
+      Object.freeze({ id: 'company_name', label: '企业名称', inputAnchor: true, defaultSelected: true }),
+      Object.freeze({ id: 'credit_no', label: '统一社会信用代码', inputAnchor: true, defaultSelected: true }),
+      Object.freeze({ id: 'reg_no', label: '注册号', inputAnchor: true }),
+      Object.freeze({ id: 'org_no', label: '组织机构代码' }),
+      Object.freeze({ id: 'reg_status', label: '登记状态', defaultSelected: true }),
+      Object.freeze({ id: 'legal_rep', label: '法定代表人', defaultSelected: true }),
+      Object.freeze({ id: 'reg_capital', label: '注册资本', defaultSelected: true }),
+      Object.freeze({ id: 'paid_capital', label: '实缴资本' }),
+      Object.freeze({ id: 'establish_date', label: '成立日期', defaultSelected: true }),
+      Object.freeze({ id: 'company_type', label: '企业类型' }),
+      Object.freeze({ id: 'registration_authority', label: '登记机关' }),
+      Object.freeze({ id: 'former_name', label: '曾用名' }),
+      Object.freeze({ id: 'english_name', label: '英文名' }),
+    ]),
+  }),
+  Object.freeze({
+    id: 'contact',
+    label: '地址与联系方式',
+    fields: Object.freeze([
+      Object.freeze({ id: 'registered_address', label: '注册地址', defaultSelected: true }),
+      Object.freeze({ id: 'province', label: '省份地区', matchAuxiliary: true }),
+      Object.freeze({ id: 'city', label: '城市', matchAuxiliary: true }),
+      Object.freeze({ id: 'district', label: '区县' }),
+      Object.freeze({ id: 'phone', label: '电话', matchAuxiliary: true }),
+      Object.freeze({ id: 'email', label: '邮箱' }),
+      Object.freeze({ id: 'website', label: '官网' }),
+    ]),
+  }),
+  Object.freeze({
+    id: 'operation',
+    label: '经营信息',
+    fields: Object.freeze([
+      Object.freeze({ id: 'business_scope', label: '经营范围' }),
+      Object.freeze({ id: 'industry_category', label: '国标行业' }),
+      Object.freeze({ id: 'industry_large', label: '一级行业' }),
+      Object.freeze({ id: 'industry_middle', label: '二级行业' }),
+      Object.freeze({ id: 'operating_period', label: '营业期限' }),
+      Object.freeze({ id: 'company_size', label: '企业规模' }),
+      Object.freeze({ id: 'company_profile', label: '企业简介' }),
+    ]),
+  }),
+  Object.freeze({
+    id: 'risk',
+    label: '风险摘要',
+    capability: 'qcc.risk',
+    fields: Object.freeze([
+      Object.freeze({ id: 'risk_summary', label: '风险摘要', capability: 'qcc.risk' }),
+      Object.freeze({ id: 'operating_exception', label: '经营异常摘要', capability: 'qcc.risk' }),
+      Object.freeze({ id: 'administrative_penalty', label: '行政处罚摘要', capability: 'qcc.risk' }),
+    ]),
+  }),
+  Object.freeze({
+    id: 'ipr',
+    label: '知识产权摘要',
+    capability: 'qcc.ipr',
+    fields: Object.freeze([
+      Object.freeze({ id: 'trademark_summary', label: '商标摘要', capability: 'qcc.ipr' }),
+      Object.freeze({ id: 'patent_summary', label: '专利摘要', capability: 'qcc.ipr' }),
+      Object.freeze({ id: 'software_copyright_summary', label: '软件著作权摘要', capability: 'qcc.ipr' }),
+    ]),
+  }),
+]);
+
+const FIELD_IDS = new Set(FIELD_CATALOG.flatMap((group) => group.fields.map((field) => field.id)));
+const STAGE_IDS = new Set(WORKFLOW_STAGES.map((stage) => stage.id));
+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'],
+  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'],
+  parse_failed: ['draft', 'uploaded', 'cancelled'],
+  authorization_required: ['matching', 'enriching', 'failed', 'cancelled'],
+  partial: ['review_required', 'enriching', 'export_ready', 'authorization_required', 'completed', 'failed', 'cancelled'],
+  failed: ['draft', 'uploaded', 'rules_confirmed', 'diagnosed', 'matching', 'enriching', 'cancelled'],
+  completed: [],
+  cancelled: [],
+});
+
+export class WorkflowContractError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'WorkflowContractError';
+    this.code = code;
+  }
+}
+
+function text(value, max = 160) {
+  return String(value ?? '').trim().slice(0, max);
+}
+
+function uniqueStrings(values, max = 64) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => text(value)).filter(Boolean))].slice(0, max);
+}
+
+export function normalizeMappings(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 128).map((mapping) => ({
+    sourceField: text(mapping?.sourceField),
+    targetField: text(mapping?.targetField),
+  })).filter((mapping) => mapping.sourceField && FIELD_IDS.has(mapping.targetField));
+}
+
+export function validateMappings(value) {
+  if (!Array.isArray(value) || value.length > 128) {
+    throw new WorkflowContractError('DC_WORKFLOW_MAPPING_INVALID', 'Field mappings must be an array with at most 128 entries.');
+  }
+  const mappings = normalizeMappings(value);
+  if (mappings.length !== value.length) {
+    throw new WorkflowContractError('DC_WORKFLOW_MAPPING_INVALID', 'Every mapping needs a source field and a supported target field.');
+  }
+  if (mappings.length === 0) {
+    throw new WorkflowContractError('DC_WORKFLOW_MAPPING_REQUIRED', 'At least one valid field mapping is required.');
+  }
+  if (!mappings.some((mapping) => MATCH_ANCHORS.includes(mapping.targetField))) {
+    throw new WorkflowContractError(
+      'DC_WORKFLOW_ANCHOR_REQUIRED',
+      'Map at least one enterprise identity anchor: company name, unified social credit code, or registration number.',
+    );
+  }
+  const targets = new Set();
+  const sources = new Set();
+  for (const mapping of mappings) {
+    if (targets.has(mapping.targetField)) {
+      throw new WorkflowContractError('DC_WORKFLOW_DUPLICATE_MAPPING', `Duplicate target mapping: ${mapping.targetField}`);
+    }
+    if (sources.has(mapping.sourceField)) {
+      throw new WorkflowContractError('DC_WORKFLOW_DUPLICATE_MAPPING', `Duplicate source mapping: ${mapping.sourceField}`);
+    }
+    targets.add(mapping.targetField);
+    sources.add(mapping.sourceField);
+  }
+  return mappings;
+}
+
+export function normalizeFieldSelection(value) {
+  return uniqueStrings(value).filter((field) => FIELD_IDS.has(field));
+}
+
+export function normalizeWorkflowDraft(value = {}) {
+  const objectives = uniqueStrings(value.objectives, 16).filter((item) => (
+    ['clean_name', 'deduplicate', 'validate_identity', 'complete_fields'].includes(item)
+  ));
+  return {
+    title: text(value.title, 120) || '未命名数据清洗补全任务',
+    objectives,
+    fieldSelection: normalizeFieldSelection(value.fieldSelection),
+    mappings: normalizeMappings(value.mappings),
+    matchRules: {
+      normalizeNames: value.matchRules?.normalizeNames !== false,
+      preferCreditNo: value.matchRules?.preferCreditNo !== false,
+      deduplicate: value.matchRules?.deduplicate !== false,
+      manualReviewAmbiguous: value.matchRules?.manualReviewAmbiguous !== false,
+    },
+  };
+}
+
+export function canTransition(from, to) {
+  if (!STATE_IDS.has(from) || !STATE_IDS.has(to)) return false;
+  return TRANSITIONS[from].includes(to);
+}
+
+export function assertWorkflowTransition(from, to) {
+  if (!canTransition(from, to)) {
+    throw new WorkflowContractError('DC_WORKFLOW_TRANSITION', `Invalid workflow transition: ${from} -> ${to}`);
+  }
+}
+
+export function publicWorkflowContract() {
+  return {
+    schemaVersion: WORKFLOW_SCHEMA_VERSION,
+    stages: WORKFLOW_STAGES,
+    states: WORKFLOW_STATES,
+    terminalStates: TERMINAL_WORKFLOW_STATES,
+    sourceTypes: SOURCE_TYPES,
+    matchStatuses: MATCH_STATUSES,
+    matchAnchors: MATCH_ANCHORS,
+    fieldCatalog: FIELD_CATALOG,
+    crossCuttingCapabilities: [
+      { id: 'prompt', label: '任务设置' },
+      { id: 'profile', label: '质量体检' },
+      { id: 'history', label: '任务历史' },
+    ],
+    privacy: {
+      persisted: ['task metadata', 'numeric summaries', 'artifact references'],
+      notPersisted: ['raw rows and enterprise lists', 'QCC response payloads', 'candidate details'],
+    },
+    deferredDomains: ['history', 'person', 'tender'],
+  };
+}
+
+export function assertWorkflowRecordShape(record) {
+  if (!record || record.schemaVersion !== WORKFLOW_SCHEMA_VERSION) {
+    throw new WorkflowContractError('DC_WORKFLOW_SCHEMA', 'Unsupported workflow record schema.');
+  }
+  if (!STAGE_IDS.has(record.stage) || !STATE_IDS.has(record.state)) {
+    throw new WorkflowContractError('DC_WORKFLOW_SCHEMA', 'Workflow record contains an invalid stage or state.');
+  }
+  return record;
+}