# 艺赛旗开发包说明

这个包包含艺赛旗(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 回调
```bash
# 假设你本地起了个 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"
      }
    ]
  }'
```

**期望响应**:
```json
{
  "ok": true,
  "next_node": "OCR_EXTRACT"  // 或 "PRODUCT_MATCH"(如果是线上单,跳过 OCR)
}
```

### 示例2:CONTRACT_CREATE 必须回传合同编号
```bash
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 质管缺失的失败回调
```bash
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"
  }'
```

**期望响应**:
```json
{
  "ok": true,
  "job_status": "FAILED_MANUAL"  // 注意:不是 FAILED_RETRYABLE
}
```

---

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