# 采购主链 RPA 一期 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 建成采购主链一期的轻量状态中心、统一 RPA 执行适配层、企业微信手机协同入口，以及支撑 OCR、返利中心、M5 流程追踪的最小可用中台。

**Architecture:** 采用“RPA 执行平台 + Python/MySQL 状态中心 + 本地 OCR + 企业微信 H5 协同”的分层方案。状态中心负责建单、节点状态机、幂等、待办、日志、审计和执行平台路由，底层 RPA 平台只负责外部系统操作与结果回传，企业微信只负责通知与手机端操作入口。

**Tech Stack:** Python、MySQL、HTTP API、RPA 执行平台（影刀 / 艺赛旗等）、企业微信应用、本地 OCR（PaddleOCR 优先）

---

## 0. 使用说明

本文件既可作为技术实施底稿，也可作为后续拆更细执行计划的母稿。

## 1. 文档定位

本文面向开发、测试、实施和项目负责人，目标是把 [PLAN.md](/Users/yuuuu/Documents/AutoRpa/资料/PLAN.md) 进一步落成“可排期、可拆人、可建库、可对接口”的实施稿。

默认前提：

- 一期范围只覆盖 `合同扫描件/合同系统 -> 返利中心采购协议 -> M5 采购订单`
- RPA 执行平台负责页面操作
- Python + MySQL 负责状态中心
- 企业微信负责消息通知和 H5 处理入口
- OCR 一期采用本地部署方案

如果后续要正式开工，建议以本文件作为技术排期底稿，再补充具体工期、负责人和环境信息。

---

## 2. 推荐项目结构

当前仓库还没有正式代码结构，一期建议直接按下面的边界建工程，避免把流程编排、RPA 平台回调、企业微信回调、查询页混在一起。

```text
AutoRpa/
├── 资料/
│   ├── PLAN.md
│   ├── 一期开发任务清单_表结构_API草案.md
│   └── 一期需求简版说明_业务版.md
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── db.py
│   │   ├── models/
│   │   │   ├── job.py
│   │   │   ├── job_node.py
│   │   │   ├── user_task.py
│   │   │   ├── mapping_config.py
│   │   │   ├── job_artifact.py
│   │   │   └── job_event.py
│   │   ├── schemas/
│   │   │   ├── job.py
│   │   │   ├── task.py
│   │   │   ├── node_callback.py
│   │   │   └── wecom.py
│   │   ├── api/
│   │   │   ├── jobs.py
│   │   │   ├── tasks.py
│   │   │   ├── admin.py
│   │   │   └── wecom.py
│   │   ├── services/
│   │   │   ├── intake_service.py
│   │   │   ├── workflow_service.py
│   │   │   ├── retry_service.py
│   │   │   ├── task_service.py
│   │   │   ├── executor_router.py
│   │   │   ├── ocr_service.py
│   │   │   ├── mapping_service.py
│   │   │   ├── artifact_service.py
│   │   │   └── wecom_service.py
│   │   ├── integrations/
│   │   │   ├── rpa/
│   │   │   │   ├── base_adapter.py
│   │   │   │   ├── yingdao_adapter.py
│   │   │   │   └── isearch_adapter.py
│   │   │   ├── paddle_ocr_client.py
│   │   │   └── wecom_client.py
│   │   └── views/
│   │       └── h5_task_page.py
│   ├── migrations/
│   └── tests/
│       ├── api/
│       ├── services/
│       └── integration/
├── agent-contract/
│   ├── node_callback_examples.json
│   └── error_codes.md
└── deployment/
    ├── env.example
    ├── nginx.conf
    └── systemd/
```

边界原则：

- `api/` 只收发请求，不放业务流程判断
- `services/` 负责状态迁移、幂等、路由、重试、消息发送
- `integrations/` 只封装外部系统调用
- `executor_router.py` 统一决定节点该交给哪个平台执行
- `models/` 和 `schemas/` 分开，避免数据库对象和接口对象互相污染

---

## 3. 自有能力边界与多平台策略

我们自己的能力必须沉淀在状态中心中：

- 流程主状态
- 合同入池、判重、幂等
- OCR 归档和映射配置
- 手机待办、人工协同、角色路由
- 成功判定、错误码体系、证据归档
- 多平台统一查询和统一审计

RPA 平台提供的是底层执行能力：

