13 KiB

Raw Blame History

给艺赛旗(iS-RPA)的开发交接说明

你(艺赛旗开发)负责"采购主链RPA一期"里点外部系统页面的活:登录、导订单、建合同、返利中心操作、M5 录单。每做完一步,用 HTTP 回调告诉"状态中心"结果。状态中心是大脑(记每单跑到哪、派活、存证据),你是手脚(照它给的顺序点页面)。你俩只通过 HTTP JSON 回调对接,不共享数据库。

一、你要干什么(一句话)

按状态中心下发的 job(一个供应商+一个订单日期=一条合同),在各外部系统页面上完成对应节点的操作,每个节点用三个回调(start / complete / fail)把状态回传。

二、你和状态中心怎么对接(核心)

状态中心(Python/FastAPI)         艺赛旗 iS-RPA
   记状态/派活/存证据      <--HTTP-->   点页面/填表/上传
        |                                  |
        |  1) 你开始一个节点: POST .../start        |
        |  2) 点完页面成功:   POST .../complete      |
        |  3) 出错:          POST .../fail          |

状态中心不会调用你(一期没有反向下发);是你主动调它三个回调。
每次调用必须带 header X-Agent-Token(默认 dev-agent-token,上线换正式值,找状态中心开发要)。
节点顺序由状态中心维护,你 complete 后它自己算下一个节点是谁并返回 next_node,你照着它返回的 next_node 跑下一步,不要自己写死顺序。

三、三个回调契约(照抄字段,别改名)

基础地址:http://<状态中心地址>:8000(联调时给你实际 IP)。所有回调 header 带 X-Agent-Token: <token>、Content-Type: application/json。

3.1 节点开始 start

POST /api/jobs/{jobId}/nodes/{nodeCode}/start
{
  "attemptNo": 1,                 // 第几次尝试,重试就 +1
  "executorPlatform": "iS-RPA",   // 可选,标记是哪个RPA平台跑的
  "operator": "agent"             // 可选
}

返回 {"ok": true}。开始点页面前先调一次,让状态中心把该节点标 RUNNING。

3.2 节点成功 complete

POST /api/jobs/{jobId}/nodes/{nodeCode}/complete
{
  "attemptNo": 1,
  "executorRunId": "YD-RUN-001",  // 可选,你这边的流程运行号,便于回查
  "businessRefs": {               // 业务编号回写(见下表,产出编号的节点必传)
    "contractSystemNo": "HT2026..."
  },
  "summary": { "orderCount": 12 } // 可选,给业务看的摘要
}

返回 {"ok": true, "next_node": "OCR_EXTRACT"}。拿到 next_node 跑下一节点;next_node=null 表示整单跑完。

3.3 节点失败 fail

POST /api/jobs/{jobId}/nodes/{nodeCode}/fail
{
  "attemptNo": 1,
  "errorCode": "SYS_LOGIN_FAIL",  // 错误码,见第五节各节点表,照抄
  "errorSummary": "验证码识别失败", // 人能看懂的一句话
  "retryable": true,              // 系统类错误填 true(状态中心可安排重试);业务类填 false
  "routeRole": "OPS"              // 转给谁:OPS(运维)/PLANNER(计划员)/PURCHASE(采购)
}

返回 {"ok": true, "job_status": "..."}。

状态中心对 fail 的处理逻辑(你要知道,免得填错):

errorCode == "M5_QC_MISSING" → 无条件 FAILED_MANUAL(转人工手工做,不重试、不等质管),retryable 填什么都没用。
否则 retryable=true → FAILED_RETRYABLE(系统类,等重试)。
否则 → WAITING_USER(业务类,进人工待办,按 routeRole 派人)。

判断原则:系统能自愈的填 retryable=true(登录超时、页面卡顿);要人来决定的填 false(对码要选、合同被禁、返利重复编码)。

四、businessRefs 业务编号回写(三把钥匙 + 收货单)

有三个节点必须在 complete 时回传对应编号,否则状态中心返回 400 拒绝记成功:

节点 nodeCode	必传字段	是什么
CONTRACT_CREATE	`contractSystemNo`	🔑合同编号(后续返利、M5 靠它串)
REBATE_HEADER	`rebateOrderNo`	返利中心总单号
M5_RECEIPT_NOTICE	`receiptNoticeNo`	收货通知单号(全链终点)

其余节点若产出编号也可回传(如 M5 单号 m5OrderNo),状态中心会落库。字段名照抄,大小写别改。

五、逐节点你要做什么(页面操作 + 回调)

完整版看 资料/采购主链RPA一期实施与验收规范.md 第四部分,每节点都有"页面操作步骤 + 代码验收 + 业务验收 + 失败去向"。这里给精简对照,让你知道每步调哪个回调、错误码填什么。

