kangshifu-board/server/references/cloud-contracts-v07-r1.json

{
  "designVersion": "v0.7",
  "schemaVersion": "ksf.v0.7",
  "contractRevision": "ksf.functions.v0.4",
  "deploymentStatus": "design_only_not_deployed",
  "title": "云函数接口设计表",
  "version": "ksf.functions.v0.4",
  "status": "接口合同草案；未实现、未部署、未调用正式接口",
  "note": "function表是接口设计清单。报告入库和发布到看板是两次明确调用；云函数代码部署在服务端，不新增一张存放函数代码的数据库表。",
  "flow": "助手生成报告 → 员工确认当前版本 → Skill调用入库函数 → 数据库保存成功 → Skill调用看板发布函数 → 看板读取已发布卡片。",
  "transport": "建议采用Parse Cloud Code：POST {PARSE_BASE_URL}/functions/{functionName}。实际挂载前缀及现有函数名称需与经理核对。Parse成功返回外层{result:业务响应}；传输/认证错误按Parse实际{code,error}处理。",
  "auth": "调用者用用户会话或受限服务身份认证，身份与可访问项目从服务上下文取得。masterKey只留在受控后端，不写进Skill、HTML、提示词或请求体。只读查询与人工确认采用不同授权范围。",
  "commonInputs": [
    {
      "name": "requestId",
      "label": "请求追踪编号",
      "type": "String",
      "required": false,
      "rule": "写操作必填且稳定幂等；只读操作可由服务分配。"
    },
    {
      "name": "schemaVersion",
      "label": "服务合同版本",
      "type": "String",
      "required": false,
      "rule": "入库验证/提交必填；其他接口按合同兼容处理。"
    }
  ],
  "response": [
    {
      "name": "requestId",
      "label": "请求追踪编号",
      "type": "String",
      "required": true,
      "rule": "回传或服务生成。"
    },
    {
      "name": "schemaVersion",
      "label": "服务合同版本",
      "type": "String",
      "required": true,
      "rule": "已部署合同版本。"
    },
    {
      "name": "ok",
      "label": "请求是否被接受/处理",
      "type": "Boolean",
      "required": true,
      "rule": "true可能只是已排队，写入是否成功须看status和逐条回执。"
    },
    {
      "name": "status",
      "label": "处理状态",
      "type": "String",
      "required": true,
      "rule": "读操作ok；写操作按各接口枚举。"
    },
    {
      "name": "data",
      "label": "接口业务结果",
      "type": "Object",
      "required": false,
      "rule": "按各函数返回字段定义。"
    },
    {
      "name": "errors",
      "label": "可核查错误",
      "type": "Array",
      "required": true,
      "rule": "{code,message,itemKey?,field?,retryable}；成功时为空。"
    }
  ],
  "errors": [
    "AUTH_REQUIRED",
    "FORBIDDEN",
    "SCHEMA_VERSION_UNSUPPORTED",
    "VALIDATION_FAILED",
    "REFERENCE_NOT_FOUND",
    "IDEMPOTENCY_CONFLICT",
    "VERSION_CONFLICT",
    "UPLOAD_INCOMPLETE",
    "IMPORT_FAILED",
    "CAPABILITY_UNAVAILABLE",
    "REPORT_NOT_CONFIRMED",
    "REPORT_CONTENT_CHANGED",
    "REPORT_NOT_READY",
    "DASHBOARD_PUBLISH_FAILED",
    "NOISE_REASON_REQUIRED",
    "NOISE_CONTEXT_REQUIRED",
    "NOISE_CONTENT_CHANGED",
    "NOISE_REVIEW_REQUIRED"
  ],
  "constraints": [
    "ksfPrepareFileUpload只准备传输；文件字节必须真正上传，ksfRegisterSource核验后才登记来源。",
    "Skill生成并提取候选内容，服务端按字段合同验证和落库；云函数不把任意文本自动当成已确认业务事实。",
    "通用入库不能绕过项目阶段、人工确认、问卷答案应用等专门操作；allowedImportClasses仅为候选，实际可写字段按身份和操作裁剪。",
    "只读函数不写业务表；校验函数不落业务成果。预校验结果不能代替提交时再次检查。",
    "任务队列、事务、唯一约束、并发控制、文件大小和分页上限均按实际平台验证；不能仅靠提示词保证。",
    "员工对具体报告版本的确认是正式入库前置条件；确认来源必须可核验，助手不能自行伪造。",
    "ksfSubmitImport只负责入库，ksfPublishToDashboard负责独立发布。发布可复用同一报告内容，通过状态和卡片引用控制展示，无须假定复制整份数据。",
    "入库成功、发布成功、看板查询可见与浏览器刷新分别记录和验收。报告修改重新确认，入库失败不发布，发布失败单独重试。",
    "先完整保存原始记录，再保存筛选结果；不修改rawPayload、不删除噪声，也不把平台没有返回的字段冒充上游字段。",
    "未判断、噪声和已判断可用分开。正式样本只能使用当前范围、当前规则、当前内容的有效isNoise=false；true排除，null/缺失列为待判断。",
    "相同平台真实对象ID、当前判定所需内容指纹、研究范围和规则版本一致时才能跨采集复用。idOrigin不是upstream时，不自动跨批次复用；整条payloadHash变化不能单独说明正文变化。",
    "同一原始记录可有多个研究范围的判断。顶层9字段展示最近判断，noiseHistory保留各范围历史；查询必须匹配scope、ruleVersion、contentHash的同一条记录，并取该组合最新有效结论。",
    "模型或规则不能无声覆盖同范围的人工判断。人工修订必须基于最新版本追加历史。",
    "记录真实样本总数、噪声数、待判断数、有效数和去重口径。噪声变化后已有报告不静默改写，应标记受影响证据及待复核问题，必要时重算为新报告版本，经员工确认、入库、发布。",
    "接口补充ksf.functions.v0.4独立于数据库ksf.v0.7；本次不改表、不部署云函数、不导入样本。布尔false不得被当作缺失。"
  ],
  "allowedImportClasses": [
    "KfSource",
    "KfSession",
    "KfInsight",
    "KfArtifact",
    "KfOpportunity",
    "KfCategory",
    "KfCategoryRelation",
    "KfProduct",
    "KfEvidence",
    "KfEvidenceLink",
    "KfMarketMetric",
    "KfAssessment",
    "KfConcept",
    "KfReviewIssue",
    "KfSupplier",
    "KfMaterial",
    "KfProcess",
    "KfStandard",
    "KfSupplyQuote",
    "KfFormulaItem",
    "KfRawXhsNote",
    "KfRawXhsComment",
    "KfRawDouyinVideo",
    "KfRawDouyinComment",
    "KfRawTaobaoItem",
    "KfRawTaobaoReview",
    "KfRawJdItem",
    "KfRawJdReview",
    "KfRawBilibiliPost",
    "KfRaw1688Offer",
    "KfSku",
    "KfRetailPriceSnapshot",
    "KfProcessStep",
    "KfQuestionnaireQuestion"
  ],
  "functions": [
    {
      "name": "ksfGetIngestContract",
      "label": "读取入库字段规则",
      "group": "基础与文件",
      "caller": "Skill",
      "purpose": "取得当前表、可写字段、数据类型、必填、枚举、映射和限制，避免Skill使用过期Schema。",
      "inputs": [
        {
          "name": "clientSchemaVersion",
          "label": "Skill使用的结构版本",
          "type": "String",
          "required": false,
          "rule": "本轮使用ksf.v0.7。结构版本与contractRevision分别校验。"
        },
        {
          "name": "clientContractRevision",
          "label": "客户端接口修订号",
          "type": "String",
          "required": false,
          "rule": "本补充为ksf.functions.v0.4；不支持时明确返回能力或版本错误。"
        }
      ],
      "returns": [
        {
          "name": "schemaVersion",
          "label": "服务合同版本",
          "type": "String",
          "required": true,
          "rule": "ksf.v0.7或服务公布的兼容版本。"
        },
        {
          "name": "allowedClasses",
          "label": "允许导入的表及字段",
          "type": "Array",
          "required": true,
          "rule": "按调用身份裁剪；含各表的版本与类型规则。"
        },
        {
          "name": "limits",
          "label": "批量和文件限制",
          "type": "Object",
          "required": true,
          "rule": "实际部署配置；不能预先假定固定大小或数量。"
        },
        {
          "name": "capabilities",
          "label": "已部署能力",
          "type": "Object",
          "required": true,
          "rule": "标明文件上传、可信员工确认、独立报告发布、异步任务、知识同步是否实际可用。 同时公布噪声判定能力、范围键、规则版本、内容指纹规范及查询模式；未实现时必须明确不可用。"
        },
        {
          "name": "contractRevision",
          "label": "接口修订号",
          "type": "String",
          "required": true,
          "rule": "ksf.functions.v0.4；数据库结构仍为ksf.v0.7，不新增表字段。"
        },
        {
          "name": "noiseScopes",
          "label": "登记的研究范围",
          "type": "Array",
          "required": true,
          "rule": "[{id,label,scopeRevision,status,include,exclude,focus,allowedRuleVersions}]；只能选择status=active且当前身份可用的项。设计附件的defined不等于服务已激活。"
        },
        {
          "name": "noiseRuleVersions",
          "label": "登记的筛选规则",
          "type": "Array",
          "required": true,
          "rule": "[{id,label,status,scopeIds,allowedClasses,fingerprintSpecId,allowedMethods,rules}]；范围与规则必须匹配。"
        },
        {
          "name": "fingerprintSpecs",
          "label": "内容指纹规范",
          "type": "Array",
          "required": true,
          "rule": "返回本补充的投影、换行/Unicode规范、规范JSON、哈希域前缀和版本；服务和Skill使用同一共享实现。"
        }
      ],
      "reads": [],
      "writes": [],
      "rules": [
        "读取部署中的服务规则，不用正式库Schema快照代替业务校验。",
        "所有接口名称和路径均为首版设计；部署前与经理现有函数核对，避免重复开发。",
        "本补充附件noise-registry.json是设计参考，不是运行时授权。服务仅返回真实部署和授权范围；capabilities.noiseAssessment=false时不得通过本地登记表绕过不可用状态。",
        "正文规则第一版仅支持7张社媒/评论表；淘宝商品、京东商品和1688货源保留待判断，不用不完整文本规则替代商品/货源筛选。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfGetIngestContract",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfPrepareFileUpload",
      "label": "准备报告和附件上传",
      "group": "基础与文件",
      "caller": "Skill",
      "purpose": "取得文件上传方式、大小限制和上传凭证；文件内容通过专用文件接口传输。",
      "inputs": [
        {
          "name": "requestId",
          "label": "本次准备请求编号",
          "type": "String",
          "required": true,
          "rule": "同一文件上传重试保持稳定。"
        },
        {
          "name": "fileName",
          "label": "文件名",
          "type": "String",
          "required": true,
          "rule": "保留原名用于展示，存储路径由服务生成。"
        },
        {
          "name": "contentType",
          "label": "文件类型",
          "type": "String",
          "required": true,
          "rule": "如text/html、application/json。"
        },
        {
          "name": "sizeBytes",
          "label": "文件字节数",
          "type": "Number",
          "required": true,
          "rule": "非负整数；服务校验上限。"
        },
        {
          "name": "sha256",
          "label": "文件内容指纹",
          "type": "String",
          "required": true,
          "rule": "用于上传后核验及去重。"
        }
      ],
      "returns": [
        {
          "name": "upload",
          "label": "上传方式",
          "type": "Object",
          "required": true,
          "rule": "{mode,method,url,headers?,expiresAt?,receiptRequirements}；实际适配Parse Files或对象存储。临时凭证只在本次传输使用。"
        },
        {
          "name": "limits",
          "label": "实际限制",
          "type": "Object",
          "required": true,
          "rule": "支持的类型、最大体积等。"
        }
      ],
      "reads": [],
      "writes": [],
      "rules": [
        "返回准备信息不表示文件已上传。Skill必须继续执行upload指定的文件传输，再调用ksfRegisterSource。",
        "不要把本机路径或临时签名链接当成共享文件地址。上传适配器的选择属于部署待定项。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfPrepareFileUpload",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfRegisterSource",
      "label": "登记原始文件与资料",
      "group": "基础与文件",
      "caller": "Skill",
      "purpose": "文件上传完成后登记共享文件引用；纯文本或JSON资料也可直接登记，返回sourceId。",
      "inputs": [
        {
          "name": "requestId",
          "label": "本次登记请求编号",
          "type": "String",
          "required": true,
          "rule": "相同身份下稳定幂等。"
        },
        {
          "name": "source",
          "label": "资料内容和来源",
          "type": "Object",
          "required": true,
          "rule": "{title,sourceKind,fileReceipt?,rawText?,payload?,sourceUrl?,platform?,collectedAt?,dataMode}；至少有真实文件、内容或可核验来源。"
        },
        {
          "name": "contentHash",
          "label": "原始内容指纹",
          "type": "String",
          "required": true,
          "rule": "服务核验；不能只信任客户端声称已上传。"
        }
      ],
      "returns": [
        {
          "name": "sourceId",
          "label": "来源记录编号",
          "type": "String",
          "required": true,
          "rule": "对应KfSource.objectId。"
        },
        {
          "name": "operation",
          "label": "保存结果",
          "type": "String",
          "required": true,
          "rule": "created / unchanged；内容变更走新来源版本。"
        },
        {
          "name": "file",
          "label": "已核验共享文件引用",
          "type": "Object",
          "required": false,
          "rule": "纯文本资料可空；文件输入应有可访问的File引用。"
        }
      ],
      "reads": [
        {
          "table": "KfSource",
          "fields": [
            "externalKey",
            "contentHash",
            "file"
          ],
          "purpose": "查重及核验文件。"
        }
      ],
      "writes": [
        {
          "table": "KfSource",
          "fields": [
            "title",
            "payload",
            "rawText",
            "file",
            "sourceKind",
            "sourceUrl",
            "contentHash",
            "collectedAt",
            "dataMode",
            "ingestedAt"
          ],
          "purpose": "保存原件、内容与来源。"
        }
      ],
      "rules": [
        "先验证文件实际存在和访问范围；文件失败时不能登记为上传完成。",
        "内容相同但提供方、权限或采集批次不同，不可仅凭哈希跨范围合并。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfRegisterSource",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfRecordVocRun",
      "label": "记录VOC采集执行",
      "group": "入库与回执",
      "caller": "采集Skill",
      "purpose": "保存采集请求、真实采集模式、开始/结束状态、用量与完整响应来源；不负责执行VOC采集。",
      "inputs": [
        {
          "name": "requestId",
          "label": "执行事件请求编号",
          "type": "String",
          "required": true,
          "rule": "同一次状态事件重试不重复记录。"
        },
        {
          "name": "runKey",
          "label": "本次采集稳定编号",
          "type": "String",
          "required": true,
          "rule": "同一次采集开始到结束保持不变。"
        },
        {
          "name": "run",
          "label": "采集执行信息",
          "type": "Object",
          "required": true,
          "rule": "对应KfVocRun的平台、工具、查询条件、collectionMode、status、startedAt/finishedAt等。"
        }
      ],
      "returns": [
        {
          "name": "runId",
          "label": "采集执行编号",
          "type": "String",
          "required": true,
          "rule": "就是实际保存的KfVocRun.objectId；不是runKey、requestId、usageTraceId或上游任务ID。"
        },
        {
          "name": "status",
          "label": "已记录的执行状态",
          "type": "String",
          "required": true,
          "rule": "pending / running / succeeded / partial / failed / stale。"
        }
      ],
      "reads": [
        {
          "table": "KfVocRun",
          "fields": [
            "externalKey",
            "status",
            "startedAt",
            "sourceRef"
          ],
          "purpose": "查找同一次执行并校验状态更新。"
        }
      ],
      "writes": [
        {
          "table": "KfVocRun",
          "fields": [
            "platform",
            "toolName",
            "interfaceId",
            "requestContext",
            "collectionMode",
            "status",
            "startedAt",
            "finishedAt",
            "usageTraceId",
            "sourceRef",
            "usage"
          ],
          "purpose": "记录实际采集结果。"
        }
      ],
      "rules": [
        "只有获授权的采集服务可写采集结果，状态和live/sample以真实上游结果为准。",
        "采集成功与结构化入库成功分别记录。",
        "返回的runId可构造{__type:\"Pointer\",className:\"KfVocRun\",objectId:runId}，写KfRaw*.runRef；服务再次检查目标存在、类型与访问范围。普通字符串不能冒充Pointer。",
        "start事件可先保存没有sourceRef的执行记录；登记原始来源后，end事件沿同一runKey更新run.sourceRef并返回同一runId。不得为绑定来源另建一次采集；不向schema增添rawResponseRef。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfRecordVocRun",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfValidateImport",
      "label": "校验结构化入库内容",
      "group": "入库与回执",
      "caller": "Skill",
      "purpose": "在写库前检查结构化候选数据，返回逐字段错误和依赖顺序；不会生成报告或写入业务成果。",
      "inputs": [
        {
          "name": "schemaVersion",
          "label": "结构版本",
          "type": "String",
          "required": true,
          "rule": "ksf.v0.7或服务公布的兼容版本。"
        },
        {
          "name": "sourceId",
          "label": "输入资料编号",
          "type": "String",
          "required": true,
          "rule": "真实存在且调用者可访问。"
        },
        {
          "name": "items",
          "label": "待入库条目",
          "type": "Array",
          "required": true,
          "rule": "每条含{itemKey,className,externalKey,data,dependsOn?}；data按表规则校验。"
        },
        {
          "name": "reportConfirmations",
          "label": "报告确认凭据",
          "type": "Array",
          "required": false,
          "rule": "正式报告条目必填；预校验检查与待提交正文一致，提交时仍重新验证。"
        },
        {
          "name": "noiseAssessments",
          "label": "首次噪声判断的执行依据",
          "type": "Array",
          "required": false,
          "rule": "原始条目携带首次规则或模型判断时必填；[{itemKey,provenance:{executionEventRef,ruleVersion,modelVersion?}}]。服务核验实际执行事件、规则、输入内容及输出与items内候选一致，再保存来源历史。人工修订使用专门函数。"
        }
      ],
      "returns": [
        {
          "name": "valid",
          "label": "是否通过校验",
          "type": "Boolean",
          "required": true,
          "rule": "仅表示当前校验通过，提交时还要重新校验权限和并发变化。"
        },
        {
          "name": "itemResults",
          "label": "逐条校验结果",
          "type": "Array",
          "required": true,
          "rule": "{itemKey,valid,errors:[{field,code,message}],warnings}。"
        },
        {
          "name": "writePlan",
          "label": "依赖顺序",
          "type": "Array",
          "required": false,
          "rule": "只返回可执行计划；不表示已经保存。"
        }
      ],
      "reads": [
        {
          "table": "KfSource",
          "fields": [
            "objectId",
            "dataMode"
          ],
          "purpose": "检查来源和采集模式。"
        },
        {
          "table": "KfSource",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfSession",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfInsight",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfArtifact",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfOpportunity",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfCategory",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfCategoryRelation",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfProduct",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfEvidence",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfEvidenceLink",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfMarketMetric",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfAssessment",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfConcept",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfSupplier",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfMaterial",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfProcess",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfStandard",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfSupplyQuote",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfFormulaItem",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawXhsNote",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfSku",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRetailPriceSnapshot",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfProcessStep",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfQuestionnaireQuestion",
          "fields": [
            "objectId",
            "externalKey"
          ],
          "purpose": "仅在需要核对重复或引用时按身份查询。"
        },
        {
          "table": "KfRawXhsNote",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        }
      ],
      "writes": [],
      "rules": [
        "检查类型、单位、证据定位、状态、真实/样例标记与目标白名单。",
        "禁止任意类名、系统字段或ACL写入；禁止由报告汇总倒造平台原始记录。",
        "$ref/$id等临时引用由服务解析为真实Pointer；普通字符串不会自动成为外键。",
        "正式报告的确认事件与内容哈希必须一致；抽取的衍生结论仍按证据状态标记，不把员工接受报告等同全部事实已核验。",
        "平台原始条目可携带isNoise/noiseReason/noiseScope/noiseRuleVersion/noiseMethod作为首次规则或模型判断候选；服务核验实际执行来源和内容指纹后写noiseAssessedAt、noiseContentHash、noiseHistory。未提供判断时留空，不能默认可用。人工结果与已有记录的判定修订走ksfSetNoiseAssessment，不用通用入库绕过认证。",
        "isNoise=true须有非空noiseReason，作出判断时范围、规则和方式条件必填。禁止客户端直接写noiseAssessedByRef、noiseAssessedAt、noiseContentHash或noiseHistory；相同原始文件重导不得清空或覆盖人工筛选结果。",
        "噪声原始记录仍可保存；它被排除的是对应研究范围的分析样本，不是入库记录。证据与衍生统计的有效性另按查询和报告口径校验。",
        "item层必须使用className；items[].data顶层残留__className或其他未允许字段时返回VALIDATION_FAILED，定位items[i].data.__className。客户端边界转换删除自身路由标记并回查白名单，不在服务端静默丢字段。不能递归删除rawPayload中真实上游同名键。",
        "初次未判断的isNoise为缺失/null；noiseAssessedAt/noiseAssessedByRef/noiseContentHash/noiseHistory是服务维护字段，本地计算值可放旁路文件，不得混入通用data。首次规则/模型候选需搭配noiseAssessments的真实执行依据。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfValidateImport",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfSubmitImport",
      "label": "提交报告与结构化成果入库",
      "group": "入库与回执",
      "caller": "Skill",
      "purpose": "接收员工已确认的报告及结构化条目，校验后正式入库。报告默认未发布，成功后还需独立调用发布函数。VOC原始数据不受报告内容确认步骤阻塞。",
      "inputs": [
        {
          "name": "requestId",
          "label": "稳定提交编号",
          "type": "String",
          "required": true,
          "rule": "作为幂等键；同一请求相同内容返回已有批次，不重复创建。"
        },
        {
          "name": "schemaVersion",
          "label": "结构版本",
          "type": "String",
          "required": true,
          "rule": "ksf.v0.7或服务公布的兼容版本。"
        },
        {
          "name": "sourceId",
          "label": "原始资料编号",
          "type": "String",
          "required": true,
          "rule": "原件先登记。"
        },
        {
          "name": "vocRunId",
          "label": "VOC执行编号",
          "type": "String",
          "required": false,
          "rule": "外部报告或文件导入可空。"
        },
        {
          "name": "projectId",
          "label": "所属项目编号",
          "type": "String",
          "required": false,
          "rule": "公共行业资料可空；有项目时验证归属。"
        },
        {
          "name": "producer",
          "label": "Skill版本信息",
          "type": "Object",
          "required": true,
          "rule": "{skillName,skillVersion}；实际操作者从认证上下文取得。"
        },
        {
          "name": "items",
          "label": "已提取的结构化条目",
          "type": "Array",
          "required": true,
          "rule": "{itemKey,className,externalKey,data,dependsOn?}；报告全文写KfArtifact，其他内容拆到对应表。"
        },
        {
          "name": "reportConfirmations",
          "label": "各报告的员工确认凭据",
          "type": "Array",
          "required": false,
          "rule": "items包含正式KfArtifact报告时必填；[{itemKey,confirmationReceipt}]，须覆盖每份报告。纯原始数据导入可空。"
        },
        {
          "name": "noiseAssessments",
          "label": "首次噪声判断的执行依据",
          "type": "Array",
          "required": false,
          "rule": "原始条目携带首次规则或模型判断时必填；[{itemKey,provenance:{executionEventRef,ruleVersion,modelVersion?}}]。服务核验实际执行事件、规则、输入内容及输出与items内候选一致，再保存来源历史。人工修订使用专门函数。"
        }
      ],
      "returns": [
        {
          "name": "jobId",
          "label": "入库批次编号",
          "type": "String",
          "required": true,
          "rule": "供查询和重试。"
        },
        {
          "name": "status",
          "label": "当前批次状态",
          "type": "String",
          "required": true,
          "rule": "queued / validating / writing / partial / succeeded / failed。"
        },
        {
          "name": "counts",
          "label": "当前保存数量",
          "type": "Object",
          "required": true,
          "rule": "{created,updated,unchanged,failed,skipped,pending}；排队中不表示已完成。"
        },
        {
          "name": "recordRefs",
          "label": "已保存成果引用",
          "type": "Array",
          "required": false,
          "rule": "{className,objectId,operation}；不另存一份看板副本。"
        }
      ],
      "reads": [
        {
          "table": "KfSource",
          "fields": [
            "objectId",
            "dataMode"
          ],
          "purpose": "校验原件和数据取得模式。"
        },
        {
          "table": "KfImportJob",
          "fields": [
            "jobKey",
            "status",
            "inputSourceRef"
          ],
          "purpose": "幂等与续传检查。"
        },
        {
          "table": "KfRawXhsNote",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "已保存记录的首次导入重放先回读判断历史，避免覆盖人工筛选结果。"
        }
      ],
      "writes": [
        {
          "table": "KfSource",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfSession",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfInsight",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfArtifact",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfOpportunity",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfCategory",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfCategoryRelation",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfProduct",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfEvidence",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfEvidenceLink",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfMarketMetric",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfAssessment",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfConcept",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfSupplier",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfMaterial",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfProcess",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfStandard",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfSupplyQuote",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfFormulaItem",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawXhsNote",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfSku",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfRetailPriceSnapshot",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfProcessStep",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfQuestionnaireQuestion",
          "fields": [
            "externalKey",
            "recordState",
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "按该表允许字段写入；具体data仍须通过独立合同验证。"
        },
        {
          "table": "KfImportJob",
          "fields": [
            "jobKey",
            "inputSourceRef",
            "producer",
            "status",
            "expectedCount",
            "successCount",
            "failureCount",
            "startedAt",
            "finishedAt",
            "vocRunRef"
          ],
          "purpose": "保存批次与真实结果。"
        },
        {
          "table": "KfImportItem",
          "fields": [
            "jobRef",
            "itemKey",
            "targetClass",
            "targetId",
            "businessKey",
            "payloadHash",
            "dependencies",
            "status",
            "operation",
            "attempts",
            "errorCode",
            "errorMessage"
          ],
          "purpose": "保存逐条回执。"
        },
        {
          "table": "KfArtifact",
          "fields": [
            "reportContentHash",
            "contentConfirmedByRef",
            "contentConfirmedAt",
            "contentConfirmationRef",
            "dashboardState"
          ],
          "purpose": "从已核验确认事件保存确认信息，初始化为未发布。"
        }
      ],
      "rules": [
        "服务再次执行校验并保存可重放的输入快照，异步执行必须有持久任务机制；不得在返回后依赖临时进程继续工作。",
        "同一requestId但载荷不同返回IDEMPOTENCY_CONFLICT。部分成功返回partial，失败条目和依赖失败均有结果。",
        "KfProject阶段推进、人工确认、问卷答案应用等状态受专门接口控制，不能用通用入库绕过。",
        "报告、机会和方案保留版本；实际计数只从已确认的写入结果产生。",
        "报告入库必须验证confirmationReceipt对应当前报告版本、内容指纹、项目与员工身份；缺少可信确认时返回REPORT_NOT_CONFIRMED。员工确认字段由服务写入，调用者不能任意指定。",
        "服务端为正式报告设置dashboardState=unpublished，不接收外部覆盖发布元数据。入库完成后由Skill另调ksfPublishToDashboard。",
        "平台原始条目可携带isNoise/noiseReason/noiseScope/noiseRuleVersion/noiseMethod作为首次规则或模型判断候选；服务核验实际执行来源和内容指纹后写noiseAssessedAt、noiseContentHash、noiseHistory。未提供判断时留空，不能默认可用。人工结果与已有记录的判定修订走ksfSetNoiseAssessment，不用通用入库绕过认证。",
        "isNoise=true须有非空noiseReason，作出判断时范围、规则和方式条件必填。禁止客户端直接写noiseAssessedByRef、noiseAssessedAt、noiseContentHash或noiseHistory；相同原始文件重导不得清空或覆盖人工筛选结果。",
        "噪声原始记录仍可保存；它被排除的是对应研究范围的分析样本，不是入库记录。证据与衍生统计的有效性另按查询和报告口径校验。",
        "item层必须使用className；items[].data顶层残留__className或其他未允许字段时返回VALIDATION_FAILED，定位items[i].data.__className。客户端边界转换删除自身路由标记并回查白名单，不在服务端静默丢字段。不能递归删除rawPayload中真实上游同名键。",
        "初次未判断的isNoise为缺失/null；noiseAssessedAt/noiseAssessedByRef/noiseContentHash/noiseHistory是服务维护字段，本地计算值可放旁路文件，不得混入通用data。首次规则/模型候选需搭配noiseAssessments的真实执行依据。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfSubmitImport",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfGetImportResult",
      "label": "查询入库状态与逐条回执",
      "group": "入库与回执",
      "caller": "Skill",
      "purpose": "轮询批次和失败原因，确认排队任务是否真正完成。",
      "inputs": [
        {
          "name": "jobId",
          "label": "批次编号",
          "type": "String",
          "required": true,
          "rule": "只可查看授权批次。"
        },
        {
          "name": "cursor",
          "label": "条目分页游标",
          "type": "String",
          "required": false,
          "rule": "服务生成的稳定游标。"
        },
        {
          "name": "limit",
          "label": "回执条数",
          "type": "Number",
          "required": false,
          "rule": "默认值与上限由部署合同公布。"
        }
      ],
      "returns": [
        {
          "name": "job",
          "label": "批次及计数",
          "type": "Object",
          "required": true,
          "rule": "包含jobId、status和计数。"
        },
        {
          "name": "items",
          "label": "逐条写入回执",
          "type": "Array",
          "required": true,
          "rule": "{itemKey,status,targetClass,targetId,objectId?,updatedAt?,targetSnapshot?,snapshotState,operation,errorCode?,errorMessage?}；成功且回读有权访问时objectId=targetId，updatedAt为当前目标记录ISO UTC时间，不是批次或条目时间。"
        },
        {
          "name": "nextCursor",
          "label": "下一页游标",
          "type": "String",
          "required": false,
          "rule": "无更多结果时为空。"
        }
      ],
      "reads": [
        {
          "table": "KfImportJob",
          "fields": [
            "status",
            "successCount",
            "failureCount",
            "expectedCount",
            "summary"
          ],
          "purpose": "查询批次。"
        },
        {
          "table": "KfImportItem",
          "fields": [
            "itemKey",
            "status",
            "targetClass",
            "targetId",
            "operation",
            "errorCode",
            "errorMessage"
          ],
          "purpose": "返回逐条结果。"
        }
      ],
      "writes": [],
      "rules": [
        "succeeded只代表保存及必要关联完成；不表示浏览器页面已经刷新。",
        "返回真实目标编号，避免只回复“上传成功”。",
        "targetId仍是稳定编号；兼容增加objectId别名及updatedAt。targetSnapshot={className,objectId,updatedAt,observedAt,noiseContentHash?,fingerprintSpecId?}；从返回时同一份目标记录快照取得。snapshotState=available/unavailable/not_applicable。不可回读时不得伪造时间，保留条目真实入库状态并说明原因。",
        "回执快照不是锁。Skill用快照时间作为expectedUpdatedAt，服务还须对当前文本重新算指纹并原子校验；VERSION_CONFLICT时通过ksfGetRecord重新读取目标，不必重查整批。本修订只加返回字段，不向KfImportItem加字段。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfGetImportResult",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfRetryImport",
      "label": "重试失败入库条目",
      "group": "入库与回执",
      "caller": "Skill",
      "purpose": "重试可恢复失败，复用原业务键和成功回执；修改原载荷应重新校验后提交新的请求。",
      "inputs": [
        {
          "name": "requestId",
          "label": "本次重试编号",
          "type": "String",
          "required": true,
          "rule": "重试操作本身也需幂等。"
        },
        {
          "name": "jobId",
          "label": "原批次编号",
          "type": "String",
          "required": true,
          "rule": "需可写权限。"
        },
        {
          "name": "itemKeys",
          "label": "待重试条目编号",
          "type": "Array",
          "required": false,
          "rule": "省略时只重试允许恢复的失败及受依赖阻塞条目。"
        }
      ],
      "returns": [
        {
          "name": "jobId",
          "label": "原批次编号",
          "type": "String",
          "required": true,
          "rule": "继续关联原批次。"
        },
        {
          "name": "status",
          "label": "重试后状态",
          "type": "String",
          "required": true,
          "rule": "queued / writing / partial / succeeded / failed。"
        },
        {
          "name": "retryItemKeys",
          "label": "已接受重试条目",
          "type": "Array",
          "required": true,
          "rule": "不重复创建已经成功的记录。"
        }
      ],
      "reads": [
        {
          "table": "KfImportJob",
          "fields": [
            "jobKey",
            "status",
            "inputSourceRef"
          ],
          "purpose": "取得原载荷来源与批次。"
        },
        {
          "table": "KfImportItem",
          "fields": [
            "itemKey",
            "status",
            "businessKey",
            "payloadHash",
            "dependencies",
            "attempts"
          ],
          "purpose": "校验重试范围。"
        }
      ],
      "writes": [
        {
          "table": "KfImportJob",
          "fields": [
            "status",
            "successCount",
            "failureCount",
            "finishedAt"
          ],
          "purpose": "重新汇总批次。"
        },
        {
          "table": "KfImportItem",
          "fields": [
            "status",
            "attempts",
            "errorCode",
            "errorMessage",
            "targetId",
            "operation"
          ],
          "purpose": "更新逐条回执。"
        },
        {
          "table": "KfSource",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfSession",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfInsight",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfArtifact",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfOpportunity",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfCategory",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfCategoryRelation",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfProduct",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfEvidence",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfEvidenceLink",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfMarketMetric",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfAssessment",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfConcept",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfSupplier",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfMaterial",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfProcess",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfStandard",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfSupplyQuote",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfFormulaItem",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawXhsNote",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfSku",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfRetailPriceSnapshot",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfProcessStep",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        },
        {
          "table": "KfQuestionnaireQuestion",
          "fields": [
            "externalKey",
            "ingestedAt"
          ],
          "purpose": "仅重放原载荷中允许重试的记录。"
        }
      ],
      "rules": [
        "不能无条件重试已经成功或正在执行的条目。",
        "网络中断后先查原请求与目标业务键，避免未知写入结果造成重复。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfRetryImport",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfGetRecord",
      "label": "回读成果及其关联",
      "group": "查询与看板",
      "caller": "Skill、助手、看板",
      "purpose": "按真实编号读取报告、机会、方案或原始记录，供入库核验和详情查看。",
      "inputs": [
        {
          "name": "className",
          "label": "目标表名",
          "type": "String",
          "required": true,
          "rule": "只允许服务公布的可读业务表。"
        },
        {
          "name": "objectId",
          "label": "记录编号",
          "type": "String",
          "required": true,
          "rule": "真实数据库编号。"
        },
        {
          "name": "include",
          "label": "关联展开范围",
          "type": "Array",
          "required": false,
          "rule": "仅允许约定关联，不支持任意递归。"
        }
      ],
      "returns": [
        {
          "name": "record",
          "label": "已授权字段",
          "type": "Object",
          "required": true,
          "rule": "字段按角色裁剪；具有噪声复核权限时返回objectId、updatedAt和对应表的正文投影字段，供版本冲突后重算指纹，不返回伪造内容。"
        },
        {
          "name": "related",
          "label": "可读关联记录",
          "type": "Object",
          "required": false,
          "rule": "如来源、证据和项目；超限分页。"
        }
      ],
      "reads": [
        {
          "table": "KfSource",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfSession",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfInsight",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfArtifact",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfProject",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfOpportunity",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfCategory",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfCategoryRelation",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfProduct",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfEvidence",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfEvidenceLink",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfMarketMetric",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfAssessment",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfConcept",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfStageEvent",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfImportJob",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfImportItem",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfSupplier",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfMaterial",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfProcess",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfStandard",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfSupplyQuote",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfFormulaItem",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfVocRun",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawXhsNote",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfSku",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfRetailPriceSnapshot",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfProcessStep",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfQuestionnaireQuestion",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        },
        {
          "table": "KfQuestionnaireAnswer",
          "fields": [
            "objectId"
          ],
          "purpose": "按授权范围回读该对象及限定关联。"
        }
      ],
      "writes": [],
      "rules": [
        "记录存在不等于当前身份可见；回读失败返回明确错误。",
        "本机路径不会转换为已上传文件；正文按安全文本或经处理的文档展示。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfGetRecord",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfSearchRecords",
      "label": "检索可复用资料和成果",
      "group": "查询与看板",
      "caller": "助手、Skill",
      "purpose": "按品类、项目、平台、时间、类型和关键词检索已有数据，支持后续报告复用。",
      "inputs": [
        {
          "name": "className",
          "label": "查询表",
          "type": "String",
          "required": true,
          "rule": "只允许可读白名单。"
        },
        {
          "name": "query",
          "label": "关键词",
          "type": "String",
          "required": false,
          "rule": "使用已规划的searchText或受支持搜索字段。"
        },
        {
          "name": "filters",
          "label": "结构化筛选",
          "type": "Object",
          "required": false,
          "rule": "按表白名单字段筛选，不接收任意数据库查询表达式。"
        },
        {
          "name": "sort",
          "label": "排序规则",
          "type": "Object",
          "required": false,
          "rule": "限定字段和方向；用objectId作稳定并列排序。"
        },
        {
          "name": "cursor",
          "label": "下一页游标",
          "type": "String",
          "required": false,
          "rule": "与筛选条件绑定。"
        },
        {
          "name": "limit",
          "label": "每页数量",
          "type": "Number",
          "required": false,
          "rule": "以部署限制为准。"
        },
        {
          "name": "noiseContext",
          "label": "原始数据筛选口径",
          "type": "Object",
          "required": false,
          "rule": "涉及平台原始记录、其样本统计或证据筛选时必填{scope,ruleVersion,mode?}；mode=usable（默认）/pending/noise/all。查看noise/all须有维护权限；不涉及原始样本的普通报告列表可空。"
        }
      ],
      "returns": [
        {
          "name": "records",
          "label": "授权结果",
          "type": "Array",
          "required": true,
          "rule": "按表类型返回。"
        },
        {
          "name": "nextCursor",
          "label": "下一页游标",
          "type": "String",
          "required": false,
          "rule": "结果分页。"
        },
        {
          "name": "asOf",
          "label": "查询时间",
          "type": "Date",
          "required": true,
          "rule": "说明本次数据快照时间。"
        },
        {
          "name": "noiseSummary",
          "label": "当前口径的样本筛选数量",
          "type": "Object",
          "required": false,
          "rule": "涉及原始样本时返回{rawCount,usableCount,noiseCount,pendingCount,scope,ruleVersion,countingBasis}；按授权完整筛选范围统计，不把当前分页条数冒充总数。"
        }
      ],
      "reads": [
        {
          "table": "KfSource",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfSession",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfInsight",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfArtifact",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfProject",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfOpportunity",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfCategory",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfCategoryRelation",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfProduct",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfEvidence",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfEvidenceLink",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfMarketMetric",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfAssessment",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfConcept",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfStageEvent",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfImportJob",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfImportItem",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfSupplier",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfMaterial",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfProcess",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfStandard",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfSupplyQuote",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfFormulaItem",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfVocRun",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawXhsNote",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "objectId",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfSku",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfRetailPriceSnapshot",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfProcessStep",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfQuestionnaireQuestion",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        },
        {
          "table": "KfQuestionnaireAnswer",
          "fields": [
            "objectId"
          ],
          "purpose": "按表和访问范围查询；字段和索引仍需联调。"
        }
      ],
      "writes": [],
      "rules": [
        "默认过滤归档和未授权内容；演示数据需显式选择演示范围，不能混入真实业务结果。",
        "检索已有资料与重新调用VOC是两个操作，本函数不发起采集。",
        "原始样本查询按noiseContext.scope/ruleVersion及当前内容指纹匹配noiseHistory同一条元素的最新有效判断，不能仅用顶层isNoise，也不能跨元素拼条件。usable只返回false；缺失、过期或失效判断进入pending，true进入noise；filters不能绕过该规则。",
        "对已归一证据和衍生样本沿rawRecordTable/rawRecordId复查有效判断。已发布历史报告保留当时统计口径，发现变化以待复核提示和新版本处理，不静默修改原报告数字。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfSearchRecords",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfGetDashboardView",
      "label": "读取看板卡片与列表",
      "group": "查询与看板",
      "caller": "看板；Skill可用于展示前回查",
      "purpose": "读取已经发布的报告卡片及其他区域数据。报告只有入库后再经ksfPublishToDashboard成功发布才进入普通看板列表。",
      "inputs": [
        {
          "name": "view",
          "label": "看板区域",
          "type": "String",
          "required": true,
          "rule": "reports / opportunities / projects / insights / resources / issues。"
        },
        {
          "name": "projectId",
          "label": "项目筛选",
          "type": "String",
          "required": false,
          "rule": "公共资料区域可空。"
        },
        {
          "name": "filters",
          "label": "筛选条件",
          "type": "Object",
          "required": false,
          "rule": "按区域限定类型、品类、时间、阶段和状态。"
        },
        {
          "name": "cursor",
          "label": "分页游标",
          "type": "String",
          "required": false,
          "rule": "由服务生成。"
        },
        {
          "name": "limit",
          "label": "每页卡片数",
          "type": "Number",
          "required": false,
          "rule": "以部署限制为准。"
        },
        {
          "name": "noiseContext",
          "label": "原始数据筛选口径",
          "type": "Object",
          "required": false,
          "rule": "涉及平台原始记录、其样本统计或证据筛选时必填{scope,ruleVersion,mode?}；mode=usable（默认）/pending/noise/all。查看noise/all须有维护权限；不涉及原始样本的普通报告列表可空。"
        }
      ],
      "returns": [
        {
          "name": "cards",
          "label": "看板展示对象",
          "type": "Array",
          "required": true,
          "rule": "{id,entityClass,entityId,title,summary?,status,version?,updatedAt,detailRef}；字段由区域决定。"
        },
        {
          "name": "nextCursor",
          "label": "下一页游标",
          "type": "String",
          "required": false,
          "rule": "无更多数据时为空。"
        },
        {
          "name": "asOf",
          "label": "数据读取时间",
          "type": "Date",
          "required": true,
          "rule": "不代表页面已经刷新。"
        },
        {
          "name": "noiseSummary",
          "label": "当前口径的样本筛选数量",
          "type": "Object",
          "required": false,
          "rule": "涉及原始样本时返回{rawCount,usableCount,noiseCount,pendingCount,scope,ruleVersion,countingBasis}；按授权完整筛选范围统计，不把当前分页条数冒充总数。"
        }
      ],
      "reads": [
        {
          "table": "KfArtifact",
          "fields": [
            "title",
            "reportType",
            "version",
            "projectRef",
            "reviewState",
            "updatedAt",
            "dashboardState",
            "dashboardCardId",
            "dashboardPublishedAt"
          ],
          "purpose": "报告列表。"
        },
        {
          "table": "KfOpportunity",
          "fields": [
            "title",
            "oneLiner",
            "version",
            "reviewState",
            "updatedAt"
          ],
          "purpose": "机会卡。"
        },
        {
          "table": "KfProject",
          "fields": [
            "title",
            "stageCode",
            "progressState",
            "currentConceptRef",
            "lastActiveAt"
          ],
          "purpose": "项目与进度卡。"
        },
        {
          "table": "KfInsight",
          "fields": [
            "title",
            "body",
            "reviewState",
            "updatedAt"
          ],
          "purpose": "洞察卡。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "question",
            "status",
            "blocking",
            "artifactRef"
          ],
          "purpose": "待办。"
        },
        {
          "table": "KfSource",
          "fields": [
            "title",
            "summary",
            "file",
            "sourceKind"
          ],
          "purpose": "资料入口。"
        },
        {
          "table": "KfRawXhsNote",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "按研究范围读取原始样本及筛选历史；噪声与待判断维护入口单独授权。"
        }
      ],
      "writes": [],
      "rules": [
        "不假设已存在自动刷新；由看板实现轮询、订阅或重新加载，缓存策略与默认可见状态在联调时确定。",
        "展示待核验机会时明确状态；sample默认进入演示范围。",
        "reports区域默认强制dashboardState=published；Skill不能通过filters绕过未发布限制。内部报告回查用ksfGetRecord，不能冒充已上看板。",
        "原始样本查询按noiseContext.scope/ruleVersion及当前内容指纹匹配noiseHistory同一条元素的最新有效判断，不能仅用顶层isNoise，也不能跨元素拼条件。usable只返回false；缺失、过期或失效判断进入pending，true进入noise；filters不能绕过该规则。",
        "对已归一证据和衍生样本沿rawRecordTable/rawRecordId复查有效判断。已发布历史报告保留当时统计口径，发现变化以待复核提示和新版本处理，不静默修改原报告数字。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfGetDashboardView",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfCreateProjectFromOpportunity",
      "label": "从机会卡创建新品项目",
      "group": "项目与反馈",
      "caller": "助手、Skill",
      "purpose": "绑定选定机会版本并建立项目、初始阶段和事件。",
      "inputs": [
        {
          "name": "requestId",
          "label": "创建请求编号",
          "type": "String",
          "required": true,
          "rule": "相同请求不重复建项目。"
        },
        {
          "name": "opportunityId",
          "label": "机会卡编号",
          "type": "String",
          "required": true,
          "rule": "必须可读并符合项目启动要求。"
        },
        {
          "name": "opportunityVersion",
          "label": "选定机会版本",
          "type": "Number",
          "required": true,
          "rule": "显式绑定，不能自动换成最新版本。"
        },
        {
          "name": "title",
          "label": "项目名称",
          "type": "String",
          "required": true,
          "rule": "面向实际新品任务。"
        }
      ],
      "returns": [
        {
          "name": "projectId",
          "label": "新品项目编号",
          "type": "String",
          "required": true,
          "rule": "新建或幂等复用结果。"
        },
        {
          "name": "stageCode",
          "label": "初始阶段",
          "type": "String",
          "required": true,
          "rule": "采用服务部署的阶段配置。"
        },
        {
          "name": "eventId",
          "label": "初始阶段事件",
          "type": "String",
          "required": true,
          "rule": "对应KfStageEvent。"
        }
      ],
      "reads": [
        {
          "table": "KfOpportunity",
          "fields": [
            "objectId",
            "version",
            "reviewState",
            "dataMode"
          ],
          "purpose": "校验选定版本与可用状态。"
        }
      ],
      "writes": [
        {
          "table": "KfProject",
          "fields": [
            "title",
            "opportunityRef",
            "stageCode",
            "progressState",
            "lastActiveAt"
          ],
          "purpose": "创建项目并保留旧字段兼容投影。"
        },
        {
          "table": "KfStageEvent",
          "fields": [
            "projectRef",
            "fromStage",
            "toStage",
            "eventType",
            "occurredAt",
            "sequence"
          ],
          "purpose": "记录项目建立事件。"
        }
      ],
      "rules": [
        "当前设计的机会卡每版有独立记录；opportunityRef指向所选版本，服务额外核验version。",
        "用户动作与身份由认证上下文确认，禁止客户端假冒负责人；项目启动条件待业务确认。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfCreateProjectFromOpportunity",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfTransitionProject",
      "label": "更新项目阶段与进度",
      "group": "项目与反馈",
      "caller": "助手、Skill、看板操作",
      "purpose": "在成果满足约定条件后推进、退回或阻塞项目，同时保存事件历史。",
      "inputs": [
        {
          "name": "requestId",
          "label": "阶段操作请求编号",
          "type": "String",
          "required": true,
          "rule": "幂等。"
        },
        {
          "name": "projectId",
          "label": "项目编号",
          "type": "String",
          "required": true,
          "rule": "需要项目写权限。"
        },
        {
          "name": "expectedSequence",
          "label": "预期最新事件序号",
          "type": "Number",
          "required": true,
          "rule": "服务以原子比较或锁校验；冲突后重新读取，不直接覆盖。"
        },
        {
          "name": "action",
          "label": "阶段操作",
          "type": "String",
          "required": true,
          "rule": "started / submitted / reviewed / returned / completed / blocked。"
        },
        {
          "name": "toStage",
          "label": "目标阶段",
          "type": "String",
          "required": true,
          "rule": "校验合法迁移和完成条件。"
        },
        {
          "name": "artifactId",
          "label": "对应成果编号",
          "type": "String",
          "required": false,
          "rule": "提交、审核或完成时按阶段规则必填。"
        },
        {
          "name": "note",
          "label": "说明",
          "type": "String",
          "required": false,
          "rule": "退回或阻塞时必填。"
        }
      ],
      "returns": [
        {
          "name": "project",
          "label": "更新后项目状态",
          "type": "Object",
          "required": true,
          "rule": "包含stageCode、progressState及lastActiveAt。"
        },
        {
          "name": "eventId",
          "label": "本次事件编号",
          "type": "String",
          "required": true,
          "rule": "用于回溯。"
        },
        {
          "name": "sequence",
          "label": "最新事件序号",
          "type": "Number",
          "required": true,
          "rule": "供下次并发检查。"
        }
      ],
      "reads": [
        {
          "table": "KfProject",
          "fields": [
            "stageCode",
            "progressState"
          ],
          "purpose": "校验当前阶段。"
        },
        {
          "table": "KfStageEvent",
          "fields": [
            "projectRef",
            "sequence",
            "eventType"
          ],
          "purpose": "校验历史和并发。"
        },
        {
          "table": "KfArtifact",
          "fields": [
            "projectRef",
            "stageCode",
            "reviewState"
          ],
          "purpose": "核对成果归属和状态。"
        }
      ],
      "writes": [
        {
          "table": "KfProject",
          "fields": [
            "stageCode",
            "progressState",
            "lastActiveAt"
          ],
          "purpose": "更新当前投影。"
        },
        {
          "table": "KfStageEvent",
          "fields": [
            "projectRef",
            "fromStage",
            "toStage",
            "eventType",
            "artifactRef",
            "note",
            "occurredAt",
            "sequence"
          ],
          "purpose": "保留事件历史。"
        }
      ],
      "rules": [
        "事件和当前阶段的一致性需要事务或可恢复的状态更新机制；不能假定多次Parse保存天然原子。",
        "上传报告成功不会自动认定项目完成。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfTransitionProject",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfApplyReviewFeedback",
      "label": "保存校准答复并应用修订",
      "group": "项目与反馈",
      "caller": "助手、Skill、审核操作",
      "purpose": "记录问卷答复和客户补充材料；经授权核验后修订具体业务记录或新版本。",
      "inputs": [
        {
          "name": "requestId",
          "label": "校准操作编号",
          "type": "String",
          "required": true,
          "rule": "幂等。"
        },
        {
          "name": "issueId",
          "label": "校准问题编号",
          "type": "String",
          "required": false,
          "rule": "与answers至少提供一项。"
        },
        {
          "name": "answers",
          "label": "真实答复",
          "type": "Array",
          "required": false,
          "rule": "{questionId,responseBatchKey,fieldCode,rawAnswer,valueNumber?,valueText?,valueBoolean?,valueOptions?,unit?,sourceId}。"
        },
        {
          "name": "answerSourceId",
          "label": "答复证据来源",
          "type": "String",
          "required": true,
          "rule": "已登记邮件、口述记录或补充文件。"
        },
        {
          "name": "action",
          "label": "处理动作",
          "type": "String",
          "required": true,
          "rule": "record_answer / confirm_and_apply；确认应用需要单独授权角色。"
        },
        {
          "name": "changes",
          "label": "拟应用修改",
          "type": "Array",
          "required": false,
          "rule": "确认应用时提供{className,objectId,fieldPath,expectedVersion?,expectedUpdatedAt?,newValue,reason}。"
        }
      ],
      "returns": [
        {
          "name": "answerIds",
          "label": "已保存答案编号",
          "type": "Array",
          "required": true,
          "rule": "记录实际回答，空白问卷不产生答案。"
        },
        {
          "name": "issueState",
          "label": "问题处理状态",
          "type": "Object",
          "required": false,
          "rule": "区分answered、confirmed和closed。"
        },
        {
          "name": "applyResults",
          "label": "逐项应用结果",
          "type": "Array",
          "required": true,
          "rule": "applied / failed / not_needed及真实目标编号/新版本。"
        },
        {
          "name": "knowledgeSync",
          "label": "知识同步状态",
          "type": "Object",
          "required": false,
          "rule": "pending / succeeded / failed / not_required；不会默认成功。"
        }
      ],
      "reads": [
        {
          "table": "KfQuestionnaireQuestion",
          "fields": [
            "questionCode",
            "answerType",
            "targetMappings"
          ],
          "purpose": "核对题号、类型与目标字段。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "targetClass",
            "targetId",
            "fieldPath",
            "status"
          ],
          "purpose": "定位问题。"
        },
        {
          "table": "KfSource",
          "fields": [
            "objectId",
            "providerName",
            "file"
          ],
          "purpose": "校验答复来源。"
        }
      ],
      "writes": [
        {
          "table": "KfQuestionnaireAnswer",
          "fields": [
            "questionRef",
            "responseBatchKey",
            "fieldCode",
            "rawAnswer",
            "valueNumber",
            "valueText",
            "valueBoolean",
            "valueOptions",
            "unit",
            "sourceRef",
            "verificationState",
            "applyState",
            "appliedAt"
          ],
          "purpose": "保存答案与应用结果。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "answer",
            "answerSourceRef",
            "feedbackKind",
            "confirmedBy",
            "confirmedAt",
            "resolution",
            "applyState",
            "appliedAt",
            "knowledgeSync",
            "status"
          ],
          "purpose": "保存问题修订记录。"
        },
        {
          "table": "KfProduct",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfInsight",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfOpportunity",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfAssessment",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfConcept",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfMaterial",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfProcess",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfStandard",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfSupplyQuote",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfCategory",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfCategoryRelation",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfMarketMetric",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfSupplier",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfSku",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfRetailPriceSnapshot",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfProcessStep",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        },
        {
          "table": "KfQuestionnaireAnswer",
          "fields": [
            "reviewState",
            "ingestedAt"
          ],
          "purpose": "仅当changes明确指向该表时，按字段白名单核验并修订；有版本的成果创建新版本。"
        }
      ],
      "rules": [
        "confirm_and_apply按s.targetAllowlist和字段白名单更新实际业务目标，版本对象创建新版本，confirmedBy从服务身份记录。",
        "只有答复保存成功不等于修订成功；只有修订成功也不等于独立知识库同步成功。",
        "核验失败或并发冲突时保留待处理状态，不能覆盖新数据。",
        "修订报告正文时新建未发布版本并重新取得员工确认，不能沿用旧版本确认或直接覆盖已发布报告。",
        "平台原始记录的噪声人工修订调用ksfSetNoiseAssessment，不借通用changes覆盖筛选历史。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfApplyReviewFeedback",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfSyncKnowledge",
      "label": "同步独立知识库并回查结果",
      "group": "可选适配",
      "caller": "服务任务；Skill可查询",
      "purpose": "只有数字人另有独立知识库或检索索引时启用；助手直接查询数据库时可无需此函数。",
      "inputs": [
        {
          "name": "requestId",
          "label": "同步请求编号",
          "type": "String",
          "required": true,
          "rule": "按目标版本幂等。"
        },
        {
          "name": "issueId",
          "label": "变更问题编号",
          "type": "String",
          "required": true,
          "rule": "必须指向已应用修订，供同步状态持久记录。"
        },
        {
          "name": "action",
          "label": "同步动作",
          "type": "String",
          "required": true,
          "rule": "enqueue / status；队列写入和同步完成分别反馈。"
        }
      ],
      "returns": [
        {
          "name": "status",
          "label": "实际同步状态",
          "type": "String",
          "required": true,
          "rule": "pending / succeeded / failed / not_required。"
        },
        {
          "name": "target",
          "label": "知识系统回执",
          "type": "Object",
          "required": false,
          "rule": "包含targetSystem、targetObjectId、indexVersion、syncedAt或errorCode；以真实适配器结果为准。"
        }
      ],
      "reads": [
        {
          "table": "KfReviewIssue",
          "fields": [
            "resolution",
            "applyState",
            "knowledgeSync"
          ],
          "purpose": "读取已应用变更和同步目标。"
        }
      ],
      "writes": [
        {
          "table": "KfReviewIssue",
          "fields": [
            "knowledgeSync"
          ],
          "purpose": "持久保存真实同步结果。"
        }
      ],
      "rules": [
        "异步同步须有持久任务及去重机制；排队完成不等于索引已更新。",
        "知识库无接口或未部署时返回明确not_required或CAPABILITY_UNAVAILABLE，不冒充同步成功。"
      ],
      "optional": true,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfSyncKnowledge",
      "basis": [
        "C09",
        "C03",
        "C05"
      ]
    },
    {
      "name": "ksfConfirmReport",
      "label": "核验员工对报告的确认",
      "group": "报告确认与发布",
      "caller": "员工确认通道；Skill传递可信确认事件",
      "purpose": "在正式报告入库前核验员工的确认，绑定具体报告版本和内容指纹，返回供入库校验的确认凭据。",
      "inputs": [
        {
          "name": "requestId",
          "label": "确认操作编号",
          "type": "String",
          "required": true,
          "rule": "同一确认事件稳定幂等。"
        },
        {
          "name": "reportIdentity",
          "label": "报告身份与版本",
          "type": "Object",
          "required": true,
          "rule": "{reportSeriesKey,version,reportContentHash,projectId?}；与员工实际看到的内容一致。"
        },
        {
          "name": "confirmationEvent",
          "label": "员工确认事件",
          "type": "Object",
          "required": true,
          "rule": "可信页面或聊天通道产生的事件引用；服务器核验身份、操作、展示内容和作用范围。"
        }
      ],
      "returns": [
        {
          "name": "confirmationReceipt",
          "label": "经核验的确认凭据",
          "type": "String",
          "required": true,
          "rule": "短期有效的签名凭据或等效服务回执；绑定用户、版本、哈希和项目。"
        },
        {
          "name": "confirmedIdentity",
          "label": "已核验的确认身份",
          "type": "Object",
          "required": true,
          "rule": "{eventId,confirmedBy,confirmedAt,reportSeriesKey,version,reportContentHash}；确认人由服务取得。"
        }
      ],
      "reads": [],
      "writes": [],
      "rules": [
        "员工先查看报告，明确确认当前版本；助手推断“员工应该同意”或传employeeConfirmed=true无效。可信确认通道未接通时不能跳过本步骤。",
        "本函数只核验并签发确认回执，不把报告正文写入成果表；随后Skill登记原件、校验并正式入库。",
        "报告内容、标题、版本或项目发生改变后，原确认失效，须重新请员工确认。",
        "员工接受报告内容不等于报告内每一项市场推断或工厂参数均已核验；reviewState及证据确认状态继续独立管理。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfConfirmReport",
      "basis": [
        "C10",
        "C09"
      ]
    },
    {
      "name": "ksfPublishToDashboard",
      "label": "将已入库报告发布到看板",
      "group": "报告确认与发布",
      "caller": "助手通过Skill调用",
      "purpose": "入库完成后执行独立发布动作，创建或更新报告卡片引用并保存发布回执；入库成功本身不会发布报告。",
      "inputs": [
        {
          "name": "requestId",
          "label": "发布操作编号",
          "type": "String",
          "required": true,
          "rule": "同一报告版本的同一次发布重试保持稳定，不重复创建卡片。"
        },
        {
          "name": "artifactId",
          "label": "已入库报告编号",
          "type": "String",
          "required": true,
          "rule": "真实KfArtifact编号；必需内容和关联已保存。"
        },
        {
          "name": "version",
          "label": "要发布的报告版本",
          "type": "Number",
          "required": true,
          "rule": "绑定已确认版本，避免不经确认发布新内容。"
        },
        {
          "name": "reportContentHash",
          "label": "要发布的内容指纹",
          "type": "String",
          "required": true,
          "rule": "须与报告入库和员工确认的内容一致。"
        }
      ],
      "returns": [
        {
          "name": "artifactId",
          "label": "报告编号",
          "type": "String",
          "required": true,
          "rule": "对应已入库成果。"
        },
        {
          "name": "publicationStatus",
          "label": "发布结果",
          "type": "String",
          "required": true,
          "rule": "published / failed；仅完成发布后可返回published。"
        },
        {
          "name": "cardId",
          "label": "看板卡片编号",
          "type": "String",
          "required": false,
          "rule": "发布成功时必填；同库为稳定引用编号，独立看板为真实回执。"
        },
        {
          "name": "publishedAt",
          "label": "真实发布时间",
          "type": "Date",
          "required": false,
          "rule": "成功后必填。"
        },
        {
          "name": "readable",
          "label": "看板查询接口已可读",
          "type": "Boolean",
          "required": true,
          "rule": "服务回查后填写；不等于员工浏览器已刷新。"
        }
      ],
      "reads": [
        {
          "table": "KfArtifact",
          "fields": [
            "reportContentHash",
            "contentConfirmedByRef",
            "contentConfirmedAt",
            "contentConfirmationRef",
            "version",
            "dashboardState"
          ],
          "purpose": "校验报告已正式入库，版本与员工确认一致。"
        },
        {
          "table": "KfImportItem",
          "fields": [
            "targetClass",
            "targetId",
            "status",
            "dependencies"
          ],
          "purpose": "核对本报告必需条目和关联已成功；不以排队回执代替。"
        }
      ],
      "writes": [
        {
          "table": "KfArtifact",
          "fields": [
            "dashboardState",
            "dashboardPublishedAt",
            "dashboardPublishedByRef",
            "dashboardCardId",
            "dashboardPublication"
          ],
          "purpose": "只更新发布元数据；不改报告正文。"
        }
      ],
      "rules": [
        "必须先完成该报告和必需关联的入库，再调用本函数。ksfSubmitImport不得自动发布，也不得接受客户端自行写published。",
        "同库看板通过本函数设置发布状态和稳定卡片引用；若经理有独立看板发布服务，本函数调用实际适配器并核对回执后才标成功。",
        "发布失败保留已经成功入库的报告，记录publication_failed及错误；允许单独重试发布，无须重新导入报告。",
        "相同发布requestId而目标版本或内容不同返回冲突。同一报告版本重试不重复建卡；数据库与独立看板间部分失败须按真实回执恢复。",
        "发布后看板查询函数仅返回已发布报告。浏览器仍按看板刷新机制展示，不以接口成功冒充页面已刷新。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfPublishToDashboard",
      "basis": [
        "C10",
        "C09"
      ]
    },
    {
      "name": "ksfSetNoiseAssessment",
      "label": "保存或修订原始数据噪声判断",
      "group": "噪声筛选与复用",
      "caller": "助手通过Skill；员工复核操作",
      "purpose": "给已入库的平台原始记录保存按研究范围划分的噪声判断、原因及可复用历史；人工修订、自动判断和复用均留下真实来源。",
      "inputs": [
        {
          "name": "requestId",
          "label": "稳定判定操作编号",
          "type": "String",
          "required": true,
          "rule": "同一操作重试不重复追加历史；相同编号不同载荷返回冲突。"
        },
        {
          "name": "className",
          "label": "平台原始表名",
          "type": "String",
          "required": true,
          "rule": "只允许10张voc_raw表；禁止任意业务表和系统表。"
        },
        {
          "name": "recordId",
          "label": "原始记录编号",
          "type": "String",
          "required": true,
          "rule": "已经成功入库且调用者有权访问。"
        },
        {
          "name": "expectedUpdatedAt",
          "label": "读取时的记录更新时间",
          "type": "Date",
          "required": true,
          "rule": "JSON线上类型为UTC ISO 8601 String，如2026-10-30T03:00:00.000Z；服务解析为Date后原子校验当前原始记录更新时间。先处理同requestId幂等回放，再校验版本。不能使用入库批次时间。"
        },
        {
          "name": "noiseScope",
          "label": "当前研究范围键",
          "type": "String",
          "required": true,
          "rule": "须在服务合同中登记并对应本任务的品类、目的和范围。"
        },
        {
          "name": "noiseRuleVersion",
          "label": "当前筛选规则版本",
          "type": "String",
          "required": true,
          "rule": "服务端可回查该版本及指纹规范；任意字符串不能当有效规则。"
        },
        {
          "name": "decision",
          "label": "噪声判断及依据",
          "type": "Object",
          "required": true,
          "rule": "{isNoise,noiseReason?,method,contentHash,provenance}；isNoise严格Boolean，true或false均可提交，null不调用。contentHash遵守所选规则fingerprintSpecId；不是payloadHash。"
        },
        {
          "name": "reuseFrom",
          "label": "复用的原始判断",
          "type": "Object",
          "required": false,
          "rule": "reused时必填{className,recordId,assessmentRequestId}；服务校验真实平台对象ID、内容、范围及规则一致，并保存原来源链。"
        }
      ],
      "returns": [
        {
          "name": "recordRef",
          "label": "已更新原始记录",
          "type": "Object",
          "required": true,
          "rule": "{className,objectId,updatedAt}。"
        },
        {
          "name": "assessment",
          "label": "实际保存的判断",
          "type": "Object",
          "required": true,
          "rule": "{requestId,noiseScope,noiseRuleVersion,isNoise,noiseReason,noiseMethod,noiseContentHash,noiseAssessedAt,noiseAssessedByRef?}；返回已持久保存值。"
        },
        {
          "name": "affectedReviewIssues",
          "label": "受影响结论复核问题",
          "type": "Array",
          "required": true,
          "rule": "返回实际创建或复用的KfReviewIssue编号；没有可追溯衍生引用则为空，不虚构已重算报告。"
        }
      ],
      "reads": [
        {
          "table": "KfRawXhsNote",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "platform",
            "externalObjectId",
            "idOrigin",
            "rawPayload",
            "payloadHash",
            "updatedAt",
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "核对身份、并发版本、判断输入和原有分范围历史；复用时同时回读来源记录。"
        },
        {
          "table": "KfEvidence",
          "fields": [
            "rawRecordTable",
            "rawRecordId"
          ],
          "purpose": "定位该原始记录已被提取的证据，避免判断变化后结论继续无提示复用。"
        },
        {
          "table": "KfEvidenceLink",
          "fields": [
            "evidenceRef",
            "targetClass",
            "targetId"
          ],
          "purpose": "定位受影响的洞察、机会或成果引用。"
        }
      ],
      "writes": [
        {
          "table": "KfRawXhsNote",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRawXhsComment",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRawDouyinVideo",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRawDouyinComment",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRawTaobaoItem",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRawTaobaoReview",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRawJdItem",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRawJdReview",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRawBilibiliPost",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfRaw1688Offer",
          "fields": [
            "isNoise",
            "noiseReason",
            "noiseScope",
            "noiseRuleVersion",
            "noiseMethod",
            "noiseAssessedAt",
            "noiseAssessedByRef",
            "noiseContentHash",
            "noiseHistory"
          ],
          "purpose": "保存判断并追加服务审计历史，顶层字段作为最近判断的便查投影。"
        },
        {
          "table": "KfReviewIssue",
          "fields": [
            "targetClass",
            "targetId",
            "fieldPath",
            "question",
            "status"
          ],
          "purpose": "判断变化影响已有关联证据或结论时标记待复核，不自动改写已发布报告。"
        }
      ],
      "rules": [
        "核心字段isNoise须严格区分false、true、缺失/null。已判断必须具备范围、规则、方式、内容指纹和服务时间；true时原因非空。",
        "服务自行计算noiseContentHash并核对decision.contentHash；计算规范由noiseRuleVersion固定，不能直接用整条payloadHash代替。",
        "manual由可信员工会话直接认证，或核验绑定当前记录与判断的真实员工操作事件；模型自称人工无效。服务记录人、时间和实际生产者，不允许客户端写noiseHistory及身份字段。",
        "自动判断不得覆盖同范围、同规则、同内容的有效人工判断；人工修改使用最新expectedUpdatedAt，以原子条件更新或等效事务追加历史。",
        "noiseHistory中同范围、规则和内容取最新有效记录；同一requestId的幂等回放先返回已保存结果，不重复追加。新内容或规则变化先视为待判断，不能沿用旧结果。",
        "reused必须回查源判断并匹配真实平台对象ID、内容指纹、范围与规则。上游ID缺失或插件生成时不自动跨批次复用。人工来源保留为原判断来源，本次method=reused不伪造新人工确认。",
        "原文不删除，rawPayload不改写；噪声判定和通用reviewState相互独立，不把审核通过当作没有噪声。",
        "已有关联证据或已发布统计受影响时，记录待复核问题；报告重算仍走新版本、员工确认、入库、独立发布流程。",
        "isNoise=false与true都是有效判断，均保存范围、规则、方法、内容指纹、时间和历史。不得只生成true请求，否则已判断可用的数据仍无法进入usable查询。信息不足不把剩余记录批量改false。",
        "当前第一版指纹及规则见noise-registry.json；不去掉正文空白，不把全角问号、表情、负面情绪简单等同噪声；父上下文不在v1指纹投影内，不得暗中参与有状态判定。"
      ],
      "optional": false,
      "status": "设计新增 · 未实现/未部署",
      "route": "POST {PARSE_BASE_URL}/functions/ksfSetNoiseAssessment",
      "basis": [
        "C11"
      ]
    }
  ],
  "examples": [
    {
      "label": "助手生成报告并发布的主流程",
      "steps": [
        "助手生成报告并展示给员工",
        "员工确认当前内容和版本",
        "ksfConfirmReport",
        "ksfGetIngestContract",
        "有附件时ksfPrepareFileUpload并实际上传",
        "ksfRegisterSource",
        "Skill从已确认报告提取结构化条目",
        "ksfValidateImport",
        "ksfSubmitImport",
        "ksfGetImportResult",
        "ksfPublishToDashboard",
        "看板调用ksfGetDashboardView"
      ]
    },
    {
      "label": "已有报告文件的补充入口",
      "steps": [
        "员工提交报告并确认待入库版本",
        "ksfConfirmReport",
        "ksfPrepareFileUpload",
        "实际上传文件字节",
        "ksfRegisterSource",
        "ksfValidateImport",
        "ksfSubmitImport",
        "ksfGetImportResult",
        "ksfPublishToDashboard"
      ]
    },
    {
      "label": "原始数据采集与入库",
      "steps": [
        "助手调用VOC采集",
        "ksfRecordVocRun",
        "ksfRegisterSource",
        "ksfValidateImport",
        "ksfSubmitImport",
        "ksfGetImportResult"
      ]
    },
    {
      "label": "发布失败后的恢复",
      "steps": [
        "ksfGetRecord回查已入库报告和发布错误",
        "仅重试ksfPublishToDashboard",
        "ksfGetDashboardView核对卡片可读"
      ]
    },
    {
      "label": "噪声判断保存、复核与后续复用",
      "steps": [
        "VOC采集并完整保存平台原始记录",
        "ksfGetIngestContract",
        "助手按已登记范围和规则初筛；不确定时留待判断",
        "ksfValidateImport",
        "ksfSubmitImport",
        "ksfGetImportResult",
        "员工复核或修订时ksfSetNoiseAssessment",
        "ksfSearchRecords按noiseContext读取可用样本",
        "正文、范围及规则一致时复用已有判断；否则重新判断",
        "助手生成报告 → 员工确认 → 正式入库 → 独立发布看板"
      ]
    }
  ],
  "sample": {
    "note": "虚构样例；体现员工先确认、Skill入库、再单独发布。确认凭据、来源与报告编号均为占位，不能直接用于正式调用。 噪声样例也为虚构占位，不代表已经识别或保存14条实测噪声。",
    "functionName": "ksfSubmitImport",
    "request": {
      "requestId": "demo:banmian-report:v1",
      "schemaVersion": "ksf.v0.7",
      "sourceId": "SOURCE_OBJECT_ID",
      "producer": {
        "skillName": "ksf-structured-ingest",
        "skillVersion": "0.1"
      },
      "items": [
        {
          "itemKey": "report-1",
          "className": "KfArtifact",
          "externalKey": "demo:report:banmian:v1",
          "data": {
            "title": "拌面研发报告（虚构样例）",
            "reportType": "integrated_banmian_rd_report",
            "reportSeriesKey": "demo:report:banmian",
            "version": 1,
            "content": {
              "summary": "仅演示结构，不代表真实市场结论。"
            },
            "rawText": "虚构全文",
            "reviewState": "pending",
            "dataMode": "sample",
            "sourceRef": {
              "__type": "Pointer",
              "className": "KfSource",
              "objectId": "SOURCE_OBJECT_ID"
            },
            "reportContentHash": "CANONICAL_REPORT_CONTENT_HASH"
          }
        }
      ],
      "reportConfirmations": [
        {
          "itemKey": "report-1",
          "confirmationReceipt": "TRUSTED_EMPLOYEE_CONFIRMATION_RECEIPT"
        }
      ]
    },
    "queuedResponse": {
      "result": {
        "requestId": "demo:banmian-report:v1",
        "schemaVersion": "ksf.v0.7",
        "ok": true,
        "status": "queued",
        "data": {
          "jobId": "JOB_OBJECT_ID",
          "counts": {
            "created": 0,
            "updated": 0,
            "unchanged": 0,
            "failed": 0,
            "skipped": 0,
            "pending": 1
          }
        },
        "errors": []
      }
    },
    "completedResponse": {
      "result": {
        "requestId": "demo:poll:job-1",
        "schemaVersion": "ksf.v0.7",
        "ok": true,
        "status": "succeeded",
        "data": {
          "job": {
            "jobId": "JOB_OBJECT_ID",
            "status": "succeeded",
            "counts": {
              "created": 1,
              "updated": 0,
              "unchanged": 0,
              "failed": 0,
              "skipped": 0,
              "pending": 0
            }
          },
          "items": [
            {
              "itemKey": "report-1",
              "status": "succeeded",
              "targetClass": "KfArtifact",
              "targetId": "ARTIFACT_OBJECT_ID",
              "operation": "created",
              "objectId": "ARTIFACT_OBJECT_ID",
              "updatedAt": "2026-10-30T03:00:00.000Z",
              "snapshotState": "available",
              "targetSnapshot": {
                "className": "KfArtifact",
                "objectId": "ARTIFACT_OBJECT_ID",
                "updatedAt": "2026-10-30T03:00:00.000Z",
                "observedAt": "2026-10-30T03:00:01.000Z"
              }
            }
          ]
        },
        "errors": []
      }
    },
    "publishRequest": {
      "requestId": "demo:publish:report-v1",
      "artifactId": "ARTIFACT_OBJECT_ID",
      "version": 1,
      "reportContentHash": "CANONICAL_REPORT_CONTENT_HASH"
    },
    "publishResponse": {
      "result": {
        "requestId": "demo:publish:report-v1",
        "schemaVersion": "ksf.v0.7",
        "ok": true,
        "status": "published",
        "data": {
          "artifactId": "ARTIFACT_OBJECT_ID",
          "publicationStatus": "published",
          "cardId": "REPORT_CARD_ID",
          "publishedAt": "2026-10-29T12:00:00.000Z",
          "readable": true
        },
        "errors": []
      }
    },
    "noiseRequest": {
      "requestId": "demo:noise:raw-record-v1",
      "className": "KfRawXhsNote",
      "recordId": "RAW_RECORD_OBJECT_ID",
      "expectedUpdatedAt": "2026-10-29T12:00:00.000Z",
      "noiseScope": "REGISTERED_RESEARCH_SCOPE_KEY",
      "noiseRuleVersion": "REGISTERED_NOISE_RULE_VERSION",
      "decision": {
        "isNoise": true,
        "noiseReason": "示例：正文与当前研究的即食面消费需求无关。",
        "method": "manual",
        "contentHash": "SERVICE_VERIFIED_SEMANTIC_CONTENT_HASH",
        "provenance": {
          "confirmationEventId": "TRUSTED_EMPLOYEE_ACTION_EVENT_ID"
        }
      }
    },
    "noiseQuery": {
      "className": "KfRawXhsNote",
      "noiseContext": {
        "scope": "REGISTERED_RESEARCH_SCOPE_KEY",
        "ruleVersion": "REGISTERED_NOISE_RULE_VERSION",
        "mode": "usable"
      },
      "limit": 20
    }
  }
}