AutoRpa/艺赛旗开发包-README.md

艺赛旗开发包说明

这个包包含艺赛旗(iS-RPA)开发采购主链 RPA 一期所需的全部材料。

文档清单

📘 1-技术规范(必读).md

就是 state_center/给艺赛旗的开发交接.md

用途:你们的技术圣经,开发过程中反复查。

内容:

• HTTP 回调契约(start/complete/fail 三个接口的字段规范)
• 三把钥匙(必须回传的业务编号:合同编号、返利总单号、收货通知单号)
• 错误码表(什么情况返回什么错误码、retryable 怎么填、routeRole 怎么填)
• 逐节点操作说明(哪个节点点什么页面、拿什么编号、失败怎么处理)
• 硬规则红线(10条,踩了就是错的)

📋 2-并行开发任务.md

用途:你们的开发计划和检查清单。

内容:

• 阶段1:独立开发(2-3周,不依赖状态中心)
  • 逐节点开发页面自动化(ORDER_FETCH、CONTRACT_CREATE、REBATE_*、M5_CREATE_ORDER 等)
  • 本地模拟回调验证 payload 格式
  • 错误码识别验证
• 阶段2:准备对接(1天)
  • 拿到状态中心联调环境信息
  • 改成调真实接口
  • 小范围试跑
• 联调阶段(3-5天,和状态中心一起)
  • 按节点逐个验证
  • 跑完整链(医药城线上单、线下单、对码 MULTI、缺货源等场景)
  • 异常场景验证

✅ 3-联调检查清单.md

用途:联调前自证、联调时逐条勾。

内容:

• 功能检查(15项):能登录各系统、能导出订单、能拿到三把钥匙、能处理 M5 桌面自动化…
• 回调检查(6项):知道何时调什么接口、必传字段是否正确、错误码是否识别准确…
• 异常检查(4项):登录失败、页面改版、M5质管缺失、合同被禁的处理是否正确…

---

开发顺序(重要)

第1周          第2周          第3周          第4周
│─────阶段1:独立开发─────│阶段2:准备对接│──联调阶段──│
  (2-3周,不依赖状态中心)    (1天)        (3-5天)

现在(第1天)你们要做的:

1. 仔细读 1-技术规范(必读).md,尤其是:

   • 第三节:三个回调契约(start/complete/fail 的 JSON 格式)
   • 第四节:三把钥匙(contractSystemNo/rebateOrderNo/receiptNoticeNo)
   • 第五节:逐节点操作说明(每个节点点什么页面、拿什么数据)
   • 第六节:硬规则红线(10条,违反就是错的)

2. 确认环境:

   • iS-RPA 开发环境能访问医药城、小药药、合同系统、返利中心、M5 吗?
   • 有测试账号吗?
   • M5 是桌面客户端,iS-RPA 的桌面自动化能力 OK 吗?(这是最大风险点)

3. POC 验证:

   • 先做一个最简单的节点(比如 ORDER_FETCH:登录医药城 → 导出订单)
   • 不调状态中心,在自己环境跑通,验证 iS-RPA 能点页面、能拿到数据
   • 手工构造一个 complete 回调的 JSON,确认能拿到订单号列表

第1周你们要完成的:

• ORDER_FETCH 页面自动化 + 回调 payload 验证
• CONTRACT_CREATE 页面自动化(重点:能拿到合同编号)
• REBATE_HEADER 页面自动化(重点:能拿到返利总单号)

第2周你们要完成的:

• REBATE_IMPORT 页面自动化(重点:Excel 模板生成、字段映射、上传、读成功/失败行)
• REBATE_SUBMIT 页面自动化(简单,就一个按钮,但关键)
• M5_CREATE_ORDER 页面自动化(最难,桌面客户端,录完不保存)

第3周:

• CONTRACT_APPROVE_WAIT 定时查询逻辑(不是连续轮询,是到点查一次)
• 错误码识别验证(登录失败、页面改版、质管缺失、合同被禁等场景)
• 本地模拟回调,验证所有 payload 格式正确