节点编排一共 13 个 = 11 主节点 + 2 条件节点(状态中心的 NODE_ORDER): ORDER_FETCH → OCR_EXTRACT → PRODUCT_MATCH → SOURCE_ADD → CONTRACT_CREATE → CONTRACT_APPROVE_WAIT → REBATE_HEADER → REBATE_IMPORT → REBATE_SUBMIT → M5_CREATE_ORDER → M5_MANUAL_CONFIRM → M5_RECEIPT_NOTICE → ARCHIVE_JOB

2 个条件节点会被自动跳过(你收不到 next_node 就是被跳了,别当 bug):
- OCR_EXTRACT:只有线下手工单才走,线上单(医药城/小药药)自动跳过。
- SOURCE_ADD:只有对码判定缺货源才走,货源齐全自动跳过。
不是你点页面的节点:PRODUCT_MATCH(对码=状态中心内部算)、SOURCE_ADD/M5_MANUAL_CONFIRM/M5_RECEIPT_NOTICE(一期人工)、ARCHIVE_JOB(状态中心归档)。
你负责的是下面标"★你的活"的节点。顺序永远听 complete 返回的 next_node,别自己写死(条件节点跳过就是状态中心帮你算好的)。

状态中心对回调做了幂等 + 乱序拒绝:

同一节点同 attemptNo 重复 complete,不会二次推进(会返回上次的 next_node,带 "idempotent": true),网络重发放心。

回调的节点若不是该 job 的当前节点,返回 409(乱序被拒)。别跳着节点调,照 next_node 走。

complete 可带 idempotencyKey(你生成的唯一串),便于状态中心去重。

① ORDER_FETCH · 订单获取 ★你的活

页面(医药城 / 小药药):登录 → 我的订单 → 选日期(默认前一天)→【待确认:按订单状态过滤】→ 导出订单明细 Excel → 存证据目录 + 截图。

complete:summary 带 orderCount / supplierList / orderNoList,businessRefs 无。
当天无订单:正常结束(不算失败)。
fail 错误码:登录失败 SYS_LOGIN_FAIL(retryable=true, OPS)、页面超时 SYS_PAGE_TIMEOUT(true, OPS)、导出按钮改版找不到 UI_ELEMENT_NOT_FOUND(false, OPS)。

①b OCR_EXTRACT · 线下手工单识别(仅线下单)

不是你主导。线上订单直接跳过此节点(complete 空过)。线下单由 OCR 服务识别,你只负责取件/触发。

fail:图片模糊 BIZ_OCR_LOW_CONF(false, PLANNER)、OCR服务挂 SYS_OCR_DOWN(true, OPS)。

③ CONTRACT_CREATE · 合同建单 ★你的活

页面(合同系统 contract.gzmpc.com):登录 → 按供应商对照表判断模板(格式/非格式承兑)→ 可复制历史合同再改 → 填基础信息,签约日期/合同开始日期 = 订单日期(硬约束,不是今天) → 填货品明细 → 填付款信息 → 提交送审。

医药城分支:下载平台购销合同,同供应商同日合并成一个PDF再上传(先合并!传第二份会覆盖第一份)。
小药药分支:格式合同,跳过合同证文上传。
complete:必传 businessRefs.contractSystemNo(合同编号)。
fail 错误码:供应商合同被禁/失效 BIZ_CONTRACT_DISABLED(false, PURCHASE)、PDF合并不支持 CAP_PDF_MERGE_UNSUPPORTED(false, OPS)、页面改版 UI_ELEMENT_NOT_FOUND(false, OPS)。

④ CONTRACT_APPROVE_WAIT · 等合同审批 ★你的活(定时查一次,不连续轮询)

合同送审(CONTRACT_CREATE complete)后,状态中心把该 job 挂成 WAITING_EXTERNAL,并按业务方案每约半小时排一次查。这个节点不用 start/complete/fail 三件套,用下面两个专用接口:

到点扫待查:你(或调度器)定时 GET /api/scheduler/due-contract-checks(带 X-Agent-Token),拿到到点该查的 job 列表(含 contractSystemNo)。
登录查一次审批状态,把结果回给状态中心:
```
POST /api/jobs/{jobId}/nodes/CONTRACT_APPROVE_WAIT/check-result
{ "approved": true, "operator": "agent", "detail": "已审批通过" }
```
- approved=true → 状态中心放行,返回 {"ok":true,"next_node":"REBATE_HEADER"},你接着跑返利。
- approved=false → 状态中心把 wait_check_count+1,排下一次查(约半小时后又出现在待查列表);查满上限(默认 8 次≈4 小时)还没过 → 自动升级 OPS(WAITING_USER),你不用管了。