- 桌面/UI 自动化
- 文件上传下载
- 表单填写与模板导入
- 截图、日志、录屏
- 对状态中心发起回调

多平台切换边界必须明确：

- 支持“按新单切换平台”
- 支持“按节点配置平台”
- 不支持“半节点执行过程中跨平台接力”
- 平台切换前先跑统一 POC 用例

---

## 4. 里程碑与开发任务清单

## Milestone 0：项目初始化与基础设施

目标：把后端服务、数据库连接、配置管理、日志规范先搭起来。

任务清单：

1. 创建 `backend/app/main.py`，跑通基础 HTTP 服务
2. 创建 `backend/app/config.py`，统一读取数据库、OCR、企业微信、RPA 平台回调密钥配置
3. 创建 `backend/app/db.py`，封装 MySQL 连接和事务入口
4. 建立 `backend/tests/` 目录，先接入最基础的接口测试框架
5. 创建 `deployment/env.example`，列出所有必需环境变量
6. 定义统一日志字段：`trace_id`、`job_id`、`node_code`、`task_id`

交付物：

- 服务能启动
- 健康检查接口可用
- 数据库连接可用
- 开发/测试环境变量模板可发给团队

## Milestone 1：入池建单与判重

目标：把“共享目录文件 -> 状态中心建单 -> 判重 -> 可追踪 job”跑通。

任务清单：

1. 建 `job`、`job_artifact`、`job_event` 三张核心表
2. 开发 `POST /api/jobs` 建单接口
3. 开发共享目录文件入池服务，读取文件基础元数据
4. 实现文件哈希计算与 `source_file_hash` 去重逻辑
5. 实现业务唯一键判重逻辑：`合同编号 + 合同类型 + 供应商 + 发起来源`
6. 入池失败时生成事件记录和人工待处理状态
7. 支持通过状态中心页面手工建单，作为共享目录监听的兜底入口

交付物：

- 同一合同重复上传不会生成多条未完成流程
- 文件命名异常可被识别并阻断
- 每次建单都有 `job_id`

## Milestone 2：OCR 与映射规则

目标：把扫描件变成结构化字段，并明确哪些能自动映射、哪些必须转人工。

任务清单：

1. 创建 `mapping_config` 表和版本字段
2. 建立 OCR 适配接口，统一输出 JSON
3. 保存原始 OCR JSON 到 `job_artifact`
4. 实现供应商、货品、结算方式、承付模式映射服务
5. 实现置信度阈值判断和低置信度转待办逻辑
6. 为每个 `job` 绑定 `mapping_version`
7. 把字段识别结果、映射结果写入 `job_event`

交付物：

- OCR 结果可追溯
- 映射规则支持版本化
- 低置信度不会自动猜测后继续执行

## Milestone 3：流程编排与节点状态机

目标：把节点开始、成功、失败、待人工、重试这些规则稳定下来。

任务清单：

1. 创建 `job_node` 表
2. 定义节点状态枚举与状态迁移规则
3. 定义节点尝试号 `attempt_no`
4. 开发节点开始接口 `POST /api/jobs/{jobId}/nodes/{nodeCode}/start`
5. 开发节点成功接口 `POST /api/jobs/{jobId}/nodes/{nodeCode}/complete`
6. 开发节点失败接口 `POST /api/jobs/{jobId}/nodes/{nodeCode}/fail`
7. 实现节点回调幂等控制
8. 实现节点超时扫描与升级策略

交付物：

- 节点不会重复推进
- 同一节点重复回调时可安全去重
- 失败与超时都能落事件

## Milestone 4：RPA 执行适配层与统一契约

目标：让底层 RPA 平台只做执行，不做流程主状态判断，并具备可切换能力。

任务清单：

1. 输出 `agent-contract/node_callback_examples.json`
2. 定义统一的 `base_adapter` 接口
3. 实现 `yingdao_adapter` 与 `isearch_adapter` 骨架
4. 定义平台回调鉴权方式
5. 约定统一回传字段：错误码、截图路径、日志路径、录屏路径、输出业务单号
6. 约定节点编码字典，例如 `OCR_EXTRACT`、`REBATE_IMPORT_ITEMS`、`M5_CREATE_ORDER`
7. 定义平台失败错误码分层：系统类、业务类、配置类、页面变化类、能力不满足类
8. 为每个节点定义能力标签，例如 `desktop_ui`、`file_upload`、`excel_template`、`http_callback`
9. 制作联调用的假回调脚本或 Postman 集合

