# 洁达 RPA × 订单中心接口——开发口径

对照开发，避免跑偏。口径锁于 2026-09-29～30。接口路径暂时空着，本阶段用造数。

依据：

- `Downloads/RPA与订单中心接口设计_20260922.xlsx`（以当时最新一份为准）
- `资料/API鉴权.doc`
- `资料/合同返利系统字段映射_20260911.xlsx`（返利总单默认值）
- `选品流程/` 既有规则

---

## 1. 总原则

- 四条作业独立：选品、加购/支付回传、合同、返利。不要一个任务从加购挂到付款、录完协议。
- 对码在订单中心做完。接口 1 进来时已有 `goodsId`，本方不再做对码。
- 订单中心推接口 1、3；本方推接口 2、4。表是落盘，不是接口本身。
- 给什么填什么。领导批不批、驳回，RPA 不盯。驳回后要再录，等他们重新推数。
- 这期只做账期客户。`customerType` 固定按 `1`。预付不做。
- 出问题、接口没写清的数，打回订单中心。不要猜着填。

---

## 2. 四张表和四个口

| 口 | 方向 | 底表 | 用途 |
| --- | --- | --- | --- |
| 1 | 订单中心 → RPA | 销售商品对码数据 | 选品收件箱 |
| 2 | RPA → 订单中心 | 加购及结算商品数据 | 加购结果、支付单 |
| 3 | 订单中心 → RPA | 采购合同数据 | 合同 + 返利源数据（行级） |
| 4 | RPA → 订单中心 | 合同协议录入结果 | 合同结果、协议结果 |

- 表 1：接口收下才有数，不是手填。选品只读待处理行。
- 幂等：接口 1 按 `omsId`，已存在回 `DUPLICATE`，不更新、不重跑。接口 3 按对方 `fid`。
- 平台：`48` 药帮忙，`66` 1 药城。
- MDM：`goodsMdmCode`、`supplierMdmCode`（及选品侧货品/客户 MDM）按必填收、必填存。
- 货主 `orgCode` 原样落表、回写带上。

---

## 3. 选品

### 3.1 入口

从表 1 捞 `deal_flag=0`，一条条处理。一张 `omsId` 一个品种。

商城查询键：**条形码**。批准文号照收，不拿去搜。

规则沿用 `选品流程/`（自营仓、毛利 ≥ 4%、效期 ≥ 12 个月；两平台合并后按仓序拆量，凑齐计划量才算成功）。毛利用 `salePrice`，拆量目标用 `planPurchaseQty`。详见 `docs/superpowers/specs/2026-10-02-selection-split-allocation-design.md`。

### 3.2 加购结果（接口 2，`operateType=1`）

`status` 只给加购用。

| 现场 | 表 1 | 表 2 | 回订单中心 |
| --- | --- | --- | --- |
| 规则过了，已加购 | 处理成功 | `status=1`，带平台/供应商/价/量 | 推送 |
| 登录挂、页面报错 | 处理失败 | `status=2`，原因写系统故障 | 推送；对方可重推再跑 |
| 规则不过，故意不买 | 处理失败 | `status=2`，原因如「无符合规则商品，毛利不足 4%」或「库存不足」 | 推送；**此 `omsId` 不重推、不重跑选品** |

不再要第三种状态码。失败原因必须能区分「业务不买」和「系统故障」。

### 3.3 一单多平台

入站一行一个药。数量要两个平台才凑得齐时：

- 表 2 多行，同一个 `omsId`
- `multi_platform_flag=1`
- **同一次报文**推回，禁止先回一个平台再补另一个
- 这组平台都判定完之前不要推

凑不齐计划量：不落部分成功行，整单 `status=2`，原因「库存不足」。一边平台故障且另一边单独凑不齐：系统故障，可重跑。

### 3.4 支付（接口 2，`operateType=2`）

采购员在商城自己付。选品任务加购回传后结束，不要挂着等付款。

