608 lines
31 KiB
Markdown
608 lines
31 KiB
Markdown
# 采购主链 RPA 一期设计文档（技术设计 / HLD+LLD）
|
||
|
||
> 用途：把《采购主链RPA一期需求文档_三方会审版》（业务规则）和《采购主链RPA一期开发规划》（排期与阶段）落成**可建库、可对接口、可分工**的技术设计底稿。
|
||
> 关系说明：本文取代早期《一期开发任务清单_表结构_API草案.md》的**架构与数据模型部分**——该草案工程框架扎实，但建立在"合同文件入池→OCR→映射"的错误骨架上，缺**订单驱动主线、产品对码、三来源分流**。本文保留其状态机/幂等/证据/待办思想，按订单驱动重排实体与节点。
|
||
> 术语：状态中心 = 我们自研的编排与审计中台；执行器 = RPA 平台（影刀/来也等）；对码 = 电商药品匹配到 M5 货品ID/编码。
|
||
|
||
---
|
||
|
||
## 一、设计目标与非目标
|
||
|
||
### 1.1 设计目标
|
||
1. **订单驱动**：以电商订单（医药城/小药药）导出为入口，线下手工单为 OCR 分支，贯穿到 M5 录入待保存。
|
||
2. **分层解耦**：业务规则、状态机、审计、对码口径掌握在状态中心；RPA 平台仅做页面执行，可替换。
|
||
3. **对码可迭代**：对码表版本化、累积迭代，未命中一对多转人工，命中率可统计。
|
||
4. **不可逆保护**：一期末端"保存/签订/生成收货通知单"由人工执行，自动化做成配置开关。
|
||
5. **可追溯**：订单号→合同号→返利总单号→M5单号→收货通知单号全链路可查，每节点留证。
|
||
|
||
### 1.2 非目标（一期不做）
|
||
- 招财平台接入。
|
||
- M5 自动保存/签订（阶段三才放开，本期只留开关）。
|
||
- 加单/拆单的全自动重做（父订单号先记录，处理转人工，待确认）。
|
||
- 返利中心重复订单的全自动重建（规则未讲完，先转人工）。
|
||
|
||
---
|
||
|
||
## 二、系统架构
|
||
|
||
### 2.1 分层架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 人工协同层 │
|
||
│ 企业微信应用消息/群机器人 + H5待办页(Vue/React) │
|
||
│ 待办推送 / 一对多对码选择 / 人工检查入口 / 修改留痕 │
|
||
└───────────────▲─────────────────────────────▲───────────────┘
|
||
│ 待办/回执 │ OAuth身份
|
||
┌───────────────┴─────────────────────────────┴───────────────┐
|
||
│ 状态中心（自研，核心资产） │
|
||
│ ┌──────────┬──────────┬──────────┬──────────┬────────────┐ │
|
||
│ │ 建单入池 │ 状态机 │ 对码引擎 │ 待办路由 │ 审计/证据 │ │
|
||
│ │ 幂等去重 │ 编排调度 │ mapping │ 角色分派 │ 事件流 │ │
|
||
│ └──────────┴──────────┴──────────┴──────────┴────────────┘ │
|
||
│ 统一节点契约 / 回调接口 / 执行平台路由 / 查询审计 API │
|
||
└──────▲───────────────▲──────────────────▲───────────────────┘
|
||
│ HTTP回调 │ OCR调用 │ 平台路由
|
||
┌──────┴──────┐ ┌──────┴──────┐ ┌───────┴─────────────────┐
|
||
│ RPA执行器 │ │ OCR服务 │ │ 对象存储(MinIO/NAS) │
|
||
│ 影刀/来也 │ │ PaddleOCR │ │ 合同PDF/截图/OCR JSON │
|
||
│ 登录/导出/ │ │ (本地优先) │ │ 证据目录 │
|
||
│ 建单/导入/ │ └─────────────┘ └─────────────────────────┘
|
||
│ 截图/上传 │
|
||
└──────▲──────┘
|
||
│ 操作
|
||
┌──────┴───────────────────────────────────────────────────────┐
|
||
│ 外部业务系统（RPA 通过 UI 操作，非 API 集成） │
|
||
│ 医药城 │ 小药药 │ 合同系统 contract.gzmpc.com │ 返利中心 │
|
||
│ │ │ │ flgzmpc.com │
|
||
│ M5(INCA) 采购订单管理 1055 │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 组件职责边界
|
||
|
||
| 组件 | 职责 | 明确不做 |
|
||
| --- | --- | --- |
|
||
| **状态中心** | job 生命周期、状态机流转、对码、幂等、待办路由、证据审计、平台路由、统一查询 | 不直接操作外部系统页面 |
|
||
| **RPA 执行器** | 登录/导出Excel/建合同/PDF合并上传/返利导入/M5录入/截图/文件读写/HTTP回调 | 不做流程主状态判断、不做业务规则决策 |
|
||
| **OCR 服务** | 线下手工单图片→结构化字段 JSON + 置信度 | 仅线下单，线上走 Excel 不经 OCR |
|
||
| **企业微信/H5** | 待办通知、一对多选择、人工确认、修改留痕、身份识别 | 不直接写业务结果，须经状态中心标准动作 |
|
||
| **对象存储** | 合同PDF、截图、OCR JSON、日志等证据落盘 | — |
|
||
|
||
**关键设计原则**：RPA 平台"半节点执行过程中不跨平台接力"；支持"按新单切换平台""按节点配置平台"；切换前跑统一 POC 用例。
|
||
|
||
### 2.3 技术选型（推荐，可依公司栈调整）
|
||
|
||
| 层 | 采用 | 备选 |
|
||
| --- | --- | --- |
|
||
| 状态中心 | Python 3 + FastAPI（开发快、与 OCR/对码脚本同栈、Pydantic 校验回调契约方便） | Java + Spring Boot |
|
||
| 数据库 | MySQL 8（状态中心自有库，只存流程状态+累积别名+证据） | PostgreSQL |
|
||
| 状态机 | 轻量自实现（NODE_ORDER 顺序驱动 + 7 状态枚举） | — |
|
||
| 对象存储 | MinIO / 公司现有 NAS | 本地文件系统 |
|
||
| RPA | 影刀 / 来也UiBot / 艺赛旗 择一 POC | — |
|
||
| OCR | PaddleOCR 本地部署（无信息安全顾虑） | 阿里/腾讯云OCR |
|
||
| 前端 | Vue/React + 企业微信 OAuth | — |
|
||
|
||
> 注：状态中心确定采用 **Python 3 + FastAPI + MySQL 8**，骨架代码在 `state_center/`（建库脚本、对码引擎、三回调、整单查询已跑通）。若后续团队要平移到 Java+Spring Boot，数据模型与接口契约保持不变即可。
|
||
|
||
### 2.4 部署拓扑
|
||
|
||
```
|
||
公司内网（与业务系统同网段，便于 RPA 访问）
|
||
├── 状态中心服务(容器/虚机) ── MySQL主 ── 对象存储MinIO
|
||
├── OCR服务(本地GPU/CPU) [仅阶段2.2线下单启用]
|
||
├── RPA运行机(独立虚机, 保持登录态, 定时/7×24)
|
||
└── 企业微信应用(内网可信域名 + H5静态站)
|
||
```
|
||
|
||
安全边界：
|
||
- RPA 回调接口用 `X-Agent-Token`；内部服务用 `Bearer service-token`；H5 用企业微信身份换 JWT。
|
||
- 合同/OCR 证据按角色可见（`visible_roles`），敏感文件脱敏标记 `is_masked`。
|
||
- **网络暴露提醒**：状态中心所有写接口须鉴权，回调接口须校验 token + 幂等键，禁止无认证暴露。
|
||
|
||
---
|
||
|
||
## 三、数据模型设计
|
||
|
||
> 按订单驱动重排。核心实体：`job / job_node / order_item / product_match / user_task / mapping_config / executor_binding_config / job_artifact / job_event`。
|
||
> 相比早期草案新增：`order_item`（订单明细行）、`product_match`（对码结果，核心难点落库）；`job` 主键由"合同文件"改为"订单批次"。
|
||
|
||
### 3.1 实体关系
|
||
|
||
```
|
||
job (一次流程实例 = 同供应商同日一批订单)
|
||
├─1:N─ order_item (订单明细行, 对码前的原始行)
|
||
├─1:N─ product_match (对码结果, 命中/未命中/一对多候选)
|
||
├─1:N─ job_node (每节点每次尝试)
|
||
├─1:N─ user_task (人工待办)
|
||
├─1:N─ job_artifact (证据)
|
||
└─1:N─ job_event (事件流)
|
||
|
||
mapping_config (对码表/供应商对照/承付结算映射, 版本化)
|
||
executor_binding_config (节点→平台路由)
|
||
```
|
||
|
||
### 3.2 `job`（流程实例）
|
||
|
||
一次流程实例 = **同一供应商 + 同一订单日期 + 同一来源** 的一批订单（对应一条合同）。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint PK | |
|
||
| job_id | varchar(64) unique | 对外流程单号 |
|
||
| business_key | varchar(160) | 业务唯一键：`来源+供应商+订单日期`（见§5.2） |
|
||
| parent_job_id | varchar(64) null | 重跑/加单来源 |
|
||
| source_type | varchar(16) | `YYC`(医药城)/`XYY`(小药药)/`OFFLINE`(线下单) |
|
||
| order_date | date | 订单日期（=合同签约日期） |
|
||
| supplier_name | varchar(128) | 供应商/商家 |
|
||
| order_no_list_json | json | 该批订单号数组（贯穿追溯） |
|
||
| contract_template | varchar(16) null | `FORMAT`(格式)/`NON_FORMAT`(非格式承兑) |
|
||
| need_pdf_upload | tinyint | 医药城=1，小药药=0 |
|
||
| planner_name | varchar(64) null | 计划员 |
|
||
| current_node_code | varchar(64) | 当前节点 |
|
||
| status | varchar(24) | 见§4.1 |
|
||
| mapping_version | varchar(64) null | 绑定的对码表版本 |
|
||
| executor_platform | varchar(16) 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(16) null | 当前责任角色 |
|
||
| current_assignee | varchar(64) null | 当前责任人 |
|
||
| auto_save_enabled | tinyint | M5自动保存开关(阶段一=0) |
|
||
| created_by | varchar(64) | |
|
||
| created_at / updated_at / finished_at | datetime | |
|
||
|
||
索引：`uniq_job_business_open(business_key, status)`、`idx_supplier_date(supplier_name, order_date)`、`idx_status`、`idx_created_at`。
|
||
|
||
### 3.3 `order_item`（订单明细行，对码前原始数据）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint PK | |
|
||
| job_id | varchar(64) | |
|
||
| order_no | varchar(64) | 订单号 |
|
||
| parent_order_no | varchar(64) null | 父订单号（加单/拆单） |
|
||
| raw_product_name | varchar(255) | 平台品名 |
|
||
| platform_product_code | varchar(64) null | 平台产品编码 |
|
||
| spec | varchar(128) null | 规格（对码痛点：15×2 vs 30片） |
|
||
| manufacturer | varchar(255) null | 厂家（含进口英文） |
|
||
| approval_no | varchar(64) null | 国药准字/批准文号 |
|
||
| qty | decimal(14,2) | 数量 |
|
||
| unit_price | decimal(14,4) null | 单价 |
|
||
| source_row_no | int | 原始 Excel 行号（回溯） |
|
||
| created_at | datetime | |
|
||
|
||
索引：`idx_job(job_id)`、`idx_order_no`。
|
||
|
||
### 3.4 `product_match`（对码结果，核心难点落库）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint PK | |
|
||
| job_id | varchar(64) | |
|
||
| order_item_id | bigint | 对应订单行 |
|
||
| match_key | varchar(512) | 四要素拼接键：通用名+批准文号+规格+厂家 |
|
||
| match_status | varchar(16) | `EXACT`(精确命中)/`FUZZY`(模糊)/`MULTI`(一对多)/`NONE`(未命中)/`MANUAL`(人工确认) |
|
||
| goods_id | varchar(64) null | 命中的 M5 货品ID |
|
||
| goods_code | varchar(64) null | 货品编码 |
|
||
| base_unit | varchar(32) null | 基本单位 |
|
||
| candidates_json | json null | 一对多候选列表（供H5选择） |
|
||
| source_add_needed | tinyint | 是否需 M5 新增货源 |
|
||
| confirmed_by | varchar(64) null | 人工确认人 |
|
||
| confirmed_at | datetime null | |
|
||
| mapping_version | varchar(64) | 使用的对码表版本 |
|
||
| created_at | datetime | |
|
||
|
||
索引：`idx_job(job_id)`、`idx_status(match_status)`。
|
||
|
||
### 3.5 `job_node`（节点执行）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint PK | |
|
||
| job_id | varchar(64) | |
|
||
| node_code | varchar(64) | 见§4.2 |
|
||
| attempt_no | int | 第几次尝试（不覆盖历史） |
|
||
| status | varchar(24) | 节点状态 |
|
||
| executor_platform | varchar(16) null | 实际执行平台 |
|
||
| executor_run_id | varchar(64) null | 平台侧任务号 |
|
||
| started_at / ended_at | datetime null | |
|
||
| duration_ms | bigint null | |
|
||
| error_code | varchar(64) null | |
|
||
| error_summary | varchar(500) null | |
|
||
| role_at_failure | varchar(16) null | |
|
||
| output_json | json null | 节点输出（业务编号等） |
|
||
| callback_idempotency_key | varchar(128) null | 回调幂等键 |
|
||
| created_at | datetime | |
|
||
|
||
索引：`uniq_job_node_attempt(job_id, node_code, attempt_no)`、`idx_status`。
|
||
|
||
### 3.6 `user_task`（人工待办）
|
||
|
||
沿用早期草案结构，`reason_type` 扩展订单驱动场景。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint PK | |
|
||
| task_id | varchar(64) unique | |
|
||
| job_id | varchar(64) | |
|
||
| node_code | varchar(64) | |
|
||
| role_code | varchar(16) | `PLANNER`/`PURCHASER`/`QC`/`OPS` |
|
||
| assignee_user_id | varchar(64) null | |
|
||
| title | varchar(255) | |
|
||
| reason_type | varchar(32) | `MATCH_MULTI`/`MATCH_NONE`/`SOURCE_ADD`/`OCR_LOW_CONF`/`REBATE_DUP`/`QC_MISSING`/`CONTRACT_DISABLED`/... |
|
||
| reason_user_friendly | varchar(500) | 人话说明 |
|
||
| why_me_text | varchar(255) | 为什么派给你 |
|
||
| editable_fields_json | json | 白名单字段 |
|
||
| action_schema_json | json | 允许动作 |
|
||
| comparison_snapshot_json | json null | 原值/建议/当前对比 |
|
||
| candidates_json | json null | 一对多对码候选 |
|
||
| status | varchar(16) | `OPEN`/`SUBMITTED`/`CANCELLED`/`EXPIRED` |
|
||
| submit_token | varchar(64) | 防重复 |
|
||
| submitted_action | varchar(24) null | |
|
||
| submitted_payload_json | json null | |
|
||
| submitted_by / submitted_at | | |
|
||
| due_at | datetime null | 超时升级 |
|
||
| created_at | datetime | |
|
||
|
||
### 3.7 `mapping_config`（映射/对码，版本化）
|
||
|
||
统一映射表，`config_type` 区分用途。对码表是其中 `PRODUCT` 类型的累积数据。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint PK | |
|
||
| config_type | varchar(24) | `PRODUCT`(对码)/`SUPPLIER`(供应商对照)/`SETTLEMENT`/`PAYMENT_TERM`/`PLANNER_ROUTE` |
|
||
| config_key | varchar(512) | 对码时=四要素拼接键 |
|
||
| source_value | varchar(512) | 来源值 |
|
||
| target_value | varchar(512) | 目标值（对码=货品ID+编码+单位JSON） |
|
||
| extra_json | json null | 扩展 |
|
||
| version_no | varchar(64) | 版本号 |
|
||
| is_active | tinyint | |
|
||
| effective_from / effective_to | datetime | |
|
||
| updated_by / updated_at | | |
|
||
|
||
索引：`idx_type_key(config_type, config_key)`、`idx_active(is_active)`。
|
||
|
||
### 3.8 `executor_binding_config` / `job_artifact` / `job_event`
|
||
|
||
沿用早期草案结构（见《一期开发任务清单_表结构_API草案.md》§4.5/4.6/4.7）。要点：
|
||
- `executor_binding_config`：`node_code → preferred_platform/fallback_platform + required_capabilities_json + route_policy`。
|
||
- `job_artifact`：`artifact_type ∈ {SOURCE_EXCEL, SOURCE_IMAGE, OCR_JSON, CONTRACT_PDF, MERGED_PDF, SCREENSHOT, TEMPLATE, LOG}`；证据目录 `job_id/node_code/attempt_no/`。
|
||
- `job_event`：`event_type ∈ {JOB_CREATED, NODE_STARTED, NODE_SUCCESS, NODE_FAILED, TASK_CREATED, TASK_SUBMITTED, MANUAL_HANDOFF, JOB_FINISHED}`；`operator_type ∈ {SYSTEM, ROBOT, USER}`。
|
||
|
||
### 3.9 关键 DDL 片段（新增表）
|
||
|
||
```sql
|
||
CREATE TABLE job (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||
job_id VARCHAR(64) NOT NULL UNIQUE,
|
||
business_key VARCHAR(160) NOT NULL,
|
||
parent_job_id VARCHAR(64) NULL,
|
||
source_type VARCHAR(16) NOT NULL, -- YYC/XYY/OFFLINE
|
||
order_date DATE NOT NULL,
|
||
supplier_name VARCHAR(128) NOT NULL,
|
||
order_no_list_json JSON NULL,
|
||
contract_template VARCHAR(16) NULL, -- FORMAT/NON_FORMAT
|
||
need_pdf_upload TINYINT NOT NULL DEFAULT 0,
|
||
planner_name VARCHAR(64) NULL,
|
||
current_node_code VARCHAR(64) NOT NULL,
|
||
status VARCHAR(24) NOT NULL,
|
||
mapping_version VARCHAR(64) NULL,
|
||
executor_platform VARCHAR(16) 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(16) NULL,
|
||
current_assignee VARCHAR(64) NULL,
|
||
auto_save_enabled TINYINT NOT NULL DEFAULT 0,
|
||
created_by VARCHAR(64) NOT NULL,
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
finished_at DATETIME NULL,
|
||
KEY idx_supplier_date (supplier_name, order_date),
|
||
KEY idx_status (status),
|
||
KEY idx_created_at (created_at)
|
||
);
|
||
|
||
CREATE TABLE order_item (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||
job_id VARCHAR(64) NOT NULL,
|
||
order_no VARCHAR(64) NOT NULL,
|
||
parent_order_no VARCHAR(64) NULL,
|
||
raw_product_name VARCHAR(255) NOT NULL,
|
||
platform_product_code VARCHAR(64) NULL,
|
||
spec VARCHAR(128) NULL,
|
||
manufacturer VARCHAR(255) NULL,
|
||
approval_no VARCHAR(64) NULL,
|
||
qty DECIMAL(14,2) NOT NULL,
|
||
unit_price DECIMAL(14,4) NULL,
|
||
source_row_no INT NULL,
|
||
created_at DATETIME NOT NULL,
|
||
KEY idx_job (job_id),
|
||
KEY idx_order_no (order_no)
|
||
);
|
||
|
||
CREATE TABLE product_match (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||
job_id VARCHAR(64) NOT NULL,
|
||
order_item_id BIGINT NOT NULL,
|
||
match_key VARCHAR(512) NOT NULL,
|
||
match_status VARCHAR(16) NOT NULL, -- EXACT/FUZZY/MULTI/NONE/MANUAL
|
||
goods_id VARCHAR(64) NULL,
|
||
goods_code VARCHAR(64) NULL,
|
||
base_unit VARCHAR(32) NULL,
|
||
candidates_json JSON NULL,
|
||
source_add_needed TINYINT NOT NULL DEFAULT 0,
|
||
confirmed_by VARCHAR(64) NULL,
|
||
confirmed_at DATETIME NULL,
|
||
mapping_version VARCHAR(64) NOT NULL,
|
||
created_at DATETIME NOT NULL,
|
||
KEY idx_job (job_id),
|
||
KEY idx_status (match_status)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 四、状态机与节点设计
|
||
|
||
### 4.1 job 主状态机（7 状态）
|
||
|
||
```
|
||
PENDING ──► RUNNING ──► SUCCESS
|
||
│ │ ▲
|
||
│ │ └──── (重试 attempt_no+1)
|
||
│ ├──► WAITING_USER ──► RUNNING (人工处理后继续)
|
||
│ ├──► FAILED_RETRYABLE ──► RUNNING
|
||
│ └──► FAILED_MANUAL (转人工手工做，如M5质管缺失)
|
||
└──────────────► CANCELLED
|
||
```
|
||
|
||
| 状态 | 含义 | 触发 |
|
||
| --- | --- | --- |
|
||
| PENDING | 已建单待调度 | 建单成功 |
|
||
| RUNNING | 节点执行中 | 调度启动节点 |
|
||
| WAITING_USER | 等人工（对码未命中/一对多/货源新增/OCR确认） | 节点转人工 |
|
||
| SUCCESS | 全链完成（一期到 M5 待保存+人工完成后） | 末节点成功 |
|
||
| FAILED_RETRYABLE | 可自动重试（网页卡顿/登录失败） | 系统类错误 |
|
||
| FAILED_MANUAL | 停止转人工手工做（M5质管资料缺失） | 业务决策终止 |
|
||
| CANCELLED | 取消 | 人工终止 |
|
||
|
||
**重试机制**：节点失败不覆盖历史，`attempt_no+1` 新建 `job_node` 行；系统类自动重试 1-2 次，超时升级。
|
||
|
||
### 4.2 节点编码字典（订单驱动重排）
|
||
|
||
| 顺序 | 节点编码 | 内容 | 转人工场景 | 能力标签 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 1 | `ORDER_FETCH` | 登录平台，选前一天，导出订单Excel（状态过滤【待确认】） | 登录失败→OPS | desktop_ui, file_download |
|
||
| 1b | `OCR_EXTRACT` | 仅线下单：图片→字段 | 低置信度→PLANNER | ocr, http_callback |
|
||
| 2 | `PRODUCT_MATCH` | 四要素对码→货品ID/编码 | 未命中/一对多→PLANNER | (状态中心内算) |
|
||
| 2b | `SOURCE_ADD` | 未采购过品种→通知M5新增货源 | 缺货源→业务 | (通知) |
|
||
| 3 | `CONTRACT_CREATE` | 合同建单，选模板，签约日=订单日；医药城合并PDF上传 | 合同禁掉失效→采购邮件 | desktop_ui, file_upload, pdf_merge |
|
||
| 4 | `CONTRACT_APPROVE_WAIT` | 送审后等半小时查审核 | 未审完→等待 | http_callback, timer |
|
||
| 5 | `REBATE_HEADER` | 按合同号查总单，填必填项保存 | — | desktop_ui |
|
||
| 6 | `REBATE_IMPORT` | 细单模板导入（备注填订单号,特定补偿=0） | 重复编码→采购【待确认】 | excel_template, file_upload |
|
||
| 7 | `REBATE_SUBMIT` | 提交送审（决定M5能否带出协议）⭐ | 未送审→阻断 | desktop_ui |
|
||
| 8 | `M5_CREATE_ORDER` | M5-1055新增订单+细单，备注填订单号，选正常保管账，**不点保存** | 质管资料缺失→FAILED_MANUAL | desktop_ui |
|
||
| 9 | `M5_MANUAL_CONFIRM` | 人工检查→保存→签订（阶段一人工，开关控制） | — | (人工/可配自动) |
|
||
| 10 | `M5_RECEIPT_NOTICE` | 生成收货通知单 | — | (人工/可配自动) |
|
||
| 11 | `ARCHIVE_JOB` | 归档业务编号链 | — | (系统) |
|
||
|
||
**关键卡点**：`REBATE_SUBMIT` 未送审则 M5 带不出协议，是硬阻断点。
|
||
|
||
### 4.3 节点转移规则（示例）
|
||
|
||
- `PRODUCT_MATCH`：全 EXACT/已确认 → 进 `CONTRACT_CREATE`；有 MULTI/NONE → `WAITING_USER` 建 `user_task`。
|
||
- `CONTRACT_APPROVE_WAIT`：定时器半小时后查；未审完保持等待并重查，超阈值升级 OPS。
|
||
- `M5_CREATE_ORDER` 报质管错 → 直接 `FAILED_MANUAL`（不重试、不等质管），通知业务手工做。
|
||
|
||
---
|
||
|
||
## 五、幂等、追溯与证据设计
|
||
|
||
### 5.1 幂等三层
|
||
1. **入池幂等**：源文件哈希 `source_file_hash` + `business_key`，同批订单重复导入不生成多条未完成 job。
|
||
2. **回调幂等**：`job_id + node_code + attempt_no` 唯一键；重复回调按幂等键去重。
|
||
3. **人工提交幂等**：`task_id + submit_token`，防止 H5 重复点击重复推进。
|
||
4. **执行前检索**：RPA 在返利/M5 建单前先检索已有单号，避免重复建单。
|
||
|
||
### 5.2 business_key 生成
|
||
`business_key = source_type + "|" + supplier_name + "|" + order_date`
|
||
（同供应商同日同来源 = 一条合同 = 一个 job）。加单场景父订单号记录在 order_item，重做逻辑待确认。
|
||
|
||
### 5.3 订单号贯穿追溯
|
||
|
||
| 位置 | 填什么 | 给谁看 |
|
||
| --- | --- | --- |
|
||
| 电商平台 | 原始订单号 ZQD... | 源头 |
|
||
| 返利中心细单备注 | 订单号 | 物流部软件 |
|
||
| M5 订单备注 | 订单号 | 采购结算（打结算勾对账） |
|
||
|
||
归档链：订单号→合同编号→返利总单号→M5单号→收货通知单号，写入 `job` 各字段 + `job_event`。
|
||
|
||
### 5.4 证据存储
|
||
目录 `对象存储/{job_id}/{node_code}/{attempt_no}/`，含截图、日志、OCR JSON、合同PDF/合并PDF。`job_artifact` 记录元数据、哈希、可见角色、脱敏标记。
|
||
|
||
---
|
||
|
||
## 六、接口契约设计
|
||
|
||
> 所有写操作经状态中心，RPA/H5/企业微信不得直连数据库。鉴权：内部 `Bearer`，RPA `X-Agent-Token`，H5 企业微信身份换 JWT，写接口带 `X-Idempotency-Key`。
|
||
|
||
### 6.1 统一节点回调契约
|
||
|
||
节点开始 `POST /api/jobs/{jobId}/nodes/{nodeCode}/start`
|
||
```json
|
||
{ "attemptNo": 1, "executorPlatform": "YINGDAO", "operator": "agent-01", "startedAt": "2026-08-07T22:00:00+08:00" }
|
||
```
|
||
|
||
节点成功 `POST /api/jobs/{jobId}/nodes/{nodeCode}/complete`
|
||
```json
|
||
{
|
||
"attemptNo": 1,
|
||
"executorRunId": "YD-RUN-001",
|
||
"endedAt": "2026-08-07T22:03:00+08:00",
|
||
"businessRefs": { "contractSystemNo": "HT...", "rebateOrderNo": null, "m5OrderNo": null, "receiptNoticeNo": null },
|
||
"summary": { "importedItemCount": 18, "failedItemCount": 0 },
|
||
"artifacts": [ { "artifactType": "SCREENSHOT", "storagePath": "/data/jobs/.../success.png" } ]
|
||
}
|
||
```
|
||
约束：节点要求业务编号却未回传，不得记 SUCCESS。
|
||
|
||
节点失败 `POST /api/jobs/{jobId}/nodes/{nodeCode}/fail`
|
||
```json
|
||
{
|
||
"attemptNo": 1, "errorCode": "REBATE_DUP_CODE", "errorSummary": "存在重复的编码",
|
||
"retryable": false, "routeRole": "PURCHASER",
|
||
"artifacts": [ { "artifactType": "SCREENSHOT", "storagePath": "/data/jobs/.../error.png" } ]
|
||
}
|
||
```
|
||
|
||
### 6.2 错误码分层
|
||
|
||
| 层 | 前缀 | 处理 | 例 |
|
||
| --- | --- | --- | --- |
|
||
| 系统类 | `SYS_` | 自动重试1-2次 | SYS_LOGIN_FAIL, SYS_PAGE_TIMEOUT |
|
||
| 业务类 | `BIZ_` | 转对应角色 | BIZ_MATCH_NONE, REBATE_DUP_CODE, M5_QC_MISSING |
|
||
| 配置类 | `CFG_` | 转OPS/管理员 | CFG_TEMPLATE_MISSING |
|
||
| 页面变化类 | `UI_` | 转OPS | UI_ELEMENT_NOT_FOUND |
|
||
| 能力不满足 | `CAP_` | 换平台/转OPS | CAP_PDF_MERGE_UNSUPPORTED |
|
||
|
||
特例：`M5_QC_MISSING` → 不重试，直接 `FAILED_MANUAL`。
|
||
|
||
### 6.3 待办与查询接口
|
||
- `GET /api/tasks/my?roleCode=PLANNER&status=open`
|
||
- `POST /api/tasks/{taskId}/submit`：动作 `CONFIRM_AND_CONTINUE`/`SELECT_CANDIDATE`(对码一对多)/`RETRY_CURRENT_NODE`/`TRANSFER_MANUAL`/`TERMINATE_JOB`；返回即时回执 `receiptMessage`/`nextExpectedAction`。
|
||
- `POST /api/jobs/{jobId}/retry`、`POST /api/jobs/{jobId}/handoff`
|
||
- `GET /api/jobs/{jobId}`：job基础+节点轨迹+待办+对码摘要+业务编号+证据列表。
|
||
- `POST /api/wecom/callback`：只接动作/身份，转标准动作后调内部逻辑。
|
||
|
||
### 6.4 对码专用接口（新增）
|
||
- `POST /api/jobs/{jobId}/match/run`：触发对码引擎，返回命中率与未命中清单。
|
||
- `GET /api/jobs/{jobId}/match/unmatched`：未命中/一对多候选（供H5）。
|
||
- `POST /api/match/{matchId}/confirm`：人工确认选择候选或新增，回写 `mapping_config`（累积迭代）。
|
||
|
||
---
|
||
|
||
## 七、对码引擎设计（核心难点）
|
||
|
||
### 7.1 匹配流程
|
||
```
|
||
order_item ──► 规范化(去空格/全半角/规格标准化) ──► 拼接 match_key(通用名+批准文号+规格+厂家)
|
||
│
|
||
├─ 精确命中 mapping_config(PRODUCT) ──► EXACT, 填 goods_id/code
|
||
├─ 模糊命中(规格/厂家容错规则) ─────► FUZZY(标记待复核)
|
||
├─ 同商品名多规格 ─────────────────► MULTI, 生成 candidates
|
||
└─ 无命中 ─────────────────────────► NONE, 建 user_task 转人工
|
||
```
|
||
|
||
### 7.2 规格标准化规则（针对痛点）
|
||
- `15×2 ↔ 30片`（乘积展开）、`干一瓶 ↔ ×1瓶`、进口厂家英文名容错（大小写/标点/B.V. S.r.l.）。
|
||
- 规则表化，可迭代补充；未覆盖的进 MULTI/NONE 人工。
|
||
|
||
### 7.3 迭代闭环
|
||
人工确认结果回写 `mapping_config`（新版本 `version_no`），下次自动命中。命中率统计写入 `job_event`，支撑阶段0/阶段3的准确率报告。
|
||
|
||
---
|
||
|
||
## 八、关键时序图
|
||
|
||
### 8.1 医药城端到端（正向）
|
||
```
|
||
定时器 → 状态中心: 触发建单(前一天医药城订单)
|
||
状态中心 → RPA: 启动 ORDER_FETCH
|
||
RPA → 医药城: 登录/导出Excel
|
||
RPA → 状态中心: complete(ORDER_FETCH, artifacts=Excel)
|
||
状态中心 → 对码引擎: PRODUCT_MATCH(解析order_item, 匹配)
|
||
对码引擎 → 状态中心: 全命中
|
||
状态中心 → RPA: 启动 CONTRACT_CREATE(need_pdf_upload=1)
|
||
RPA → 合同系统: 建单/选格式模板/改签约日/合并PDF上传/送审
|
||
RPA → 状态中心: complete(合同编号)
|
||
状态中心: 定时器等30分钟 → RPA: CONTRACT_APPROVE_WAIT 查审核
|
||
状态中心 → RPA: REBATE_HEADER(按合同号查总单填必填)
|
||
状态中心 → RPA: REBATE_IMPORT(细单模板,备注=订单号,特定补偿0)
|
||
状态中心 → RPA: REBATE_SUBMIT(送审) ⭐
|
||
状态中心 → RPA: M5_CREATE_ORDER(新增订单+细单,备注订单号,正常保管账,不保存)
|
||
RPA → 状态中心: complete(M5待保存)
|
||
状态中心 → 企业微信: 推送人工检查待办
|
||
计划员 → H5: 检查→保存→签订→生成收货通知单(阶段一人工)
|
||
状态中心: ARCHIVE_JOB 归档编号链
|
||
```
|
||
|
||
### 8.2 对码未命中（一对多）
|
||
```
|
||
对码引擎 → 状态中心: MATCH_MULTI(candidates)
|
||
状态中心 → user_task: 建待办(reason=MATCH_MULTI, candidates_json)
|
||
状态中心 → 企业微信: 推送"对码待确认"
|
||
计划员 → H5: 选择候选/新增
|
||
H5 → 状态中心: submit(SELECT_CANDIDATE)
|
||
状态中心 → mapping_config: 回写(累积迭代)
|
||
状态中心: job WAITING_USER → RUNNING, 继续 CONTRACT_CREATE
|
||
```
|
||
|
||
### 8.3 M5 质管资料缺失（转人工，不等质管）
|
||
```
|
||
RPA → M5: 新增订单保存时报错(供应商年报过期)
|
||
RPA → 状态中心: fail(M5_QC_MISSING, retryable=false)
|
||
状态中心: job → FAILED_MANUAL (不重试/不等质管)
|
||
状态中心 → 企业微信: 通知业务"此单转人工手工做"
|
||
业务: 次日质管维护后自行在M5手工完成
|
||
```
|
||
|
||
---
|
||
|
||
## 九、模块设计（状态中心内部）
|
||
|
||
| 模块 | 职责 | 关键接口/服务 |
|
||
| --- | --- | --- |
|
||
| intake_service | 建单入池、哈希/业务键去重、Excel解析入 order_item | POST /api/jobs |
|
||
| workflow_service | 状态机流转、节点调度、转移规则 | node start/complete/fail |
|
||
| match_service | 对码引擎、规格标准化、候选生成、迭代回写 | match/run, match/confirm |
|
||
| retry_service | 系统类自动重试、超时扫描升级 | 定时任务 |
|
||
| task_service | 待办生成、角色路由、提交幂等、回执 | tasks/my, tasks/submit |
|
||
| executor_router | 节点→平台路由（FIXED/PREFERRED/FALLBACK） | 内部 |
|
||
| ocr_service | 线下单OCR适配、置信度阈值 | OCR_EXTRACT |
|
||
| artifact_service | 证据落盘、可见角色、脱敏 | 内部 |
|
||
| wecom_service | 企业微信消息、卡片更新、身份 | wecom/callback |
|
||
| audit/query | 事件流、整单查询、审计导出 | GET /api/jobs/{id} |
|
||
|
||
---
|
||
|
||
## 十、与早期草案的设计差异（供评审）
|
||
|
||
| # | 早期草案 | 本设计 | 原因 |
|
||
| --- | --- | --- | --- |
|
||
| 1 | job=一份合同文件的流程 | job=同供应商同日一批订单 | 订单驱动，合同是产物非入口 |
|
||
| 2 | 无 order_item/product_match 表 | 新增两表 | 对码是核心难点须落库 |
|
||
| 3 | 节点以合同/OCR为主线 | 节点订单驱动重排(ORDER_FETCH起) | 骨架方向纠正 |
|
||
| 4 | 送审在合同系统 | 关键送审 REBATE_SUBMIT | 卡点位置纠正 |
|
||
| 5 | 质管缺料转质管重试 | M5_QC_MISSING→FAILED_MANUAL | 业务明确否决重试 |
|
||
| 6 | 无自动化开关 | job.auto_save_enabled 分阶段 | 分阶段上线诉求 |
|
||
| 7 | 技术栈未定 | 确定 Python+FastAPI+MySQL,骨架已跑通 | 与对码/OCR同栈,开发快 |
|
||
| 8 | OCR为全流程核心 | OCR仅线下单分支 | 范围纠正 |
|
||
|
||
---
|
||
|
||
## 十一、待确认的设计输入（阻塞项）
|
||
|
||
1. **OCR信息安全**：线上是否获批 / 本地部署预算 → 决定 `OCR_EXTRACT` 节点部署方式。
|
||
2. **返利中心重复订单**完整规则 → 决定 `REBATE_DUP_CODE` 是否可自动重建总单。
|
||
3. **医药城订单状态过滤**：只取"待收货"还是含其他 → `ORDER_FETCH` 过滤条件。
|
||
4. **加单场景**：父订单号关联与重做逻辑 → `parent_job_id/parent_order_no` 处理策略。
|
||
5. **测试账号/对码表(Oracle连接串+表名列名)/供应商对照表/邮箱/计划员表**到位时间 → 影响联调。
|
||
|
||
> 技术栈已确认：状态中心 = Python 3 + FastAPI + MySQL 8（骨架见 `state_center/`），不再作为阻塞项。
|
||
|
||
---
|
||
|
||
## 附录：联调顺序建议
|
||
1. 状态中心单独跑通建单/状态流转/待办。
|
||
2. 假OCR+假RPA回调打通全流程。
|
||
3. 接真实对码引擎（复用阶段0成果）。
|
||
4. 接真实企业微信+H5身份。
|
||
5. 接真实RPA（先医药城单来源）。
|
||
6. 返利中心/M5端到端联调。
|