AutoRpa/docs/superpowers/specs/2026-09-13-jieda-rpa-detailed-design.md

福建洁达采购 RPA 详细设计

文档属性	内容
版本	V3.1
日期	2026-09-13
配套概要设计	《福建洁达采购 RPA 概要设计》
状态	设计评审稿；未实施代码或建表
适用范围	接口接收、四条流程执行、状态记录、运维与异常恢复

本文件承接概要设计，规定可供开发、测试和运维执行的表、字段、状态、接口和处理规则。外部正式字段名、节点代码和现场 Oracle 表结构以第 9 章未决事项为准。

**本期范围收敛：**只实现订单接收、平台订单推送、选品、合同、返利四条流程及基本状态记录。版本冲突、内容哈希、执行令牌、文件证据表、复杂事件分类和自动化核验接口不作为本期新增必做项；现场已有能力可以复用，确需新增时另行确认。

4. 详细设计：数据模型

4.1 实体关系和存储位置

flowchart LR
    IF[接口接收记录<br/>RPA_JD_IF_REQ]
    SH[销售接口头<br/>RPA_JD_SALES_H]
    SL[销售接口明细<br/>RPA_JD_SALES_L]
    OH[合同返利共用头<br/>RPA_JD_ORDER_H]
    OL[合同返利共用明细<br/>RPA_JD_ORDER_L]
    J[流程作业<br/>JOB]
    N[作业节点<br/>JOB_NODE]
    E[操作事件<br/>JOB_EVENT]
    A[文件证据<br/>JOB_ARTIFACT]
    P[订单推送台账<br/>JD_ORDER_PUSH]
    IF --> SH
    IF --> OH
    SH --> SL
    OH --> OL
    SL --> J
    OH --> J
    J --> N
    J --> E
    J --> A
    J --> P

图中括号内为数据库表名，前面的中文为业务含义。

本节所有实体均存放在同一套 Oracle 数据库，不再区分接口库、状态库或 MySQL。实体按用途分为三组：

分组	表	作用
接口输入表	RPA_JD_IF_REQ、RPA_JD_SALES_H/L、RPA_JD_ORDER_H/L	保存订单中心传入的原始报文、销售数据及合同/返利共用数据
流程业务表	JOB、JOB_NODE、JOB_EVENT、JOB_ARTIFACT	保存四条流程的作业、节点执行、操作记录和文件证据
订单推送表	JD_ORDER_PUSH	保存平台订单导出后推送订单中心的请求、回执和推送状态

接口输入数据只保存一份。合同和返利通过相同的 INPUT_ID、INPUT_VERSION 关联；两条流程分别在 JOB 中记录自己的状态，不复制两套合同/返利输入表。已有表能承载上述用途时优先复用，只有确实缺少的表或字段才在 Oracle 中新增。图中的关联由主键、外键或业务关联字段实现，具体以现场 Oracle 表结构核对结果为准。

接口表内的合同/返利状态不各写一份。运维总览按 INPUT_ID 汇总两份 job 与其节点，展示三个独立标志：合同保存、链路更新、返利办理。读写来源见第 5 章。

4.2 接收记录 RPA_JD_IF_REQ

一行是一回接收尝试；错误请求也能查到，不能依赖先有 job 才记录。

字段	建议类型	含义与约束
REQUEST_LOG_ID	VARCHAR2(64) PK	本方生成，返回给上游和运维定位
TRACE_ID	VARCHAR2(64)	本次请求关联应用日志
SOURCE_SYSTEM / MESSAGE_ID	VARCHAR2(32) / VARCHAR2(128)	调用方及其请求标识；MESSAGE_ID 格式由对方提供
DATA_TYPE	VARCHAR2(24)	SALES 或 ORDER_COMMON；没有独立 REBATE 接收类型
BODY_HASH	VARCHAR2(64)	规范化业务报文哈希，识别同请求内容是否一致
RECEIVE_STATUS	VARCHAR2(16)	ACCEPTED、REJECTED、DUPLICATE、CONFLICT
ORIGINAL_REQ_ID	VARCHAR2(64)，可空	重复请求关联首次成功记录
RAW_BODY / RESPONSE_BODY	CLOB	实际业务报文和返回内容，不记录鉴权口令
ERROR_CODE / ERROR_DETAIL	VARCHAR2(64) / CLOB	字段路径、明细标识、错误说明
RECEIVED_AT / RESPONDED_AT	TIMESTAMP	收到及生成返回结果的时间
REGISTER_STATUS	VARCHAR2(8)，可空	成功记录的作业登记标志：PENDING、DONE、FAILED；非成功记录为空
REGISTER_ERROR / REGISTERED_AT	VARCHAR2(500) / TIMESTAMP	作业登记失败原因及最终登记时间

RECEIVE_STATUS 表示接收事实，REGISTER_STATUS 仅表示是否已登记作业，均不代表合同或返利完成。成功接收同事务保存接口头明细并置 REGISTER_STATUS=PENDING；脚本取数前补登记，完成后更新 DONE。登记失败在下一次脚本取数重试，无需上游重传。

约束：对 ACCEPTED 记录建立 (SOURCE_SYSTEM, MESSAGE_ID) 条件唯一索引；Oracle 可用 CASE 表达式索引实现。失败/重复尝试保留独立行，不占用成功消息键。索引还包括 (DATA_TYPE, REGISTER_STATUS, RECEIVED_AT)、TRACE_ID、(SOURCE_SYSTEM, MESSAGE_ID)。

4.3 接口头公共字段

销售头和共用订单头均使用以下控制列。

字段	建议类型	用途
INPUT_ID	VARCHAR2(64) PK	本方输入身份，跨流程统一关联
REQUEST_LOG_ID	VARCHAR2(64) FK	首次成功接收记录
SOURCE_SYSTEM / SOURCE_DOC_ID	VARCHAR2(32) / VARCHAR2(128)	上游稳定业务标识；与展示单号分开
SOURCE_DOC_NO	VARCHAR2(128)	业务查询展示用单号
INPUT_VERSION	VARCHAR2(64)	上游版本；未提供时首版用固定 1，变更走第 6.2 节冲突规则
DATA_HASH	VARCHAR2(64)	本对象完整头明细内容哈希
DATA_STATUS	VARCHAR2(16)	READY：成功接收的完整输入；本期不另设待补字段状态
CREATED_AT	TIMESTAMP	成功保存时间

头表唯一键为 (SOURCE_SYSTEM, SOURCE_DOC_ID, INPUT_VERSION)。明细以 (INPUT_ID, SOURCE_LINE_ID) 唯一，关联本头，不以货品编码唯一。成功输入不由 RPA 改写，处理结果记录在 Oracle 业务表中。

