MT-Workflow: Odoo 可视化工作流引擎

MT-Workflow 功能总览

---

第1章：核心概念

在深入使用之前，理解以下几个核心概念至-关重要：

• 工作流定义 (Workflow Definition): 对应 workflow.definition 模型。这是流程的“蓝图”，由 bpmn_designer 创建和配置。它定义了流程的步骤、流转条件和每个节点的具体行为。一个定义可以被多次实例化。
• 工作流实例 (Workflow Instance): 对应 workflow.instance 模型。这是“蓝图”的一次具体运行，它总是关联到一个具体的Odoo业务单据（如一张销售订单、一张请假单）。它记录了该单据审批流程的当前状态、所有历史记录和待办任务。
• 审批项 (Workitem): 对应 workflow.workitem 模型。当流程流转到需要人工审批的**用户任务（审批任务）**时，系统会为指定的审批人创建一个审批项。这是审批人与流程交互的主要对象。
• 办理项 (Handling Item): 对应 workflow.handling.item 模型。当流程流转到需要人工处理但非决策性的**用户任务（办理任务）**时创建。它分为两种模式：
  • 阻塞式 (Blocking): 流程会暂停，直到办理人完成任务。
  • 非阻塞式 (Non-blocking): 流程不暂停，仅为办理人创建一个待办事项，流程会继续向下流转。
• 抄送项 (CC Item): 对应 workflow.cc_item 模型。当流程流转到**服务任务（抄送任务）**时，系统会为指定的抄送人创建一条待阅记录，并发送通知。此节点不影响流程的正常流转。
• 引擎注入 (Engine Injection): 通过 base_workflow_patch.py 实现。这是本系统的“魔法”所在，它动态地为Odoo的所有模型（技术上是base模型）添加了工作流相关的字段和方法（如 mtwk_action_start_workflow），使得任何业务单据都能轻松接入工作流。

---

第2章：工作流设计 (bpmn_designer 模块)

作为管理员，第一步是设计您的业务流程。

2.1 创建工作流定义

1. 进入 审批中心 -> 配置 -> 工作流定义。
2. 新建一个定义，填写基本信息：
   • 流程名称: 一个清晰的名称，如“采购订单审批流程 > 10000元”。
   • 关联业务模型: 选择此流程将应用于哪个Odoo模型，例如 purchase.order。这是流程与业务单据绑定的关键。
   • 优先级: 当一个业务单据可能满足多个流程定义时，数字小的优先匹配。
   • 适用条件: 使用Odoo Domain表达式，精确定义此流程适用于哪些记录。例如，对于采购订单，可以设置为 [('amount_total', '>', 10000)]。
3. 保存后，点击顶部的 “设计流程图” 按钮，进入BPMN设计器界面。

2.2 设计器界面概览

• 左侧工具栏 (Palette): 提供了所有可用的BPMN节点，如开始/结束事件、审批任务、办理任务、抄送任务和排他网关。
• 中间画布 (Canvas): 您的绘图区域，在这里拖放节点并连接它们。
• 右侧属性面板 (Properties Panel): 核心配置区域。选中画布上的任何一个元素，这里都会显示其可配置的Odoo属性。
• 右上角操作按钮: 保存、返回、导入/导出BPMN文件。
  

2.3 核心节点配置详解

2.3.1 审批任务 (User Task - Approval)

这是最常用的节点，用于需要人工决策的环节。

• 审批方式:

  • 单人审批/或签: 任何一个审批人处理后，任务即完成。
  • 多人会签: 必须所有审批人都同意，流程才会通过。任一人拒绝，流程即终止。
    

• 人员指派: 定义谁来审批。

  • 指定用户: 直接选择一个或多个Odoo用户。
  • 按职位/范围查找: （需hr模块）根据员工的职位和部门查找。
    • 搜索范围: 可限定在全局、指定部门或提交人的相关部门（本部门、上级部门等）。
  • 按汇报关系查找: （需hr模块）根据员工档案中的汇报关系（经理）自动查找。
    • 汇报层级: 1代表直属上级，2代表上级的上级，以此类推。
    • 审批至职位: 可选，设置一个“天花板”，汇报链查找到此职位后即停止，防止审批到CEO以上。
      天花板职位之上的不能发起流程
      