交付物：

- 不同平台都可以按统一 JSON 回调
- 开发和平台实施同学对节点编码、错误码、能力标签理解一致

## Milestone 5：手机待办、企业微信与 H5 页面

目标：让业务能在手机端收到通知、看上下文、补字段、继续或转人工。

任务清单：

1. 创建 `user_task` 表
2. 实现角色路由规则：计划员、采购、质管、运维
3. 开发 `GET /api/tasks/my`
4. 开发 `POST /api/tasks/{taskId}/submit`
5. 开发 `POST /api/jobs/{jobId}/handoff`
6. 开发企业微信消息发送与模版卡片更新
7. 开发“人话状态”和“错误翻译”展示逻辑
8. 开发 H5 处理页，展示关键字段、截图、待办动作
9. 开发“为什么发给你”“修改前后对比”“提交后即时回执”
10. 接入企业微信身份识别
11. 为待办提交增加 `submit_token`，防止重复点击重复推进
12. 为高风险动作增加短时间撤回设计

交付物：

- 业务能在企业微信打开待办详情
- 人工提交只能推进一次
- 所有修改留痕
- 用户能看懂待办原因、知道该怎么处理、处理后知道系统已受理

## Milestone 6：查询页、审计与运维能力

目标：让项目负责人和运维能查问题、追流程、看证据。

任务清单：

1. 开发 `GET /api/jobs/{jobId}`
2. 开发按合同编号、供应商、日期、状态筛选列表接口
3. 展示节点轨迹、责任角色、重试记录
4. 展示 OCR 结果、映射结果、截图和日志摘要
5. 增加人工重试接口 `POST /api/jobs/{jobId}/retry`
6. 增加“整单重跑”能力，生成新的 `job`
7. 增加查看/下载审计日志

交付物：

- 出问题时能快速看出卡在哪一层
- 能区分当前实例和历史重跑实例

## Milestone 7：测试、联调与上线准备

目标：把关键链路和关键失败场景都压一遍。

任务清单：

1. 覆盖全自动正向场景
2. 覆盖 OCR 低置信度转计划员场景
3. 覆盖返利中心模板部分失败场景
4. 覆盖 M5 质管基础资料不全场景
5. 覆盖不同平台回调重复提交场景
6. 覆盖企业微信待办重复提交场景
7. 覆盖共享目录重复上传场景
8. 覆盖节点超时升级场景
9. 覆盖新单切换执行平台场景
10. 输出上线切换清单、回滚清单、账号权限清单

交付物：

- 联调报告
- UAT 场景清单
- 上线/回滚 checklist

---

## 5. 表结构草案

说明：下面是一期最低可用表结构，不追求一次做成大而全平台，先满足幂等、留痕、查询和待办协同。

### 4.1 `job`

一份合同的一次流程实例。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint PK | 主键 |
| job_id | varchar(64) unique | 对外流程单号 |
| business_key | varchar(128) | 业务唯一键 |
| parent_job_id | varchar(64) null | 重跑来源 |
| source_type | varchar(32) | shared_folder/manual_upload |
| source_file_name | varchar(255) | 原始文件名 |
| source_file_hash | varchar(64) | 原始文件哈希 |
| contract_type | varchar(32) | 年度协议/批次合同 |
| contract_no | varchar(64) null | 合同编号 |
| supplier_name | varchar(128) null | 供应商名称 |
| planner_name | varchar(64) null | 计划员 |
| current_node_code | varchar(64) | 当前节点 |
| status | varchar(32) | PENDING/RUNNING/WAITING_USER/... |
| mapping_version | varchar(64) null | 映射配置版本 |
| executor_platform | varchar(32) null | 默认执行平台 |
| contract_system_no | varchar(64) null | 合同系统单号 |
| rebate_order_no | varchar(64) null | 返利中心总单号 |
| m5_order_no | varchar(64) null | M5 采购订单号 |
| receipt_notice_no | varchar(64) null | 收货通知单号 |
| current_role | varchar(32) null | 当前责任角色 |
| current_assignee | varchar(64) null | 当前责任人 |
| created_by | varchar(64) | 发起人或系统 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
| finished_at | datetime null | 完成时间 |

