# 工作流指南 > 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`。如果传入 `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` 的功能才能绑定流程模板。