• 附件配置:

  • 允许上传附件: 审批时是否可以上传附件。
  • 附件为必填项: 强制审批人必须上传附件才能完成操作。
    

• 超时处理:

  • 启用: 开启后，若任务在规定时间内未处理，将自动执行预设动作。
  • 超时时长: 定义“规定时间”。
  • 超时后动作:
    • 自动同意/拒绝: 系统自动完成任务。
    • 转交给…: 将任务自动转派给另一组人。转交目标的配置方式与“人员指派”完全相同。
      

• 提醒设置:

  • 可配置多条提醒规则，在任务截止时间的之前或之后，通过Odoo通知、邮件、Chatter等渠道，向当前处理人或流程发起人发送提醒。
  • 支持重复提醒，例如“每隔1小时提醒一次，最多提醒3次”。
    

2.3.1.1 ⚠️ 高级配置与最佳实践

在配置审批任务时，请特别注意以下高级功能，它们能极大提升流程的健壮性和智能化水平：

• 理解超时审批的自动化力量:
  超时处理不仅仅是一个提醒，更是一套流程自动纠错和推进的保险机制。当某个环节的负责人因故未能及时处理时，此功能可确保业务不会因此停滞。

  • 何时使用“自动同意”？ 适用于那些审批重要性相对较低，但时效性要求高的环节。例如，一份常规报告的审阅，如果主管24小时内未提异议，则视为默认同意。
  • 何时使用“自动拒绝”？ 适用于那些需要明确批准才能进行的敏感操作。如果超时，系统默认选择最安全的操作——拒绝。
  • 何时使用“转交”？ 这是最常用且最灵活的选项。例如，可设置一个任务如果2天内未处理，则自动转交给其上级或部门内的备岗人员，确保任务始终有人跟进。

• 理解汇报链中的“天花板”设置:
  在使用“按汇报关系查找”指派人时，“审批至职位（Ceiling Job）”是一个至-关重要的风险控制工具。

  • 问题场景: 在大型企业中，如果一个基层员工的普通申请（如500元的报销）没有设置上限，汇报链可能会一直上溯，最终将任务错误地指派给CEO。
  • 解决方案: “天花板”设置解决了这个问题。例如，您可以设定一个报销流程的汇报链最高只能达到“部门总监”这个职位。当引擎沿着汇报关系查找到某位经理的职位是“部门总监”时，无论他上面是否还有更高级别的领导，审批流程都将在此处停止，并将任务指派给他。这确保了审批权限被控制在合理的范围内。
    注意 天花板之上的岗位不能发起流程，否则会一直找到最高层

• 理解超时与提醒的联动机制:
  务必清晰理解超时时长、截止时间与提醒时间三者之间的关系，它们是按以下顺序工作的：

  1. 任务创建: 当流程流转到审批节点时，任务被创建。
  2. 截止时间计算: 系统立即根据您配置的“超时时长”计算出任务的绝对截止时间 (Deadline)。公式为：任务创建时间 + 超时时长。
  3. 提醒调度: 系统根据所有提醒规则，基于上一步计算出的绝对截止时间来安排提醒的发送时间。公式为：任务截止时间 +/- 提醒规则的偏移量。
  • 示例: 一个任务在周一上午9点创建，超时时长设置为24小时。
    • 其截止时间被确定为：周二上午9点。
    • 如果您设置了一条“截止时间之前2小时提醒”的规则，那么这条提醒的预定发送时间就是：周二上午7点。
    • 如果您设置了“超时后1小时提醒（催办）”，那么发送时间就是周二上午10点。

2.3.2 办理任务 (User Task - Handling)

用于需要人工执行操作，但不需要“同意/拒绝”决策的环节。例如“财务部盖章”、“仓库备货”。

• 办理模式:
  • 阻塞式: 流程会暂停在此节点，等待办理人点击“完成办理”。
  • 非阻塞式: 流程不会暂停，仅为办理人创建一个待办事项，流程会立即继续流转到下一节点。
