核心能力：企业工作文件理解、核对与数据补录

技术方案 v1，2026-10-21。作为 LangGraph 平台的第二条核心主线，与九个运营场景并列。面向企业初次上线及日常增量补录；本轮仅设计，未处理真实文件或导入业务数据。

授权规则参见 统一权限方案：上传、实体匹配、创建、更新、导入、导出分别授权，批次中的每条记录及其关联对象都需要验证数据范围。

1. 目标与交付结果

企业可按文件夹/批次提交日常 WPS 工作文件，系统识别其中的客户、供应商、物料、设备、合同、订单、库存、报工、质检等内容，经过多轮检查与人员补充，形成可预览、可追溯、可恢复的导入方案。

每次导入交付五项产物：原始文件清单与版本关系、字段映射和来源证据、待补充/冲突清单、带依赖顺序的入库计划、逐项执行与核对报告。文件内容存在不确定性时保留原值和候选值；未确认的历史事实不能通过模型推测补齐。

2. 文件范围与解析策略

解析采用“格式结构解析 → 版面/区域识别 → 局部 OCR → 语义映射”。具体解析/转换组件通过真实样本兼容测试后选型，不在设计阶段宣称已兼容所有 WPS 版本。转换服务独立隔离，禁止自动执行宏、脚本或外部数据连接。

保留原始文件不可变副本、文件 hash、原格式、解析器版本及转换产物。文件密码由安全输入流程处理，不写进对话、检查点或日志。失败原因必须具体到“加密”“损坏”“格式不支持”“OCR 不确定”等。

3. 补录对象与边界

以上是目标范围，不表示现有项目已经提供所有历史迁移接口。每类对象通过能力登记返回“可导入 / 仅草稿 / 仅归档 / 需新增业务接口”。HR 薪酬、个人证件等字段仅向授权岗位开放，映射和预览同样受数据权限控制。

4. LangGraph 图设计

在主路由新增 document_onboarding，业务案件以 import_batch_id 为核心，子任务按文件/区域解析，随后在批次层统一消歧和核对。

flowchart TD
    A[建立导入批次与迁移范围] --> B[文件清单 / 去重 / 版本识别]
    B --> C[并行解析文件与表格区域]
    C --> D[识别业务类型与字段映射]
    D --> E[规范化候选记录与字段证据]
    E --> F[主数据匹配 / 跨文件关联]
    F --> G[结构 / 业务 / 数量金额 / 时序校验]
    G --> H{存在阻断问题？}
    H -->|是| I[聚合同类问题与建议]
    I --> J[interrupt 等待确认 / 补文件 / 改值]
    J --> K[应用修订，标记受影响依赖失效]
    K --> F
    H -->|否| L[生成依赖 DAG 与 Java dry-run]
    L --> M[冻结方案版本、影响预览与审批]
    M --> N[interrupt 等待授权执行]
    N --> O[重新核验权限 / 方案 hash / 目标版本]
    O -->|变化| F
    O -->|有效| P[按业务聚合分批幂等导入]
    P --> Q[回读 / 对账 / 完整性验证]
    Q --> R{通过？}
    R -->|否| S[暂停相关链，修复或业务补偿]
    R -->|是| T[归档报告 / 关闭批次]

解析子图按文件独立运行，可并行；匹配、去重和供应/金额汇总在批次范围完成。审批和入库集中在命令执行图，解析节点不直接写业务数据。大文件按稳定分区处理，记录分区进度；检查点保存引用，不保存整本表格或图片。

问题反馈只触发受影响的记录、校验器和下游依赖重新运行。变更单位映射要重算相关数量与金额；变更客户归属要重做权限和关联检查；上传新文件要判断是补充证据还是替代版本。迭代轮数有预算，未解决事项转人工处理；不能为了结束循环自动把警告改成通过。

5. 多轮检查的具体分工

模型复核可以提出遗漏或冲突，但不能替代数量金额核算与 Java 业务校验。审核以独立规则、源文件证据和人工决策为依据；多次模型给出相同答案不代表通过。