索引建议：

- `uniq_job_business_open`：`business_key + status`
- `idx_job_contract_no`
- `idx_job_supplier_status`
- `idx_job_created_at`

### 4.2 `job_node`

记录每个节点每次尝试。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint PK | 主键 |
| job_id | varchar(64) | 流程单号 |
| node_code | varchar(64) | 节点编码 |
| attempt_no | int | 第几次执行 |
| status | varchar(32) | 节点状态 |
| executor_platform | varchar(32) null | 实际执行平台 |
| executor_run_id | varchar(64) null | 平台侧任务号 |
| started_at | datetime null | 开始时间 |
| ended_at | datetime null | 结束时间 |
| duration_ms | bigint null | 耗时 |
| error_code | varchar(64) null | 错误码 |
| error_summary | varchar(500) null | 错误摘要 |
| role_at_failure | varchar(32) null | 失败时责任角色 |
| assignee_at_failure | varchar(64) null | 失败时责任人 |
| output_json | json null | 节点输出 |
| callback_idempotency_key | varchar(128) null | 回调幂等键 |
| created_at | datetime | 创建时间 |

索引建议：

- `uniq_job_node_attempt`
- `idx_job_node_status`

### 4.3 `user_task`

企业微信/H5 里的人工处理单。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint PK | 主键 |
| task_id | varchar(64) unique | 待办编号 |
| job_id | varchar(64) | 所属流程 |
| node_code | varchar(64) | 对应节点 |
| role_code | varchar(32) | 目标角色 |
| assignee_user_id | varchar(64) null | 当前处理人 |
| title | varchar(255) | 待办标题 |
| reason_type | varchar(32) | OCR_LOW_CONF/REBATE_FAIL/... |
| reason_summary | varchar(500) | 待办原因 |
| reason_user_friendly | varchar(500) | 面向业务的人话说明 |
| why_me_text | varchar(255) | 为什么发给当前角色/当前人 |
| editable_fields_json | json | 白名单字段 |
| action_schema_json | json | 允许动作 |
| comparison_snapshot_json | json null | 原值/建议值/当前值对比 |
| status | varchar(32) | OPEN/SUBMITTED/CANCELLED/EXPIRED |
| submit_token | varchar(64) | 防重复令牌 |
| submitted_action | varchar(32) null | 继续/重试/转人工/终止 |
| submitted_payload_json | json null | 人工提交内容 |
| submitted_by | varchar(64) null | 提交人 |
| submitted_at | datetime null | 提交时间 |
| due_at | datetime null | 超时升级时间 |
| created_at | datetime | 创建时间 |

### 4.4 `mapping_config`

映射规则表，一期可以先做统一表，后续再拆子表。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint PK | 主键 |
| config_key | varchar(128) | 业务键 |
| config_type | varchar(32) | supplier/item/settlement/payment_term/route |
| source_value | varchar(255) | 来源值 |
| target_value | varchar(255) | 目标值 |
| extra_json | json null | 扩展参数 |
| version_no | varchar(64) | 版本号 |
| is_active | tinyint | 是否生效 |
| effective_from | datetime | 生效时间 |
| effective_to | datetime null | 失效时间 |
| updated_by | varchar(64) | 更新人 |
| updated_at | datetime | 更新时间 |

### 4.5 `executor_binding_config`

节点与执行平台路由配置。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint PK | 主键 |
| node_code | varchar(64) | 节点编码 |
| preferred_platform | varchar(32) | 首选平台 |
| fallback_platform | varchar(32) null | 备用平台 |
| required_capabilities_json | json | 所需能力标签 |
| route_policy | varchar(32) | FIXED / PREFERRED / FALLBACK |
| is_active | tinyint | 是否生效 |
| updated_by | varchar(64) | 更新人 |
| updated_at | datetime | 更新时间 |

### 4.6 `job_artifact`

存证表。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint PK | 主键 |
| job_id | varchar(64) | 流程单号 |
| node_code | varchar(64) null | 所属节点 |
| artifact_type | varchar(32) | SOURCE_FILE/OCR_JSON/SCREENSHOT/TEMPLATE/LOG |
| storage_path | varchar(500) | 存储路径 |
| file_name | varchar(255) | 文件名 |
| file_hash | varchar(64) null | 文件哈希 |
| is_masked | tinyint | 是否脱敏 |
| visible_roles_json | json | 可见角色 |
| created_at | datetime | 创建时间 |