• 人员指派、附件、超时、提醒的配置与审批任务完全相同。
  

2.3.3 抄送任务 (Service Task - CC)

用于知会相关人员，不影响流程。

• 人员指派: 配置方式与审批任务相同，定义需要抄送给谁。

2.3.4 排他网关 (Exclusive Gateway) 与 顺序流 (Sequence Flow)

用于实现流程的分支。

1. 从网关节点拖出多条顺序流（连接线）。
2. 选中其中一条非默认的顺序流。
3. 在右侧属性面板的 “分支条件” 中，使用Odoo Domain选择器配置此条线路的通行条件。引擎在执行时，会用此Domain去匹配关联的业务单据，若匹配成功，则流程走这条路。
4. 必须在网关上指定一条 默认流 (Default Flow)，当所有其他分支条件都不满足时，流程将走默认路线。

2.4 校验与保存

点击 “保存” 按钮时，系统会运行内置的WorkflowValidator进行逻辑检查，例如：

• 是否包含结束节点？
• 网关是否至少有两条出路？
• 网关是否指定了默认流？
• 是否存在没有输入或输出的孤立节点？
  

只有校验通过后，BPMN XML内容才会保存到Odoo的“工作流定义”记录中。

---

第3章：工作流执行 (用户视角)

流程设计完成后，终端用户就可以在日常业务操作中使用它了。

3.1 用户操作

系统通过 base_workflow_patch.py 动态地在符合条件的业务单据（如销售订单、采购订单）的表单视图顶部注入了一个专属操作栏。

• 提交审批: 当单据满足某个工作流定义的“适用条件”且尚未启动流程时，此按钮可见。点击后，创建工作流实例，流程开始运行。单据的mtwk_kanban_state（看板状态）变为 to_approve。
• 同意/拒绝: 如果您是当前节点的审批人，会看到这两个按钮。点击后会弹出窗口，让您填写意见和上传附件。
• 完成办理: 如果您是阻塞式办理任务的处理人，会看到此按钮。
• 我已办理: 如果您是非阻塞式办理任务的处理人，会看到此按钮。
• 标记为已阅: 如果您是抄送人，会看到此按钮，用于确认已阅。
• 撤回申请: 如果您是流程发起人，且流程尚未被任何人处理过，可以撤回申请。
• 取回任务: 如果您刚刚批准了一个任务，但发现有误，且下游任务尚未被处理，可以取回您的审批操作，重新处理。

⚠️ 重要提示：关于“取回任务”的审慎使用

“取回任务”是一个强大的纠错功能，但必须理解其背后的机制和后果：

• 它不仅仅是收回您的“同意”状态。当您执行取回时，工作流引擎的状态会真正地回退到您这个节点，等待您重新处理。
• 所有下游的待办任务都将被自动取消。例如，您批准后，流程流转到了财务部，为财务人员创建了待办任务。此时您取回任务，财务人员的待办任务将被系统自动取消，并收到“上游节点被取回”的通知。
• 最佳使用时机: 在您提交后，立即发现错误，且确信下游同事尚未开始处理时。在执行取回前，强烈建议通过其他方式（如电话、即时消息）与下游环节的同事进行沟通，避免造成混淆。

3.2 审批中心

所有与用户相关的流程任务都汇总在 “审批中心” 菜单下。

• 我的待办: 您需要审批的所有任务列表。
• 我的办理: 您需要处理的所有办理任务列表。
• 我已处理: 您处理过的所有审批任务的历史记录。
• 抄送我的: 所有抄送给您的记录。
• 我发起的: 您发起的所有流程实例的列表。
  

3.3 流程追踪

在任何关联了工作流的业务单据上，都会出现一个名为 “流程” 的智能按钮。点击此按钮，会打开一个可视化的流程追踪界面。

• 左侧 - 流程图:
  • 绿色: 已完成的路径（节点和连线）。
  • 蓝色: 当前待处理的节点。
  • 灰色虚线: 待处理的非阻塞/抄送节点。
