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

18 KiB
Raw Blame History

工作流指南

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。

排查步骤:

  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 的功能才能绑定流程模板。