18 KiB
工作流指南
JNPF 工作流(Workflow)完整开发指南:模板管理、审批操作、委托监控。
概述
JNPF 工作流模块支持完整的审批流程管理,包括流程模板创建、流程设计、审批操作(同意/拒绝/转审/退回/加签等)、流程委托和监控。
AIBridge 通过 WorkflowAPI 封装了全部工作流接口。
from aibridge.modules.workflow import WorkflowAPI
workflow = WorkflowAPI(client)
流程模板管理
创建流程模板
# 创建流程模板
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}")
获取模板列表
# 分页获取模板列表
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']})")
通过表单获取关联流程
# 获取某表单关联的所有流程
resp = workflow.get_flow_list(form_id="visual_dev_func_id")
for flow in resp.data:
print(f"关联流程: {flow.get('fullName')}")
模板 CRUD
# 获取模板详情
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)
流程设计
保存流程设计
# 保存流程设计(包含节点、连线等完整配置)
workflow.save_flow({
"id": template_id,
"flowTemplateJson": json.dumps(flow_design_data),
"flowTemplateNodes": json.dumps(flow_nodes),
"flowTemplateLines": json.dumps(flow_lines),
})
获取流程设计详情
# 获取流程引擎设计详情
info = workflow.get_flow_info(template_id)
flow_data = info.data
# 包含节点配置、连线配置、表单绑定等
流程版本管理
# 获取版本列表
versions = workflow.get_version_list(template_id)
# 删除版本
workflow.delete_version(version_id)
# 复制创建新版本
workflow.copy_version(version_id)
简单流程切换为标准流程
# 简单流程 → 标准流程(不可逆)
workflow.change_type(template_id)
获取决策参数
# 获取流程决策参数(用于条件分支配置)
params = workflow.get_decision_parameter(template_id)
流程表单绑定
获取流程表单信息
# 通过小流程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)
流程发起
新建流程发起
# 创建并发起流程(填写表单 + 发起)
# 注意: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}")
获取发起列表
# 获取我发起的流程列表
resp = workflow.get_launch_list({
"currentPage": 1,
"pageSize": 20,
})
发起后操作
# 撤回发起
workflow.launch_recall(task_id)
# 撤销发起(终止流程)
workflow.revoke(task_id)
# 催办
workflow.press(task_id)
# 获取事件日志
workflow.get_event_log(task_id)
审批操作
获取待审核列表
# 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')})")
审核(同意/拒绝)
# 同意
workflow.audit(operator_id, {
"status": 1, # 1=同意 2=拒绝 3=驳回
"handleOpinion": "同意采购",
"sign": "",
"copyIds": [],
})
# 拒绝
workflow.audit(operator_id, {
"status": 2,
"handleOpinion": "预算超支,拒绝",
})
签收/退签
# 签收
workflow.sign(operator_id)
# 退签
workflow.cancel_sign(operator_id)
# 批量签收/退签(type: 0=签收 1=退签)
workflow.batch_sign({
"ids": [operator_id_1, operator_id_2],
"type": 0,
})
转审
将审批任务转给其他人处理:
workflow.transfer(operator_id, {
"handleOpinion": "转给部门经理处理",
"transferUserId": "target_user_id",
})
退回
将流程退回到指定节点:
# 先获取可退回的节点列表
nodes = workflow.get_back_node_list(operator_id)
# nodes.data 包含可退回的节点信息
# 退回到指定节点
workflow.back(operator_id, {
"handleOpinion": "信息不完整,退回补充",
"targetNodeId": "target_node_id",
})
加签/减签
# 加签(增加审批人)
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",
})
暂存审批
# 暂存审批意见(不提交)
workflow.save_audit(operator_id, {
"handleOpinion": "正在核实中...",
})
协办
# 协办(请他人协助处理)
workflow.assist(operator_id, {
"handleOpinion": "请协助核实金额",
"candidateList": [{"userId": "assistant_user_id"}],
})
# 协办保存
workflow.save_assist(operator_id, {
"handleOpinion": "核实结果:金额正确",
})
开始办理
# 标记开始办理
workflow.handle(operator_id)
# 批量办理
workflow.batch_handle({"ids": [op_id_1, op_id_2]})
撤回审核
workflow.audit_recall(operator_id, {
"handleOpinion": "审批有误,撤回重新审核",
})
候选人
获取候选人列表
# 获取当前节点的候选人
workflow.get_candidate_user({
"operatorId": operator_id,
"keyword": "",
})
判断是否有候选人
# 检查当前节点是否需要选择候选人
workflow.get_candidates(operator_id, {})
批量审批
# 批量审批(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()
进度查询
经办记录
# 获取进度节点的经办列表
records = workflow.get_record_list(task_id, node_id)
for record in records.data:
print(f"经办人: {record.get('handleUserName')} - {record.get('handleStatus')}")
抄送人员
# 获取节点的抄送人员
circulate = workflow.get_circulate_list(task_id, node_id)
查看发起节点表单
# 查看发起节点填写的表单数据
form = workflow.get_start_form_info(task_id)
查看子流程
# 查看子流程信息
workflow.get_sub_flow_info(node_code="sub_node", flow_id=task_id)
流程实例相关人员
# 获取流程实例相关人员(分页)
workflow.get_task_user_list({
"taskId": task_id,
"currentPage": 1,
"pageSize": 20,
})
流程评论
# 获取评论列表
comments = workflow.get_comment_list({"taskId": task_id})
# 添加评论
workflow.create_comment({
"taskId": task_id,
"content": "请尽快处理",
"type": 1,
})
# 删除评论
workflow.delete_comment(comment_id)
流程委托
获取委托列表
delegates = workflow.get_delegate_list({
"currentPage": 1,
"pageSize": 20,
})
委托用于将审批权临时转交给其他用户,通常在请假或出差时使用。
流程监控
获取监控列表
monitors = workflow.get_monitor_list({
"currentPage": 1,
"pageSize": 20,
})
流程监控用于管理员查看所有进行中的流程实例,支持终止异常流程等操作。
Webhook
获取 Webhook URL
# 获取 Webhook URL(用于外部系统触发流程)
url_info = workflow.get_webhook_url({"flowId": flow_id})
webhook_url = url_info.data # 外部系统调用的 URL
获取 Webhook 字段
# 获取 Webhook 需要传递的字段信息
params = workflow.get_webhook_params(random_str)
# 返回 Webhook 需要的参数列表
开启/关闭 Webhook
# 开启 Webhook 接收请求
workflow.webhook_start(flow_id, random_str)
Webhook 使用流程
1. 调用 get_webhook_url 获取 Webhook URL
2. 调用 webhook_start 开启接收
3. 外部系统向 Webhook URL 发送 POST 请求,携带流程表单数据
4. JNPF 自动创建并启动流程实例
流程模板其他功能
收藏流程
# 获取收藏流程列表
workflow.get_collect_flow_list()
# 收藏/取消收藏
workflow.set_collect_flow(template_id)
上架/下架
# 上架/下架流程模板
workflow.up_down_shelf({"id": template_id, "enabledMark": 1})
流程选择器
# 获取流程列表(用于发起页面选择)
workflow.get_flow_selector({"keyword": "采购"})
# 获取流程树形列表
workflow.get_tree_list(form_type="3") # 3=工作流表单
自定义按钮发起流程
在 OnlineDev 表单中,可以通过自定义按钮发起关联流程:
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。
完整流程
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:
# 正确: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,不做序列化。
# 正确:直接传 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:
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,如果先删表单,会因外键约束报错。
正确顺序:流程模板 → 表单 → 功能菜单 → 目录菜单。
# 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。
排查步骤:
- 确认表单已发布(
base_visualdev_release有记录) - 确认
workflow_node起始节点的f_form_id与base_visual_devID 一致 - 确认
App-Code正确(多租户隔离) - 运行诊断脚本:
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 的功能才能绑定流程模板。