### 4.7 `job_event`

事件流表，用来查轨迹。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint PK | 主键 |
| job_id | varchar(64) | 流程单号 |
| node_code | varchar(64) null | 节点 |
| event_type | varchar(64) | JOB_CREATED/NODE_FAILED/TASK_CREATED/... |
| event_summary | varchar(500) | 事件摘要 |
| event_payload_json | json null | 事件详情 |
| operator_type | varchar(32) | SYSTEM/ROBOT/USER |
| operator_id | varchar(64) | 操作人 |
| created_at | datetime | 创建时间 |

---

## 5. MySQL DDL 示例

以下 DDL 不是最终生产版，但足够作为建库初稿。

```sql
CREATE TABLE job (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  job_id VARCHAR(64) NOT NULL UNIQUE,
  business_key VARCHAR(128) NOT NULL,
  parent_job_id VARCHAR(64) NULL,
  source_type VARCHAR(32) NOT NULL,
  source_file_name VARCHAR(255) NOT NULL,
  source_file_hash VARCHAR(64) NOT NULL,
  contract_type VARCHAR(32) NOT NULL,
  contract_no VARCHAR(64) NULL,
  supplier_name VARCHAR(128) NULL,
  planner_name VARCHAR(64) NULL,
  current_node_code VARCHAR(64) NOT NULL,
  status VARCHAR(32) NOT NULL,
  mapping_version VARCHAR(64) NULL,
  executor_platform VARCHAR(32) NULL,
  contract_system_no VARCHAR(64) NULL,
  rebate_order_no VARCHAR(64) NULL,
  m5_order_no VARCHAR(64) NULL,
  receipt_notice_no VARCHAR(64) NULL,
  current_role VARCHAR(32) NULL,
  current_assignee VARCHAR(64) NULL,
  created_by VARCHAR(64) NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  finished_at DATETIME NULL,
  KEY idx_job_contract_no (contract_no),
  KEY idx_job_supplier_status (supplier_name, status),
  KEY idx_job_created_at (created_at)
);

CREATE TABLE job_node (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  job_id VARCHAR(64) NOT NULL,
  node_code VARCHAR(64) NOT NULL,
  attempt_no INT NOT NULL,
  status VARCHAR(32) NOT NULL,
  executor_platform VARCHAR(32) NULL,
  executor_run_id VARCHAR(64) NULL,
  started_at DATETIME NULL,
  ended_at DATETIME NULL,
  duration_ms BIGINT NULL,
  error_code VARCHAR(64) NULL,
  error_summary VARCHAR(500) NULL,
  role_at_failure VARCHAR(32) NULL,
  assignee_at_failure VARCHAR(64) NULL,
  output_json JSON NULL,
  callback_idempotency_key VARCHAR(128) NULL,
  created_at DATETIME NOT NULL,
  UNIQUE KEY uniq_job_node_attempt (job_id, node_code, attempt_no)
);

CREATE TABLE user_task (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  task_id VARCHAR(64) NOT NULL UNIQUE,
  job_id VARCHAR(64) NOT NULL,
  node_code VARCHAR(64) NOT NULL,
  role_code VARCHAR(32) NOT NULL,
  assignee_user_id VARCHAR(64) NULL,
  title VARCHAR(255) NOT NULL,
  reason_type VARCHAR(32) NOT NULL,
  reason_summary VARCHAR(500) NOT NULL,
  editable_fields_json JSON NOT NULL,
  action_schema_json JSON NOT NULL,
  status VARCHAR(32) NOT NULL,
  submit_token VARCHAR(64) NOT NULL,
  submitted_action VARCHAR(32) NULL,
  submitted_payload_json JSON NULL,
  submitted_by VARCHAR(64) NULL,
  submitted_at DATETIME NULL,
  due_at DATETIME NULL,
  created_at DATETIME NOT NULL
);
```

---

## 6. API 草案

说明：接口统一由状态中心对外提供，RPA 平台、H5 页面、企业微信回调都走状态中心，不允许直接改数据库。

鉴权建议：

- 内部服务接口：`Authorization: Bearer <service-token>`
- RPA 平台回调接口：`X-Agent-Token`
- H5 用户接口：企业微信身份换取后端 session 或 JWT
- 幂等写接口：增加 `X-Idempotency-Key`

