# 采购主链 RPA 编排与手机待办一期方案

## Summary

一期按 `RPA执行平台 + Python/MySQL 轻量状态中心 + 企业微信正式应用 + 本地 OCR` 落地，覆盖主链 `合同扫描件/合同系统 -> 返利中心采购协议 -> M5 采购订单`。  
目标不是只做一个机器人脚本，而是做成一套**业务可见、异常可处理、手机可协同**的流程编排系统：

- 主流程默认尽量全自动运行
- OCR/映射不确定项转为企业微信手机待办
- 每个节点状态、耗时、错误原因、处理人都写入状态中心
- 业务可在手机端完成 `查看上下文 / 补录字段 / 继续 / 重试 / 转人工`
- RPA 执行平台只负责系统操作与节点执行，不承载核心状态和业务协同

## Key Changes

### 0. 入池触发与文件规范

一期默认以“**共享文件夹入池 + 状态中心建单**”作为统一触发方式，不接受 RPA 平台内部自行起单。

- 合同扫描件、年度协议、批次协议、返利中心导入模板都必须先进入约定共享目录
- 状态中心负责监听入池目录，或由人工在状态中心页面选择文件后建单
- RPA 平台只能消费已经建好的 `job`，不能绕过状态中心直接执行

入池对象至少区分以下几类：

- 年度协议
- 批次合同
- 合同附件/补充页
- 返利中心细单导入模板

文件命名规则一期建议固定为：

- `日期_供应商名称_计划员_合同类型`
- 允许补充流水号或附件序号，例如 `20260625_国药控股_张三_批次合同_01.pdf`

入池校验至少包括：

- 文件类型是否在允许范围内（PDF/图片/Excel）
- 是否命中命名规范
- 是否能识别供应商名称与计划员
- 同一合同编号/同一业务键是否已存在未完成实例
- 是否存在多页缺失、重复上传、同名覆盖

入池失败时不得直接丢给 RPA 平台，应由状态中心生成待处理记录：

- 命名不规范 -> 计划员待办
- 关键文件缺失 -> 计划员待办
- 疑似重复入池 -> 提示并阻止新建，必要时转运维或项目负责人确认

### 1. 总体架构与职责边界

- **RPA 执行平台（影刀 / 艺赛旗 / 其他）**
  - 负责登录系统、页面检索、字段填充、模板导入、截图、日志/录屏采集、执行结果回传
  - 每完成一个节点，调用状态中心接口上报节点结果
  - 不直接保存业务主状态，不直接承载人工审批逻辑

- **轻量状态中心（Python + MySQL）**
  - 负责流程实例、节点状态、待办、角色路由、重试控制、日志归档、配置映射、执行平台路由
  - 提供给 RPA 平台的流程启动、节点回调、异常上报、人工处理、继续执行接口
  - 提供给企业微信的消息卡片、待办链接、处理回调接口

- **本地 OCR 服务**
  - 一期默认本地部署，优先按 PaddleOCR 设计
  - 负责从扫描件/PDF 中提取文本和结构化字段
  - 输出带置信度的 JSON，不直接写业务系统

- **企业微信正式应用**
  - 负责个人待办、异常告警、处理入口、节点进度消息
  - 不做主流程编排，只作为移动交互层

#### 1.1 我方自有能力边界

以下能力必须沉淀在“我们自己的状态中心”中，而不是绑定在某一家 RPA 平台内部：

- 流程主状态与节点状态机
- 合同入池、判重与幂等控制
- OCR 结果存档、映射配置、规则版本
- 手机待办、角色路由、人工处理留痕
- 成功判定口径、错误码体系、证据归档
- 多 RPA 平台的统一查询、统一审计和统一对外口径

换句话说，RPA 平台是可替换的“执行手”，状态中心才是我们的“流程主控”和“业务资产沉淀层”。

#### 1.2 执行平台可替换边界

一期支持将底层执行器设计为可切换，但边界要先写死：

