Files
aibridge/docs/workflow-guide.md
T
2026-05-18 09:28:15 +08:00

737 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 工作流指南
> JNPF 工作流(Workflow)完整开发指南:模板管理、审批操作、委托监控。
## 概述
JNPF 工作流模块支持完整的审批流程管理,包括流程模板创建、流程设计、审批操作(同意/拒绝/转审/退回/加签等)、流程委托和监控。
AIBridge 通过 `WorkflowAPI` 封装了全部工作流接口。
```python
from aibridge.modules.workflow import WorkflowAPI
workflow = WorkflowAPI(client)
```
## 流程模板管理
### 创建流程模板
```python
# 创建流程模板
resp = workflow.create_template({
"fullName": "采购审批流程",
"enCode": "purchaseApproval",
"type": 1, # 流程类型
"category": "your_category_id",
"formId": "visual_dev_func_id", # 关联的表单功能ID
"enabledMark": 1,
"sortCode": 100,
})
template_id = resp.id
print(f"模板创建成功: {template_id}")
```
### 获取模板列表
```python
# 分页获取模板列表
resp = workflow.get_template_list({
"currentPage": 1,
"pageSize": 20,
})
for item in resp.data.get("list", []):
print(f"流程: {item['fullName']} (id={item['id']}, type={item['type']})")
```
### 通过表单获取关联流程
```python
# 获取某表单关联的所有流程
resp = workflow.get_flow_list(form_id="visual_dev_func_id")
for flow in resp.data:
print(f"关联流程: {flow.get('fullName')}")
```
### 模板 CRUD
```python
# 获取模板详情
info = workflow.get_template_info(template_id)
# 修改模板
workflow.update_template({
"id": template_id,
"fullName": "采购审批流程(修订版)",
})
# 复制模板
workflow.copy_template(template_id)
# 删除模板
workflow.delete_template(template_id)
# 导出模板
workflow.export_template(template_id)
```
## 流程设计
### 保存流程设计
```python
# 保存流程设计(包含节点、连线等完整配置)
workflow.save_flow({
"id": template_id,
"flowTemplateJson": json.dumps(flow_design_data),
"flowTemplateNodes": json.dumps(flow_nodes),
"flowTemplateLines": json.dumps(flow_lines),
})
```
### 获取流程设计详情
```python
# 获取流程引擎设计详情
info = workflow.get_flow_info(template_id)
flow_data = info.data
# 包含节点配置、连线配置、表单绑定等
```
### 流程版本管理
```python
# 获取版本列表
versions = workflow.get_version_list(template_id)
# 删除版本
workflow.delete_version(version_id)
# 复制创建新版本
workflow.copy_version(version_id)
```
### 简单流程切换为标准流程
```python
# 简单流程 → 标准流程(不可逆)
workflow.change_type(template_id)
```
### 获取决策参数
```python
# 获取流程决策参数(用于条件分支配置)
params = workflow.get_decision_parameter(template_id)
```
## 流程表单绑定
### 获取流程表单信息
```python
# 通过小流程ID获取发起节点表单
form_info = workflow.get_flow_form_info(template_id)
# 通过大流程ID获取发起节点表单
start_form = workflow.get_flow_start_form_info(template_id)
# 获取流程版本ID和发起节点表单ID
form_ids = workflow.get_flow_start_form_id(template_id)
```
## 流程发起
### 新建流程发起
```python
# 创建并发起流程(填写表单 + 发起)
# 注意:formData 直接传 dict,不要 json.dumps
resp = workflow.create({
"flowId": template_id,
"status": 1, # 1=发起
"formData": {
"f_orderNo": "PO-2026-001",
"f_customer": "测试公司",
"f_amount": 5000.00,
"f_orderDate": int(time.time() * 1000),
"f_remark": "办公用品采购",
},
})
task_id = resp.id
print(f"流程发起成功: {task_id}")
```
### 获取发起列表
```python
# 获取我发起的流程列表
resp = workflow.get_launch_list({
"currentPage": 1,
"pageSize": 20,
})
```
### 发起后操作
```python
# 撤回发起
workflow.launch_recall(task_id)
# 撤销发起(终止流程)
workflow.revoke(task_id)
# 催办
workflow.press(task_id)
# 获取事件日志
workflow.get_event_log(task_id)
```
## 审批操作
### 获取待审核列表
```python
# category: 0=待审核 1=已审核 2=抄送我 3=所有
resp = workflow.get_before_list(category=0, data={
"currentPage": 1,
"pageSize": 20,
})
for item in resp.data.get("list", []):
print(f"待审核: {item.get('fullName')} (operatorId={item.get('id')})")
```
### 审核(同意/拒绝)
```python
# 同意
workflow.audit(operator_id, {
"status": 1, # 1=同意 2=拒绝 3=驳回
"handleOpinion": "同意采购",
"sign": "",
"copyIds": [],
})
# 拒绝
workflow.audit(operator_id, {
"status": 2,
"handleOpinion": "预算超支,拒绝",
})
```
### 签收/退签
```python
# 签收
workflow.sign(operator_id)
# 退签
workflow.cancel_sign(operator_id)
# 批量签收/退签(type: 0=签收 1=退签)
workflow.batch_sign({
"ids": [operator_id_1, operator_id_2],
"type": 0,
})
```
### 转审
将审批任务转给其他人处理:
```python
workflow.transfer(operator_id, {
"handleOpinion": "转给部门经理处理",
"transferUserId": "target_user_id",
})
```
### 退回
将流程退回到指定节点:
```python
# 先获取可退回的节点列表
nodes = workflow.get_back_node_list(operator_id)
# nodes.data 包含可退回的节点信息
# 退回到指定节点
workflow.back(operator_id, {
"handleOpinion": "信息不完整,退回补充",
"targetNodeId": "target_node_id",
})
```
### 加签/减签
```python
# 加签(增加审批人)
workflow.free_approver(operator_id, {
"handleOpinion": "请法务部会签",
"candidateList": [{"userId": "user_id_1"}, {"userId": "user_id_2"}],
})
# 减签(移除审批人)
workflow.reduce_approver(operator_id, {
"handleOpinion": "取消法务会签",
"operatorId": "operator_to_remove",
})
```
### 暂存审批
```python
# 暂存审批意见(不提交)
workflow.save_audit(operator_id, {
"handleOpinion": "正在核实中...",
})
```
### 协办
```python
# 协办(请他人协助处理)
workflow.assist(operator_id, {
"handleOpinion": "请协助核实金额",
"candidateList": [{"userId": "assistant_user_id"}],
})
# 协办保存
workflow.save_assist(operator_id, {
"handleOpinion": "核实结果:金额正确",
})
```
### 开始办理
```python
# 标记开始办理
workflow.handle(operator_id)
# 批量办理
workflow.batch_handle({"ids": [op_id_1, op_id_2]})
```
### 撤回审核
```python
workflow.audit_recall(operator_id, {
"handleOpinion": "审批有误,撤回重新审核",
})
```
## 候选人
### 获取候选人列表
```python
# 获取当前节点的候选人
workflow.get_candidate_user({
"operatorId": operator_id,
"keyword": "",
})
```
### 判断是否有候选人
```python
# 检查当前节点是否需要选择候选人
workflow.get_candidates(operator_id, {})
```
## 批量审批
```python
# 批量审批(0=通过 1=退回 2=转审)
workflow.batch_operation({
"batchHandleList": [
{
"operatorId": op_id_1,
"status": 1,
"handleOpinion": "批量通过",
},
{
"operatorId": op_id_2,
"status": 1,
"handleOpinion": "批量通过",
},
],
})
# 获取批量审批候选人
workflow.get_batch_candidate()
# 获取批量审批流程列表
workflow.get_batch_flow_selector()
```
## 进度查询
### 经办记录
```python
# 获取进度节点的经办列表
records = workflow.get_record_list(task_id, node_id)
for record in records.data:
print(f"经办人: {record.get('handleUserName')} - {record.get('handleStatus')}")
```
### 抄送人员
```python
# 获取节点的抄送人员
circulate = workflow.get_circulate_list(task_id, node_id)
```
### 查看发起节点表单
```python
# 查看发起节点填写的表单数据
form = workflow.get_start_form_info(task_id)
```
### 查看子流程
```python
# 查看子流程信息
workflow.get_sub_flow_info(node_code="sub_node", flow_id=task_id)
```
### 流程实例相关人员
```python
# 获取流程实例相关人员(分页)
workflow.get_task_user_list({
"taskId": task_id,
"currentPage": 1,
"pageSize": 20,
})
```
## 流程评论
```python
# 获取评论列表
comments = workflow.get_comment_list({"taskId": task_id})
# 添加评论
workflow.create_comment({
"taskId": task_id,
"content": "请尽快处理",
"type": 1,
})
# 删除评论
workflow.delete_comment(comment_id)
```
## 流程委托
### 获取委托列表
```python
delegates = workflow.get_delegate_list({
"currentPage": 1,
"pageSize": 20,
})
```
委托用于将审批权临时转交给其他用户,通常在请假或出差时使用。
## 流程监控
### 获取监控列表
```python
monitors = workflow.get_monitor_list({
"currentPage": 1,
"pageSize": 20,
})
```
流程监控用于管理员查看所有进行中的流程实例,支持终止异常流程等操作。
## Webhook
### 获取 Webhook URL
```python
# 获取 Webhook URL(用于外部系统触发流程)
url_info = workflow.get_webhook_url({"flowId": flow_id})
webhook_url = url_info.data # 外部系统调用的 URL
```
### 获取 Webhook 字段
```python
# 获取 Webhook 需要传递的字段信息
params = workflow.get_webhook_params(random_str)
# 返回 Webhook 需要的参数列表
```
### 开启/关闭 Webhook
```python
# 开启 Webhook 接收请求
workflow.webhook_start(flow_id, random_str)
```
### Webhook 使用流程
```
1. 调用 get_webhook_url 获取 Webhook URL
2. 调用 webhook_start 开启接收
3. 外部系统向 Webhook URL 发送 POST 请求,携带流程表单数据
4. JNPF 自动创建并启动流程实例
```
## 流程模板其他功能
### 收藏流程
```python
# 获取收藏流程列表
workflow.get_collect_flow_list()
# 收藏/取消收藏
workflow.set_collect_flow(template_id)
```
### 上架/下架
```python
# 上架/下架流程模板
workflow.up_down_shelf({"id": template_id, "enabledMark": 1})
```
### 流程选择器
```python
# 获取流程列表(用于发起页面选择)
workflow.get_flow_selector({"keyword": "采购"})
# 获取流程树形列表
workflow.get_tree_list(form_type="3") # 3=工作流表单
```
## 自定义按钮发起流程
在 OnlineDev 表单中,可以通过自定义按钮发起关联流程:
```python
from aibridge.modules.visual_dev import VisualDevAPI
visual_dev = VisualDevAPI(client)
# 通过自定义按钮发起流程(formData 直接传 dict)
visual_dev.launch_flow(model_id, {
"id": record_id,
"formData": {"f_amount": 5000},
})
```
## 完整示例:创建「采购审批」工作流
以下示例演示从零开始创建一个带审批的完整功能,参考 `examples/create_procurement_workflow.py`。
### 完整流程
```python
from aibridge import JNPFClient, JNPFConfig
from aibridge.models import FieldDef
from aibridge.builders.full_config import build_full_config, build_create_payload
# 1. 配置并登录
config = JNPFConfig(
base_url="http://localhost:30000",
account="admin",
password="d4958348...", # 96字符AES密文(从浏览器提取)
app_code="your_app_code",
)
client = JNPFClient.from_config(config)
client.login()
# 2. 定义字段
fields = [
FieldDef(field="f_orderNo", field_name="采购编号", required=True),
FieldDef(field="f_itemName", field_name="文具名称", required=True),
FieldDef(field="f_quantity", field_name="采购数量", jnpf_key="inputNumber",
data_type="int", data_length="10", required=True),
FieldDef(field="f_totalAmount", field_name="总金额", jnpf_key="inputNumber",
data_type="decimal", data_length="18"),
FieldDef(field="f_supplier", field_name="供应商", required=True),
FieldDef(field="f_reqPerson", field_name="申请人", required=True),
]
# 3. 创建并发布表单(webType=3 表单列表工作流)
config_result = build_full_config(
full_name="文具采购",
en_code="stationeryProcurement",
table_name="base_stationery_procurement",
table_label="文具采购表",
description="文具采购申请与审批管理",
category="",
fields=[f.to_dict() for f in fields],
web_type=3, # 表单列表工作流
)
payload = build_create_payload(config_result) # 动态建表模式
resp = client.visual_dev.create(payload)
func_id = resp.id
client.visual_dev.release(func_id) # 发布,自动建表
# 4. 一步创建流程模板并发布
# 内部:create_template(含 flowXml/flowNodes/flowConfig) → get_version_list → save_flow
flow_result = client.workflow.create_simple_flow(
full_name="文具采购审批",
en_code="stationeryProcurementFlow",
form_id=func_id,
approver_user_ids=["user_id_here"], # 审批人 ID
form_name="文具采购",
flow_type=1, # 简单流程
)
version_id = flow_result["version_id"]
# 5. 创建菜单
dir_resp = client.menu.create_directory_menu("文具管理", "stationery_mgmt")
client.menu.create_form_menu("文具采购", "stationeryProcurement",
func_id, dir_resp.id, web_type=3)
# 6. 发起流程
task_resp = client.workflow.launch_task(version_id, {
"f_orderNo": "CG-2026-001",
"f_itemName": "中性笔(黑色)",
"f_quantity": 500,
"f_supplier": "晨光文具有限公司",
"f_reqPerson": "李明",
})
task_id = task_resp.id
# 7. 审批
pending = client.workflow.get_pending_tasks()
operator_id = pending[0]["taskOperatorId"]
client.workflow.approve(operator_id, "同意采购")
```
### 便捷方法速查
| 方法 | 用途 | 说明 |
|------|------|------|
| `create_simple_flow()` | 一键创建并发布流程模板 | 整合 create_template + save_flow |
| `launch_task()` | 快捷发起流程 | formData 直接传 dict,不做 JSON 序列化 |
| `approve()` | 快捷审批通过 | 自动带 status=1 |
| `reject()` | 快捷审批拒绝 | 自动带 status=2 |
| `get_pending_tasks()` | 获取待审批列表 | 返回 list[dict] |
## 关键经验与踩坑记录
### 1. create_template 必须包含 flowXml/flowNodes/flowConfig
**问题**:`create_template()` 调用后端 `templateService.create()`,内部会调用 `flowUtil.create()`。如果 `flowNodes` 为 null,`flowUtil.create()` 会从 flowNodes 中解析起始节点时抛 NPE,导致 `templateJson` 条目未创建。后续 `save_flow` 调用 `getInfo(flowId)` 会报 "数据不存在"。
**解决**:AIBridge 的 `create_simple_flow()` 已在 `create_template` 调用中包含完整的 flowXml/flowNodes/flowConfig,避免此问题。
### 2. 审批需要 status 字段
**问题**:`POST /api/workflow/operator/Audit/{operatorId}` 需要在请求体中包含 `status` 字段:
- `status=1`:同意
- `status=2`:拒绝
如果缺少 status 字段,审批操作可能不生效或报错。
**解决**:AIBridge 的 `approve()` 和 `reject()` 便捷方法已自动包含 `status` 字段。
### 3. launch_task 的 isFlow 参数必须是整数
**问题**:`POST /api/workflow/task` 请求体中 `isFlow` 字段,Java 后端类型为 `Integer`。
如果传入 Python 布尔值 `True`,序列化为 JSON `true` 会导致 Jackson 反序列化失败:
```
Cannot deserialize value of type java.lang.Integer from Boolean value
```
**解决**:AIBridge 的 `launch_task()` 已修复,内部使用整数 `1`:
```python
# 正确:AIBridge 内部发送 isFlow: 1
client.workflow.launch_task(version_id, {"f_orderNo": "CG-001", ...}) # ✓
# 错误:手动传布尔值
# client.request("POST", "/api/workflow/task", data={"isFlow": True, ...}) # ✗
```
### 4. 流程发起 formData 必须传 dict,不要 json.dumps
**问题**:`POST /api/workflow/task` 的请求体中 `formData` 字段,后端 `FlowHandleModel.formData`
类型为 `Map<String, Object>`。如果传入 `json.dumps(dict)` 产生的 JSON 字符串,Jackson 会将其
反序列化为 String 而非 Map,后续取值时抛 NPE("系统异常")。
**解决**:AIBridge 的 `launch_task()` 直接传 dict,不做序列化。
```python
# 正确:直接传 dict
client.workflow.launch_task(version_id, {"f_orderNo": "CG-001", "f_itemName": "中性笔"})
# 错误:不要手动序列化
# client.workflow.launch_task(version_id, json.dumps({"f_orderNo": "CG-001"})) # ✗
```
### 4. get_flow_info 的参数是 version_id,不是 template_id
**问题**:`GET /api/workflow/template/Info/{id}` 查的是 templateJson 实体(version_id / flowId),
不是 template_id。用 template_id 调用会返回 "数据不存在"。
**解决**:先通过 `get_version_list(template_id)` 获取 version_id:
```python
versions = client.workflow.get_version_list(template_id)
flow_id = versions.data[0]["id"]
info = client.workflow.get_flow_info(flow_id) # 用 flow_id,不是 template_id
```
### 5. 删除资源时的正确顺序
**问题**:流程模板通过 workflow_node 引用了表单的 formId,如果先删表单,会因外键约束报错。
**正确顺序**:流程模板 → 表单 → 功能菜单 → 目录菜单。
```python
# 1. 先删模板(解除表单引用)
client.workflow.delete_template(template_id)
# 2. 再删表单
client.visual_dev.delete(func_id)
# 3. 删功能菜单
client.menu.delete(menu_id)
# 4. 最后删目录菜单
client.menu.delete(dir_id)
```
### 6. 前端发起流程报 undefined.vue 的排查
**问题**:前端报 "该文件不存在: ../views/workFlow/workFlowForm/undefined.vue"。
**根因**:后端 `getFormByTemplateId` 返回的表单信息中 `enCode` 为空,导致前端路径拼接为 `undefined.vue`。
**排查步骤**:
1. 确认表单已发布(`base_visualdev_release` 有记录)
2. 确认 `workflow_node` 起始节点的 `f_form_id` 与 `base_visual_dev` ID 一致
3. 确认 `App-Code` 正确(多租户隔离)
4. 运行诊断脚本:`python3 -m aibridge.examples.diagnose_workflow_form`
### 5. 审批人不能与发起人相同
**问题**:审批时报"系统异常",可能是因为当前用户就是流程发起人,同时又被设为审批人。JNPF 规则不允许用户审批自己发起的流程。
**解决**:使用另一个用户账号登录来审批,或在创建流程时指定不同的审批人。
### 6. 动态建表模式
**问题**:`visual_dev.create()` 如果传非空 `tables`,后端会校验物理表是否存在和主键策略。新功能通常没有物理表,会报 "请在数据库中添加对应的数据表"。
**解决**:使用 `build_create_payload(config)` 默认传空 tables,`release()` 时后端自动从 formData 创建物理表。
### 7. webType=3 是工作流类型
创建需要审批流程的功能时,必须使用 `webType=3`(表单列表工作流),不能使用 `webType=2`(表单加列表)。只有 `webType=3` 的功能才能绑定流程模板。