> **历史版本，已合并替代。** 当前请使用[福建洁达采购 RPA 概要设计与详细设计 V3.0](/Users/yuuuu/Documents/AutoRpa/docs/superpowers/specs/2026-09-13-jieda-rpa-integrated-design.md)。合同与返利一次接收、共用接口头明细，以新稿为准。下文保留历史内容，不作为当前实施依据。

# 福建洁达四流程技术实现说明

版本：V2.3 · 2026-09-12  
配套：[设计稿 V1.9](/Users/yuuuu/Documents/AutoRpa/docs/superpowers/specs/2026-09-12-jieda-four-flow-design-codex.md)。本文为待实施说明，代码和数据库尚未修改。

## 1. 在现有结构上改

FastAPI 接收并校验订单中心数据，RPA Oracle 保存业务头明细，Oracle 继续管理 job、节点、日志和结果。四条脚本分别由业务点击或定时任务启动，不在一个 HTTP 请求里同步执行四条流程。

现有 `job` 增加流程类型和来源数据关联；按各流程配置节点。优先复用 `job_node / job_event / job_artifact`，不另建运行中心、对码中心或多套状态表。

## 2. 接收和取数

建议本方接收入口为 sales、contract-data、rebate-data，正式路径开发时统一命名。每个入口执行：

```text
检查对应必填字段 → 不通过：返回失败和字段位置
→ 通过：同事务保存业务头明细 → 返回成功
```

字段来源和默认值按[设计稿第 4 节](/Users/yuuuu/Documents/AutoRpa/docs/superpowers/specs/2026-09-12-jieda-four-flow-design-codex.md)。系统生成和回显字段不作为上游必填。失败由订单中心修正重传，不建立等待补字段的业务作业。

取数接口按 flow 返回成功接收且未处理的数据。保存来源单号及明细标识，用于识别重复传入。状态中心登记或复用对应 job；领取时将其标记处理中，避免重复执行。脚本逐条回报，处理完本批退出。

## 3. 四条脚本

| flow | job 对象 | 执行节点 | 结束结果 |
| --- | --- | --- | --- |
| PROCURE | 一条销售明细 | `PROCURE_ITEM_RUN` | 已加购或已跳过；执行失败记原因 |
| ORDER_PUSH | 一次平台订单导出批次 | `ORDER_EXPORT_PUSH` | 文件已保存，应推送订单已接收；失败保留具体订单和原因 |
| CONTRACT | 一份上游合同数据及其明细 | `CONTRACT_CREATE → CONTRACT_CHAIN_UPDATE` | 合同已保存，订单中心节点已更新 |
| REBATE | 一份返利数据及其明细 | `REBATE_HEADER → REBATE_IMPORT → REBATE_SUBMIT` | 提交成功或失败 |

**选品脚本：** 按批准文号查询，依次判断自营仓、盈利、效期、库存和仓库顺序；合格加购物车，不合格记录跳过，继续下一条。同批准文号按一个规格处理，不增加属性匹配。复用节点结果记录已加购/已跳过，不等待人工付款。

**订单脚本：** 登录平台导出订单，保存到平台对应共享目录，按映射生成订单中心报文并推送。原文件、来源订单号、发送内容和回执保存在现有文件/日志记录中。再次处理依据已接收订单记录跳过成功项。

**合同脚本：** 读取成功接收的合同头明细，复用页面操作填写并保存。确认保存成功后回报合同号，进入链路更新节点。该节点通过订单中心接口适配器调用更新接口并回报结果。两步在同一条合同流程中执行，失败后恢复当前步骤；不增加独立后台调度任务。

**返利脚本：** 按合同号查询协议，填写总单、导入明细并提交，回报实际结果。原业务要求的未尽调合同及返利失败交业务处理，继续其他记录。

## 4. 数据如何保存

| 内容 | 保存位置 |
| --- | --- |
| 销售头明细 | RPA Oracle 销售表，字段按订单中心数据及选品条件 |
| 合同头明细及链路关联 | RPA Oracle 合同表，字段按 Excel |
| 返利头明细及计划员对应信息 | RPA Oracle 返利表，字段按 Excel |
| 流程、处理状态、合同号、失败原因 | 现有 Oracle job/job_node |
| 文件路径及推送/链路调用记录 | 现有 job_artifact/job_event |
| 平台原始订单文件 | 对应平台共享文件夹 |

表名及列定义见设计稿第 5 节；开发前对照现场已有表和正式报文确定。头明细按来源关联保存，不用供应商＋日期代替所有业务唯一标识，不自行合并合同。

处理状态复用现有待处理、处理中、成功、失败等状态。选品正常跳过属于处理完成，业务结果记录为“已跳过”。合同的“保存成功”和“链路更新成功”分别记录，更新失败不回退到重新建合同。

## 5. 代码改动

| 文件/模块 | 改动 |
| --- | --- |
| `state_center/app/main.py` | 接收校验、取数及结果接口；按 flow 创建和查询作业 |
| `state_center/app/db.py`、数据库脚本 | RPA 业务表访问、头明细事务、job 的 flow 和来源字段；成功数据重复传入不重复建单 |
| `state_center/app/web_state_machine.py` | 四条节点配置；旧作业继续用旧配置 |
| `state_center/app/config.py` | 数据库、订单中心接口、平台共享路径和字段映射配置 |
| 订单中心接口适配器 | 两项调用：平台订单推送、合同保存后的链路节点更新；路径及参数按对方协议 |
| `rpa_yisaiqi/agent.py`、`runtime/shell.py`、`callback_client.py` | 四种脚本入口、取数循环、实际执行次数、结果回报、失败步骤恢复 |
| 选品/平台导出模块 | 登录查询、采购筛选、加购、导出、共享文件保存及报文组装 |
| `contract_draft.py`、`contract_create_node.py`、`contract_flow_steps.py` | 按 Excel 字段录入；确认保存结果，衔接链路接口；修正错误单价默认值及明细定位 |
| 返利模块 | 补真实页面填写、导入、提交操作 |
| 前端列表/详情 | 展示四种流程及已有状态，增加文件、接收结果和链路更新结果 |

现有固定主链、供应商＋日期建单规则不能直接套用到全部新流程。商城实际登录/查询/导出模块需核对是否已有可用代码；现有 mock 代理和返利 runner 不能算真实执行已完成。

## 6. 开发顺序

1. 按正式报文和 Excel 确定字段，核对已有表，完成接收校验和落表。
2. 增加 flow、取数、结果记录及四个脚本入口，复用现有状态中心。
3. 完成平台导出、共享归档和订单推送。
4. 完成合同字段适配，接上保存后的链路更新接口。
5. 完成逐条选品加购及返利页面操作。
6. 在实际执行机配置四条排期，按设计稿第 7 节联调验收。

## 7. 待确认及可能的问题

- 订单中心正式字段、链路节点代码、平台导出样例、共享路径及排期需提供；5% 盈利公式需明确。
- 重复点击、重复传单、重复导出可能重复办理；使用现有状态和来源标识防重，同一流程不重入。
- 保存或推送成功后回报失败，不能直接重做；先查看已有文件、回执或目标合同结果，再从失败步骤继续。
- 合同链路更新失败只补接口调用；不额外增加后台维护任务。
- 当前合同缺价填 1.00、同编码行定位及前 30 行扫描行为需要处理；具体风险见设计稿末尾。
- 新四流程改动按 flow 区分，保留旧在途单节点，避免影响旧 OCR、对码和 M5 流程。