- 可切换的是“执行平台”，不可切换的是状态中心、企业微信协同、业务规则和成功判定口径
- 允许“按新单切换平台”，也允许“按节点配置平台”
- 不做“单个节点执行到一半跨平台接力”
- 老单默认沿用建单时选定的平台，不在执行过程中强行迁移
- 新平台接入前必须通过统一 POC 验证清单

#### 1.3 候选平台能力判断原则

当前候选执行平台可包括影刀、艺赛旗等，但是否可用于本项目，不能只看厂商宣传页，要按本项目关键动作验证：

- 目标系统登录与稳定检索
- 表单填写、弹窗处理、模板导入
- 文件上传/下载与本地目录交互
- 截图、日志、录屏留证
- 自定义 HTTP 回调状态中心

满足上述能力后，才能认为该平台可替代现有执行器。

### 2. 一期业务主链与节点定义

一期只做以下主链，其他如订单中心分货、招采子系统不纳入一期：

1. 合同文件入池
2. OCR 识别与字段抽取
3. 字段映射与业务校验
4. 合同系统信息补齐/确认
5. 返利中心采购协议检索与总单录入
6. 返利中心细单模板生成与导入
7. 返利中心结果校验
8. M5 采购订单创建
9. M5 保存与收货通知单生成
10. 流程完成归档

#### 2.1 合同系统前置条件

返利中心与 M5 的自动执行，必须建立在“合同系统已达到可执行状态”的前提上。

一期要明确区分以下几个动作：

- 合同系统信息补齐
- 合同系统送审
- 合同系统审核通过
- 审核驳回/需补充资料

建议一期按以下边界落地：

- 机器人可协助录入合同系统字段，并回写录入结果
- “送审”动作是否由机器人执行，需要业务确认后写死
- 只有合同处于“已审核/审核通过”状态，才能进入返利中心节点
- 审核未通过或缺资料，不得继续推进，直接转计划员或采购待办

状态中心中必须记录：

- 合同系统单号
- 合同系统当前审核状态
- 审核通过时间
- 驳回原因摘要

#### 2.2 一期明确不纳入范围

以下内容虽然在原始资料中提到，但不纳入一期实施：

- 订单中心分货与销售订单联动
- 招采子系统医院计划抓取与回传
- 发货后的一票/二票自动上传
- 渠道价管理与维护

如后续要做，应单独建二期/三期方案，不在一期需求、排期和验收中混入。

每个节点统一有以下状态：

- `PENDING`
- `RUNNING`
- `WAITING_USER`
- `SUCCESS`
- `FAILED_RETRYABLE`
- `FAILED_MANUAL`
- `CANCELLED`

#### 2.3 状态流转规则

节点状态不仅要有枚举，还要有明确迁移规则，避免同一单被重复推进：

- `PENDING -> RUNNING`
- `RUNNING -> SUCCESS`
- `RUNNING -> WAITING_USER`
- `RUNNING -> FAILED_RETRYABLE`
- `RUNNING -> FAILED_MANUAL`
- `WAITING_USER -> RUNNING`
- `WAITING_USER -> CANCELLED`
- `WAITING_USER -> FAILED_MANUAL`
- `FAILED_RETRYABLE -> RUNNING`

补充约束：

- 同一节点同一时刻只能有一个有效执行上下文
- 手机端“确认并继续”只能成功推进一次，后续重复提交必须返回幂等结果
- 节点超时后不能静默停留，必须升级为催办或异常状态
- `CANCELLED` 和 `FAILED_MANUAL` 默认不可自动恢复，只能人工明确重开

每个节点必须记录：

- 流程单号
- 合同编号
- 供应商
- 当前节点编码
- 节点开始/结束时间
- 执行结果
- 错误码
- 错误摘要
- 截图/日志路径
- 当前处理角色
- 当前处理人
- 重试次数

### 3. 手机待办与角色路由

手机待办默认按**角色路由**，不是固定发给某个人。

一期角色至少包括：

- 计划员
- 采购
- 质管
- 运维/机器人管理员