### 6.1 建单接口

`POST /api/jobs`

用途：

- 共享目录监听器建单
- 状态中心手工上传建单

请求示例：

```json
{
  "sourceType": "shared_folder",
  "sourceFileName": "20260625_国药控股_张三_批次合同_01.pdf",
  "sourceFileHash": "6f6f5d8c...",
  "contractType": "BATCH",
  "supplierName": "国药控股",
  "plannerName": "张三",
  "executorPlatform": "YINGDAO",
  "createdBy": "system-folder-watcher",
  "artifacts": [
    {
      "artifactType": "SOURCE_FILE",
      "storagePath": "/data/jobs/inbox/20260625_国药控股_张三_批次合同_01.pdf"
    }
  ]
}
```

响应示例：

```json
{
  "jobId": "JOB202606260001",
  "status": "PENDING",
  "currentNodeCode": "FILE_INTAKE"
}
```

### 6.2 节点开始

`POST /api/jobs/{jobId}/nodes/{nodeCode}/start`

请求示例：

```json
{
  "attemptNo": 1,
  "executorPlatform": "YINGDAO",
  "operator": "yingdao-agent-01",
  "startedAt": "2026-06-26T10:00:00+08:00"
}
```

### 6.3 节点成功

`POST /api/jobs/{jobId}/nodes/{nodeCode}/complete`

请求示例：

```json
{
  "attemptNo": 1,
  "executorPlatform": "YINGDAO",
  "executorRunId": "YD-RUN-20260626-001",
  "endedAt": "2026-06-26T10:03:25+08:00",
  "businessRefs": {
    "contractSystemNo": "HT20260626018",
    "rebateOrderNo": "FL20260626009",
    "m5OrderNo": null,
    "receiptNoticeNo": null
  },
  "summary": {
    "importedItemCount": 18,
    "failedItemCount": 0
  },
  "artifacts": [
    {
      "artifactType": "SCREENSHOT",
      "storagePath": "/data/jobs/JOB202606260001/REBATE_IMPORT_ITEMS/success.png"
    }
  ]
}
```

约束：

- 如果没有业务编号且节点本身要求有编号，则不能直接记 `SUCCESS`

### 6.4 节点失败

`POST /api/jobs/{jobId}/nodes/{nodeCode}/fail`

请求示例：

```json
{
  "attemptNo": 1,
  "executorPlatform": "YINGDAO",
  "executorRunId": "YD-RUN-20260626-001",
  "endedAt": "2026-06-26T10:05:01+08:00",
  "errorCode": "REBATE_TEMPLATE_PARTIAL_FAIL",
  "errorSummary": "18 行中有 3 行校验失败",
  "retryable": false,
  "routeRole": "PURCHASER",
  "artifacts": [
    {
      "artifactType": "SCREENSHOT",
      "storagePath": "/data/jobs/JOB202606260001/REBATE_IMPORT_ITEMS/error.png"
    },
    {
      "artifactType": "LOG",
      "storagePath": "/data/jobs/JOB202606260001/REBATE_IMPORT_ITEMS/agent.log"
    }
  ]
}
```

### 6.5 我的待办

`GET /api/tasks/my`

查询参数建议：

- `status=open`
- `roleCode=PLANNER`
- `pageNo=1`
- `pageSize=20`

响应字段建议：

- `taskId`
- `jobId`
- `title`
- `reasonSummary`
- `reasonUserFriendly`
- `whyMeText`
- `nodeCode`
- `supplierName`
- `contractNo`
- `dueAt`
- `detailUrl`

### 6.6 待办提交

`POST /api/tasks/{taskId}/submit`

请求示例：

```json
{
  "submitToken": "9f5f2c1d",
  "action": "CONFIRM_AND_CONTINUE",
  "payload": {
    "paymentModeCode": "2",
    "paymentModeDays": 30,
    "settlementCode": "3"
  },
  "comment": "已根据合同正文修正承付模式"
}
```

动作枚举建议：

- `CONFIRM_AND_CONTINUE`
- `RETRY_CURRENT_NODE`
- `TRANSFER_MANUAL`
- `TERMINATE_JOB`

提交成功后的响应，建议额外返回：