4.4 销售接口头明细 RPA_JD_SALES_H / L

表	业务字段	用途
SALES_H	第 4.3 节公共字段、BUSINESS_DATE	一份销售总单
SALES_L	LINE_ID、INPUT_ID、SOURCE_LINE_ID、APPROVAL_NO、PURCHASE_QTY、SALES_PRICE	逐条查询所需批准文号、需求采购数量、销售价格
SALES_L 可选描述	GOODS_NAME、SPEC、MANUFACTURER、UNIT	按上游原值保留供查看，不作为新增属性匹配门槛

LINE_ID 建议 VARCHAR2(64)，数量 NUMBER(18,4)，价格 NUMBER(18,6)，标识/文号 VARCHAR2(128)，描述 VARCHAR2(256)。最终长度和精度按真实接口及目标系统核对。

4.5 合同/返利共用接口头明细 RPA_JD_ORDER_H / L

一份头代表上游明确给定的一组合同及对应返利数据，范围由报文的 SOURCE_DOC_ID 和明细集合确定。首版不按供应商＋日期自行合单。若实际存在一组数据对应多份合同/返利，需要上游给出组标识，见第 12 章。

位置	建议字段	含义/使用流程
ORDER_H	第 4.3 节公共字段	合同和返利共用输入标识
ORDER_H	CUSTOMER_NAME、CUSTOMER_TYPE、CREDIT_DAYS	合同客户名称、预付/账期类型、账期天数
ORDER_H	CONTRACT_SIGN_DATE、CONTRACT_START_DATE、CONTRACT_END_DATE	三个独立合同日期
ORDER_H	SUPPLIER_CODE、REBATE_UNIT_CODE、PLANNER、PURCHASER	返利供应商、返利单位、计划员及采购员对应信息
ORDER_H	CHAIN_REF	订单中心链路/源业务关联；精确结构按正式接口
ORDER_L	LINE_ID、INPUT_ID、SOURCE_LINE_ID、ORDER_NO、SOURCE_DETAIL_ID	本方行 ID、来源行、订单号、货源细单号；订单号与货源细单号分列
ORDER_L	GOODS_CODE、GOODS_NAME、REG_CERT_NO、SPEC、UNIT	标准货品编码/名称、注册证号、规格、单位
ORDER_L	PURCHASE_QTY、PURCHASE_UNIT_PRICE	采购数量和单价；用于合同明细
ORDER_L	REBATE_QTY、REBATE_TAX_PRICE	返利数量和含税协议单价；用于返利明细
ORDER_L	PAYMENT_CONDITION，可空	实际合同模板需要时从同一报文提供

同一次报文中数量如只有一个来源字段且供两流程共用，映射层同时引用它；不因此要求上游重复传两个数量。采购单价与含税协议单价按 Excel 的不同含义分别映射，未经接口确认不互相代替。

建议数量 NUMBER(18,4)、价格 NUMBER(18,6)、金额 NUMBER(18,2)、日期 DATE；名称 VARCHAR2(256)、编码 VARCHAR2(128)、类型 VARCHAR2(16)、账期 NUMBER(6)、CHAIN_REF CLOB 或按正式关联键拆列。固定默认值不强迫订单中心传入，在节点执行输入中生成并记录所用模板/映射版本。

此处没有 RPA_JD_CONTRACT_HEAD / RPA_JD_REBATE_HEAD 两套输入表。两流程取数的 INPUT_ID 必须相同。

4.6 业务作业与节点记录

表/字段	现有或新增	详细用途
job.flow_code / flow_version	新增 VARCHAR(24) / VARCHAR(16)	旧作业归原主链，新作业区分四条流程
job.input_id / input_version	新增 VARCHAR(64)	指向 Oracle 成功输入；ORDER_PUSH 指向本方导出批次 ID
job.source_line_id	新增 VARCHAR(128)，头级作业用空串	PROCURE 对应一条销售明细；合同/返利对应头
job.business_key	复用	改为上述来源关联的展示/定位键；防重以组合唯一约束为准
job.status / current_node_code	复用	当前执行状态和恢复节点
job.contract_system_no / rebate_order_no	复用	合同 job 保存合同号，返利 job 保存返利总单/协议编号
job.next_check_at	复用	可重试失败或外部等待的下次处理时间
job.execution_token / execution_host	本期不新增	如现有状态中心已有执行占用机制则继续复用，否则按单实例运行约束处理
job_node.attempt_no、status、output_json	复用	每次尝试独立记录；输入引用、业务结果和外部编号
job_node.started_at / ended_at / duration_ms	复用	操作开始结束及耗时
job_node.error_code / error_summary	复用	可筛选错误分类和具体原因
job_node.executor_run_id / callback_idempotency_key	复用	一次脚本运行 ID、稳定回报键，重发回报不重复推进

本期按 (flow_code, input_id, source_line_id) 识别同一流程作业；已有系统若必须保留版本字段，可作为可选扩展，不因规则升级自动创建第二份作业。

共用数据成功接收后登记两份 job：CONTRACT 初始 PENDING，REBATE 初始 WAITING_EXTERNAL，原因为 WAIT_CONTRACT。同一 Oracle 输入即便登记调用重复，也只建立这一对作业。一次接收多组业务对象则逐头建立，不共享一个总完成标志。

旧列兼容迁移：保留 job_id、business_key、source_type、current_node_code、status、created_by 非空；supplier_name 和 order_date 改为允许空值，新来源数据有值时填入。旧入口继续校验其原必填，不给新作业补造供应商或日期。business_key 由新唯一键各项组合生成可读/哈希值；created_by 记录业务启动人或计划任务账号。

flow	source_type	supplier_name / order_date	首节点
PROCURE	本方定义 ORDER_CENTER	供应商为空；日期取销售业务日（若提供）	PROCURE_ITEM_RUN
ORDER_PUSH	明确的平台配置代码	文件批次可含多供应商，供应商为空；日期不强制单日	ORDER_EXPORT_FILE
CONTRACT / REBATE	ORDER_CENTER	接口明确提供的展示供应商及业务日期；合同三个日期仍取接口独立字段	CONTRACT_CREATE / REBATE_HEADER

source_type 上述取值是本方分类建议；药帮忙使用单独配置代码，不映射成旧 XYY。若任一新增标识超出现有列长度，迁移时扩列。旧 job 赋旧 flow/version 及唯一 input_id，新组合唯一键对全部历史行先回填再建立。