路由规则：

- OCR/映射不确定 -> 计划员
- 返利中心录入失败且需业务判断 -> 采购
- M5 保存失败且提示质管基础数据问题 -> 质管
- 机器人登录失败、页面结构变化、系统超时 -> 运维
- 多次重试仍失败 -> 运维 + 当前业务角色

#### 3.1 企业微信一期落地方式

一期建议将企业微信能力落成：

- 消息通知
- 模版卡片消息更新
- H5 处理页/详情页
- 用户身份识别与回调处理

即：企业微信负责“通知 + 打开处理入口 + 提交处理动作”，状态推进仍由状态中心完成。

说明：

- 一期文档中的“手机待办”默认指“企业微信消息卡片 + H5 待处理页”的组合能力
- 不把企业微信原生待办体系作为一期已确认前提，若后续验证可接，再单独扩展
- 所有按钮动作最终都必须调用状态中心接口，并以状态中心结果为准

企业微信待办支持的动作固定为：

- `查看详情`
- `补录/修改字段`
- `确认并继续`
- `重新执行当前节点`
- `转人工处理`
- `终止本单`

消息内容必须包含：

- 合同编号
- 供应商名称
- 当前节点
- 错误摘要或待确认原因
- 已识别关键字段摘要
- 最近一张错误截图
- 处理入口链接

#### 3.2 人工处理字段边界

手机端“补录/修改字段”不能放成无限编辑，必须收敛为白名单字段。

一期建议按角色控制：

- 计划员：合同编号、承付模式、承付参数、计划员归属、合同有效期、OCR 识别结果修正
- 采购：供应商映射、货品映射、协议单价、返利中心导入模板相关字段
- 质管：仅处理基础资料维护完成确认，不直接改合同业务字段
- 运维：只能做重试、转派、失败归档，不修改业务字段值

以下字段若涉及修改，必须记录修改前后值、修改人、修改时间、修改原因：

- 合同编号
- 供应商名称/编码
- 结算方式
- 承付模式与承付参数
- 货品编码/数量/单价
- M5 货源选择

#### 3.3 人性化待办体验

为了提升业务接受度，一期建议把以下体验项明确纳入需求，而不是留到后期“有空再优化”：

- **人话状态**
  - 不只显示节点编码，要显示“系统正在做什么、通常还要多久、下一步会怎样”
- **错误翻译**
  - 除错误码外，必须给出业务能看懂的错误原因和建议动作
- **为什么发给你**
  - 每条待办都说明“当前归你处理的原因”和“本次需要你确认什么”
- **修改前后对比**
  - 补录字段时同时展示 OCR 原值、系统建议值、用户当前填写值
- **提交后即时回执**
  - 用户点击继续/重试后，立即反馈“已受理、预计多久再次执行、不要重复提交”
- **一屏看完最近证据**
  - 待办详情首页直接展示合同编号、供应商、关键字段、最近错误截图、错误摘要
- **预计耗时提示**
  - 关键节点给出大概执行时长，降低业务等待焦虑
- **高风险动作撤回窗口**
  - 对“终止本单”“转人工处理”等动作，建议提供短时间撤回能力

### 4. OCR 与规则映射策略

一期默认**本地 OCR**，并预留适配层，后续可切云 OCR，但一期不依赖云能力。

OCR 输出必须是结构化 JSON，至少包含：

- `supplier_name`
- `planner_name`
- `contract_no`
- `settlement_text`
- `payment_term_text`
- `contract_validity`
- `items[]`
- `field_confidence{}`

映射与校验不在 RPA 平台里硬编码，统一放在状态中心配置表中。配置表至少包括：

- 供应商映射表
- 货品映射表
- 结算方式映射表
- 承付模式映射表
- 合同编号规则表
- 角色路由规则表
- 执行平台路由规则表

配置治理还需补充：

