# 艺赛旗联调包

这个目录是 Windows 和 macOS 共用的 RPA 包。状态机在 `state_center`，这里只负责回调外壳和节点 runner。

Mac 上先用 mock runner 把契约跑通：

```bash
# 状态中心已启动、DEV_MODE=true
python -m rpa_yisaiqi --create --auto-human
```

Agent 只听状态中心的当前节点和 `next_node`，不写死顺序。人工节点默认停下；加 `--auto-human` 才会替你提交待办。

## CONTRACT_CREATE 联调骨架

第一版目标是先验证：

1. Windows 虚拟机能访问状态中心。
2. `CONTRACT_CREATE` 能按约定调用 `start`。
3. 合同系统动作完成后能调用 `complete`，并带 `businessRefs.contractSystemNo`。
4. 登录失败、页面改版、合同禁用等异常能调用 `fail`。

## 合同节点步骤点

来自 `state_center/给艺赛旗的开发交接.md`：

1. 打开合同测试系统：`http://contract-test.gzmpc.com:8080/`
2. 登录：`test002 / 1`
3. 左侧菜单进入 `合同管理 > 合同起草`
4. 在最近使用模板中选择 `templateName`，非格式默认 `非格式--采购协议`
5. 填签约方信息：客户编码、客户名称
6. 填基础信息：合同版本类型、合同类别、结算类型、合同背景概述、合同性质
7. 填金额和日期，合同签订日期和合同开始日期必须等于订单日期
8. 填货品明细
9. 填付款信息与特殊标志：是否重大合同、是否预付款、归属年份、付款方式、付款期限、合同状态、是否包含血液制品
10. 医药城 `YYC`：同供应商同日 PDF 先合并成一个再上传
11. 小药药 `XYY`：格式合同，跳过合同证文上传
12. 提交并读取合同编号
13. 调状态中心 `complete`，必传 `businessRefs.contractSystemNo`

## 先做联通验证

在项目根目录执行：

```powershell
python -m rpa_yisaiqi.contract_create_node `
  --state-center-url http://127.0.0.1:8000 `
  --token dev-agent-token `
  --job-id YYC-联调测试供应商-20260811-a6e5df `
  --supplier-name 联调测试供应商 `
  --order-date 2026-08-11 `
  --source-type YYC `
  --contract-system-no HT-20260811-001
```

这条只验证回调链路，合同号由命令行传入。

## 真实合同起草运行

客商必须用合同测试系统里**真实存在**的操作码。`CUST-YYC-001` 这类占位符会在选客商时搜不到，入参校验会直接拒绝。

测试环境当前可用：

| 字段 | 值 |
| --- | --- |
| customerCode | `DW0100046361` |
| customerName | `重庆亿昊药业有限公司` |

联调入参用：

- `examples/contract_create_input_dry_run.json`：真客商 + `dry_run`，先校准页面
- `examples/contract_draft_yyc.json`：医药城，同上客商
- `examples/contract_draft_xyy.json`：小药药分支（不上传 PDF），客商仍用合同系统里能搜到的同一条

YYC 有多份平台 PDF 时需要合并，先安装：

```powershell
pip install -r rpa_yisaiqi/requirements.txt
```

然后运行：

```powershell
python -m rpa_yisaiqi.contract_create_node `
  --state-center-url http://192.168.x.x:8000 `
  --token dev-agent-token `
  --job-id <状态中心job_id> `
  --supplier-name 重庆亿昊药业有限公司 `
  --order-date 2026-08-11 `
  --source-type YYC `
  --draft-path rpa_yisaiqi/examples/contract_draft_yyc.json `
  --merged-pdf-output C:/rpa/jobs/<状态中心job_id>/contract-merged.pdf