4.7 逐订单推送记录 JD_ORDER_PUSH（按现有表复用，缺少时再新增）

文件/操作日志不能替代按订单查询的处理标志，因此该表只保存推送控制与结果，不复制完整平台业务表。

字段	建议类型	用途
id	BIGINT PK	推送记录 ID
platform / account_key / source_order_id	VARCHAR(32) / VARCHAR(64) / VARCHAR(128)	来源订单唯一键，不按文件名去重
source_order_no / job_id / artifact_id	VARCHAR(128) / VARCHAR(64) / BIGINT	展示单号、首次导出 job、原始文件关联
content_hash / request_key	VARCHAR(64) / VARCHAR(128)	订单内容识别和本次固定请求标识
push_status	VARCHAR(16)	PENDING、SENDING、ACCEPTED、REJECTED、UNKNOWN
request_body / response_body	JSON	本次实际结构化发送内容、返回内容或所属批次引用
receipt_no / error_code / error_message	VARCHAR(128) / VARCHAR(64) / VARCHAR(500)	回执及失败原因
attempt_count / next_retry_at	INT / DATETIME	发送次数及重试时间
created_at / last_sent_at / accepted_at	DATETIME	关键时点

唯一键 (platform, account_key, source_order_id)；相同订单相同内容复用结果，内容变化不能覆盖旧成功记录，记录冲突交运维核对。每次发送详细历史写 job_event，最近状态保存在此表。多个文件含同一订单时，在各导出 job 的日志中记录对应 artifact_id 与台账 id。

接口若支持批量发送，固定请求键绑定整份实际请求体；同键重发内容不变。逐单成功的回执更新对应台账；只发失败子集时生成新请求键并保留与原批次关联。没有逐单回执时按对方整批接收语义记录，不凭本方猜部分成功。

5. 详细设计：标志字段与取数条件

5.1 状态来源

业务标志	保存/计算位置	何时改变
接收是否成功	IF_REQ.RECEIVE_STATUS	当前接收请求完成时
作业是否登记	IF_REQ.REGISTER_STATUS	在 Oracle 中幂等建立本次所需 job 后
选品处理结果	PROCURE job_node.output_json.result	加购或正常跳过回报时：ADDED / SKIPPED
合同保存状态	CONTRACT_CREATE 节点状态及 result	开始、保存成功、失败或结果未知回报
链路更新状态	CONTRACT_CHAIN_UPDATE 节点状态及 result	合同保存后调用订单中心，单独记录结果
返利状态	REBATE job.status / current_node_code	等合同、执行、失败、提交成功
平台订单接收状态	JD_ORDER_PUSH.push_status	每次发送和回执记录

运维接口返回 contract_save_status / chain_update_status / rebate_status 三列，是以上权威记录的汇总字段，不再写回接口表形成第二套状态。当前节点按 job 指针及该节点最新 attempt 取值，历史成功节点保留，不用整个合同 job.status 代替保存状态。

5.2 状态转换

job 状态	含义	后续动作
PENDING	已登记，等待执行	对应脚本领取
RUNNING	已被领取且正在执行	接收匹配 execution_token 的回报
SUCCESS	本流程应做步骤完成	常规取数不再领取
FAILED_RETRYABLE	明确失败，可重试当前步骤	到 next_check_at 后或运维重试，新增 attempt
WAITING_EXTERNAL	前置尚未完成或结果待核对	按 wait_reason 处理，不能一律自动重做
WAITING_USER / FAILED_MANUAL	业务或运维需介入	在原待办上处理、核对并记录动作
CANCELLED	明确停止办理	保留原数据和历史

wait_reason 建议保存在 job 新增 VARCHAR(32) 字段：WAIT_CONTRACT、PROTOCOL_NOT_READY、RESULT_UNKNOWN。前两种下次检查条件；RESULT_UNKNOWN 需要核对外部结果，确认失败才可重试。

节点复用 PENDING/RUNNING/SUCCESS/FAILED，未知结果用节点 WAITING_EXTERNAL 并在 output_json 记 result=UNKNOWN；需要新增相应前后端状态支持。未尽调转人工保留待办，不能把“停止自动办理”显示为“合同已保存”。

stateDiagram-v2
    [*] --> PENDING
    PENDING --> RUNNING: 领取
    RUNNING --> SUCCESS: 完成
    RUNNING --> FAILED_RETRYABLE: 明确可重试失败
    RUNNING --> WAITING_EXTERNAL: 前置等待或结果未知
    RUNNING --> WAITING_USER: 业务处理
    FAILED_RETRYABLE --> PENDING: 重试当前步骤
    WAITING_EXTERNAL --> PENDING: 前置满足或核对未成功
    WAITING_EXTERNAL --> SUCCESS: 核对本流程已完成
    WAITING_USER --> PENDING: 处理后恢复未完成步骤
    PENDING --> CANCELLED: 停止办理

中文对照：PENDING=待执行，RUNNING=执行中，SUCCESS=成功，FAILED_RETRYABLE=可重试失败，WAITING_EXTERNAL=等待外部结果，WAITING_USER=等待人工处理，CANCELLED=已取消。

上图为通用 job 状态。合同保存结果核对成功时若链路尚未更新，实际转移到链路节点 PENDING，不能直接标整个合同 SUCCESS。

5.3 领取规则

flow	读取范围及条件	成功/失败记录
PROCURE	SALES 数据 READY；分别按 1 号药城、药帮忙的平台配置领取；行 job=PENDING，或到期可重试	两个平台使用同一套采购条件；合格 ADDED、不合格 SKIPPED 均结束行 job；错误单独失败
ORDER_PUSH	对应平台导出任务及历史未完成台账；ACCEPTED 不重发	归档文件及每单 push_status
CONTRACT	ORDER_COMMON 数据 READY；合同 job 待执行，按 current_node 恢复	CREATE 成功保存合同号；CHAIN 失败只重试 CHAIN
REBATE	同 INPUT_ID/版本的 CREATE 节点确认 SUCCESS，合同号非空；返利待执行或到期重试	从共用接口表读取返利字段；读取合同 job 合同号；提交后 SUCCESS

新录入与重试均覆盖历史未完成记录，不只筛选当天。创建返利 job 时可处于 WAIT_CONTRACT，合同失败不改它的接口输入；合同成功后，返利下一次扫描将其转 PENDING。

领取使用现有状态中心的领取机制；同一条记录同一时刻只允许一个脚本处理。脚本中断后由运维确认并恢复，不自动启动第二个执行器。

5.4 节点定义与订单导出生命周期