- 所有映射配置必须带版本号、生效时间、维护人
- 每个 `job` 在开始执行时要绑定一份映射版本快照
- 重试默认沿用原映射版本，除非人工明确选择“按最新配置重跑”
- 配置表变更要保留审计记录，不能直接覆盖无痕修改

承付模式映射规则一期采用“**规则优先 + 人工兜底**”：

- 精确命中字典表达，直接转系统编码
- 能识别 `N天` 的标准表达，拆成 `模式代码 + N`
- 无法稳定命中或置信度低于阈值，转 `WAITING_USER`
- 禁止在低置信度情况下自动猜测继续录入

### 5. 状态中心接口与数据实体

重要接口/公共契约如下：

- `POST /api/jobs`
  - 创建流程实例，入参为合同文件元数据和发起来源
- `POST /api/jobs/{jobId}/nodes/{nodeCode}/start`
  - RPA 平台或调度器上报节点开始
- `POST /api/jobs/{jobId}/nodes/{nodeCode}/complete`
  - 上报节点成功，附输出数据
- `POST /api/jobs/{jobId}/nodes/{nodeCode}/fail`
  - 上报失败，附错误码、截图、日志、是否可重试
- `POST /api/tasks/{taskId}/submit`
  - 手机端提交人工处理结果
- `POST /api/jobs/{jobId}/retry`
  - 人工或系统触发重试
- `POST /api/jobs/{jobId}/handoff`
  - 转人工或转其他角色
- `GET /api/jobs/{jobId}`
  - 查询整单状态与节点轨迹
- `GET /api/tasks/my`
  - 查询当前用户手机待办

#### 5.1 幂等与唯一键

状态中心必须承担幂等控制，不能把“是否重复执行”交给具体 RPA 平台临时判断。

至少要定义以下唯一键/幂等键：

- `job` 业务唯一键：建议由 `合同编号 + 合同类型 + 供应商 + 发起来源` 组合生成
- 入池幂等键：建议由 `文件哈希 + 文件名 + 上传时间窗` 组合生成
- 节点回调幂等键：`jobId + nodeCode + attemptNo + callbackType`
- 手机待办提交幂等键：`taskId + action + submitToken`

系统行为建议固定为：

- 未完成实例存在时，同业务键默认禁止重复建单
- 允许“重跑当前节点”，但不得覆盖历史节点记录
- 如需整单重跑，应新建新的 `job`，并关联原 `jobId`
- 历史 `job` 的 OCR 结果、截图、日志必须可追溯，不得被新单覆盖

核心实体至少包括：

- `job`：一份合同的一次全流程实例
- `job_node`：流程实例下的节点执行记录
- `user_task`：手机待办/人工处理单
- `mapping_config`：业务映射配置
- `executor_binding_config`：节点与执行平台绑定配置
- `job_artifact`：截图、OCR JSON、导入模板、日志文件
- `job_event`：状态变更事件流

建议增加的关键字段：

- `job.parent_job_id`：整单重跑或克隆来源
- `job.mapping_version`：执行时绑定的配置版本
- `job.executor_platform`：本单默认执行平台
- `job.source_file_hash`：源文件去重标识
- `job_node.attempt_no`：节点第几次尝试
- `job_node.executor_platform`：本次节点尝试由哪个平台执行
- `job_node.executor_run_id`：平台侧任务号/运行号
- `user_task.submit_token`：防重复提交令牌
- `job_artifact.artifact_type`：OCR JSON、截图、模板、日志等分类

### 6. 节点执行与重试策略

重试分三类：

- **系统型自动重试**
  - 页面超时、偶发网络异常、系统短暂不可用
  - 默认自动重试 1 到 2 次
- **业务型人工确认后重试**
  - 字段识别不确定、映射缺失、返利中心校验不通过
  - 手机待办确认后重试当前节点
- **人工接管**
  - 连续失败、逻辑分支超出机器人能力、系统规则变化
  - 标记为 `FAILED_MANUAL`，由人工线下处理，流程保留上下文

必须明确的失败分流：