6. 字段级证据与暂存模型

每个候选字段保存 raw_value、normalized_value、类型、来源定位、变换规则、提取可靠度、匹配依据与确认状态。表格定位为文件版本/工作表/单元格或区域；文档定位为页码/段落/表格；扫描件保存页码/框坐标。排序或重解析后仍保留原始定位。

候选记录有稳定 candidate_id，与业务 ID 分开；原始行、业务单据头、单据行采用显式分组关系。一个源行可对应多条业务记录，多个源行也可组成一张单据，每次拆分/合并保留转换链。

新增暂存表：

• import_batch：导入模式、切换时点、范围、负责人、当前 revision 与状态。
• import_file_version / import_region：文件血缘、hash、版本关系、解析区域与缓存。
• import_candidate / import_field_evidence：候选对象、字段、来源与变换过程。
• import_entity_match：系统候选、匹配特征、决策与别名适用范围。
• import_issue / import_resolution：问题类型、阻断级别、影响对象、人工补丁与失效状态。
• import_plan / import_plan_item / import_dependency：不可变方案、目标版本、依赖 DAG。
• import_execution / import_record_link：幂等键、业务 ID、源到目标映射、回读结果。

候选记录状态为 待解析 → 待匹配 → 待补充 → 可校验 → 可提交 → 已提交 → 已核实，另有 跳过 / 冲突 / 失败 / 结果未知。文件解析成功不等于候选记录可提交。界面分别统计文件数、源行数、候选对象数、业务单据数和明细行数，避免不同计数混在一起。

7. 复杂情况处理清单

不存在可靠匹配的实体可提议新建，但默认“待新增确认”，不是自动制造物料或客户。缺失法定/财务/追溯关键字段时阻断相关对象；非必填字段可保留空并列入补充清单，不能塞入“默认客户”“默认仓库”掩盖问题。

8. 人工补充与多轮交互

导入工作台采用“源文件证据—候选业务数据—问题与处理”三栏。选择某字段时定位原表单元格或原文区域；批量选择同类问题后可一次确认映射，例如“这些文件里的‘件’均映射成系统单位 PCS”。确认必须限定文件/区域/物料类别等范围，不能无条件扩散到全企业。

提问按影响面优先：先确认导入模式、期间、主体、权威文件，再解决影响大量记录的单位/实体映射，最后处理个别缺失。用户可补文件、修正字段、选择候选、暂缓、跳过或要求人工处理。批量应用前显示影响数量和示例，应用后重跑相关检查。

每次回答成为版本化 ResolutionPatch，包含目标字段/问题、原值、新值、依据、操作者、时间、作用范围与基线 revision。问题可以重新打开；新证据推翻旧决策时标记旧决策过期。金额、数量、历史状态等必须能解释采用哪个来源。

9. 前期上线补录：切换时点与防止重复记账

批次必须选择模式：①主数据初始化；②历史资料归档；③未结业务迁移；④期初余额/库存；⑤日常新增/修订。不同模式有不同允许动作和接口，不共用一个“全量导入”开关。

先确定切换时点 T、组织/仓库范围、业务期间、权威台账和控制总额。T 之前的累计历史与 T 时点余额采用明确迁移策略：若历史收发只作归档，期初库存入账一次；若重建完整交易链，则不得再把相同余额作为额外库存入账。应收应付、在制与未结订单同样处理。

例如历史合同已生成订单且已发部分货，补录合同时不能再次触发“审批通过自动生成销售订单”，也不能重跑销售单生成 MPS、报工倒冲、质检回调和通知。Java 需要明确的迁移入口、迁移权限与受控副作用策略；不支持时仅导入草稿/归档并标记后续待建设，不绕过服务写库。

业务发生时间、原系统创建/审批时间（有证据时）、本次补录时间分别保存。历史审批证据作为附件/来源记录，当前系统操作日志记录真实补录操作者，不能冒充历史人员执行审批。