flow	节点链	正常结束条件
PROCURE	PROCURE_ITEM_RUN	本行 ADDED 或 SKIPPED
ORDER_PUSH	ORDER_EXPORT_FILE → ORDER_CENTER_PUSH	文件完整归档后，解析及推送该批应发送订单，均确认接收
CONTRACT	CONTRACT_CREATE → CONTRACT_CHAIN_UPDATE	保存及链路更新分别成功；未尽调为当前节点人工待办，不另建供数流程
REBATE	REBATE_HEADER → REBATE_IMPORT → REBATE_SUBMIT	正常提交成功；首次领取前检查合同保存条件

ORDER_PUSH 脚本先领取历史未完成批次；再按当前排期需要产生 export_batch_id 并登记新 job（input_id=export_batch_id，input_version=1，source_line_id=空串）。新 job 从 ORDER_EXPORT_FILE 领取执行。导出失败保留该 job；已保存文件和路径写 job_artifact，node_code=ORDER_EXPORT_FILE，恢复时先查已有归档文件。

归档成功后推进 ORDER_CENTER_PUSH：解析文件、按源订单建立/复用 JD_ORDER_PUSH、保存固定请求并推送。本批所有源订单到台账 ID 的关联写入该 job 的节点 output_json（大批量可用 artifact 保存清单），因此同一台账复用于多个文件时仍可判断每个批次是否完成。首次 job_id/artifact_id 不覆盖，后续文件关联由各批次记录持有。

源订单均为 ACCEPTED，或本轮确无可推送订单时，批次 job SUCCESS；零数据结果记 NO_DATA 并显示零条，不创建空订单。部分失败保留当前推送节点，已接收项跳过；同订单不同内容记冲突，阻止该批盲目完成，交运维核对。脚本退出与该批次 job 成功是两件事。

6. 详细设计：接口与交互时序

6.1.1 平台订单推送中的对码原始数据

平台订单推送给订单中心时，RPA 不传本方判断出的货品编码作为对码结论，而是传订单中心完成判断所需的原始订单信息。每条订单明细至少需要保留并按正式接口字段映射传递：

数据组	建议字段	用途
来源标识	平台代码、平台账号、源订单号、父订单号（如有）、源订单明细号、导出批次号	订单中心识别来源、拆单/明细及幂等关系
商品原始信息	平台商品编码（如有）、平台品名、批准文号、通用名/商品名称、规格、生产厂家、单位	订单中心进行货品对码；平台没有的字段传空并按接口规则处理
采购信息	实际采购数量、采购单价、订单金额、订单日期、订单状态	形成标准采购订单并供后续合同数据使用
商家及追溯	平台商家/供应商原始标识、仓库、文件名、文件哈希、原始行号	追溯和订单关联；文件信息作为来源追踪，不替代业务订单键

其中，批准文号、平台品名、通用名/商品名称、规格、生产厂家、单位属于“给订单中心判断用的原始值”，不代表 RPA 已经完成对码。平台订单接口的正式必填字段、字段名称、枚举和缺项规则由订单中心确认；不能只传一个批准文号、数量和金额就宣称对码数据完整。

订单中心处理后至少应能按源订单号/源明细号返回或在合同共用接口数据中提供：标准货品编码、标准货品名称、注册证号、规格、单位，以及合同/返利所需的采购数量、单价、货源细单号等字段。返回方式可以是订单接收后的后续推送或双方约定的查询接口，但必须保持与源订单明细的关联。本方只使用该标准结果填合同和返利，不在本地补做对码。

6.1 接口清单

接口/方向	状态	主要契约
POST /api/jieda/inbound/sales	本方拟新增	完整销售对象，接收校验后落表
POST /api/jieda/inbound/order-data	本方拟新增	一次传入合同及返利共同需要的数据，返回接收记录 ID 和 INPUT_ID
POST /api/flows/{flow_code}/jobs/claim	复用或按现有方式实现	按流程领取待处理作业并返回输入关联
POST /api/flows/ORDER_PUSH/jobs	本方拟新增	导出前按 export_batch_id 幂等登记平台/账号/范围及 job，导出失败也有作业可查
GET /api/jobs/{job_id}/input	本方拟新增	对应接口头明细；返利额外返回关联合同 job 及合同号
POST /api/jobs/{job_id}/nodes/{node}/{action}	复用 start/complete/fail	保存结果、编号和错误原因
POST /api/jobs/{job_id}/push-records	按现有回报方式实现	保存订单推送结果；不强制新增独立接口
POST /api/jobs/{job_id}/retry	复用并修正	只恢复当前失败步骤，记录操作者及原因
平台订单接收 API（本方→订单中心）	外部契约待提供	来源订单、对码原始字段、数量金额及实际接收回执
链路节点更新 API（本方→订单中心）	外部契约待提供	来源链路关联、对应节点、已保存合同标识及业务结果

订单推送由 ORDER_PUSH 脚本、链路更新由 CONTRACT 脚本通过统一客户端调用。调用前通过状态中心记录固定请求，调用后保存回执。状态中心不同时后台发送同一请求。外部正式路径、业务枚举和鉴权由订单中心提供。

6.2 请求、校验及重复处理

接收报文在本方适配层统一表示为 message_id + objects[]。每个对象有 source_doc_id、input_version（可选）、header、lines。ORDER_COMMON 的 header/lines 包含第 4.5、7 章共同字段，不是分别推 contract 和 rebate。

返回情况	本方建议 HTTP	业务返回及持久化
缺字段/格式不合法/空明细	422	REJECTED，errors 含对象标识、行标识及字段路径；无业务头明细
全部校验通过且保存成功	200	ACCEPTED、request_log_id、input_ids；表示接收成功
已接收同消息同内容	200	DUPLICATE，返回原 input_ids，另记接收尝试
已接收同标识不同内容	409	CONFLICT，旧成功输入及作业不变
保存失败	503	STORE_FAILED＋trace_id；不返回接收成功
鉴权失败	401/403	拒绝，不建立业务作业

首版整次请求校验通过后，同一个 Oracle 事务保存成功接收记录及全部对象头明细。任一必填缺失则整次失败，返回全部可识别字段错误；上游可按完整单据分批发送。缺的是返利字段也当次返回，因为这一份数据承担两个流程。

客户类型、三个合同日期、合同明细字段，以及供应商/返利单位/计划员/订单号/货源细单号/含税协议单价在本次共用数据中按第 7 章校验。合同号是本方执行结果，接收时允许不存在。固定值、系统生成字段、页面尽调回显不要求上游提供。

