684 lines
52 KiB
Markdown
684 lines
52 KiB
Markdown
# 福建洁达采购 RPA 详细设计
|
||
|
||
| 文档属性 | 内容 |
|
||
| --- | --- |
|
||
| 版本 | V3.1 |
|
||
| 日期 | 2026-09-13 |
|
||
| 配套概要设计 | [《福建洁达采购 RPA 概要设计》](./2026-09-13-jieda-rpa-overview-design.md) |
|
||
| 状态 | 设计评审稿；未实施代码或建表 |
|
||
| 适用范围 | 接口接收、四条流程执行、状态记录、运维与异常恢复 |
|
||
|
||
本文件承接概要设计，规定可供开发、测试和运维执行的表、字段、状态、接口和处理规则。外部正式字段名、节点代码和现场 Oracle 表结构以第 9 章未决事项为准。
|
||
|
||
**本期范围收敛：**只实现订单接收、平台订单推送、选品、合同、返利四条流程及基本状态记录。版本冲突、内容哈希、执行令牌、文件证据表、复杂事件分类和自动化核验接口不作为本期新增必做项；现场已有能力可以复用，确需新增时另行确认。
|
||
|
||
## 4. 详细设计：数据模型
|
||
|
||
### 4.1 实体关系和存储位置
|
||
|
||
```mermaid
|
||
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`；需要新增相应前后端状态支持。未尽调转人工保留待办，不能把“停止自动办理”显示为“合同已保存”。
|
||
|
||
```mermaid
|
||
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 时序图：订单中心接收共用数据
|
||
|
||
订单中心推送完成后只表示本方已接收并保存数据，合同、返利由各自排期执行。
|
||
|
||
```mermaid
|
||
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 时序图：平台订单导出并推送
|
||
|
||
```mermaid
|
||
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 时序图：合同排期处理
|
||
|
||
```mermaid
|
||
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 时序图：返利排期处理
|
||
|
||
```mermaid
|
||
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 建单](/Users/yuuuu/Documents/AutoRpa/state_center/app/main.py:499) | 供应商＋日期键，固定首节点，只复用未完成作业 | 新接收/登记/领取按 flow 和 INPUT_ID；已完成作业也防重 |
|
||
| [schema.sql](/Users/yuuuu/Documents/AutoRpa/state_center/sql/schema.sql:11) | job 无 flow/input 关联；已有节点、日志及证据表 | 第 4 章 Oracle 接口表及推送台账；job 扩展字段/索引，supplier_name/order_date 允许空；job_event 错误保存在现有 detail_json |
|
||
| [db.py](/Users/yuuuu/Documents/AutoRpa/state_center/app/db.py:22) | 当前数据库访问实现 | 按 Oracle 驱动和事务方式调整登记、领取、结果及推进 |
|
||
| [main.py 完成回报](/Users/yuuuu/Documents/AutoRpa/state_center/app/main.py:712) | 保存节点、编号和推进分步执行；节点定义全局固定 | 同事务回报，校验 execution_token/attempt；按 flow 定义完成规则 |
|
||
| [main.py 重试](/Users/yuuuu/Documents/AutoRpa/state_center/app/main.py:812) | 已保留 attempt 历史、重试当前节点 | 保留机制，支持共用输入关联及 UNKNOWN 核对 |
|
||
| [main.py 人工提交](/Users/yuuuu/Documents/AutoRpa/state_center/app/main.py:1346) | 通用确认可直接推进；RETRY_CURRENT_NODE 分支当前只记录事件 | 按第 10.3 节校验结果和动作，实现真实重试及核查恢复 |
|
||
| [agent.py](/Users/yuuuu/Documents/AutoRpa/rpa_yisaiqi/agent.py:1) | 通用代理主要调用 mock；存在节点硬编码与默认 attempt=1 | 四条独立入口、真实 runner、领取结果中的 attempt/token |
|
||
| [contract_create_node.py](/Users/yuuuu/Documents/AutoRpa/rpa_yisaiqi/contract_create_node.py:241) | 已校验空明细及正数量，仍要求旧 customerCode | 适配共用接口数据和客商定位；保留有效输入检查 |
|
||
| [contract_flow_steps.py](/Users/yuuuu/Documents/AutoRpa/rpa_yisaiqi/contract_flow_steps.py:788) | 缺价补 1.00，同码首行及前 30 行定位 | 移除缺价补值；按来源明细/目标行定位并核对实际导入结果 |
|
||
| [Web 节点详情](/Users/yuuuu/Documents/AutoRpa/state_center_web/src/components/JobNodeDetailList.tsx:1) | 已展示时间、尝试次数、错误及证据 | 复用组件，补三个独立状态、输入关联、接收列表及恢复动作 |
|
||
|
||
当前 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 分开，旧单保持原链；切换前确定同一来源由哪套办理 |
|
||
| 两库或共享目录不可用 | 接收失败、原文不可查、文件不可达 | 独立错误可见；执行记录保留，不伪装成空数据或成功 |
|
||
|
||
本稿的表与字段是详细设计建议，尚未核对现场字典。对外契约尚未提供的部分保留为明确缺口；不以增加业务操作、复制数据或自动猜规则来填补。
|