10. Java 导入协议与执行顺序

现有 MdmItemController 物料导入、CRM 合同导入、ERP 采购申请/采购单导入可作为领域校验与映射参考。它们的模板导入语义不等于通用历史迁移语义；逐项审查 Service 的默认值、自动编号、更新策略、状态推进与自动生成下游单据后再复用。

拟增加内部接口：capabilities 返回支持对象/字段/模式/限制；validate 做无副作用校验并返回引用冲突与副作用预览；plan 冻结执行计划；commit 按方案版本与授权令牌执行；status 按命令号查询；reconcile 回读对账。LLM 仅生成候选 DTO，不能直接调用 commit。

依赖通常为单位/分类/仓库 → 客户/供应商/物料 → 产品 BOM/工艺 → 合同/订单 → 工单/收发/质检等，但最终以对象依赖 DAG 决定，环依赖单独拆解。暂存候选通过 candidate_id 引用，入库后生成候选到真实 ID 映射供下游使用。

以完整业务聚合（单据头+全部行）为原子边界，不逐行提交半张单据。默认一个依赖组失败则阻止下游；无依赖组可选择继续，并在审批方案里明确策略。外部接口返回成功后必须回读验证。

记录幂等键由企业/迁移范围、稳定源记录标识、目标对象、方案版本和动作组成；另设跨批次业务唯一键/内容指纹冲突检测，避免新建批次绕过防重。源记录修改使用显式更新策略与期望目标版本；不能默默覆盖已有人工修改。

提交超时先查询结果。部分成功后只补失败/未尝试项；重试不重新导入成功记录。撤销按业务能力执行：未被引用的草稿可以撤销；已发生库存/资金/下游引用的记录走冲销或受控更正，不能承诺整批硬删除回滚。

11. 对账、验收与实施优先级

提交前后控制总额至少包括对象数、行数、物料数量（按单位分组）、金额（按币种与税口径分组）、库存（按仓库/物料/批次口径）、应收应付/未结数量，以及引用完整率。跨单位/币种不能直接求总和。报告明确可核对、不可核对、人工确认差异及原因。

样本集覆盖：标准表、复杂合并表、扫描件、跨文件冲突、同名实体、重复版本、公式错误、日期/金额歧义、缺少批次、历史已执行单据、同时期初与历史交易、并发修改、执行后断网、部分失败和更正重导。关键事实不得由模型凭空补全；阻断问题未解决不得提交。

交付顺序提升为：A 图运行与暂存/证据底座；B 主数据文件补录闭环；C 合同/采购/销售等业务草稿与未结迁移；D 期初库存及复杂历史迁移；E 与运营九场景联动。复杂历史迁移按实际业务接口成熟度开放，不能为了补录速度绕过审批和库存规则。

上线前需要企业提供脱敏的常用样本与对应正确结果，建立格式兼容集和业务基准集；当前方案不要求先上传文件才能继续技术设计。最终验收看字段准确、实体关联、重复防护、控制总额、人工工作量与恢复能力，分别统计自动确认与人工确认结果。

12. Python 模块增量

graphs/scenarios/document_onboarding.py
graphs/documents/parse.py, resolve.py, review.py, import.py
documents/adapters/       # 格式解析、转换、OCR 的可替换接口
documents/layout/         # 区域、表头、单据分组与来源定位
documents/normalization/  # 日期、金额、单位、编码，保留原始值
documents/matching/       # 实体匹配、跨文件版本和业务关联
documents/validation/     # 结构、业务、算术、跨文件、迁移规则
documents/staging/        # 候选、证据、问题、修订、方案版本
documents/planning/       # 依赖 DAG、dry-run、影响预览
documents/reconciliation/ # 入库回读、控制总额、异常恢复

该能力共享主平台的权限、检查点、命令幂等、审批与事件系统，并独立保存文件解析和候选数据。运营图只有在相应数据已核实入库后，才把它作为实时业务事实使用；未确认候选仅用于补录工作台。