相同业务对象换 message_id 再传，由头表来源＋版本唯一键识别：内容相同引用原 INPUT_ID，内容不同冲突。没有源版本号时，哈希只判断内容同异，不自动判定“哪条更新”。已成功接收的同 SOURCE_DOC_ID 改内容或改版本，本期返回 INPUT_CONFLICT，不自动创建第二组合同/返利 job；这是按业务标识检查，不能仅依赖版本唯一索引。运维和订单中心确认改单处理后再另行安排，原作业和结果保持可查。此前校验失败的修正重传可正常接收。

接收失败日志存 IF_REQ；Oracle 本身不可用时只能写应用错误日志和 trace_id，不能宣称数据库必有失败记录。响应在事务提交后产生；若响应丢失，上游重传可取得原接收结果。

6.3 时序图：订单中心接收共用数据

订单中心推送完成后只表示本方已接收并保存数据，合同、返利由各自排期执行。

sequenceDiagram
    participant OC as 订单中心
    participant API as 接口服务
    participant ORA as Oracle
    OC->>API: 推送合同返利共用数据
    API->>API: 校验必填字段
    alt 校验失败
        API->>ORA: 保存失败记录
        API-->>OC: 失败及字段位置
    else 校验通过
        API->>ORA: 保存接口数据
        ORA-->>API: 返回 INPUT_ID
        API-->>OC: 返回接收成功
    end

6.4 时序图：平台订单导出并推送

sequenceDiagram
    participant R as 订单脚本
    participant P as 采购平台
    participant F as 共享文件夹
    participant OC as 订单中心
    participant ORA as Oracle
    R->>P: 导出订单文件
    P-->>R: 返回订单文件
    R->>F: 保存平台订单文件
    R->>ORA: 保存文件和订单记录
    R->>OC: 推送订单及对码原始字段
    alt 接收成功
        OC-->>R: 返回接收结果
        R->>ORA: 保存推送成功
    else 保存失败或接口失败
        R->>ORA: 保存失败原因
    end

订单中心接收平台订单和对码原始字段，订单中心内部完成对码，并在后续共用数据中提供标准货品结果。

6.5 时序图：合同排期处理

sequenceDiagram
    participant C as 合同脚本
    participant ORA as Oracle
    participant CT as 合同系统
    participant OC as 订单中心
    C->>ORA: 按合同排期领取待处理数据
    ORA-->>C: 返回共用数据
    C->>CT: 录入并保存合同
    CT-->>C: 返回合同号
    C->>ORA: 保存合同号和合同结果
    C->>OC: 更新订单链路
    OC-->>C: 返回链路结果
    C->>ORA: 保存链路结果

合同保存和链路更新分别记录。链路失败时保留合同号，后续只重试链路更新，不重新创建合同。

6.6 时序图：返利排期处理

sequenceDiagram
    participant R as 返利脚本
    participant ORA as Oracle
    participant RB as 返利中心
    R->>ORA: 按返利排期领取待处理数据
    ORA->>ORA: 检查同 INPUT_ID 的合同结果
    alt 合同未保存成功
        ORA-->>R: 暂不处理，保留等待状态
    else 合同已保存且合同号存在
        ORA-->>R: 返回共用数据和合同号
        R->>RB: 查询协议并提交返利
        RB-->>R: 返回办理结果
        R->>ORA: 保存返利结果
    end

四张图之间的关系是：第一张完成数据接收，第二张完成平台订单推送，第三张和第四张由各自排期独立运行。合同和返利通过同一个 INPUT_ID 关联。

7. 详细设计：业务字段映射

本章保留 Excel 的实际字段和行号。合同/返利列来源都指向第 4.5 节同一份接口输入；按各自模板生成执行数据。生成的模板、默认日期及映射版本记录到节点 output_json/文件证据，不再复制成独立合同或返利输入表。

7.1 合同头

目标字段	取值规则	行号
客户名称	订单中心	12
客户编码	目标系统自动生成	11
尽调情况	读取回显；未尽调停止本单自动录入并转采购员处理	13
结算类型	收支双向	15
合同版本类型	预付：我司定制；账期：非格式合同	17
合同金额（单位元）	预估本次合作金额	24
金额（元）	明细汇总；与导入后页面汇总核对并回填	25
合同签订日期、合同开始日期、合同结束日期	订单中心分别提供，三个独立字段	26–28
是否重大合同	否	29
是否预付款	预付：是；账期：否	30
付款方式	电汇	32
付款期限	预付：1；账期：订单中心账期天数，缺失不默认 30	33
合同具体分类	国内药品类、器械类品种	37
运输方式	公路运输	39

7.2 合同明细

目标字段	来源/规则	行号
货品编码	订单中心	43
货品名称	订单中心标准货品名称	44
注册证号	订单中心	46
规格、单位	按订单中心标准字段填报	47–48
数量、单价	按订单中心最终采购数量、单价填报	49–50
付款方式	电汇	52
付款条件	订单中心；模板无此字段时不填	53
付款期限	同合同头规则	54

7.3 返利总单

目标字段	来源/规则	行号
返利合约	否	5
供应商编码	订单中心	6
返利单位编码	订单中心	7
计划员	订单中心，按业务给定的计划员/采购员对应关系填写	8
采购结算方式	文案“否”；与细单代码 3 分别映射	9
承付模式	下月 N 号结	10
协议开始日期、协议结束日期	当天	11–12

7.4 返利细单

目标字段	来源/规则	行号
货品编码、数量、含税协议单价	本次共用接口数据的货品编码、数量及含税协议单价	15–17
税率、关税税率	均为 0.13	18–19
承付模式、承付参数	11、25	20–21
细单开始日期	当天	22
细单结束日期	本年度最后一天	23
采购结算方式	3	24
特定补偿预估值、进货补偿预估值	均为 0	25–26
细单备注	订单中心订单号	33
货源细单ID	订单中心货源细单号；与订单号分列	34

合同明细导入列按 Excel 的 Sheet3。表中标注无需填写的字段不填；系统自动生成字段由系统处理。

7.5 映射与运行日期规则

• 合同与返利的数量来自同一次报文；实际只提供一列数量时共用该列。含税协议单价与采购单价分别保留来源映射。
• 首次执行该流程时生成所用默认日期及模板记录。重试已生成的相同步骤使用原输入，避免跨日重试更改已导入单据；新返利作业按返利首次执行当天生成“当天/年底”。这是实现规则，不增加业务确认步骤。
• 合同客户编码为系统生成字段。现有 RPA 入口要求的 customerCode 实际用作客商搜索标识，须与系统自动生成的客户编码分清；按新页面取数方式适配，不要求上游为自动生成字段填占位符。
• 映射表标注无需填写的字段不填。尽调读取页面回显；未尽调按原流程转采购员并通知。接口数据保留，人工完成后核对实际合同号并登记保存成功，进入链路更新步骤；返利按第 5.3 节条件领取。