- `accepted`: 是否已受理
- `receiptMessage`: 给用户看的即时回执
- `nextExpectedAction`: 系统接下来会做什么
- `estimatedWaitMinutes`: 预计多久有下一次结果

### 6.7 重试当前节点

`POST /api/jobs/{jobId}/retry`

请求示例：

```json
{
  "scope": "CURRENT_NODE",
  "operatorId": "zhangsan",
  "reason": "计划员已修正承付模式，允许重试"
}
```

### 6.8 转派/转人工

`POST /api/jobs/{jobId}/handoff`

请求示例：

```json
{
  "targetRole": "OPS",
  "targetUserId": "wangwu",
  "reason": "返利中心页面结构变化，需要机器人管理员处理"
}
```

### 6.9 查询整单

`GET /api/jobs/{jobId}`

返回建议包含：

- `job` 基础信息
- 当前状态
- 节点轨迹数组
- 当前待办数组
- 关键业务编号
- OCR 摘要
- 映射摘要
- 证据文件列表
- 执行平台与平台侧运行号

### 6.10 企业微信回调

`POST /api/wecom/callback`

用途：

- 卡片动作回调
- 身份事件回调

注意：

- 回调只负责接收动作和身份，不直接写业务结果
- 必须先换成状态中心标准动作，再调用内部任务提交逻辑

---

## 7. H5 页面草案

页面最低能力建议：

1. 显示合同基础信息：合同编号、供应商、计划员、当前节点
2. 显示“当前系统正在做什么”的人话状态
3. 显示 OCR 关键字段和置信度
4. 显示最近错误截图和业务可读错误说明
5. 显示“为什么发给你”
6. 显示允许修改的字段和修改前后对比
7. 显示操作按钮：继续、重试、转人工、终止
8. 显示处理历史和最近一次失败原因
9. 提交动作后显示即时回执，避免重复点击

页面路由建议：

- `/h5/tasks/{taskId}`
- `/h5/jobs/{jobId}`

---

## 8. 平台接入 POC 清单

任何新 RPA 平台接入前，先做下面的最小验证：

1. 登录目标系统并打开指定页面
2. 读取一份合同字段并调用一次外部 HTTP API
3. 在返利中心完成一次模板导入
4. 失败时自动截图并回调到状态中心
5. 验证平台日志、录屏和运行号能被统一采集

通过后，才允许接入正式流程路由。

## 9. 联调顺序建议

建议不要一上来就四方一起联调，按下面顺序推进更稳：

1. 状态中心单独完成建单、节点流转、待办流转
2. 先用假 OCR 和假 RPA 回调，把流程跑通
3. 接入真实 OCR
4. 接入真实企业微信消息和 H5 身份
5. 最后接入真实 RPA 流程
6. 再做返利中心/M5 端到端联调

---

## 10. 测试重点

接口测试重点：

- 重复建单
- 重复回调
- 重复待办提交
- 非法状态迁移
- 低置信度转待办
- 整单重跑

集成测试重点：

- OCR 返回空字段
- 返利中心部分导入失败
- M5 保存失败
- 企业微信回调延迟或重复
- 节点长时间未回调

UAT 重点：

- 计划员在手机端补录后能继续执行
- 采购能看到失败明细和截图
- 质管收到问题后只做基础资料确认
- 运维能定位页面变化或登录失效
- 待办文案是否足够人话，业务无需培训也能理解主要动作
- 用户提交后是否明确感知“系统已受理”

---

## 11. 上线前必补清单

以下内容现在还没落在代码里，但上线前必须补齐：

1. 企业微信应用信息、回调域名、可信域名
2. 共享目录所在服务器、权限和目录清理规则
3. 合同附件的访问权限与脱敏策略
4. 执行平台运行节点、账号和截图/录屏落盘路径
5. 返利中心与 M5 的测试账号、生产账号隔离
6. 错误码清单和责任角色映射表
7. 环境监控：服务存活、数据库连接、磁盘容量、回调异常告警

---

## 12. 建议下一步

如果要继续推进，建议按下面顺序立刻开工：

1. 先定表结构和节点编码
2. 再定统一 RPA 回调 JSON 契约和能力标签
3. 再做企业微信“H5 待办页”原型和人性化文案
4. 然后并行开发：状态中心后端、RPA 平台适配器、企业微信消息联调

这份文档适合作为技术 kickoff 和任务拆分底稿。