第4周:

• 拿到状态中心联调环境,改成调真实接口
• 和状态中心一起联调,跑通完整链

---

关键提醒

⚠️ 三个最大风险点

1. M5 桌面自动化:M5 是客户端不是网页,iS-RPA 能否稳定操作?建议第1周就 POC 验证。
2. 医药城 PDF 合并:同供应商同日合同要合并成一个 PDF 再上传,iS-RPA 有 PDF 合并能力吗?
3. 错误码识别准确性:M5_QC_MISSING 必须识别准(状态中心会直接转 FAILED_MANUAL,不重试),如果误判成其他错误码,整个流程就乱了。

✅ 成功的标志

联调前,你们能自证:

• 能稳定登录 5 个系统(医药城、小药药、合同系统、返利中心、M5),处理验证码/超时
• 能拿到三把钥匙(合同编号、返利总单号、收货通知单号)
• 能识别 10+ 种错误情况并返回正确错误码
• 能按状态中心返回的 next_node 继续跑下一节点(不写死顺序)
• 所有回调都带 X-Agent-Token header

---

联系方式

状态中心负责人:[你的联系方式]

问题反馈:

• 技术问题(接口规范、字段含义):直接问状态中心负责人
• 业务问题(节点操作步骤、验收标准):查 资料/采购主链RPA一期实施与验收规范.md
• 进度协调:每周五同步一次进度

---

附录:快速上手示例

示例1:本地模拟 ORDER_FETCH complete 回调

# 假设你本地起了个 mock 状态中心在 localhost:8000
curl -X POST http://localhost:8000/api/jobs/TEST-JOB-001/nodes/ORDER_FETCH/complete \
  -H "Content-Type: application/json" \
  -H "X-Agent-Token: dev-agent-token" \
  -d '{
    "attemptNo": 1,
    "executorRunId": "YD-RUN-001",
    "summary": {
      "orderCount": 12,
      "supplierList": ["重庆亿昊药业"],
      "orderNoList": ["DD-001", "DD-002"]
    },
    "artifacts": [
      {
        "artifactType": "SOURCE_EXCEL",
        "storagePath": "/data/jobs/TEST-JOB-001/orders.xlsx",
        "fileHash": "sha256:abc123"
      }
    ]
  }'

期望响应:

{
  "ok": true,
  "next_node": "OCR_EXTRACT"  // 或 "PRODUCT_MATCH"(如果是线上单,跳过 OCR)
}

示例2:CONTRACT_CREATE 必须回传合同编号

curl -X POST http://localhost:8000/api/jobs/TEST-JOB-001/nodes/CONTRACT_CREATE/complete \
  -H "Content-Type: application/json" \
  -H "X-Agent-Token: dev-agent-token" \
  -d '{
    "attemptNo": 1,
    "businessRefs": {
      "contractSystemNo": "HT2026080400001"  // 必传!不传返回 400
    },
    "summary": {
      "contractTemplate": "FORMAT",
      "pdfMerged": true
    }
  }'

示例3:M5 质管缺失的失败回调

curl -X POST http://localhost:8000/api/jobs/TEST-JOB-001/nodes/M5_CREATE_ORDER/fail \
  -H "Content-Type: application/json" \
  -H "X-Agent-Token: dev-agent-token" \
  -d '{
    "attemptNo": 1,
    "errorCode": "M5_QC_MISSING",  // 特殊错误码,状态中心会直接转 FAILED_MANUAL
    "errorSummary": "质管资料缺失,无法在 M5 录单",
    "retryable": false,  // 填什么都没用,状态中心强制转人工
    "routeRole": "QC"
  }'

期望响应:

{
  "ok": true,
  "job_status": "FAILED_MANUAL"  // 注意:不是 FAILED_RETRYABLE
}

---

祝开发顺利!有问题随时联系状态中心负责人。