8. 详细设计：操作记录与一致性

8.1 最少需要记录的操作信息

场景	保存位置	必须能查到的信息
每次接口接收	IF_REQ	请求时间、来源消息、INPUT_ID 关联、原报文、返回结果、字段错误、trace_id
脚本执行一步	job_node	flow、job、INPUT_ID/版本、节点、attempt、run_id、执行机、开始结束、结果、错误
平台订单发送一次	JD_ORDER_PUSH＋job_event	原文件、源订单、固定请求键、实际请求、HTTP/业务返回、耗时、成功/拒绝范围
合同保存	job_node＋job_artifact	实际合同标识、保存确认、目标页面证据、所用输入和模板
链路调用一次	job_event＋链路 job_node	链路关联、节点代码、合同号、请求键、报文、回执、错误
运维操作一次	job_event / user_task	操作人、时间、动作、原因、前后状态、证据和操作结果
文件	job_artifact	原始订单、导入模板、截图或日志文件路径，文件类型及哈希

job_event 建议事件类型包括 INPUT_BOUND、NODE_STARTED、NODE_SUCCESS、NODE_FAILED、API_REQUEST、API_RESPONSE、RETRY_REQUESTED、RESULT_VERIFIED、MANUAL_HANDOFF、JOB_FINISHED。detail_json 保存结构化信息。节点列表用 job_node.error_code/error_summary 筛选及展示；事件详情从 detail_json.errorCode/errorMessage 读取错误，不假定 job_event 存在独立错误列。详细错误与报文在详情展开。

接收失败没有 job 时由 IF_REQ 独立展示；所有能定位到作业的动作都写 job_event。脚本运行 ID 使用现有 executor_run_id；无数据或启动失败的本轮摘要写应用日志，通过 run_id 查询，暂不新增运行历史表。

8.2 事务及恢复顺序

写入过程	事务范围	恢复办法
接收成功	Oracle：成功请求记录＋所有接口头明细	事务失败整体返回失败；响应丢失可同消息重传
登记作业	Oracle：同输入的合同和返利 job 一起幂等建立	成功后回写 IF_REQ.REGISTER_STATUS；回写失败下次重复登记返回同 job，再补 DONE
节点成功	Oracle：该 attempt 成功＋业务编号＋操作日志/证据索引＋推进当前节点	回报丢失重发同完成键；同成功结果返回原状态，不再次推进
外部接口调用	先 Oracle 保存请求，事务提交后调用，返回后独立事务记结果	超时保留 UNKNOWN，不把网络调用放在数据库事务中
人工恢复	Oracle：核查结果、状态变更和操作日志	同一操作请求 ID 重复提交返回原结果

接口输入和业务执行结果均在 Oracle 中保存，登记、领取、结果回报使用同一数据库事务边界；外部接口调用仍在事务提交后执行。接口表登记失败时可再次幂等登记，组合唯一约束保证不多建合同/返利作业。

8.3 文件和配置

1 药城与药帮忙分别配置共享根目录和字段映射；现场路径由配置提供。下载完成后发布文件，文件名按批次区分，保留原件。后台返回文件列表，业务/运维通过现有证据入口打开或下载，不要求共享盘在所有机器使用同一盘符。

订单中心连接、凭据、超时、链路节点映射、四条排期、重试间隔及模板配置集中管理。真实环境缺必要配置返回明确错误，不自动使用 fixture。日期、数量和金额按第 4、7 章数据类型保存，日志不保存 token 或数据库密码。

9. 详细设计：正常路径与异常处理

9.1 正常路径示例

本例标识仅用于说明字段关系，不代表正式接口报文。

时间/动作	接口记录	合同保存	链路更新	返利	记录位置
接收 M001	ACCEPTED，INPUT_ID=I001，REGISTER=PENDING	未登记	未登记	未登记	IF_REQ＋ORDER_H/L
任一相关脚本启动登记	REGISTER=DONE	PENDING	未开始	WAIT_CONTRACT	两个 job 都绑定 I001/1
合同脚本处理	原输入不变	RUNNING	未开始	WAIT_CONTRACT	CREATE 第 1 次尝试
合同保存成功 HT001	原输入不变	SUCCESS	PENDING	可领取	合同号及保存证据
更新链路成功	原输入不变	SUCCESS	SUCCESS	可领取	链路请求、回执；合同 job 完成
返利下次运行	原输入不变	SUCCESS	SUCCESS	RUNNING	读取 I001 同一头明细＋HT001
返利提交完成 FL001	原输入不变	SUCCESS	SUCCESS	SUCCESS	返利编号、模板及提交结果

9.2 异常矩阵

异常代码（建议）	识别条件	状态和保留内容	处理及恢复位置
INPUT_REQUIRED	本次共用数据缺合同或返利上游必填	IF_REQ=REJECTED，字段路径/行号，无业务输入	上游补齐后重传；RPA 无需处理
INPUT_CONFLICT	成功来源/版本再传不同内容	CONFLICT，关联旧请求、保存新原文	核对来源及版本；不覆盖已使用数据
STORE_FAILED	接口表事务失败	返回 503；应用日志 trace_id	修复数据库后重传
JOB_REGISTER_FAILED	Oracle 已接收，作业登记失败	REGISTER=FAILED、原因；输入 READY	修复数据库或服务后，下一次脚本取数补登记
PLATFORM_QUERY_FAILED	页面打不开或查询报错	行 job 明确失败，截图/错误	修复后重试该行；不记 SKIPPED
NO_ELIGIBLE_PRODUCT	查询成功但不满足采购条件	job SUCCESS，result=SKIPPED、原因	正常结束，常规轮询不重复处理
FILE_SAVE_FAILED	共享目录不可写/文件未完整	ORDER_PUSH 失败、已知路径	修复目录后从导出/归档失败处继续
OC_ORDER_REJECTED	订单中心明确业务拒收	push=REJECTED，拒绝原因及范围	修正接口映射/源数据后处理失败单，成功单保留
EXTERNAL_RESULT_UNKNOWN	加购、保存、推送或提交后无确定结果	WAITING_EXTERNAL/UNKNOWN，请求或页面证据	先核对目标结果；确认未成功才重试
CONTRACT_DUE_DILIGENCE	合同页面显示未尽调	WAITING_USER、采购员待办和页面记录	按原业务人工处理，核验保存结果后继续链路
CHAIN_UPDATE_FAILED	合同已保存，链路明确失败	CREATE 成功；CHAIN 失败、回执	下次仅重试 CHAIN；合同号不清空
PROTOCOL_NOT_READY	已有合同号，但返利协议不可查/暂不可操作	返利 WAITING_EXTERNAL，原因及检查时间	到期再查协议；不重建合同，不等第二次供数
REBATE_SUBMIT_FAILED	返利系统明确提交失败	失败步骤、目标协议/总单、已导入信息	按原业务交人工处理；保留前面成功步骤
EXECUTOR_INTERRUPTED	作业仍 RUNNING，进程已退出	执行机/run_id、最近节点、证据	运维确认无运行进程并核对结果后，恢复当前步骤