别死等、别连续轮询:只在到点被扫到时查一次。
注意:未审完也会有合同编号,但必须审批通过才能进返利导入。

⑤ REBATE_HEADER · 返利中心总单 ★你的活

页面(返利中心 flgzmpc.com):登录 → 采购协议管理 → 按合同编号查总单 → 填必填项、勾必选项 → 保存。

complete:必传 businessRefs.rebateOrderNo(总单号)。
fail:查不到总单/必填缺失 → OPS 或 PURCHASE 核查。

⑥ REBATE_IMPORT · 返利细单导入 ★你的活

页面:下载细单模板 → 填字段(操作码/货品编码、数量、单价、税率、承付方式、细单开始时间=订单时间、失效日期、结算方式、特定补偿=0、细单备注=订单号、货源信息)→ 上传导入 → 读成功/失败行。

complete:summary 带成功/失败计数与明细。
fail:重复编码(订单已做过)REBATE_DUP_CODE(false, PURCHASE)→ 该单挂起,整批继续(重建规则待确认,先转人工)。

⑦ REBATE_SUBMIT · 返利送审 ⭐决定成败⭐ ★你的活

页面:在返利中心对该总单点"提交送审"(送审即自动审批通过,合同前端已审过)。

反直觉核心:卡 M5 能不能带出品种的送审在返利中心,不在合同系统。这步不做,后面全废。
未送审 = 硬阻断,整个 job 停在这。不许跳过进 M5。

⑧ M5_CREATE_ORDER · M5 建采购单(1055)★你的活(M5 是桌面客户端)

M5 是桌面应用(不是网页),用桌面自动化处理。步骤:采购订单管理 1055 → 新增 → 保管账=正常保管账(默认唯一)→ 隔天做则日期改前一天签约日期 → 备注填订单号 → 新增细单选品种(返利已送审的才带得出)→ 选对应数量 → 结算/接收/发票用返利带入值(不填)→ ★录完就停,绝不点保存★。

complete:标记"M5待保存"(可回传 m5OrderNo)。
fail:质管资料缺失 M5_QC_MISSING(填什么状态中心都转 FAILED_MANUAL,不重试不等质管,转人工手工做)。

⑨⑩ M5_MANUAL_CONFIRM / M5_RECEIPT_NOTICE · 一期人工

一期这两步人工做(检查→保存→签订→生成收货通知单)。你不点。阶段二 auto_save_enabled 放开后才可能给你。

六、硬规则(红线,踩了就是错)

签约日期 = 订单日期,不是今天。合同建单、M5 日期都按订单日期。
医药城同供应商同日合同合并成一个PDF再上传(传第二份会覆盖);小药药不上传合同证文。
关键送审在返利中心(REBATE_SUBMIT),不是合同系统。不送审 M5 带不出协议,硬阻断。
M5 录完不点保存(一期人工把关保存/签订)。auto_save_enabled 一期=0。
M5 质管缺失(M5_QC_MISSING)不重试、不等质管,直接转人工。RPA 晚上跑,质管不会半夜维护。
返利细单:特定补偿=0、细单备注=订单号(物流/结算要看)。细单开始时间=订单时间。
对码未命中/返利重复编码 = 单条挂起,整批继续,不是停整批。
产出编号的三个节点(合同/返利总单/收货通知)complete 必传对应 businessRefs,否则被 400 拒。
每个回调必须带 X-Agent-Token;别把状态中心接口无认证暴露。
节点顺序听状态中心的(照 complete 返回的 next_node 走),别自己写死。

七、你不做什么(边界)

不碰状态存储/对码算法/前端页面——那是状态中心(Trae)的活。你只点外部系统页面 + 回调。
不做对码判断——对码是状态中心内部算,MULTI/NONE 会进人工待办,不经过你。
不做 M5 保存/签订/收货通知(一期人工)。
不做招财平台(一期不纳入)。
遇到文档标 【待确认】 的(订单状态过滤、返利重复编码重建、OCR部署方式),别自己拍板,留 TODO 问项目负责人。

八、联调建议顺序

先跟状态中心开发对齐:实际 IP、正式 X-Agent-Token、证据目录路径。
拿一个测试供应商 + 一天的测试订单,先只跑 ORDER_FETCH:start → 导出 → complete,在状态中心 GET /api/jobs/{id} 看到轨迹即通。
再一节点一节点往后接,每接一个对照 实施与验收规范 第四部分的"业务验收"栏勾。
合同、返利、M5 三段分别单独联调通过后,再跑整链。

13 KiB Raw Blame History