• 右侧 - 审批历史:
  • 按时间顺序列出所有关键操作日志，包括谁在什么时间、哪个节点做了什么操作，以及审批意见。
    

---

第4章：管理与监控

4.1 实例管理

管理员可以在 审批中心 -> 配置 -> 所有实例 查看系统里所有的工作流实例。在这里，管理员可以：

• 查看任何流程的详细状态、日志、审批项等。
• 对卡住或出错的流程执行 “作废流程” 操作。该操作会强制终止流程，取消所有相关的待办事项，并重置业务单据的工作流状态。
  

4.2 权限管理

系统定义了两个用户组：

• 用户 (User): 普通员工，只能发起流程、处理分配给自己的任务，并查看与自己相关的流程实例。
• 管理员 (Manager): 拥有所有权限，包括设计工作流定义、管理所有流程实例等。

通过严格的记录规则（Record Rules），确保了用户数据的隔离性。

---

第5章：技术架构解析 (面向开发者)

5.1 后端引擎 (visual_workflow)

• 核心引擎: SpiffWorkflow。我们没有直接使用它，而是通过自定义的 OdooWorkflowParser 来解析BPMN文件。这个解析器能够识别odoo:命名空间的自定义属性，并将标准BPMN节点（如UserTask）实例化为我们自定义的Spec类（如OdooApprovalTaskSpec）。
• 自定义Spec: spiff_extensions.py中定义了 OdooApprovalTaskSpec, OdooHandlingTaskSpec, CCTaskSpec。这些类包含了所有Odoo相关的业务逻辑，例如如何根据规则查找审批人、如何处理超时等。OdooHandlingTaskSpec 的 _update_hook 方法是实现阻塞/非阻塞逻辑的关键，它通过主动设置任务状态为WAITING来暂停引擎。
• 分支条件实现: odoo_workflow_condition.py 中的 OdooDomainCondition 是一个自定义的SpiffWorkflow操作符。它重写了 _matches 方法，在其中获取工作流上下文中的Odoo环境 (env) 和记录 (record)，然后使用Odoo的search_count方法来评估Domain表达式，从而实现了基于Odoo实时数据的动态分支判断。
• 服务层: workflow_service.py 是所有工作流操作的中心枢纽。它封装了实例化、序列化/反序列化、运行引擎 (run_workflow)、完成任务 (complete_task)等核心方法。它充当了Odoo世界和SpiffWorkflow内核之间的“翻译官”。
• 持久化: 流程实例的状态通过自定义的OdooWorkflowSerializer序列化为JSON字符串，并存储在workflow.instance模型的serialized_data字段中。反序列化时，会重新“注入”（rehydrate）Odoo的 env 和 record 对象到工作流上下文中，以便后续操作可以访问Odoo环境。

5.2 前端 (bpmn_designer & visual_workflow JS)

• 设计器 (bpmn_designer):
  • 基于 bpmn-js 库构建。
  • 通过 odoo-bpmn-moddle.json 定义了Odoo的BPMN元模型扩展，这是属性面板能够读写odoo:assigneeType等自定义属性的基础。
  • odoo_palette_provider.js 自定义了左侧工具栏，将通用的UserTask拆分为“审批任务”和“办理任务”等更具体的工具。
  • bpmn_properties_panel.js 是一个OWL组件，作为属性面板的容器。它根据当前选中元素的类型，动态加载不同的子面板（如 TaskPanel, SequenceFlowPanel）。
  • 各个子面板组件（如task_panel.js）负责渲染具体的配置项，并使用bpmnModeler.get('modeling').updateProperties()方法将用户的修改写回到BPMN元素的XML属性中。
• 追踪器 (visual_workflow):
  • workflow_instance_viewer.js 是一个注册到 ir.actions.client 的OWL组件。
  • 它通过RPC调用后端的/workflow/instance/diagram_info路由，获取流程图XML、高亮节点列表和实例状态。
  • workflow_diagram.js 子组件负责加载bpmn-js的NavigatedViewer，渲染流程图，并调用canvas.addMarker()方法根据后端数据高亮不同状态的节点和连线。
  • workflow_timeline.js 子组件负责渲染右侧的审批历史时间线。