所有正常失败恢复保留原 INPUT_ID、job 和历史 attempt。通用“重试”只增加当前失败节点尝试，不把 job 从第一个节点重新执行。已完成外部写入不能仅凭“失败”按钮反向当作没有发生。

10. 运维设计：如何查看与处理

10.1 查询入口及页面内容

复用现有列表、节点详情、时间线、待办和证据组件，新增接收列表和“同一输入的合同/返利总览”，不用另建运维平台。

页面	筛选条件	列表/详情内容
接口接收列表	时间、来源单号、MESSAGE_ID、TRACE_ID、接收状态、登记状态	请求/返回原文、缺字段路径、INPUT_ID、重复来源、登记失败原因
合同返利总览	INPUT_ID、来源单号、合同号、返利号、三个业务状态、时间	同一行显示合同保存、链路更新、返利状态及最近错误；点击进入各 job
作业详情	flow、job_id、状态、执行机、run_id	来源输入、当前节点、每次尝试、耗时、错误、回报、外部编号
订单推送列表	平台/账号、订单号、导出批次、push_status	原文件、发送内容、回执、次数、结果未知/拒收原因
操作和证据	job/INPUT_ID、操作者、动作时间	谁点击重试/人工处理，前后状态、原因、截图、模板及日志

“合同返利总览”由后端以 Oracle INPUT_ID 为基底，关联两份 job/节点结果；不存在 job 时显示未登记。分页/筛选由后端实现，不要求浏览器一次拉全表。

10.2 典型查看路径

运维问题	如何查	结论/下一步
订单中心说推过，RPA 没处理	先查 MESSAGE_ID/来源单号的接收记录	REJECTED 看缺字段；ACCEPTED＋登记失败看数据库错误；DONE 看对应 job
合同存在，为什么流程显示失败	总览看合同保存和链路更新两列	保存成功/链路失败只补链路调用，不重建
返利为什么一直没开始	看同 INPUT_ID 的合同保存结果及返利 wait_reason	合同未保存则正常等待；保存成功但协议不可查则按目标状态处理
同一批有的成功有的失败	订单推送按源订单筛选，选品按行 job 查看	重试失败项；已接收/已加购项不重复处理
数据被改过或重复推过	接收尝试记录＋DATA_HASH＋操作日志	明确首次输入、重复/冲突报文及处理人

10.3 运维动作及权限

动作	允许条件	实际改变	必须留痕
重试当前步骤	FAILED_RETRYABLE，且外部结果已明确	当前节点新增 attempt，job 转 PENDING	操作人、原因、旧状态、新 attempt
重新登记作业	已 ACCEPTED 且 REGISTER≠DONE	幂等补建缺失 job，完成登记标志	接收记录、结果、操作者
核对结果：已成功	UNKNOWN 或人工完成，提供实际业务编号/回执证据	确认对应节点成功并推进；合同保存后仍执行链路	目标编号、证据、核对人和时间
核对结果：未成功	确认目标未写入，原执行进程已停止	转可重试当前步骤	核对依据、操作者、原因
转业务处理	业务错误或系统要求人工	创建/复用现有 user_task，保存责任人	原因、接收人、操作记录
停止办理	有明确业务指令	CANCELLED，保留已产生结果	原因及外部已发生操作，不自动撤销外部单据

只读运维可看列表及证据；恢复动作限定 OPS，业务待办按采购员等现有角色处理。恢复入口必须核对实际操作者身份，不能只相信请求体里填写的 operator。沿用现有鉴权方案补动作权限，不另加业务审批流。

不能用“统一确认并继续”替代所有核对动作，不能直接改接口原始字段或数据库状态。金额、货品等源数据错误由订单中心修正重传；已被使用的输入按冲突规则处理。

10.4 查询 API 及日志定位

API（建议）	用途
GET /api/jieda/receipts、/receipts/{request_log_id}	无 job 的失败接收也能查
GET /api/jieda/orders、/orders/{input_id}	同一输入的合同/链路/返利总览及头明细
GET /api/jieda/order-pushes	按源订单查推送及文件
现有 GET /api/jobs/{job_id}、/timeline、/evidence-package	节点、历史尝试和证据
GET /api/jobs/{job_id}/events（新增）	操作日志和出站请求/返回记录
POST /api/jieda/receipts/{id}/register（新增）	运维手动补登记，与脚本取数复用同一逻辑
POST /api/jobs/{job_id}/verify-result（新增）	按第 10.3 节核对 UNKNOWN/人工结果，记录依据后恢复

应用日志统一携带 trace_id、input_id、job_id、flow_code、node_code、attempt_no、run_id 中当前已知项。接收阶段没有 job_id 时不编造；执行阶段没有 HTTP trace 时以 job/run 定位。列表展示最近错误，详情保留全部历史，不只覆盖最后一次失败。

索引建议：接口记录按时间/状态/来源，业务头按源单号，job 按 (flow_code,status,next_check_at) 和 (input_id,input_version)，节点按现有 (job_id,node_code,attempt_no)，事件按 (job_id,created_at)，推送按来源唯一键及 (push_status,next_retry_at)。

11. 实施影响与验收

11.1 现有代码到新设计的映射