- OCR 失败 -> 待办给计划员
- 合同编号无法匹配 -> 待办给计划员
- 返利中心模板导入失败 -> 待办给采购
- M5 因质管基础数据不全无法保存 -> 待办给质管
- 登录失败/控件定位失败/页面结构变化 -> 待办给运维
- 平台能力不满足当前节点要求 -> 待办给运维/项目负责人评估是否切换执行平台

#### 6.1 超时与升级策略

除失败分流外，还需要定义“长时间没人处理”与“节点卡住”的升级规则。

建议一期先定简单规则：

- OCR/映射类待办超过 30 分钟未处理 -> 再次通知当前角色
- 超过 2 小时未处理 -> 升级通知项目负责人/备岗人员
- 返利中心/M5 运行中节点超过阈值未回调 -> 标记超时异常并通知运维
- 夜间非工作时段是否升级，需按业务班次另行配置

所有升级动作都必须进入 `job_event` 留痕。

### 7. 业务可见性设计

一期不单独建设复杂 BI 看板，但状态中心必须支持后续扩展。当前可见性分两层：

- **企业微信消息流**
  - 面向业务个人，解决“手机知道发生了什么”
- **状态中心查询页**
  - 面向运维/项目负责人，按合同编号查看节点轨迹、截图、当前责任方、重试记录

查询页至少支持：

- 按日期/供应商/合同编号/状态筛选
- 查看当前卡点节点
- 查看待办归属角色与处理记录
- 查看 OCR 结果和映射结果
- 查看返利中心/M5 错误截图与日志摘要

#### 7.1 成功判定与结果回写口径

一期必须明确“节点成功”不是页面点完就算成功，而是拿到对应业务对象与校验结果。

至少要求：

- 合同系统成功：返回合同系统单号，且能查询到对应状态
- 返利中心总单成功：返回总单编号，且关键字段与输入一致
- 返利中心细单导入成功：返回导入行数、失败行数、失败原因摘要
- M5 成功：返回采购订单号
- 收货通知单生成成功：返回通知单号

建议状态中心在节点成功回调中强制要求携带：

- 业务单号
- 关键字段摘要
- 成功截图
- 校验结果

如仅有“操作已提交”但未取得业务编号，应落为中间态或待校验态，不能直接记 `SUCCESS`。

#### 7.3 多 RPA 切换策略

为了形成长期竞争力，一期方案支持“执行平台可替换”，但切换策略必须保守可控：

- 切换单位以“新单”或“节点配置”优先，不以“运行中半节点切换”为目标
- 每个节点先声明所需能力标签，例如 `desktop_ui`、`file_upload`、`excel_template`、`http_callback`
- 每个执行平台声明自己支持的能力标签
- 状态中心根据节点所需能力和平台可用能力决定路由
- 平台切换前必须通过统一验证清单：登录、检索、模板导入、截图/日志、HTTP 回调

这样做的目的不是追求脚本 100% 通用，而是确保：

- 业务流程不被单一厂商绑定
- 状态、待办、规则、证据统一留在我方系统
- 当成本、授权或稳定性发生变化时，可平滑更换底层执行平台

#### 7.4 面向业务方的竞争价值

多 RPA 可切换的价值，不只是技术选型灵活，更要落实到业务能感受到的收益：

- 不因单一工具变化而中断业务流程
- 同一套手机待办、同一套状态查询，不需要业务重新学一套系统
- 平台替换时，合同轨迹、截图、历史处理记录不会丢
- 某个平台不稳定时，可逐步把新单切到更稳的平台，业务侧感知更平滑
- 后续新增流程时，优先复用既有状态中心和手机协同能力，减少重复建设

#### 7.2 证据留存与权限控制

一期虽然不做复杂平台，但必须先把资料、日志和截图的留存规则定下来。

至少要明确：

- 合同原件、OCR JSON、返利模板、执行截图、运行日志分别存放在哪里
- 文件目录命名是否按 `jobId/节点/时间` 归档
- 保留时长与清理策略
- 哪些角色可查看合同原件，哪些只能看摘要/脱敏截图
- 企业微信消息中是否只放缩略图和链接，不直接下发完整合同文件