另排班（对准中午 12 点、下午 5 点付完后，例如 12:30、17:30）导出已支付订单：

- 付了：推 `operateType=2`，带 `payOrderNo`、`payOrderDtlId`。有单号就是成功。`status` 填空。
- 没付：**不推** 这一条。不是支付失败。
- 没有「支付失败」回写。
- 数量单价以商城实付为准，不要把加购行原样再推一遍。

### 3.5 造数阶段

失败行的单价/数量/总价接口仍标必填且数量大于 0：先填能过校验的数。`purchaseTotal` 舍入没写：先按单价×数量四位小数。对不上再打回。

---

## 4. 合同

### 4.1 班次

一天两次（中午、下午）。任务启动瞬间冻结本班未处理名单，跑的过程中新进行留给下一班。

### 4.2 合单

按 `supplierId` 合成一份合同。不用 `omsId` 合，不用供应商名称。

- 头字段（账期、签订日、起止日、采购员、计划员）取该班该供应商**第一行**。
- 下午再推来的，哪怕同一供应商，**另开一份**。不追加、不改上午已录合同。
- `contractEntryStatus=0` 且带 `contractNo`：只录协议，不进「按供应商合」，不重开合同。

### 4.3 录入

这期一律按账期客户填（不勾预付款，付款期限用 `paymentTerm`）。尽调仍看合同系统页面；未尽调本单失败，原因「客户未尽调」，不录。

点提交（不要拿暂存号去录返利）。提交成功：

- 接口 4 `actionCode=1`，`contractStatus=1` 起草，带上合同号
- **合同任务到此结束。不要重录合同。**

同一份合同下多个 `fid`：回写同一套合同号和状态。

### 4.4 合同「成功」

接口成功定义是：合同号能在返利中心搜到。不是提交成功。

查号挂在**返利班**上，不单开查状态任务。搜到再回 `contractStatus=2`。搜不到：不重录，留给下一班再搜。

---

## 5. 返利

### 5.1 班次

与合同同一天两班，建议合同班跑完再跑。不做「合同审完订单中心再推返利包」。二次推只处理协议失败重录（带合同号）。

### 5.2 查号 + 录入

拿已有合同号、尚未回合同成功的单，以及对方推来只录协议的单，打开返利中心按合同号搜：

- 搜到：先回合同成功，再录协议
- 搜不到：本班不录协议、不重开合同，下一班再搜

总单默认值跟映射表（计划员用订单中心给的，承付「下月 N 号结」，协议结束当天等）。不要用方案 5.5 的「登录人 / 账期 / 当年最后一天」。

### 5.3 协议「成功」

现场据说无审批流，点送审即成功。点完回 `actionCode=2`、`agreementStatus=1`，带上当时的协议总单/细单号。

测试环境先点一次确认：送审后号是否马上能看见。以后若打开审批流，改成送审后下一班再查，不能再点完就回成功。

---

## 6. 联调与造数

本阶段路径空着，造数跑通落表和作业。

鉴权（调订单中心时）：

- Token：`POST https://gzmpc-paas-restcloud-test.gzmpc.com/gw/rest/core/auth/token`
- 请求头：`identitytoken`
- 测试用户名：`rpa`（密码放本机环境变量，禁止写入仓库）
- 接口 2、4 真实 path 仍缺（文档 `gw/xxxx/xxxx`）
- 示例里的 `orgSecret` 是否要带，未写，真联调再问
- 订单中心调本方 1、3 的鉴权由本方定，不在这份鉴权文档里

---

## 7. 开发时不要做的

- 选品按批准文号搜商城
- 加购成功后顺手推支付
- 规则不过报 `status=1`，或报失败却让对方当故障重跑
- 多平台加购拆成两次推送
- 按 `omsId` 或「同供应商同日」另写合单
- 同一班两套账期时整组停掉（已定为取第一行照录）
- 合同搜不到号就再录一遍
- 用方案 5.5 默认值填返利总单
- 把密码、token 写进 Git