```

这条会走真实起草流程：

1. 状态中心 `/start`
2. 打开合同系统并登录
3. 进入 `合同管理 > 合同起草`
4. 选择最近使用模板
5. 填签约方、基础信息、金额日期、货品明细、付款和特殊标志
6. YYC 合并并上传 PDF，XYY 跳过上传
7. 提交
8. 读取合同编号
9. 状态中心 `/complete`

### 先做 dry-run 预览

如果你只想先验证页面，不想真的提交，把输入里的 `submitMode` 设成 `dry_run`。这时流程会跑到提交前并输出 `contract-dry-run-ready` 截图，不会点提交，也不会读取真实合同号。

适合先校准 selector 的情况：

1. 进入 `合同管理 > 合同起草`
2. 选择最近使用模板
3. 填签约方、基础信息、金额日期、明细、付款和特殊标志
4. 停在提交前

如果状态中心部署在 macOS 主机，`--state-center-url` 换成 Windows 虚拟机能访问到的地址，例如：

```powershell
--state-center-url http://192.168.x.x:8000
```

## 艺赛旗画布怎么看

Studio 里「插入代码块」标题改不了，会一直显示「插入代码块#1」。步骤名写在节点**备注**里，画布上出现在代码块下方，例如 `S06 填写签约方`。

流程按四段换行，不要再排成一条长龙：

```
准备      开始 → S01 初始化 → S02 打开系统 → S03 登录
进入起草  S04 进入起草 → S05 选择模板
填写表单  S06 签约方 → S07 基础信息 → S08 金额日期 → S09 货品 → S10 付款
提交回写  S11 上传PDF → S12 提交 → S13 读合同号 → S14 回调
```

改步骤后先关掉 Studio，再生成画布：

```powershell
python rpa_yisaiqi/build_multinode_seq.py
```

然后重新打开 `rpa_yisaiqi/studio` 项目并编译。

## 接入真实页面自动化

真实艺赛旗页面操作按流程图拆在：

- `flows/contract_create_flow.json`：流程图节点清单
- `contract_flow_steps.py`：每个流程图节点对应的动作函数
- `yisaiqi_adapter_template.py`：艺赛旗浏览器活动适配模板

艺赛旗设计器里建议按这个顺序拖流程图：

1. `S01_CALLBACK_START`：HTTP 请求状态中心 `/start`
2. `S02_OPEN_CONTRACT_SYSTEM`：打开合同系统
3. `S03_LOGIN`：输入 `j_username`、`j_password`，点击 `btn_submit`
4. `S04_ENTER_CONTRACT_DRAFT`：进入 `合同管理 > 合同起草`
5. `S05_SELECT_RECENT_TEMPLATE`：选择最近使用模板
6. `S06_FILL_SIGNATORY_INFO`：填客户编码、客户名称
7. `S07_FILL_CONTRACT_BASIC_FORM`：填合同类别、结算类型、背景概述、合同性质
8. `S08_FILL_AMOUNT_AND_DATES`：填金额、签订日期、开始日期、结束日期
9. `S09_FILL_GOODS_LINES`：循环填货品明细
10. `S10_FILL_PAYMENT_AND_FLAGS`：填付款方式、付款期限、合同状态、是否包含血液制品等
11. `S11_MERGE_PDF_IF_YYC`：`sourceType=YYC` 时先合并同供应商同日 PDF；`XYY` 跳过
12. `S12_UPLOAD_PDF_IF_YYC`：`sourceType=YYC` 时上传合并 PDF；`XYY` 跳过
13. `S13_SUBMIT`：提交
14. `S14_READ_CONTRACT_NO`：读取合同编号到变量 `contractSystemNo`
15. `S15_CALLBACK_COMPLETE`：HTTP 请求状态中心 `/complete`

如果只做预览，把这条流程里的 `submitMode` 设成 `dry_run`，或者直接导入 `flows/contract_create_preview_flow.json`。

如果艺赛旗支持 Python 脚本块，直接把每个 `contract_flow_steps.py` 函数挂到对应流程图节点。  
如果艺赛旗只支持原生活动，就按 `flows/contract_create_flow.json` 的节点顺序拖活动，用 `yisaiqi_adapter_template.py` 里的方法名做映射。

外层回调骨架仍然在 `contract_create_node.py`：

```python
create_contract_in_contract_system(spec)
```

这个函数最后返回合同编号字符串即可。状态中心回调、幂等键、错误码映射已经封在外层。后续接真页面时，可以在这里调用艺赛旗流程图，或让流程图最后把合同编号回传给这个函数。

## 异常映射

| 场景 | 异常类 | 回调错误码 | retryable | routeRole |
| --- | --- | --- | --- | --- |
| 登录失败 | `LoginFailed` | `SYS_LOGIN_FAIL` | true | OPS |
| 供应商合同被禁/失效 | `SupplierContractDisabled` | `BIZ_CONTRACT_DISABLED` | false | PURCHASER |
| PDF 合并能力不支持 | `PdfMergeUnsupported` | `CAP_PDF_MERGE_UNSUPPORTED` | false | OPS |
| 页面改版/元素找不到 | `ContractCreateError` | `UI_ELEMENT_NOT_FOUND` | false | OPS |