涉及合同和供应商信息时，建议默认：

- 手机端只展示必要摘要
- 完整附件放状态中心受控页面查看
- 所有下载和查看动作记录审计日志

## Test Plan

### 核心流程场景

1. 合同文件命名规范、字段完整、OCR 置信度高
   - 预期：全自动跑通到 M5 完成，无人工介入
2. OCR 成功但承付模式未命中字典
   - 预期：转计划员手机待办，补录后继续执行
3. 返利中心细单导入模板格式错误
   - 预期：节点失败，通知采购，可修正后重试当前节点
4. M5 保存时报质管未维护
   - 预期：转质管手机待办，修复后重试
5. 当前执行平台登录返利中心失败
   - 预期：自动重试后仍失败，转运维待办
6. 业务在手机端点击“转人工处理”
   - 预期：流程进入 `FAILED_MANUAL`，保留完整上下文
7. 同一合同重复发起
   - 预期：状态中心拦截或提示重复实例，避免重复录单
8. 合同系统未审核通过
   - 预期：流程停在审核前置节点，不进入返利中心
9. 企业微信待办重复点击提交
   - 预期：只推进一次，其余请求返回幂等结果
10. 返利中心细单部分导入成功、部分失败
   - 预期：记录成功/失败行明细，转采购判断是否修正后续跑
11. 入池文件命名不规范或缺页
   - 预期：不启动任何 RPA 平台，直接转计划员待办
12. 待办长时间未处理
   - 预期：按升级规则再次通知并记录事件
13. 新单切换到另一执行平台
   - 预期：状态中心仍可统一建单、回调、留痕与查询
14. 用户提交待办后立即收到受理回执
   - 预期：用户知道系统已接单、无需重复点击
15. 用户查看待办详情时可直接看懂错误原因
   - 预期：无需再去群里追问“这条待办要我干嘛”

### 接口与状态场景

1. 节点开始、成功、失败回调顺序正确
2. 同一节点重复回调具备幂等处理
3. 手机待办提交后只能推进一次，避免重复操作
4. 重试后产生新的节点执行记录，但保留历史失败记录
5. 企业微信消息与状态中心中的责任人、状态一致
6. 整单重跑会创建新的 `job`，并保留原 `job` 关联
7. 节点超时后会触发升级通知，不会无限停留在 `RUNNING`
8. 不同执行平台回调到状态中心时，状态口径与证据口径保持一致

### 验收标准

- 业务能在手机端知道每单当前跑到哪一步
- 关键不确定项不会被机器人“猜着填”
- 任何失败都能定位到具体节点、原因、截图和责任角色
- 一份合同从入池到 M5 完成的轨迹可完整追溯
- 能区分“本次只是操作提交”与“业务单号已真正生成”
- 同一合同不会因重复上传或重复点击而生成重复业务结果
- 不依赖 OpenClaw，也不依赖单一 RPA 厂商内置 OCR 即可完成一期

## Assumptions

- 一期默认只接入一个主执行平台上线，但架构上不与单一平台绑定
- 影刀、艺赛旗等候选平台是否正式接入，需以项目 POC 验证结果为准
- OpenClaw 一期不使用
- 企业微信可申请正式企业应用并支持消息、回调和待办入口
- 轻量服务技术栈固定为 Python + MySQL
- OCR 一期默认本地部署，优先按 PaddleOCR 设计
- 一期范围只覆盖 `合同 -> 返利中心 -> M5`
- 映射规则不再依赖 Excel，统一进入状态中心配置表
- 企业微信一期至少可提供消息卡片、H5 处理入口、身份识别与回调能力
- 合同扫描件默认来自共享目录或状态中心手工入池，不考虑邮件自动收件作为一期入口
- 业务目标是“尽量全自动”，但 OCR/映射不确定项必须转手机待办，不做自动猜测