---

第6章：重要提示与最佳实践

本章汇总了一些跨模块的重要机制和使用建议。

6.1 理解“待办事项”的截止日期

您可能会在Odoo标准的“活动/Activities”菜单中注意到，由工作流创建的待办事项，如果其对应的流程节点没有配置超时处理，其“截止日期”会被设置到一个非常遥远的未来（如100年后）。

• 这是故意设计的行为，并非错误。
• 原因: Odoo的mail.activity模型强制要求有一个截止日期。为了避免那些没有实际时间限制的流程任务在用户的待办列表中错误地显示为“逾期”，系统为其设置了一个象征性的、几乎不可能达到的截止日期。
• 结论: 请始终以流程节点的“超时处理”配置为准。只有在您为节点启用了超时处理，其计算出的截止时间才是业务上真正有意义的。Odoo活动上的截止日期主要用于在UI上进行排序和基础提醒，而流程的自动化行为（如自动同意、转交）完全由工作流引擎内部的超时机制驱动。

6.2 理解并善用“方法控制”

在工作流定义的“方法控制”页签中，您可以找到“流程控制的按钮”这一项高级功能。

• 💡 核心作用与目的:
  此功能的核心目的是将Odoo原生按钮的操作权限，交由工作流引擎管理。它能有效防止用户在审批流程完成之前，手动点击“确认”、“生效”、“过账”等关键业务按钮，从而强制所有业务操作必须严格遵循您所设计的审批路径，确保流程的严肃性和合规性。

• 工作原理:
  当您在此处配置一个按钮后，系统会自动为该按钮在视图层面注入一个额外的隐藏条件：工作流未完成或未批准。最终的隐藏条件将变为 (按钮原始的隐藏条件) 或 (工作流未完成或未批准)。
  这意味着，只有当您的工作流实例成功走到结束节点，并且最终结果是“批准”(Approved)时，这些被控制的按钮才会重新变得可见和可点击。

• 如何配置 (分步指南):

  1. 开启开发者模式: 这是获取按钮信息的关键。在Odoo界面右上角您的头像菜单中，选择“开发者工具”。
  2. 定位目标按钮: 导航到您想控制的业务单据界面（例如，一张采购订单）。
  3. 获取按钮信息:
     • 将鼠标悬停在目标按钮上（例如“确认订单”）。
     • 在弹出的开发者提示框中，找到并记下两个关键信息：
       • 方法 (Method): 这是按钮点击后会触发的python方法名，例如 button_confirm。
       • 域 (Attrs -> Invisible): 这是按钮原始的隐藏条件，例如 state not in ('draft', 'sent')。如果提示框中没有 invisible 属性，则说明该按钮没有原始隐藏条件。
  4. 填写配置:
     • 回到工作流定义的“方法控制”页签。
     • 在“流程控制的按钮”文本框中，按照以下格式输入，每行一个按钮：
       方法名, 原始隐藏条件
     • 示例 (带原始条件):
       button_confirm, state not in ('draft', 'sent')
     • 示例 (无原始条件):
       action_cancel

• ⚠️ 注意事项:

  • 逗号必须是英文逗号，并且后面最好跟一个空格。
  • 原始隐藏条件如果存在，请务必完整、准确地复制过来，否则可能导致按钮在非预期情况下显示或隐藏。
  • 此功能是流程定义级别的，意味着一旦配置，它将对所有使用此定义的工作流实例生效。

---

结论

这套可视化工作流引擎是一项卓越的Odoo增强功能。它不仅提供了符合行业标准的BPMN建模能力，更通过巧妙的架构设计，将流程引擎与Odoo的业务实体、权限体系和用户交互界面深度融合。其强大的可配置性（尤其是在人员指派、超时和提醒方面）足以满足绝大多数企业的复杂流程自动化需求。对于开发者而言，其清晰的分层和对SpiffWorkflow的优雅扩展也使其易于维护和进一步开发。