现有位置	已核对现状	实施改动
main.py 建单	供应商＋日期键，固定首节点，只复用未完成作业	新接收/登记/领取按 flow 和 INPUT_ID；已完成作业也防重
schema.sql	job 无 flow/input 关联；已有节点、日志及证据表	第 4 章 Oracle 接口表及推送台账；job 扩展字段/索引，supplier_name/order_date 允许空；job_event 错误保存在现有 detail_json
db.py	当前数据库访问实现	按 Oracle 驱动和事务方式调整登记、领取、结果及推进
main.py 完成回报	保存节点、编号和推进分步执行；节点定义全局固定	同事务回报，校验 execution_token/attempt；按 flow 定义完成规则
main.py 重试	已保留 attempt 历史、重试当前节点	保留机制，支持共用输入关联及 UNKNOWN 核对
main.py 人工提交	通用确认可直接推进；RETRY_CURRENT_NODE 分支当前只记录事件	按第 10.3 节校验结果和动作，实现真实重试及核查恢复
agent.py	通用代理主要调用 mock；存在节点硬编码与默认 attempt=1	四条独立入口、真实 runner、领取结果中的 attempt/token
contract_create_node.py	已校验空明细及正数量，仍要求旧 customerCode	适配共用接口数据和客商定位；保留有效输入检查
contract_flow_steps.py	缺价补 1.00，同码首行及前 30 行定位	移除缺价补值；按来源明细/目标行定位并核对实际导入结果
Web 节点详情	已展示时间、尝试次数、错误及证据	复用组件，补三个独立状态、输入关联、接收列表及恢复动作

当前 Oracle 配置主要服务货品主数据读取；新接口表写入连接和权限需现场配置。当前代码不等于已具备四条真实平台执行能力，平台查询/导出及返利页面模块需要核对或实现。

11.2 实施顺序

1. 按共同输入契约核对第 4、7 章字段及合同/返利范围；确认现场接口表复用方式。
2. 完成接收校验、Oracle 同事务保存及接收查询，验证失败重传和重复消息。
3. 增加 flow/input 关联、作业登记、独立状态、领取及结果事务，跑通“同一输入两个 job”。
4. 接平台订单导出、共享文件、台账及推送回执。
5. 接合同页面保存和链路更新；返利读取同 INPUT_ID 与合同号完成提交。
6. 接逐条选品；补齐异常及运维动作，配置四条排期后联调。

11.3 验收用例

编号	场景	预期结果
AT-01	一次完整 ORDER_COMMON 推送	一份头明细；登记两个相同 INPUT_ID/版本的合同、返利 job
AT-02	仅返利必填缺失	当次返回字段错误，无业务输入；补齐后可重传
AT-03	相同请求重发、相同对象换消息 ID 重发	返回原输入，不新增执行作业
AT-04	同已成功来源/版本传不同内容	冲突可查，旧数据和外部结果不被覆盖
AT-05	接收已提交，作业登记失败	接收记录显示登记失败；后续幂等补登记，不要求上游再推
AT-06	返利脚本先于合同脚本启动	WAIT_CONTRACT；无额外供数请求、无返利提交
AT-07	合同保存成功，链路更新失败	保存 SUCCESS、链路 FAILED；只恢复链路，返利可按保存条件领取
AT-08	合同完成后返利按另一排期启动	读取同一接口数据和本方合同号，字段来源可追溯
AT-09	平台订单重复导出到不同文件	原件保留，已接收同源订单不重复入单
AT-10	推送部分成功/超时	按实际回执记录逐单结果；UNKNOWN 不直接按失败重发
AT-11	选品合格/不合格/查询失败	分别 ADDED、SKIPPED、FAILED；本批结束，不等付款
AT-12	脚本中断和重复点击	不重复领取；已有结果可查，确认停止并核对后恢复当前步骤
AT-13	合同已保存但回报丢失	重发完成键或核对目标结果，不再次建合同
AT-14	未尽调或返利提交失败	保留输入及原业务待办，其他记录继续；人工结果核对可留痕
AT-15	46 个 Excel RPA 字段	共用接口来源、固定值及日期按映射填报，缺价不补 1.00
AT-16	运维按 MESSAGE_ID、INPUT_ID、合同号查询	能串起接收、两流程、尝试、文件、请求和人工动作
AT-17	未授权恢复、旧 token 回报	拒绝写入；旧成功结果不被覆盖
AT-18	新旧流程并存	旧在途单保留原节点；新流程不误入对码/OCR/M5

文档检查与业务验收分开：当前只完成设计；以上需要在测试数据库、实际共享目录及外部测试系统执行，mock 成功不代表真实业务通过。

12. 未决事项、风险及对其他模块的影响

12.1 联调前需要确认

项目	已明确	剩余信息
合同返利供数	一次推送共用	正式头明细、业务范围标识、消息 ID/版本；一组数据是否有多合同/多返利范围
业务字段	Excel 来源及默认值	实际 JSON 列名；采购/返利数量是否同字段，价格口径及精度
订单出站接口及对码字段	本方归档后推送原始订单字段	确认批准文号、品名、通用名、规格、厂家、单位等字段是否必填，以及标准货品结果的返回/后续供数方式
链路更新	合同保存成功后更新对应节点	节点代码、链路关联、合同标识字段及成功返回码
返利可操作性	用同一份输入加已保存合同号	目标协议生成时间、是否依赖审批或链路更新；未确认前不新增业务审批门槛
平台和共享目录	两平台分别导出归档	真实账号、订单状态/范围、文件样例、共享路径及四条排期
盈利	5% 以上盈利	计算基数及边界；不直接套用旧方案 0.95 公式
现场库和模板	接口输入与处理记录分开	现有 Oracle 表、权限、正式模板和确有要求的附件

12.2 可能问题与控制位置

问题	影响	对应设计
共用一个 processed 标志	合同处理后返利漏取	第 5 章分离合同保存、链路、返利标志
两份接口输入被分别修改	合同/返利货品数量不一致	同 INPUT_ID/版本只保留一份原始头明细
成功接收后没有 job	数据落表但长期未执行	REGISTER_STATUS 和取数前补登记；运维可查
接口/页面结果未知被当失败	重复订单、合同或返利	UNKNOWN 核对后恢复，不无条件重做
把链路失败当合同未保存	再建一份合同	保存节点结果与链路节点独立
当前合同缺价补值或明细定位错误	错金额、同码行覆盖或漏行	接收校验及第 11.1 节代码修正；单规格规则不消除多订单行的问题
原人工确认直接推进	未核实外部结果就完成作业	第 10.3 节按动作和证据校验
新旧流程改全局状态机	旧对码、OCR、M5 在途单无法继续	flow/version 分开，旧单保持原链；切换前确定同一来源由哪套办理
两库或共享目录不可用	接收失败、原文不可查、文件不可达	独立错误可见；执行记录保留，不伪装成空数据或成功

本稿的表与字段是详细设计建议，尚未核对现场字典。对外契约尚未提供的部分保留为明确缺口；不以增加业务操作、复制数据或自动猜规则来填补。