unis-oa/backend/app/engine/engine.py

5837 lines
268 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""The approval engine.
A python re-implementation of the runtime behaviour of O2OA's
``x_processplatform_service_processing`` component: job creation, activity
arrival, manual task materialisation, routing, 退回/加签/转办/撤回/催办/终止,
parallel + merge gateway counting, split fan-out and 子流程 embedding.
"""
from __future__ import annotations
import json
import logging
import math
import urllib.error
import urllib.request
import uuid
from collections.abc import Iterable
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from decimal import Decimal, InvalidOperation
from typing import NamedTuple
from sqlalchemy import String, cast, delete, event, func, or_, select, union, update
from sqlalchemy.orm import Session
from .. import models, readcache, storage
from ..service import (autofill, channels, dicts, events, external_check, fetch, formruntime,
gate, linkfill, numbering, org, outbox, personref, quota,
terminate as terminate_service, threshold, titles)
from . import definition as definition_module
from . import expressions, lookahead, tickets
from .definition import (
ACTIVITY_BEGIN,
ACTIVITY_CANCEL,
ACTIVITY_CHOICE,
ACTIVITY_DELAY,
ACTIVITY_EMBED,
ACTIVITY_END,
ACTIVITY_INVOKE,
ACTIVITY_MANUAL,
ACTIVITY_MERGE,
ACTIVITY_PARALLEL,
ACTIVITY_SCRIPT,
ACTIVITY_SPLIT,
ProcessDefinition,
)
logger = logging.getLogger("unisoa.engine")
def http_request(
method: str, url: str, payload: dict, headers: dict, timeout: float
) -> tuple[int, str]:
"""Stdlib HTTP call used by the invoke activity (no extra dependency)."""
data = json.dumps(payload, ensure_ascii=False).encode("utf-8") if payload is not None else None
request = urllib.request.Request(url, data=data, headers=headers, method=method.upper())
try:
with urllib.request.urlopen(request, timeout=timeout) as response: # noqa: S310
return int(response.status or 200), response.read().decode("utf-8", "replace")
except urllib.error.HTTPError as exc:
return int(exc.code), exc.read().decode("utf-8", "replace")
class EngineError(Exception):
"""Engine level failure surfaced as an HTTP 400 by the API layer."""
#: 谁来按这颗钮(与 ``service.node_approve.VIA_*`` 同值,那一边是判据,这一边是调用方声明)。
#: 默认 ``oa`` = OA 界面,认「OA 按钮锁定」;外部三条通道显式改口,不受锁影响。
#: 姿态是 fail-safe 的:新调用方漏传 ``via``,落在的是「锁住」那一边。
#: 这一份还交给 L3 写回:报文里取 ``{action.via}``,规则块上的 ``goBackVia`` 按它筛"只有第三方
#: 调接口退回来的那一单才发"。超时自动退回与延时自动流转没有"按的人",仍旧记 ``oa``。
VIA_OA = "oa"
VIA_OA_CONFIRM = "oa_confirm" # OA 里替第三方点头的那条横幅,认 oaLock.allowConfirm
VIA_OPEN = "open" # /open/nodes/…/decide 与 /open/tasks/{id}/execute
VIA_EMBED = "embed" # 嵌入页面里那一次 decide,以及引擎替父单开的调用子流程:
# 两条都不是人在 OA 里按按钮
@dataclass
class Actor:
"""引擎眼里的"办事的这个人"。
``ref`` 是登录账号(见 :mod:`app.service.personref`),会被写进
``oa_work.creator_identity`` / ``oa_task.identity`` 那一列;``unit`` 是随单据快照
存下来的部门路径,只服务打印与"发起人部门"这类取值,不参与认人。
"""
person_id: str
person_name: str
ref: str
unit: str = ""
unit_name: str = ""
is_admin: bool = False
@classmethod
def from_ref(cls, db: Session, person: models.User, ref: str = "") -> "Actor":
"""按人员行搭一个 Actor;``ref`` 不传就用这个人自己的账号。
传进来的 ``ref`` 也只按账号 / ``users.id`` 解析一次(拿部门路径给打印用),
不认身份 DN:那一串会漂,漂了就等于给一个不存在的人建单据快照。
"""
resolved = org.ref_for(db, ref or personref.ref_of(person))
return cls(
person_id=str(person.id),
person_name=person.display_name,
ref=personref.ref_of(person),
unit=resolved.unit,
unit_name=resolved.unit_name,
is_admin=person.role == models.ROLE_ADMIN,
)
@dataclass
class StepResult:
tasks: list[models.Task] = field(default_factory=list)
work: models.Work | None = None
completed: bool = False
status: str = ""
#: 办结后 ``work`` 会被归档删掉(不能再挂已删除的实例),这里留住主键与 job,
#: 让发起接口还能把标识返给调用方去查归档件。
work_id: str = ""
work_job: str = ""
notices: list[str] = field(default_factory=list)
#: 人工环节被自动跳过时写在这里,供流转日志说明「为什么这一环没人却也过了」。
skip_note: str = ""
# ---------------------------------------------------------------------------
# gateway pairing (static analysis of the graph)
# ---------------------------------------------------------------------------
_GATEWAY_CACHE: dict[tuple[int, int], dict[str, dict]] = {}
def pair_gateways(definition: ProcessDefinition) -> dict[str, dict]:
"""For every parallel/split, find the merge that closes it.
Returns ``{activity_id: {"merge": <id|''>, "branches": [<activity id>...]}}``.
"""
cache_key = (id(definition), len(definition.routes))
cached = _GATEWAY_CACHE.get(cache_key)
if cached is not None:
return cached
cache: dict[str, dict] = {}
for node in definition.activities.values():
if node.type not in {ACTIVITY_PARALLEL, ACTIVITY_SPLIT}:
continue
branches = [r.to_activity for r in definition.routes_from(node.id)]
merge_id = ""
for branch in branches:
found = _first_merge(definition, branch, {node.id})
if found and not merge_id:
merge_id = found
cache[node.id] = {"merge": merge_id, "branches": branches}
_GATEWAY_CACHE.clear()
_GATEWAY_CACHE[cache_key] = cache
return cache
def _first_merge(definition: ProcessDefinition, start: str, exclude: set[str]) -> str:
seen: set[str] = set(exclude)
queue = [start]
while queue:
current = queue.pop(0)
if current in seen:
continue
seen.add(current)
node = definition.activity(current)
if node is None:
continue
if node.type == ACTIVITY_MERGE:
return node.id
# 只沿往前走的路由找:分支绕出去又经驳回线拐回来时,那条线尽头的汇聚环不是
# 这个分叉的收尾(口径同 definition.downstream_ids,回头线不参与图遍历)。
queue.extend(r.to_activity for r in definition_module.forward_routes(definition, current))
return ""
# ---------------------------------------------------------------------------
# serial number
# ---------------------------------------------------------------------------
def next_serial(db: Session, process_id: str, template: dict | None = None) -> str:
"""取一个流水号:计数器按流程按周期走,编号长什么样交给表单上的编号规则。
``template`` 就是表单那个「单据编号」字段上的 ``autoRule``(前缀 / 日期段 /
位数 / 归零周期 / 后缀),没配时是 :data:`service.numbering.DEFAULT_RULE`,
与这份规则引入之前写死的「YYYYMMDD + 6 位、按月归零」一字不差。
取号本身挪进了 :func:`app.service.numbering.take`:草稿占号那一路(``service/drafts.py``)
也要从同一本计数器上取,而它不该反过来依赖引擎,口径留在 numbering 一处两边都用得上。
"""
return numbering.take(db, process_id, numbering.normalise_rule(template or {}, source="serial"))
def serial_fields(db: Session, definition: ProcessDefinition) -> list[dict]:
"""编号规则与编号格所在的那张表单:一律以**流程默认表单**为准。
编号口径写在表单那个「单据编号」字段上(``numbering.serial_rule_of``),
而环节可以各挂一张表单 —— 排号这件事只发生一次,认哪张表单必须有唯一答案,
否则同一张单走到不同环节会按不同规则排出两个号。发起时用的就是这张,
晚排的号也用它,两处永远是一件事。
"""
# 冻结定义(在途单重算编号那类调用)读快照里那张表单,新发起的读当前那张。
return autofill.form_fields(db, definition.latest_form, definition)
def _sync_serial_fields(work: models.Work, fields: list[dict]) -> None:
"""把刚排出来的单号写进表单上那些「单据编号」格;只补空格,人写过的不动。
找格子用的是 :mod:`service.autofill` 那两套清单(只读展示格 + 挂了自动带出的普通字段),
值就是 ``work.serial`` —— 与 ``autofill.resolve("serial")`` 回的是同一个东西,
所以设计器里预览成什么样、发出去就是什么,不必再拼一遍。
"""
data = autofill.fill_serial(work.data or {}, fields, work.serial)
if data != (work.data or {}):
# JSON 列要整份换掉 SQLAlchemy 才认这次改动(口径同 titles.sync_field)
work.data = data
def _backfill_serial(db: Session, work: models.Work) -> None:
"""把单号补到这条单在途与已归档的待办 / 待阅上。
待办列表、站内信、已办清单读的都是各自行上那一份 ``serial``(为了列表不必回查单据),
编号晚排时那些行是带着空号建出来的。不补就会出现「详情页有号、列表里那一行没号」,
而且按单号搜列表还搜不到这张已经编好号的单。
"""
serial = str(work.serial or "")[:64]
if not serial:
return
for model in (models.Task, models.TaskCompleted, models.Read, models.ReadCompleted):
db.execute(update(model).where(model.work == work.id).values(serial=serial))
def _refresh_title(
db: Session,
work: models.Work,
definition: ProcessDefinition,
*,
actor: Actor | None = None,
fields: list[dict] | None = None,
force: bool = False,
) -> bool:
"""表单动过之后把标题按同一规则算回来,在途的待办与待阅一起改名;返回标题是否真的换了。
改表单的三条路都走这一句:审批人办单(:func:`execute_task`)、晚排号补标题
(:func:`issue_serial`)、管理员修正表单(:func:`fix_data`)。列表和站内信读的是
待办 / 待阅各行自己那一份 ``title``,只换 ``work.title`` 就是「详情页改了名字、
列表还写着老那一句」,所以两处必须一起改,口径见 :func:`app.service.titles.refresh`。
"""
if not titles.refresh(db, work, definition, actor=actor, fields=fields, force=force):
return False
titles.sync_pending_titles(db, work.id, work.title)
return True
def issue_serial(
db: Session,
work: models.Work,
definition: ProcessDefinition,
*,
actor: Actor | None = None,
fields: list[dict] | None = None,
) -> bool:
"""给一张还没编号的单据补发单号,并把跟着单号走的东西一次对齐;返回是否真的排了号。
编号时机配成「走到指定环节」或「存草稿就占号」时,``create_job`` 那一刻不排号,
走到那一步再由 :func:`_advance` 回来补这一句。补的时候四件事一起办,少一件就是
界面与库里各说一套:
1. ``work.serial`` 排出来(计数器与发起时同一本账,见 :func:`next_serial`);
2. 表单里那格「单据编号」跟着填上;
3. 在途 / 已归档的待办、待阅补上单号;
4. 标题按规则重算一次 —— 模板里写了 ``{单号}`` 的单子,这一刻之前那句标题一直
缺着号, ``force=True`` 让这一句补回来(发起人亲手写过的标题仍然不动)。
已经排过号就地返回 ``False``:退回重走、重复触发都不会让一张单占两个号。
"""
if str(work.serial or "").strip():
return False
shown = fields if fields is not None else serial_fields(db, definition)
work.serial = next_serial(db, work.process, numbering.serial_rule_of(shown))
_sync_serial_fields(work, shown)
_backfill_serial(db, work)
_refresh_title(db, work, definition, actor=actor, fields=shown, force=True)
_log_serial(db, work, definition, actor)
db.flush()
return True
def _log_serial(db: Session, work: models.Work, definition: ProcessDefinition, actor: Actor | None) -> None:
"""审批记录里旁挂一句「编号已生成」:晚排号的单子要能回答"这个号是哪一步给的了"。
走 :func:`_event_log` 那条旁挂事件的路子(与挂起 / 改数据同一口径),它不算一次流转、
不进连线,画布与审批记录都不会凭空多出一「步」。
"""
activity = definition.activity(work.activity) or definition.begin
if activity is None:
return
_event_log(db, work, activity, actor, f"生成流程编号:{work.serial}", LOG_SERIAL)
# ---------------------------------------------------------------------------
# notifications
# ---------------------------------------------------------------------------
def notify(
db: Session,
identities: list[str],
*,
type_: str,
title: str,
body: str = "",
job: str = "",
work: str = "",
task: str = "",
process: str = "",
sender: str = "",
channel_event: str = "",
) -> None:
"""写站内信,并按「消息渠道」配置把同一句话再送一份到邮箱 / 群机器人。
渠道投递是**同一事务里入队**(见 ``service/channels.py``):站内信落库而邮件没排上队,
或者反过来,都会让人排查半天。真正发出去的动作在后台调度线程里,不占这次请求的时间。
``channel_event`` 留空时按 ``type_`` 同名处理;只有"同一类型里只推其中一种"时才需要显式给。
"""
rows = []
for identity in identities:
if not identity:
continue
row = models.Notification(
type=type_,
title=title[:500],
body=body,
job=job,
work=work,
task=task,
process=process,
identity=identity,
sender=sender,
)
db.add(row)
rows.append(row)
if not rows:
return
# 只刷这批站内信:下面要按它们排渠道投递,得先落库,但没理由把调用处顺带脏掉的
# 单据行也一起写出去(热路径上 ``work`` 常常正带着没写完的游标改动,多刷一次就是
# 多一条随后被盖掉的 ``UPDATE oa_work``)。站内信的主键是 Python 生成的,
# ``oa_notify_delivery`` 那边按 id 引用它,不靠这次 flush 拿到自增号。
db.flush(rows)
if not any((row.identity for row in rows)):
return
by_identity = {row.identity: row.id for row in rows}
channels.enqueue_for(
db,
list(by_identity),
event=channel_event or type_,
title=title,
body=body,
job=job,
work=work,
task=task,
process=process,
notification=",".join(by_identity.values())[:32],
)
# ---------------------------------------------------------------------------
# job creation
# ---------------------------------------------------------------------------
def create_job(
db: Session,
*,
process_id: str,
actor: Actor,
data: dict | None = None,
title: str = "",
work_create_type: str = "surface",
attachments: list[dict] | None = None,
parent_work: str = "",
parent_job: str = "",
embed_activity: str = "",
#: 草稿阶段就占下的单号(流程配了「存草稿就生成编号」时由 oa_draft.serial 递过来)。
#: 接过来是为了同一张草稿反复保存只占一个号,不是又排一个新的。
serial: str = "",
#: 开始环节开了第三方审批(提交由第三方表态或发起人确认)时的建单姿势:
#: 单子在开始环节**停着**,不流转、不发 work.submitted。之后由
#: :func:`start_from_begin` 把这一趟真正提交出去。
hold_at_begin: bool = False,
#: 谁来按「发起」这颗钮:见模块头那四个 ``VIA_*``。发起这一刻按下去的,其实就是
#: 开始环节那一颗「提交」(建单 + 提交一起做完),所以 ``oaLock.actions`` 里的
#: ``start`` 也管它——否则锁着开始环节的流程,人照样能从发起页把单发出去,
#: 外部系统一条表态都没收到,OA 这边已经跑起来了。
via: str = VIA_OA,
) -> StepResult:
definition = definition_module.load(db, process_id)
if definition.begin is None:
raise EngineError("流程缺少开始环节,无法发起")
# 通道闸放在冻快照、排单号、建单之前:挡下这一刻库里还干干净净,不会留下一张
# 「占了号却从没提交出去」的单。判据与 start_from_begin 同一把尺。
_lock_guard(db, process_id, definition.begin, "start", via, definition, starting=True)
# 发起这一刻把流程 / 环节 / 路由连同那几张表单冻成一份不可变的快照,这张单之后
# 只认它:中途改流程、改表单、发布新版,都不许改变一张已经在路上单子脚下的图。
# 新单照旧从当前设计出发,所以"改完立刻对新单生效"这条口径一字未动。
# 总闸在系统设置「流程设计」(``design_pin_enabled``,默认开,免重启),关掉回空串。
snapshot_id = definition_module.pin(db, process_id)
# 额度台账挡借用:名下还有没冲销完的就别再起一张。放在建单之前,挡住时库里
# 干干净净,不会留下一张已经建好却没占上额度的单。
if work_create_type != "embed":
quota.check_new_issue(db, process_id=definition.process_id, person=actor.person_id, actor=actor)
now = datetime.now()
job_id = uuid.uuid4().hex
work = models.Work(
job=job_id,
title=(title or definition.name)[:500],
process=definition.process_id,
process_name=definition.name,
process_alias=definition.alias,
category=definition.category,
category_name=definition.category_name,
form=definition.latest_form,
design_snapshot=snapshot_id,
# 发起页填的值先攥在手里,等 _apply_form_runtime 过完环节规则再落:
# 先塞进 work.data 会让「联动隐藏的字段退回原值」退化成「保留提交值」。
data={},
creator=actor.person_id,
creator_person=actor.person_name,
# creator_identity 存的是账号(列名沿用历史,见 service/personref.py 的口径说明);
# 姓名与部门是随单据快照下来的展示字段,不参与认人
creator_identity=actor.ref,
creator_identity_name=actor.person_name,
creator_unit=actor.unit,
creator_unit_name=actor.unit_name,
status="running",
work_create_type=work_create_type,
parent_work=parent_work,
parent_job=parent_job,
embed_activity=embed_activity,
start_time=now,
start_time_month=now.strftime("%Y%m"),
activity=definition.begin.id,
activity_name=definition.begin.name,
activity_type=ACTIVITY_BEGIN,
activity_token="",
tokens=[],
joins={},
variables={},
)
# 编号规则写在表单那个「单据编号」字段上,所以得先把表单读出来再算号;
# 换流程复用同一张表单时,编号口径跟着表单走。
begin_fields = serial_fields(db, definition)
# 什么时候排号由流程自己说(oa_process.serial_config,默认就是发起这一刻,行为不变)。
# 三种情况在这一步落定:已经占下的号原样接过来(草稿占的,或新建填单时凭条占的);
# 该在发起时排的就现在排;配了「到指定环节才排 / 不自动排」的先留空,由 _advance
# 走到那一步再补(接口直接发起、没有草稿也没凭条时,create / draft 这两档
# 也在这里补上,别让单子永远没号)。
reserved = str(serial or "").strip()
if reserved:
work.serial = reserved[:64]
elif numbering.issues_at_start(numbering.timing_of(definition), definition.begin.id):
work.serial = next_serial(db, process_id, numbering.serial_rule_of(begin_fields))
db.add(work)
db.flush()
# 发起页填的表单一并过一遍环节规则:明细表整型、公式重算、必填校验。
# 嵌入子流程是引擎替父单开的,数据来自父单,不是子单申请人当场填的,
# 所以只过规则不卡必填——否则父单数据凑不齐子单的必填项,子流程永远起不来。
# 必填还得多等一步:表单里摆了「流程标题」字段时,它的值是标题规则算出来的,
# 先卡必填会把系统自己马上要填好的那一格当成没填。
# 系统带出格先落一遍,再过表单运行时:回源带出(``fetch``)的入参常常正是这些格
# ——「开户行名称 / 收款账号」按**申请人**去账户信息里取,而申请人是 ``auto: creator``。
# 界面发起时前端已经把申请人带上过,这一句是空转;但接口发起、草稿转正、第三方代发
# 这三条服务端建单的路手里只有几个人告诉它的值,回源那一刻申请人还是空的,取不到东西,
# 于是这些必填格永远在报「请填写开户行名称」(它自己带得出来)。
# 下面那句原有的 apply_form 保留:公式与回源之后仍会有新空槽要补,它只填空值,重跑无副作用。
autofill.apply_form(db, work, actor=actor, fields=begin_fields)
_apply_form_runtime(
db, work, actor, definition.begin, begin_fields, dict(data or {}),
enforce=work_create_type != "embed",
defer_required=True,
)
# 系统自动带出的字段在发起这一刻算好落库(带生成规则的按规则写):条件表达式、
# 按表单字段找人、后续环节的表单都直接读 work.data,不用再关心是谁发起的。
autofill.apply_form(db, work, actor=actor, fields=begin_fields)
# 标题规则要等表单数据和单号都定下来才算:模板里随时可能引用它们。
# 它顺手把算好的标题写回标题字段,写完之后才是本次提交的真数据,这时才查必填。
titles.apply_start(db, work, definition, actor=actor, given=title, fields=begin_fields)
if work_create_type != "embed":
_validate_form(db, work, definition.begin, begin_fields)
# 发起页直提这条路也要有闸门,否则等于给闸门留了一个绕过它的正门(方案 §5.2)。
gate.check(db, work, activity=definition.begin, route=None, going_back=False,
actor=actor, fields=begin_fields)
token = tickets.add_token(work.tokens, definition.begin.id)
work.activity_token = token["path"]
for payload in attachments or []:
_attach_payload(db, work, payload, actor, definition.begin.id, definition.begin.name)
if hold_at_begin:
# 停在开始环节等提交:不发 work.submitted(这一单还没提交出去),不流转。
# 表单校验、编号、标题、自动带出、闸门到这里都已经过完,落定的是"待提交",
# 之后 :func:`start_from_begin` 再走真正的那一步。
return StepResult(work=work, work_id=work.id, work_job=work.job, status="running")
# 事件订阅:单据提交。放在这一刻是因为单号、标题、表单数据到这里才全部定下来,
# 推出去的快照才是对方能直接用的那份;与本次发起同一事务,回滚时这条也不会留下。
events.emit(db, work, "work.submitted", activity_name=definition.begin.name,
actor_name=actor.person_name)
return _advance(
db,
work,
definition,
from_activity=definition.begin.id,
route=definition.routes_from(definition.begin.id)[0]
if definition.routes_from(definition.begin.id)
else None,
actor=actor,
opinion="",
token=token,
log_type="create",
via=via,
)
def start_from_begin(
db: Session,
*,
work: models.Work,
actor: Actor,
route_name: str = "",
opinion: str = "",
data: dict | None = None,
#: 谁来按这颗「提交」钮:见模块头那四个 ``VIA_*``
via: str = VIA_OA,
) -> StepResult:
"""把停在开始环节的单据真正提交出去(``hold_at_begin`` 建的那一单的下一步)。
与 :func:`execute_task` 同一把尺:环节字段权限、明细表整型、公式重算、必填、
写回卡控、提交闸门一条不少——第三方表态里带的那几格值也要过这一遍才落库。
事件在流转的那一刻发:停着的单不算提交,提交出去才算。
停在开始环节的单有两条来路,而开始环节那条待办只在其中一条上存在:第三方接管
开始环节建的那一单(``hold_at_begin``)手上没有待办;被人**退回 / 撤回到发起人重填**
的那一张压着一条真实的「发起人」待办(``go_back`` 落进 :func:`_arrive_manual` 的 begin
分支派的那一条)。提交这一步必须连着它一起结掉,否则单子已经走到下一环,发起人的
「我的待办」里还留着一条点不动的「发起人」——同一张单在列表里摆出两行。
"""
if work.status != "running":
raise EngineError("流程已结束,无法再提交")
_ensure_active(work)
definition = definition_module.for_work(db, work)
begin = definition.begin
if begin is None:
raise EngineError("流程缺少开始环节,无法提交")
if work.activity != begin.id or work.activity_type != ACTIVITY_BEGIN:
raise EngineError("这张单已经离开开始环节,不能再从这里提交")
_lock_guard(db, work.process, begin, "start", via, definition)
activity_fields = _activity_form_fields(db, work, begin, definition)
form_before = dict(work.data or {})
_apply_form_runtime(
db, work, actor, begin, activity_fields, dict(data or {}),
)
_validate_form(db, work, begin, activity_fields)
form_changes = form_change_notes(activity_fields, form_before, work.data or {}, dict(data or {}))
# 写回卡控与提交闸门:位置与 execute_task 一致——在路由判断之前挡下走不了的单,
# 别让"这一单还没提交"的横幅点一下才看到一句「外部核验没过」。
blocked = outbox.blocking(db, job=work.job)
if blocked:
raise EngineError(outbox.blocking_note(db, blocked))
route = _resolve_route(definition, begin, route_name, work, work.data or {}, db=db, actor=actor)
if route is None:
raise EngineError("请选择有效的流转路由")
gate.check(db, work, activity=begin, route=route, going_back=False,
actor=actor, fields=activity_fields)
# 开始环节上这条待办是退回来时派下来的,此刻由这一次提交替本人办完:口径照
# execute_task——本人那条记一次正常表态(进「我的已办」与审批记录,改动也留痕),
# 万一还压着别人的(管理员替发起人提交会碰上)按自动结办记,不留在手上发霉。
# 闸门与校验都在上面办完了,走到这里这一步一定走得出去。
now = datetime.now()
for pending in db.execute(
select(models.Task).where(
models.Task.work == work.id,
models.Task.activity == begin.id,
models.Task.status == "pending",
).order_by(models.Task.id)
).scalars().all():
_complete_task(db, pending, actor, route, opinion, "", now,
"normal" if str(pending.identity or "") == str(actor.ref or "") else "auto",
form_changes)
# 建单那一刻落下的开始环节 token 原样交回引擎:路径与令牌都还是当时那份。
token = tickets.find_token(work.tokens, begin.id) or {
"id": "", "activity": begin.id, "path": work.activity_token,
}
events.emit(db, work, "work.submitted", activity_name=begin.name,
actor_name=actor.person_name)
return _advance(
db, work, definition, from_activity=begin.id, route=route,
actor=actor, opinion=opinion, token=token, log_type="create", via=via,
)
def _activity_form_fields(
db: Session, work: models.Work, activity, definition: ProcessDefinition | None = None
) -> list[dict]:
"""环节当前用的那张表单的字段列表,取表单的口径与引擎其他地方一致。
``definition`` 传进来的是这张单冻结的那一版时,字段清单读快照里那张表单——别人
把表单改了、加了必填、换了 key,都不该改变这张单该填什么。没传(或没冻过结)照旧现读。
"""
form_id = (activity.form if activity is not None else "") or work.form
return autofill.form_fields(db, form_id, definition)
def without_trace_keys(incoming: dict | None, fields: list[dict] | None = None) -> dict:
"""把页面回传的系统留痕键丢掉:下划线开头、且表单没定义成字段的那些。
``_fetch`` / ``_quota`` / ``_formulaErrors`` / ``_outbound`` 一律由服务端在链路里自己写。
页面手里是它打开那一刻的旧快照,按「表单里没有的键原样保留」收下来会把刚落地的留痕
盖回旧的一份——与「外部取回的值、台账带出的三个数都以服务端为准」同一分寸。表单真
定义了同名字段时以表单为准,交给上面的环节权限去管。
"""
payload = dict(incoming or {})
known = {str(item.get("key") or "") for item in fields or []}
for key in [key for key in payload if str(key).startswith("_") and key not in known]:
payload.pop(key)
return payload
def _apply_form_runtime(
db: Session,
work: models.Work,
actor: Actor | None,
activity,
fields: list[dict],
incoming: dict | None = None,
*,
enforce: bool = True,
defer_required: bool = False,
) -> None:
"""把这次提交的表单改动过一遍环节规则,再落到 ``work.data`` 上。
关键在"以库里的值为底":请求体里那些本环节只读、隐藏或该由公式算出来的字段
会被整格丢掉,原来是什么还是什么 —— 既不能被改成新值,也不该被顺手抹掉。
顺序是:挡掉不该动的字段 -> 整型明细表 -> 重算公式 -> 必填校验。公式一定是在
真实数据上算的,前端塞进来的假合计写不进去;必填卡的是"这个环节必须补上的信息",
不是发起人那一步的历史欠账。
"""
if not fields:
payload = without_trace_keys(incoming)
if payload:
work.data = {**(work.data or {}), **formruntime.normalize_person_values(db, fields, payload)}
return
# 标签页那一格被这一环藏起来时,页里那些格子也一起没了:展开成 hidden 之后,
# 下面"这一格本环节不该改"那一段才会把它们一起回滚掉,必填也不会再向人要它们。
perms = formruntime.perm_map(activity.config if activity is not None else {}, fields)
tables = {
str(item.get("key") or ""): item
for item in fields
if str(item.get("type") or "") == "table" and item.get("key")
}
cache = dicts.DictCache(db)
payload = without_trace_keys(incoming, fields)
# 选人那一格统一落成账号再往下走:公式、条件分支、额度、待办派工读的都是这一格,
# 让 DN 混进来的话,部门一改名这些下游全跟着瞎(口径见 service/personref.py)
formruntime.normalize_person_values(db, fields, payload)
# 先按「没有联动」的口径过一遍:公式值和表单里没有的键一律不进 payload。
writable = formruntime.editable_keys(fields, perms)
# 隐藏字段(hidden / 环节配成隐藏)界面上本来就给人看不到,它们的值多半是
# 发起页/脚本/字典带出来的,不该因为“看不见”就被当成乱提交抢掉。
hidden_keys = {
str(item.get("key") or "") for item in fields
if str(item.get("type") or "") == "hidden" or perms.get(str(item.get("key") or "")) == formruntime.PERM_HIDDEN
}
for key in list(payload.keys()):
field_def = next((item for item in fields if str(item.get("key") or "") == key), None)
if field_def is None:
# 表单里没有的键(变量、系统写的标记)原样保留,别替设计器做主。
continue
kind = str(field_def.get("type") or "")
if kind == "table":
payload[key] = formruntime.normalise_rows(payload[key], tables[key])
elif kind == "formula" or (key not in writable and key not in hidden_keys):
payload.pop(key, None)
data = {**(work.data or {}), **payload}
for key, field_def in tables.items():
if key not in data:
data[key] = []
# 字段联动:可见性 / 只读要按合并后的数据才算得出来,算完再决定这次提交的
# 哪些值真的收。被联动藏起来或锁掉的字段退回原值,不顺手抹掉历史数据。
# 只被自己那句条件收走 / 锁住的格子(「有值才显示」「有值就锁住」那一类)跟着一起收下:
# 这一笔值正是让它藏起来的原因,退回原样等于把人刚写下的字抹掉。
writable = (
formruntime.editable_keys(fields, perms, data)
| hidden_keys
| formruntime.self_gated_keys(fields, perms, data)
)
known = {str(item.get("key") or "") for item in fields}
for key, value in list(payload.items()):
# 只回滚「表单里定义了、但这个环节不该改」的字段;表单里没有的键
# (变量、系统写的标记)上面已经决定原样保留,这里不能再顺手抹掉。
if key not in writable and key in known:
if key in (work.data or {}):
data[key] = (work.data or {})[key]
else:
data.pop(key, None)
# 带出值以字典为准:前端把它改成什么都覆盖回去,没配 autoFill 的字段不受影响。
dicts.apply_auto_fill(fields, data, cache)
# 外部系统取回来的值同样以服务端为准:按同样的入参再取一次并覆盖前端,命中缓存不重复外呼。
# 排在公式之前,「预算余额 - 申请金额 >= 0」这类公式与后面的条件分支才读到同一份数。
# 带上这一环的字段权限:那一格被本环节藏起来时,取数失败只留痕不拦人(与阈值、额度同一口径)。
fetch.apply_form(db, fields, data, work=work, actor=actor, activity=activity, perms=perms)
# 关联审批单带出来的值同样以服务端为准:按这一格挂着的那几张单现算并覆盖前端。
# 主表那一格按配的那一档合并(几张单合成一个数),明细表那一头一单一行、
# 只在关联变化时重排(人改过的其它列一个字不动)。排在公式之前,
# 「关联单金额合计」那类公式读到的才是刚补好的那几行。口径见 service/linkfill.py。
linkfill.apply(db, fields, data)
work.data = data
formruntime.compute_formulas(fields, data, _context(db, work, actor))
work.data = data
# 额度:带出总额/已用/剩余,判超支,再按本次金额记账。必须排在公式之后——「本次
# 申请金额」多半就是上一行公式算出来的明细合计;也必须排在必填校验之前,超支要
# 在报"请填写某某"之前先挡下来。带出值以台账为准,前端把剩余额度改成多少都没用。
quota.apply_and_check(db, work, fields, data, actor=actor, activity=activity, perms=perms)
# 阈值:到没到线在这里判,命中程度写进字段指定的那一格,条件分支与必填联动读同一个结果。
# 页面上的红字只是把同一句话再说一遍——只在前端判等于没有判。
threshold.apply_check(db, fields, data, work=work, actor=actor, perms=perms)
work.data = data
if enforce:
if not defer_required:
_validate_form(db, work, activity, fields)
def _validate_form(db: Session, work: models.Work, activity, fields: list[dict]) -> None:
"""提交校验:必填、明细行数这类「这个环节必须补上的信息」。
单独拆出来是因为发起流程时要晚一步再查:标题字段的值由标题规则在这一轮里算出来,
提前查会把系统马上要填好的那一格当成没填。
"""
if not fields:
return
# 同一份展开:藏起来的格子不参与必填(判据见 service/tabpages.expand_perms)
perms = formruntime.perm_map(activity.config if activity is not None else {}, fields)
problems = formruntime.validate_submit(
fields, perms, dict(work.data or {}), dicts.DictCache(db)
)
if problems:
raise EngineError("表单校验未通过:" + ";".join(problems[:6]))
def _attach_payload(
db: Session,
work: models.Work,
payload: dict,
actor: Actor,
activity_id: str,
activity_name: str,
) -> None:
# 发起页先把文件传上 /attachment,再把返回的对象随单带上:这条记录已经存在,
# 只需要认领到本单,直接按同一个 id 再插一条会撞主键。
attachment_id = str(payload.get("id") or "")
existing = db.get(models.Attachment, attachment_id) if attachment_id else None
if existing is not None:
if not existing.work:
existing.process = work.process
existing.job = work.job
existing.work = work.id
existing.activity = activity_id
existing.activity_name = activity_name
existing.person = actor.person_id
existing.person_name = actor.person_name
db.flush()
return
db.add(
models.Attachment(
id=attachment_id or models.new_id(),
name=str(payload.get("name") or "附件"),
extension=str(payload.get("extension") or ""),
storage=str(payload.get("storage") or ""),
length=int(payload.get("length") or 0),
type=str(payload.get("type") or "attachment"),
text=str(payload.get("text") or ""),
process=work.process,
job=work.job,
work=work.id,
activity=activity_id,
activity_name=activity_name,
person=actor.person_id,
person_name=actor.person_name,
)
)
# ---------------------------------------------------------------------------
# 批注 / 审批意见随附的图片与文件:字节在 MinIO,记录里只留引用快照
# ---------------------------------------------------------------------------
#: 写进 oa_attachment.type,说明这条附件是随批注、审批意见还是处理意见发出去的
ATTACHMENT_COMMENT = models.Attachment.KIND_COMMENT
ATTACHMENT_OPINION = models.Attachment.KIND_OPINION
ATTACHMENT_READ = models.Attachment.KIND_READ
def attachment_ref(row: models.Attachment) -> dict:
"""一条附件的引用快照。存进 JSON 列,读批注/意见时不必再回附件表。
``preview`` 也一起存:审批轨迹里的随附文件靠它决定显示成图片、文档还是
只能下载。历史快照里没有这个字段,前端会按扩展名兜底判断。
"""
return {
"id": row.id,
"name": row.name,
"extension": row.extension,
"length": int(row.length or 0),
"is_image": storage.is_image_name(row.name),
"preview": storage.describe_preview(row.name, int(row.length or 0)).as_dict(),
}
def claim_attachments(
db: Session,
*,
ids: list[str] | None,
actor: Actor,
kind: str,
owner_id: str,
work: models.Work | models.WorkCompleted | None = None,
activity_id: str = "",
activity_name: str = "",
) -> list[dict]:
"""把前端先传好的文件认领到这条批注/意见上,返回引用快照列表。
只认「本人上传」且「还没被别人认领」的两条硬规则:文件名、大小、扩展名一律回
附件表取,前端传回来的元数据一个字都不信,否则随手改个 name 就能往单子里塞假附件。
``work`` 给在途单也给归档单:办结之后补的批注、填的处理意见挂在
``oa_work_completed`` 上,附件行照样要认到这一单(``work`` / ``job`` / ``process``)
并直接标成已归档——不回填的话按单查附件、按流程统计存储用量都看不见这些文件。
"""
refs: list[dict] = []
seen: set[str] = set()
for raw in ids or []:
attachment_id = str(raw or "")
if not attachment_id or attachment_id in seen:
continue
seen.add(attachment_id)
row = db.get(models.Attachment, attachment_id)
if row is None:
raise EngineError("附件已失效,请重新上传")
if row.person != actor.person_id and not actor.is_admin:
raise EngineError("只能附上本人上传的文件")
if row.business_id and row.business_id != owner_id:
raise EngineError(f"附件《{row.name}》已被其它批注使用")
row.type = kind
row.business_id = owner_id
if work is not None:
archived = isinstance(work, models.WorkCompleted)
row.process = work.process
row.job = work.job
row.work = work.id
row.activity = activity_id
row.activity_name = activity_name
row.completed = archived
row.work_completed = work.id if archived else ""
refs.append(attachment_ref(row))
db.flush()
return refs
def release_attachments(db: Session, refs: list[dict] | None, owner_id: str) -> None:
"""记录删掉后把它独占的附件一起清掉,别在 MinIO 里留下没人认领的孤儿对象。"""
for ref in refs or []:
row = db.get(models.Attachment, str(ref.get("id") or ""))
if row is None or (row.business_id and row.business_id != owner_id):
continue
if row.storage:
try:
storage.resolve_uri(row.storage).delete(row.storage)
except storage.StorageError as exc:
# 对象删不掉不该挡住业务,记录照样要删;留条日志总比静默丢对象好
logger.warning("批注附件文件删除失败 %s:%s", row.storage, exc)
db.delete(row)
# ---------------------------------------------------------------------------
# core routing
# ---------------------------------------------------------------------------
def _context(db: Session, work: models.Work, actor: Actor | None, extra: dict | None = None) -> dict:
payload = {
"data": dict(work.data or {}),
"work": {
"id": work.id,
"job": work.job,
"serial": work.serial,
"title": work.title,
"process": work.process,
"creator_identity": work.creator_identity,
"creator": work.creator,
"creator_unit": work.creator_unit,
},
"user": {
"person": actor.person_id if actor else work.creator,
"identity": actor.ref if actor else work.creator_identity,
"unit": actor.unit if actor else work.creator_unit,
},
"variables": dict(work.variables or {}),
}
if extra:
payload.update(extra)
return payload
def _action_of(definition: definition_module.ProcessDefinition, route, opinion: str,
via: str = VIA_OA) -> dict:
"""「是哪一颗按钮把单子送到了这一刻」,交给发件箱,只喂报文里的 ``{action.x}``。
四个时刻都用同一份形状:``leave`` 与 ``goBack`` 是本环节刚按下去的那颗钮,
``arrive`` 是**把单子送到这一环**的那颗钮(上一环节按的),``recall`` 是撤回那条已办。
``decision`` 走 ``definition.decision_of`` 那一份读法——环节上的 ``routeDecisions`` 覆盖
也算数,否则设计器里改了语义、报文里还写着旧的。
``via`` 是**这一送走的哪条通道**(OA 界面 / 外部表态后 OA 确认 / 第三方开放接口 / 嵌入页与
子流程),报文取 ``{action.via}``:第三方自己送进来的那一单,对面不必再被回发一条回声。
"""
return {
"route": str(route.name or "") if route is not None else "",
"route_alias": str(route.alias or "") if route is not None else "",
"decision": (definition_module.decision_of(definition, route) or str(route.decision or ""))
if route is not None else "",
"opinion": str(opinion or ""),
"via": str(via or VIA_OA),
}
def _advance(
db: Session,
work: models.Work,
definition: ProcessDefinition,
*,
from_activity: str,
route: definition_module.RouteNode | None,
actor: Actor | None,
opinion: str,
token: dict | None,
log_type: str = "normal",
split_value: str = "",
#: 把单子送到这一刻的那一下走的哪条通道:只喂写回报文里的 ``{action.via}``,
#: 认锁与放行不看它(那是各入口自己那句 ``_lock_guard`` 的事)。
via: str = VIA_OA,
) -> StepResult:
"""Follow ``route`` and keep arriving until work parks, spawns tasks or ends."""
result = StepResult(work=work)
# 编号时机读一次就够:循环里每一轮都要问「这一环是不是该排号」
timing = numbering.timing_of(definition)
if token and token.get("id"):
work.tokens = [t for t in work.tokens if t.get("id") != token.get("id")]
prefix = tickets.prefix_of(token.get("path", ""), token.get("activity", "")) if token else ""
join_key = (token or {}).get("join", "")
current_split = split_value or (token or {}).get("split_value", "")
# 拆分带下来的那一行明细要跟着 token 一路往下传,不然它只停在
# 拆分环节自己的 token 上,下一环的子待办根本拿不到。
split_item = (token or {}).get("split_item")
source = definition.activity(from_activity)
if route is None:
# Terminal arrival without a route (e.g. a branch that has nowhere to go).
_finish_if_idle(db, work, definition, result, actor)
return result
target = definition.activity(route.to_activity)
if target is None:
raise EngineError(f"路由 {route.name} 指向的环节不存在")
# 往回走 = 这一段要重新走一遍:把「谁已经批过」的记忆清到此刻,与 go_back / 撤回 /
# 干预改道用的是同一条基线。挂在这里而不是各入口,是因为"按下一条线往外走"这件事
# 只在 _advance 表达一次——界面提交、开放接口代点头、超时自动驳回、第三方回写
# 全都从这儿过;只挂在 go_back 上时,画成「驳回(reject)」的那条线漏在外面,
# 驳回之后重走就把驳回前那几票全当批过,一整条链在两秒钟里自动通过。
if definition_module.is_back_route(definition, route):
work.variables = {**(work.variables or {}), DEDUP_SINCE_KEY: datetime.now().isoformat()}
guard = 0
while True:
guard += 1
if guard > 200:
raise EngineError("流程路由出现环路,请检查流程设计")
# L3 挂载点之一「本环节审批通过后」:source 就是这一刻正在被办完、正要离开的环节。
# 放在循环顶部而不是各调用方里,是因为"离开某个环节往外走"这件事只在这里表达一次:
# 提交、审批(含会签最后一票)、超时唤醒、子流程回收、拆分支线全都从这儿过。
# 退回(goBack)不算审批完成,不触发——它不是"批完了",是"打回去了"。
# 退回要回写就挂在同一环节的「本环节被退回时」上(go_back 里那一处钩子)。
if source is not None and route.decision != "goBack":
outbox.enqueue_node(db, work, source, phase=outbox.TRIGGER_LEAVE, actor=actor,
action=_action_of(definition, route, opinion, via))
# 「本环节通过后生成编号」也挂在这一刻:与报文写回同一个口径,退回不算批完,
# 所以退回时不会有人白白占掉一个号。
if numbering.due_at(timing, source.id, numbering.WHEN_LEAVE):
issue_serial(db, work, definition, actor=actor)
jumped = _jump_redirect(db, work, definition, target)
if jumped is not None:
route = definition_module.RouteNode(
id="goBackJump",
name=route.name,
alias=f"{route.alias or route.name}(直返{jumped.name})",
from_activity=source.id,
to_activity=jumped.id,
decision=route.decision,
)
target = jumped
log_type = "jump"
arrived_token = {
"id": uuid.uuid4().hex,
"activity": target.id,
"path": tickets.unique_path(work.tokens, f"{prefix}/{target.id}" if prefix else target.id),
}
if join_key:
arrived_token["join"] = join_key
if current_split:
arrived_token["split_value"] = current_split
if isinstance(split_item, dict):
arrived_token["split_item"] = split_item
_log(
db,
work,
definition,
from_activity=source,
to_activity=target,
route=route,
actor=actor,
opinion=opinion,
token=arrived_token,
log_type=log_type,
split_value=current_split,
)
# L3 挂载点之二「到达本环节时」:放在类型分发之前而不是各分支里面,是因为
# "到了"这件事只在这里表达一次;与流转同事务提交,所以不会出现"环节到了、报文没落库"。
# 没配写回的流程在 outbox 里就地返回,一次数据库都不碰。
outbox.enqueue_node(db, work, target, phase=outbox.TRIGGER_ARRIVE, actor=actor,
action=_action_of(definition, route, opinion, via))
# 「到达本环节就生成编号」排在派发待办之前:第一条带号的待办和第一条站内信
# 就该带着单号,不必等下一次刷新才看见。
if numbering.due_at(timing, target.id, numbering.WHEN_ENTER):
issue_serial(db, work, definition, actor=actor)
if target.type in (ACTIVITY_MANUAL, ACTIVITY_BEGIN):
# 线指着开始环节(设计器拉的「退回 / 退回修改」这种)走同一个入口:
# _arrive_manual 里 begin 那一支把待办派给发起人,「重新提交」那条出口
# 再把单子送回原环。没有这一支,点那颗按钮就是「未知的环节类型: begin」。
created = _arrive_manual(
db, work, definition, target, actor, arrived_token, result,
via_goback=route is not None and definition_module.is_back_route(definition, route),
)
if created:
db.flush()
return result
# 没有解析到任何处理人 -> 环节自动跳过
route = _single_route(definition, target)
source = target
opinion = result.skip_note
result.skip_note = ""
# 整环跳过用专门的日志类型,审批记录才把它当成一步显示出来(见 service/flowmap.py)。
log_type = LOG_SKIP_ACTIVITY
prefix = tickets.prefix_of(arrived_token["path"], target.id)
join_key = arrived_token.get("join", "")
if route is None:
_finish_if_idle(db, work, definition, result, actor)
return result
# 和其它自动环节一样把游标推到下一环,否则这里会原地重跑同一个
# 人工环节,一路撞到环路保护才报错。
target = definition.activity(route.to_activity) or target
continue
if target.type == ACTIVITY_CHOICE:
picked = _pick_choice(db, work, definition, target, actor)
source, opinion, log_type = target, "", "normal"
route = picked
prefix = tickets.prefix_of(arrived_token["path"], target.id)
join_key = arrived_token.get("join", "")
if route is None:
_finish_if_idle(db, work, definition, result, actor)
return result
target = definition.activity(route.to_activity) or target
continue
if target.type in {ACTIVITY_PARALLEL, ACTIVITY_SPLIT}:
items = _split_items(db, work, target, current_split) if target.type == ACTIVITY_SPLIT else None
branches = [r.to_activity for r in definition.routes_from(target.id)]
if target.type == ACTIVITY_SPLIT and items is not None:
branch_routes = definition.routes_from(target.id)
route_branch = branch_routes[0] if branch_routes else None
if route_branch is None:
raise EngineError(f"拆分环节 {target.name} 没有出口路由")
if not items:
# 明细为空时一个分支都派不出去,而这条 token 已经被消费掉:继续走下去
# 只会「没有待办、没有 token」地被当成办结,单子悄无声息就结束比报错危险得多。
raise EngineError(
f"拆分环节 {target.name} 没有解析到明细数据(dataPath={target.config.get('dataPath') or target.config.get('splitPath') or '未设置'}),"
"请在拆分前用分支环节判断明细条数,或至少保留一行明细"
)
branches = [route_branch.to_activity] * len(items)
paired = pair_gateways(definition).get(target.id, {"merge": "", "branches": branches})
merge_id = paired["merge"]
branch_prefix_base = arrived_token["path"]
expected = len(items) if items is not None else len(branches)
key = tickets.join_key(branch_prefix_base, merge_id or target.id)
if merge_id and expected:
# 「到 N 票就放行」写在汇聚环节上(写在分叉上也认),登记票箱时一并抄进去。
quota = _join_quota(definition.activity(merge_id), target)
tickets.register_join(
db_join_store(work),
key,
expected,
merge_id,
arrived_token["id"],
pass_count=quota[0],
pass_ratio=quota[1],
)
db_join_store(work)[key]["parent_join"] = join_key
branch_routes = definition.routes_from(target.id)
for index, branch_target in enumerate(branches):
branch_route = next((r for r in branch_routes if r.to_activity == branch_target), None)
if branch_route is None:
continue
path = f"{branch_prefix_base}/{branch_target}"
child_token = {"id": uuid.uuid4().hex, "activity": branch_target, "path": path}
if merge_id:
child_token["join"] = key
if items is not None:
# Split branches share one target activity, so the path has to
# carry the item index to keep the tokens distinguishable.
child_token["path"] = f"{path}#{index}"
child_token["split_value"] = str(items[index])
child_token["split_index"] = index
# 明细是对象时把这一行原样留给分支:子待办要用明细专属表单,
# 表单上的字段就是这一行的各列,不带上等于让审批人重新抄一遍。
if isinstance(items[index], dict):
child_token["split_item"] = items[index]
sub = _advance(
db,
work,
definition,
from_activity=target.id,
route=branch_route,
actor=actor,
opinion="",
token=child_token,
via=via,
log_type="parallel" if target.type == ACTIVITY_PARALLEL else "split",
split_value=child_token.get("split_value", ""),
)
result.tasks.extend(sub.tasks)
result.notices.extend(sub.notices)
if sub.completed:
return result
# Every branch must be materialised; a branch that produced tasks
# must not short-circuit its siblings.
_sync_work_cursor(db, work, definition)
db.flush()
if result.tasks:
return result
_finish_if_idle(db, work, definition, result, actor)
return result
if target.type == ACTIVITY_MERGE:
key = join_key or tickets.join_key(tickets.prefix_of(arrived_token["path"], target.id), target.id)
joins = db_join_store(work)
# 只有「真的分过叉」才需要等票:parallel / split 派发分支时一定登记过 join。
# 没登记过说明这条 token 是分支选择后单独走进汇总的(choice 的某一条支线),
# 这时按入口路由条数去等票永远等不齐,流程会静默停在汇总环节,所以直接放行。
ready, state = tickets.arrive_join(joins, key, route.name if route else "")
if not ready:
_sync_work_cursor(db, work, definition)
db.flush()
return result
join_key = (state or {}).get("parent_join", "")
tickets.clear_join(joins, key)
source, opinion, log_type = target, "", "merge"
route = _single_route(definition, target)
prefix = _join_prefix(key, target.id)
if route is None:
_finish_if_idle(db, work, definition, result, actor)
return result
target = definition.activity(route.to_activity) or target
continue
if target.type == ACTIVITY_SCRIPT:
_run_activity_script(db, work, definition, target, actor)
source, opinion, log_type = target, "", "script"
route = _single_route(definition, target)
prefix = tickets.prefix_of(arrived_token["path"], target.id)
join_key = arrived_token.get("join", "")
if route is None:
_finish_if_idle(db, work, definition, result, actor)
return result
target = definition.activity(route.to_activity) or target
continue
if target.type == ACTIVITY_INVOKE:
_run_invoke(db, work, definition, target, actor)
source, opinion, log_type = target, "", "invoke"
route = _single_route(definition, target)
prefix = tickets.prefix_of(arrived_token["path"], target.id)
join_key = arrived_token.get("join", "")
if route is None:
_finish_if_idle(db, work, definition, result, actor)
return result
target = definition.activity(route.to_activity) or target
continue
if target.type == ACTIVITY_DELAY:
minutes = int(target.config.get("minutes") or 0)
work.tokens.append(arrived_token | {"wake_time": (datetime.now() + timedelta(minutes=minutes)).isoformat()})
_sync_work_cursor(db, work, definition)
db.flush()
return result
if target.type == ACTIVITY_EMBED:
return _arrive_embed(
db, work, definition, target, actor, arrived_token, result, route=route
)
if target.type == ACTIVITY_CANCEL:
return _finish_work(
db, work, definition, status="canceled", result=result, actor=actor,
opinion=opinion or "流程作废", activity=target,
)
if target.type == ACTIVITY_END:
return _finish_work(
db, work, definition, status="completed", result=result, actor=actor,
opinion=opinion, activity=target,
)
raise EngineError(f"未知的环节类型: {target.type}")
def _join_prefix(key: str, merge_id: str) -> str:
suffix = f"|{merge_id}"
return key[: -len(suffix)] if key.endswith(suffix) else ""
def _join_quota(merge_activity, gateway=None) -> tuple[int, float]:
"""读汇聚环节的放行配额:``passCount`` 到几张票、``passRatio`` 到多少比例。
写在汇聚环节最直观("这个汇合点要几张票"),写在分叉那一侧也照收,
免得设计器放错位置就悄悄失效。取值非法时当没配,退回全到。
"""
for node in (merge_activity, gateway):
config = dict(getattr(node, "config", None) or {})
if not config:
continue
try:
count = int(config.get("passCount") or 0)
ratio = float(config.get("passRatio") or 0)
except (TypeError, ValueError):
continue
if count > 0 or ratio > 0:
return (max(count, 0), max(ratio, 0.0))
return (0, 0.0)
def db_join_store(work: models.Work) -> dict:
if not isinstance(work.joins, dict):
work.joins = {}
return work.joins
def _single_route(definition: ProcessDefinition, activity) -> definition_module.RouteNode | None:
routes = definition.routes_from(activity.id)
return routes[0] if routes else None
def _pick_choice(
db: Session,
work: models.Work,
definition: ProcessDefinition,
activity,
actor: Actor | None,
) -> definition_module.RouteNode | None:
routes = definition.routes_from(activity.id)
if not routes:
return None
return _route_by_condition(routes, _context(db, work, actor)) or routes[0]
def _split_items(db: Session, work: models.Work, activity, current_split: str) -> list:
path = str(activity.config.get("dataPath") or activity.config.get("splitPath") or "")
items: list = []
if path:
current: object = work.data or {}
for part in path.replace("[", ".[").split("."):
if not part or part == ".":
continue
if part.startswith("[") and part.endswith("]"):
break
if isinstance(current, dict):
current = current.get(part)
else:
current = None
break
if isinstance(current, list):
items = current
if not items:
items = [current_split] if current_split else []
return items
# ---------------------------------------------------------------------------
# manual activity
# ---------------------------------------------------------------------------
#: 依次审批排队用的 work.variables 键前缀,键里带 token id,退回后老队列不会被误读。
SERIAL_QUEUE_PREFIX = "serial:"
def serial_queue_key(token_path: str) -> str:
return f"{SERIAL_QUEUE_PREFIX}{token_path or ''}"
#: 退回之后重走的环节要重新表态,所以「已经批过」只认这一轮。退回时写入基线时间。
DEDUP_SINCE_KEY = "dedupSince"
class ApprovalFlags(NamedTuple):
"""这一环最终生效的去重开关;前瞻用的口径另见 :func:`ahead_scope`。"""
skip_starter: bool
skip_approved: bool
skip_ahead: bool
def approval_flags(config: dict, approval: dict) -> ApprovalFlags:
"""这一环的三个去重开关:跳过发起人、跳过前面批过的人、跳过后面还要批的人。
环节上显式配过就以环节为准(可以配成 false 强制本人再批一次);没配过就退回
流程级默认。起草环节(``first``)不做特殊处理:它和别的环节一样看流程级开关,
默认不跳过。发起时表单虽然填过一遍,但「退回后重新提交」「先起草再补材料」
都要靠这条待办落脚,凭空吞掉起草环节会让发起人手上再也看不到自己的单。
"""
starter = config.get("skipStarter")
if starter is None:
starter = bool(approval.get("skipStarter"))
approved = config.get("skipApproved")
if approved is None:
approved = str(approval.get("dedup") or "none") == "all"
ahead = config.get("skipAhead")
if ahead is None:
ahead = str(approval.get("dedupAhead") or "none") != "none"
return ApprovalFlags(bool(starter), bool(approved), bool(ahead))
#: 重复出现的同一个人:这一单他签几次、签在哪一次。界面是一档,存储还是那两个开关。
REPEAT_EACH = "each"
REPEAT_FIRST = "first"
REPEAT_LAST = "last"
REPEAT_ONCE = "once"
def repeat_policy(config: dict, approval: dict) -> str:
"""把两个方向相反的开关折算成一档策略(与前端 ``utils/approvalDedup.dedupPolicyOf`` 一致)。
两个方向不是互相打架,也抵消不掉什么:往回看那档以「已办」为凭,而往前看那档跳过的
环节**不产生已办**,所以同一个人这一单一定至少真签一次。四档的真实差别要在有
「躲不掉的环节」(起草环节、退回到达的环节不能往前看跳过)时才看得出来:
- ``each``:每一环都派待办
- ``first``:签在最早那一次,后面重复的自动过
- ``last``:前面自动过,签在后面那一次;前面有躲不掉的环节时那一环也算一次签字,
于是这一单他可能签两次(躲不掉的那次 + 最后那次)
- ``once``:两头都收,签字落在最早躲不掉的那一次,之后一律自动过——只想让他签一次就选这档
"""
flags = approval_flags(config, approval)
if flags.skip_ahead:
return REPEAT_ONCE if flags.skip_approved else REPEAT_LAST
return REPEAT_FIRST if flags.skip_approved else REPEAT_EACH
def ahead_scope(config: dict, approval: dict) -> str:
"""前瞻去重按哪档口径判:``all`` 后面每条路径都必经,``any`` 有一条可能就算。
环节上 ``skipAheadScope`` 可以单独改口径;写了不认识的值一律回到「必经」那档,
激进口径必须显式配出来才生效。
"""
scope = str(config.get("skipAheadScope") or (approval or {}).get("dedupAhead") or "").strip()
return scope if scope in {lookahead.SCOPE_ALL, lookahead.SCOPE_ANY} else lookahead.SCOPE_ALL
@dataclass
class DedupDrops:
"""这一环被去重摘掉的人,按理由分开记,日志要说清「凭什么免掉他」。"""
starter: list[str] = field(default_factory=list)
approved: list[str] = field(default_factory=list)
ahead: list[str] = field(default_factory=list)
#: 被前瞻摘掉的人 → 后面那个还要他批的环节名。
origin: dict[str, str] = field(default_factory=dict)
@property
def empty(self) -> bool:
return not (self.starter or self.approved or self.ahead)
def _approved_persons(db: Session, work: models.Work, definition: ProcessDefinition | None) -> set[str]:
"""这一单到目前为止真正批过的人,比"手上有一条已办"严一档。
去重免掉的是重复签字,不是审批责任,所以四种"看着像批过"都不算:
- ``processing_type != normal``:或签/比例会签凑够票后被系统结掉的那几张、转办、
加签、终止,都不是他亲手表的态。把他算成批过,等于一张单上少了一个真签字。
- 走回头线的那张票(退回 / 驳回 / 没标语义但绕回自己那条):他把单子打回去,
不是他批完了,后面再遇到他得真看一遍。按路由语义判而不是按时间判,是因为
``completed_time`` 只存到秒,同一秒里按下的那颗钮拿时间挡不住。
- 开始环节那一张「提交」:那是把表交上来,不是谁批了一步。第一次发起时压根没有
开始环节的已办(``hold_at_begin`` / 界面发起都不写),退回来再提交时多出来一张,
两次算出来的"批过的人"就不一样了——发起人自己的确认环节会在重新提交那一秒被
自己刚点的提交免掉,而这一跳过第一次压根没出现过。
- ``dedupSince`` 之前的老票:退回重走要重新表态,基线之前的记忆一概不算。
"""
since = str((work.variables or {}).get(DEDUP_SINCE_KEY) or "")
stmt = select(
models.TaskCompleted.person, models.TaskCompleted.activity, models.TaskCompleted.route_name
).where(
models.TaskCompleted.work == work.id,
models.TaskCompleted.completed.is_(True),
models.TaskCompleted.processing_type == "normal",
)
if since:
stmt = stmt.where(models.TaskCompleted.completed_time >= _parse_iso(since))
out: set[str] = set()
for person, activity_id, route_name in db.execute(stmt).all():
who = str(person or "")
if not who:
continue
if definition is not None and activity_id:
node = definition.activity(str(activity_id))
if node is None:
out.add(who)
continue
if node.type == ACTIVITY_BEGIN or _route_is_back(definition, node, str(route_name or "")):
continue
out.add(who)
return out
def _skip_duplicate_identities(
db: Session,
work: models.Work,
config: dict,
identities: list[str],
approval: dict | None = None,
*,
definition: ProcessDefinition | None = None,
activity=None,
via_goback: bool = False,
protected: set[str] | None = None,
) -> tuple[list[str], DedupDrops]:
"""审批人去重:主流 OA 的三个开关,关掉的是重复劳动而不是审批责任。
- ``skipStarter``:解析出来的审批人就是发起人自己时跳过(自己批自己没意义)。
- ``skipApproved``:这个人在本单前面已经亲口批过一遍时跳过(经理兼总监时常见);
谁真表过态以 :func:`_approved_persons` 的口径为准,被系统代结、转办出去、打回去重都不算。
- ``skipAhead``:这个人后面还要再签一次时跳过前面这一环(往后看,见 ``lookahead``)。
``via_goback`` 是本环由「退回」到达:退回就是要本人重新处理,这时连发起人自己
也得真的收到待办,否则「退回给发起人补充材料」会被自动通过直接吞掉;前瞻同理,
被打回来的那一环得真有人重新看过,不能拿「后面还要他批」当理由。
起草环节(``first``)不做前瞻跳过:那张待办是发起人填单的落脚处,吞掉就交不了单。
"""
drops = DedupDrops()
if not identities:
return identities, drops
guard = protected or set()
skip_starter, skip_approved, skip_ahead = approval_flags(config, approval or {})
if via_goback:
skip_starter = False
if via_goback or bool(config.get("first")):
skip_ahead = False
keep_one = bool((approval or {}).get("dedupAheadKeepOne"))
if not (skip_starter or skip_approved or skip_ahead):
return identities, drops
done_persons = _approved_persons(db, work, definition) if skip_approved else set()
forecast = lookahead.Forecast()
if skip_ahead and definition is not None and activity is not None:
forecast = _upcoming_forecast(db, work, definition, activity)
out: list[str] = []
ahead_dropped: list[tuple[str, str]] = []
for identity in identities:
# 命中的必批规则保下的人不去重:那条规则说的是「这一单必须他签一次」,
# 比「他前面批过了」「后面还要批」都更具体,两条撞上时听更具体的那条。
if identity in guard:
out.append(identity)
continue
person = org.ref_for(db, identity).person
if skip_starter and person and person == work.creator:
drops.starter.append(identity)
continue
if skip_approved and person and person in done_persons:
drops.approved.append(identity)
continue
if skip_ahead and person and person in forecast.persons:
ahead_dropped.append((identity, person))
continue
out.append(identity)
if ahead_dropped:
# 「整环都排在后面」时保底留一个人:去重省的是重复签字,不该把一整环签空。
if keep_one and not out:
kept, kept_person = ahead_dropped.pop(0)
out.append(kept)
drops.origin.pop(kept_person, None)
for identity, person in ahead_dropped:
drops.ahead.append(identity)
drops.origin[person] = forecast.origin.get(person, "")
return out, drops
def _upcoming_forecast(
db: Session, work: models.Work, definition: ProcessDefinition, activity
) -> lookahead.Forecast:
"""往后看:后面的环节都会解析出谁,用此刻这份表单数据去算。
后面环节的审批人要是依赖那时才填的字段(「表单字段」找人、脚本找人),预测就可能
落空——这也是默认口径要求「后面每条路径都必经他」的原因。解析抛错时整次前瞻作废,
宁可多派一条待办,也不能因为算不准把人免掉。
"""
base = _context(db, work, None)
cache: dict[str, dict] = {}
def resolve(node) -> set[str]:
config = dict(node.config or {})
context = dict(base)
context["activity"] = {"id": node.id, "name": node.name}
identities = org.resolve_task_identities(
db, work.process,
{
"taskValues": config.get("taskValues") or [],
"taskScript": config.get("taskScript") or "",
},
context,
)
return {org.ref_for(db, item).person for item in identities if item}
return lookahead.upcoming(
definition,
activity.id,
resolve,
scope=ahead_scope(dict(activity.config or {}), definition.approval),
routes=lambda node: forecast_routes(db, work, definition, node, base),
droppable=lambda node: _droppable_reach(db, node, cache),
)
#: 条件式当场算出来的三种结果:算不出来是「说不准」,不能当成不成立。
GUARD_TRUE = "true"
GUARD_FALSE = "false"
GUARD_UNKNOWN = "unknown"
def guard_state(db: Session, work: models.Work, route, context: dict | None = None) -> str:
"""这一条出口的适用条件当场成不成立。
跟 :func:`route_guard_ok` 是同一件事,只是多留一档「算不出来」:引擎放行时算不出来
就当不成立(宁可拦住),往后看时算不出来必须当**说不准**——把一条可能走得通的路当成
走不通,就等于敢在一个说不准的地方免掉一个人的签字。
"""
expression = str(getattr(route, "expression", "") or "").strip()
if not expression:
return GUARD_TRUE
try:
return GUARD_TRUE if bool(expressions.evaluate(expression, context or _context(db, work, None))) else GUARD_FALSE
except expressions.ExpressionError:
return GUARD_UNKNOWN
except Exception: # noqa: BLE001 - 条件引用了还没填的字段,等于现在说不准
return GUARD_UNKNOWN
def forecast_routes(
db: Session,
work: models.Work,
definition: ProcessDefinition,
node,
context: dict | None = None,
) -> list:
"""往后看时这一环**当下真走得通**的出口。
以前前瞻把画布上所有出口都当成可能走,于是条件分支永远是「有一条路不经过他」,
后面明明必经他的那一环也免不掉前面这一票——设计者按业务把分支配得再死都没用。
这里按当前这份表单把出口收一遍,口径与引擎自己选路一致:
- 条件分支(``choice``):引擎只走第一条成立的条件路由,所以收敛成那一条;
排在它前面、当场算不出来的条件路由留着——真跑起来那句条件成立的话就走它了。
- 别的环节:出口由人挑,适用条件不成立的(``route_guard_ok`` 会拦)先剪掉。
和 ``route_guard_ok`` 一样,条件算不出来的出口一律留着:宁可少免一次签字。
"""
if node is None:
return []
rows = definition.routes_from(node.id)
if not rows:
return []
states = [guard_state(db, work, item, context or _context(db, work, None)) for item in rows]
if str(getattr(node, "type", "")) != definition_module.ACTIVITY_CHOICE:
alive = [item for item, state in zip(rows, states) if state != GUARD_FALSE]
return alive or list(rows)
guarded = [
(index, item)
for index, item in enumerate(rows)
if str(getattr(item, "expression", "") or "").strip()
]
hit = next(((index, item) for index, item in guarded if states[index] == GUARD_TRUE), None)
if hit is not None:
index, picked = hit
# 排在被选中那条之前、又算不出来的条件路由:真跑起来可能就是它先成立
before = [item for i, item in guarded if i < index and states[i] == GUARD_UNKNOWN]
return [item for item in before if item is not picked] + [picked]
unknown = [item for i, item in guarded if states[i] == GUARD_UNKNOWN]
fallback = next(
(item for item in rows if not str(getattr(item, "expression", "") or "").strip()),
rows[0],
)
return ([item for item in unknown if item is not fallback] + [fallback]) if unknown else [fallback]
def rule_reach(db: Session, rows: list[dict], *, scope_whole: bool = False) -> dict:
"""一批免审/必批规则**可能碰到哪些人**:整环、说不准、还是就这么几个。
只按规则点名的人算,不去跑它的条件——条件要等这一单的表单填出来才算得准,
现在就跑等于把猜测当事实。规则带找人脚本、按发起人/上级这类来源找人、或者名字
解析不出来,一律算「说不准」:这里放错一次手的代价是一整环没人批,
比让人多签一次重得多。前瞻去重与设计期体检共用这一份口径。
"""
whole = False
unknown = False
persons: set[str] = set()
for row in rows or []:
if not isinstance(row, dict):
continue
if scope_whole and str(row.get("scope") or "matched") == "all":
whole = True
continue
values = [item for item in (row.get("taskValues") or []) if isinstance(item, dict)]
script = str(row.get("taskScript") or "").strip()
kinds = {org.normalize_kind(item.get("type")) for item in values}
# 只有「按人员/岗位/分组/部门写死」的来源才敢现在就断定名单里没有谁
if not values or script or (kinds - org.SELECTOR_KINDS):
unknown = True
continue
preview = org.preview_selectors(db, values, "")
if preview.get("unknown"):
unknown = True
continue
# 预览目录里认得出的人才有 account;身份 DN 不是引用口径,不参与"这是谁"
batch = {
org.ref_for(db, str(item.get("account") or "")).person
for item in preview.get("identities") or []
}
if any(not item for item in batch):
unknown = True
continue
persons |= {item for item in batch if item}
return {"whole": whole, "unknown": unknown, "persons": persons}
def _droppable_reach(db: Session, node, cache: dict[str, dict]) -> dict:
"""这一环的免审规则能碰到谁(一次前瞻里按环节缓存,别一次次重算名单)。"""
key = str(getattr(node, "id", "") or "")
if key not in cache:
cache[key] = rule_reach(db, skip_rules(dict(getattr(node, "config", None) or {})), scope_whole=True)
return cache[key]
def _parse_iso(value: str) -> datetime:
try:
return datetime.fromisoformat(value)
except ValueError:
return datetime.min
def _dedup_note(db: Session, drops: DedupDrops | None, *, whole: bool) -> str:
"""去重摘掉了谁、凭什么摘,写成一句能进流转日志的话。"""
if not drops or drops.empty:
return ""
bits: list[str] = []
if drops.starter:
bits.append(f"{'、'.join(_identity_names(db, drops.starter))} 就是发起人本人")
if drops.approved:
bits.append(f"{'、'.join(_identity_names(db, drops.approved))} 前面已经批过")
if drops.ahead:
names: list[str] = []
for identity in drops.ahead:
ref = org.ref_for(db, identity)
label = ref.person_name or ref.name or identity
later = drops.origin.get(ref.person) or ""
names.append(f"{label}(后面还要在「{later}」批)" if later else label)
bits.append(f"{'、'.join(names)} 后面还要批一次")
tail = "本环节自动通过" if whole else "本环节不用他批"
return "审批人去重:" + ";".join(bits) + "," + tail
def _skip_reason(
db: Session,
work: models.Work,
config: dict,
resolved: list[str],
approval: dict | None = None,
drops: DedupDrops | None = None,
) -> str:
"""本环被清空的具体原因,写进流转日志,别让「自动通过」变成一笔糊涂账。
算过去重就照去重结果说话;没算过(调用方手里没有结果)才退回按开关猜,
口径要和 ``_skip_duplicate_identities`` 用的是同一份:流程级默认也得算进来,
否则真正起作用的是「跳过发起人」,日志却写成「前面已批过」。
"""
note = _dedup_note(db, drops, whole=True)
if note:
return note
skip_starter, skip_approved, skip_ahead = approval_flags(config, approval or {})
starter_only = skip_starter and all(
org.ref_for(db, identity).person == work.creator for identity in resolved
)
if starter_only and not (skip_approved or skip_ahead):
return "审批人是发起人本人,自动通过"
if skip_ahead and not (skip_starter or skip_approved):
return "同一审批人后面还要批,自动通过"
if starter_only:
return "同一审批人不必重复审批,自动通过"
return "同一审批人前面已批过,自动通过"
#: 环节被跳过时写进流转日志的两种类型:整环没人批(``skip``)与只免掉其中几个人(``skipPart``)。
#: 两者都要在审批记录里露出来,但只有整环跳过才算这一环「没过人」。
LOG_SKIP_ACTIVITY = "skip"
LOG_SKIP_SOME = "skipPart"
#: 必批规则往这一环加了人(``mustRules``),审批记录里要说明这一环为什么多了一个人。
LOG_MUST_SOME = "mustPart"
#: 流程干预留下的三条事件日志:挂起、恢复、修正表单数据都不改变在路上的 token,
#: 只在当前环节旁边挂一句说明(``move`` 是真的换了环节,见 :func:`move`)。
LOG_SUSPEND = "suspend"
LOG_RESUME = "resume"
LOG_DATA_FIX = "dataFix"
#: 干预改道:单据真的从一环搬到另一环,但它不是审批人办完的,路由与日志都要自己造一条。
LOG_MOVE = "move"
#: 编号在指定环节才排时旁挂的那一句(``issue_serial``):不是一次流转,只说明号是哪一步给的。
LOG_SERIAL = "serial"
#: 外部核验闸门**放行**时旁挂的那一句(人工放行 / 带病放行 / 部分通过)。
#: 挡住的那一次不会有这条:EngineError 一抛整笔事务回滚,留痕写了也不存在。
LOG_GATE_PASS = "gatePass"
#: 终止流程旁挂的那一句(:func:`terminate`)。终止本身**不写流转留痕**——它不是一步流转,
#: 也没有"到达"哪个环节,从前一张单被谁终止、写了什么原因,审批记录里一个字都查不到,
#: 只能去翻操作日志。这条留痕把操作人(``from_identity_name``)与原因留在单子上。
LOG_TERMINATE = "terminate"
#: 干预类站内信的事件名。不进 ``channels.EVENTS``:挂起 / 改道这种动作只在站内信里看,
#: 没必要跟着「新的待办」一起往邮箱和群里刷。
NOTIFY_CONTROL = "control"
def skip_rules(config: dict | None) -> list[dict]:
"""环节上的「条件跳过审批人」规则;没配或配坏都当没有,不影响流程照跑。"""
rows = (config or {}).get("skipRules")
return [row for row in rows if isinstance(row, dict)] if isinstance(rows, list) else []
def _identity_names(db: Session, identities: list[str]) -> list[str]:
names: list[str] = []
for dn in identities:
ref = org.ref_for(db, dn)
name = ref.person_name or ref.name or dn
if name not in names:
names.append(name)
return names
def must_rules(config: dict | None) -> list[dict]:
"""环节上的「条件必批」规则;和免审规则同一形状,只是方向相反。"""
rows = (config or {}).get("mustRules")
return [row for row in rows if isinstance(row, dict)] if isinstance(rows, list) else []
def _must_rule_hits(
db: Session, work: models.Work, config: dict, identities: list[str], context: dict
) -> tuple[list[str], set[str], list[dict]]:
"""命中条件的必批规则要保下谁:返回(这一环的处理人,受保护的人,命中的规则)。
必批比免审硬:人不在审批人来源里也会被加进这一环(「超过 10 万必须有总经理批」时
总经理可以完全不在常规名单里),而且后面的免审与去重都不许再把他摘掉。
条件算不出来同样按不命中处理——必批是加码,不算错成人就行。
"""
merged = list(identities)
protected: set[str] = set()
hits: list[dict] = []
for rule in must_rules(config):
expression = str(rule.get("expression") or "").strip()
if not expression:
continue
try:
if not bool(expressions.evaluate(expression, context)):
continue
except expressions.ExpressionError as exc:
logger.warning("环节必批条件算不出来,按不命中处理:%s(%s)", expression, exc)
continue
forced = org.resolve_task_identities(
db,
work.process,
{"taskValues": rule.get("taskValues") or [], "taskScript": rule.get("taskScript") or ""},
context,
)
added = [item for item in forced if item and item not in merged]
merged.extend(added)
protected.update(item for item in forced if item)
hits.append(
{
"name": str(rule.get("name") or "").strip(),
"names": _identity_names(db, added or forced),
"added": bool(added),
}
)
return merged, protected, hits
def _must_rule_note(hits: list[dict]) -> str:
"""必批规则加进来的人,写进日志说明这一环为什么多了一个人。"""
parts = [
f"{('加上 ' if hit['added'] else '仍需 ')}{'、'.join(hit['names'])}"
+ (f"「{hit['name']}」" if hit["name"] else "")
for hit in hits
if hit["names"]
]
return ("本环节必须审批:" + ";".join(parts)) if parts else ""
def _skip_rule_hits(
db: Session,
work: models.Work,
config: dict,
identities: list[str],
context: dict,
protected: set[str] | None = None,
) -> tuple[list[str], list[dict]]:
"""按环节的跳过条件把这一环不用批的人摘掉,返回(留下的人,命中的规则)。
条件算不出来(字段还没填、式子写错)一律按「没命中」处理:宁可让人多批一次,
也不能因为一条写坏的条件把该批的人悄悄免掉。规则命中但本来就没这些人在这一环,
等于这条规则这轮什么都没做,不记进命中列表,免得日志里冒出没发生过的跳过。
``protected`` 是命中的必批规则保下的人:两边同时命中时必批赢,免审对他不生效,
并且把这件事记进 hits,日志里看得见「想免没免掉」。
"""
guard = protected or set()
kept = list(identities)
hits: list[dict] = []
for rule in skip_rules(config):
expression = str(rule.get("expression") or "").strip()
if not expression:
continue
try:
if not bool(expressions.evaluate(expression, context)):
continue
except expressions.ExpressionError as exc:
logger.warning("环节跳过条件算不出来,按不命中处理:%s(%s)", expression, exc)
continue
whole = str(rule.get("scope") or "matched") == "all"
if whole:
wanted, kept = kept, [item for item in kept if item in guard]
else:
drop = set(
org.resolve_task_identities(
db,
work.process,
{
"taskValues": rule.get("taskValues") or [],
"taskScript": rule.get("taskScript") or "",
},
context,
)
)
wanted = [item for item in kept if item in drop]
kept = [item for item in kept if item not in drop or item in guard]
# 必批保下的人从「免掉」里挑出来:他们本来被这条规则命中了,但责任压得更重的那条赢
dropped = [item for item in wanted if item not in guard]
spared = [item for item in wanted if item in guard]
if not dropped and not spared:
continue
hits.append(
{
"name": str(rule.get("name") or "").strip(),
"whole": whole,
"names": _identity_names(db, dropped),
"spared": _identity_names(db, spared),
}
)
return kept, hits
def _skip_rule_note(hits: list[dict], *, whole: bool) -> str:
"""命中了哪些跳过规则,写成一句能进流转日志的话。"""
if not hits:
return ""
parts: list[str] = []
for hit in hits:
label = f"「{hit['name']}」" if hit["name"] else ""
names = "、".join(hit["names"])
if hit["whole"]:
parts.append(f"整环免审{label}" + (f"({names})" if names else ""))
elif names:
parts.append(f"免掉{names}{label}")
spared = "、".join(hit.get("spared") or [])
if spared:
parts.append(f"{spared} 属于必须审批,未被免审")
if not parts:
return ""
head = "满足跳过条件" if whole else "按跳过条件免审"
return f"{head}:" + ";".join(parts)
def _fallback_admin_ref(db: Session) -> str:
"""「空审批人交给管理员」时的那个管理员账号。
一次流转里每个配了这条兜底的环节都要问一遍,而管理员名单在一次请求里不会变;
``users`` 被写过就立刻重来。
"""
return readcache.get(db, ("users",), ("engine._fallback_admin_ref",), lambda: _fallback_admin_ref_now(db))
def _fallback_admin_ref_now(db: Session) -> str:
"""真正问库的那一步:第一个在职管理员,取库里认人用的那一串。"""
admin = db.execute(
select(models.User)
.where(
models.User.role == models.ROLE_ADMIN,
models.User.status == models.UserStatus.ACTIVE,
)
.order_by(models.User.id)
).scalars().first()
return org.identity_of_person(db, admin) if admin else ""
def _fallback_identities(db: Session, work: models.Work, config: dict, context: dict) -> list[str]:
"""一个审批人都没解析出来时怎么办。
``emptyApprover`` 取值:``toCreator`` 转交发起人(历史默认行为,兼容旧的
``emptyToCreator`` 布尔开关)、``autoPass`` 本环节自动通过、``toAdmin`` 转交系统
管理员、``fixed`` 交给 ``emptyApproverValues`` 里指定的人。返回空列表就是自动通过。
"""
policy = str(config.get("emptyApprover") or "").strip()
if not policy:
return [work.creator_identity] if config.get("emptyToCreator", True) else []
if policy in ("autoPass", "none"):
return []
if policy == "toCreator":
return [work.creator_identity]
if policy == "toAdmin":
identity = _fallback_admin_ref(db)
return [identity] if identity and identity != work.creator_identity else []
if policy == "fixed":
values = config.get("emptyApproverValues") or []
resolved = org.resolve_task_identities(
db, work.process, {"taskValues": values, "taskScript": ""}, context
)
return [i for i in resolved if i]
return [work.creator_identity]
def _spawn_next_serial(
db: Session,
work: models.Work,
activity,
actor: Actor | None,
previous: models.Task,
) -> models.Task | None:
"""依次审批:上一条办完,把队列里的下一个人提成待办;队列空了返回 None。"""
key = serial_queue_key(previous.activity_token)
queue = [str(item) for item in ((work.variables or {}).get(key) or []) if str(item or "").strip()]
if not queue:
return None
identity = queue.pop(0)
variables = dict(work.variables or {})
if queue:
variables[key] = queue
else:
variables.pop(key, None)
work.variables = variables
ref = org.ref_for(db, identity)
now = datetime.now()
task = models.Task()
for name in (
"job",
"work",
"title",
"process",
"process_name",
"category",
"category_name",
"serial",
"activity",
"activity_name",
"activity_type",
"activity_token",
"activity_description",
"creator",
"creator_person",
"creator_identity",
"creator_unit",
"route_list",
"route_name_list",
"route_opinion_list",
"form",
# 串行加签续出来的那半条待办,认的还是同一版设计
"design_snapshot",
"data_patch",
"first",
):
setattr(task, name, getattr(previous, name))
task.identity = identity
task.person = ref.person
task.identity_name = ref.name
task.unit = ref.unit
task.unit_name = ref.unit_name
task.prev_task_identity = actor.ref if actor else previous.identity
task.status = "pending"
task.act = "create"
task.order_number = previous.order_number + 1
task.start_time = now
task.start_time_month = now.strftime("%Y%m")
expire_minutes = _expire_minutes(activity.config or {})
task.expire_time = (now + timedelta(minutes=expire_minutes)) if expire_minutes else None
db.add(task)
db.flush()
_notify_task(db, task, work, activity, actor)
return task
def _arrive_manual(
db: Session,
work: models.Work,
definition: ProcessDefinition,
activity,
actor: Actor | None,
token: dict,
result: StepResult,
*,
via_goback: bool = False,
) -> list[models.Task]:
config = dict(activity.config or {})
# 上一环节只查一次:下面两个键吃的是同一份结果,写在一个字面量里会为了拼一个
# 上下文跑三趟库(limit=1 时那个"清单"最多一条,两处判断完全同源)。
previous = _recent_identities(db, work)
context = _context(
db,
work,
actor,
{
"activity": {"id": activity.id, "name": activity.name},
"prev_task_identity_list": [t.identity for t in previous],
"prev_identity": previous[0].identity if previous else "",
},
)
# 环节自己绑定的表单里也可能有系统值字段(例如只在审批环节显示的单号),到环节再补一次。
autofill.apply_form(
db, work, actor=actor,
fields=autofill.form_fields(
db, activity.form or definition.latest_form, definition
),
)
if activity.type == ACTIVITY_BEGIN:
# 退回到发起人:开始环节上没有审批人配置,这张单是谁提的就退回给谁,他改完表单
# 重新提交,单子照旧从开始环节那条出口往下走。免审、去重、必批、空审批人兜底这些
# 审批环节的规则在这里一条都套不上——「发起人办自己那张单」正是这一环存在的意义。
identities = [work.creator_identity]
must_hits = []
must_added = False
rule_hits = []
dedup_drops = []
partial_note = ""
else:
# 这一环要按角色找人之前,先把整张流程配到的角色一次取回(口径见 org.prefetch_roles_of)
org.prefetch_roles_of(db, definition, config)
resolved = [i for i in org.resolve_task_identities(db, work.process, config, context) if i]
# 条件必批先把人钉上(名单里没有也加进来),再由条件免审和去重处理其余人。
resolved, must_guard, must_hits = _must_rule_hits(db, work, config, resolved, context)
must_added = any(hit["added"] for hit in must_hits)
# 条件跳过:命中规则的审批人这一环不用批,可以是整环免审,也可以只免其中几个人。
by_condition, rule_hits = _skip_rule_hits(db, work, config, resolved, context, protected=must_guard)
identities, dedup_drops = _skip_duplicate_identities(
db, work, config, by_condition, definition.approval,
definition=definition, activity=activity, via_goback=via_goback, protected=must_guard,
)
if resolved and not identities:
# 本来有人、被去重或跳过规则清空:这是「按规则不用他批」,不是「找不到人」,
# 不能再套空审批人兜底,否则刚跳过的发起人会被兜底重新捞回来批自己。
result.skip_note = _skip_rule_note(rule_hits, whole=True) or _skip_reason(
db, work, config, by_condition, definition.approval, dedup_drops
)
elif not identities:
# 一个都没解析出来:按环节的兜底策略办(转发起人 / 自动通过 / 转管理员 / 指定人)。
identities = _fallback_identities(db, work, config, context)
# 只免掉一部分人时这一环照常有人办,跳过的那几个另记一条 skipPart 日志(见函数末尾)。
# 免审规则和去重各说各的理由,凑在一句话里才拼得出「这一环为什么少了两个人」。
partial_note = ""
if identities:
partial_note = ";".join(
item
for item in (
_skip_rule_note(rule_hits, whole=False),
_dedup_note(db, dedup_drops, whole=False),
)
if item
)
_run_activity_script(db, work, definition, activity, actor, phase="arrive")
now = datetime.now()
agents = org.apply_agents(db, work.process, identities, now)
delivered: dict[str, str] = {}
for identity in identities:
target = agents.get(identity, identity)
delivered.setdefault(target, identity)
# 依次审批:只把第一个人提成待办,其余排在 work.variables 里,办完一个放一个。
mode = str(config.get("mode") or "any")
serial_queue: list[str] = []
if mode == "serial" and len(delivered) > 1:
pairs = list(delivered.items())
delivered = dict(pairs[:1])
serial_queue = [target for _, target in pairs[1:]]
# 拆分分支带着自己那一行明细:落到待办的 data_patch 上,
# 打开子待办时表单就是预填好的这一行,必填校验也按这一行算。
patch = token.get("split_item") if isinstance(token.get("split_item"), dict) else None
once = bool(config.get("processingTaskOnceUnderSamePerson"))
seen_persons: set[str] = set()
routes = definition.routes_from(activity.id)
# 同名出口在界面上是一个按钮,待办上这份路由清单也按名字去重:
# 批量办理的下拉是拿它取交集的,「同意」冒两次会让用户以为有两个不同动作。
route_opinions_config = (activity.config or {}).get("routeOpinions", {}) or {}
route_names: list[str] = []
route_opinions: list[str] = []
for item in routes:
if item.name in route_names:
continue
route_names.append(item.name)
route_opinions.append(str(route_opinions_config.get(item.name, "")))
expire_minutes = _expire_minutes(config)
created: list[models.Task] = []
for index, (delivered_identity, from_identity) in enumerate(delivered.items()):
ref = org.ref_for(db, delivered_identity)
if once and ref.person:
if ref.person in seen_persons:
continue
seen_persons.add(ref.person)
task = models.Task(
job=work.job,
work=work.id,
title=work.title,
process=work.process,
process_name=work.process_name,
category=work.category,
category_name=work.category_name,
serial=work.serial,
activity=activity.id,
activity_name=activity.name,
activity_type=activity.type or ACTIVITY_MANUAL,
activity_token=token.get("path", ""),
activity_description=activity.description or "",
person=ref.person,
identity=delivered_identity,
identity_name=ref.name,
unit=ref.unit,
unit_name=ref.unit_name,
empower_from_identity=from_identity if from_identity != delivered_identity else "",
creator=work.creator,
creator_person=work.creator_person,
creator_identity=work.creator_identity,
creator_unit=work.creator_unit,
prev_task_identity=actor.ref if actor else work.creator_identity,
prev_task_identity_list=[i for i in ([actor.ref if actor else ""] ) if i],
route_list=[r.id for r in routes],
route_name_list=route_names,
route_opinion_list=route_opinions,
form=activity.form or work.form,
design_snapshot=work.design_snapshot,
data_patch=dict(patch or {}),
first=(activity.type == ACTIVITY_MANUAL and bool(config.get("first"))),
act="create",
order_number=index,
start_time=now,
start_time_month=now.strftime("%Y%m"),
expire_time=(now + timedelta(minutes=expire_minutes)) if expire_minutes else None,
)
db.add(task)
created.append(task)
if created:
# 先落主键再发通知:事件信封里递出去的待办号得是对方拿来就能用的真号
db.flush()
for task in created:
_notify_task(db, task, work, activity, actor)
if created:
# 队列键按本次到达重写(而不是只写不删):退回后重走本环节时,
# 上一次留下的旧队列必须清掉,否则会把已经不算数的人再提一遍待办。
variables = dict(work.variables or {})
key = serial_queue_key(token.get("path", ""))
if serial_queue:
variables[key] = serial_queue
else:
variables.pop(key, None)
work.variables = variables
if partial_note:
# 自我指向的一条事件日志:这一环照常往下走,只是其中的几个人被规则免掉了。
_log(
db, work, definition,
from_activity=activity, to_activity=activity, route=None, actor=actor,
opinion=partial_note, token=token, log_type=LOG_SKIP_SOME,
)
if must_added:
# 必批规则把名单外的人加了进来,这一环为什么多了一位审批人要留在记录里。
_log(
db, work, definition,
from_activity=activity, to_activity=activity, route=None, actor=actor,
opinion=_must_rule_note(must_hits), token=token, log_type=LOG_MUST_SOME,
)
if created:
work.activity = activity.id
work.activity_name = activity.name
work.activity_type = activity.type or ACTIVITY_MANUAL
work.activity_token = token.get("path", "")
work.activity_arrived_time = now
work.tokens = [t for t in work.tokens if t.get("id") != token.get("id")]
work.tokens.append(token)
# 这一问按 ``work`` 从库里捞本环节的名单(``SELECT oa_task``),所以刚 ``db.add``
# 的那几条待办必须先落库——autoflush 是关着的。以前这件事是"顺带"办成的:
# ``notify`` 里那次整刷先把待办刷了出去。把那次整刷改成只刷站内信之后,
# 这里不自己刷就会算出一份空名单(``check_flush_defer.py`` 逐字段比对抓到的
# 就是它:``manual_identity_list`` 从 ``['某账号']`` 变成 ``[]``)。
db.flush(created)
_sync_work_cursor(db, work, definition)
db.flush()
apply_activity_cc(db, work, activity, actor, "arrive")
result.tasks.extend(created)
return created
def _completed_rows(db: Session, work_id: str) -> list[models.TaskCompleted]:
"""这张单的已办记录,办结时间从新到旧,一次取完并在同一个 Session 里复用。
「上一环节处理人」「抄送上下文里的上一批人」「最后一条正常办结的记录」问的都是这一批行:
一次审批里 ``_arrive_manual`` 与抄送上下文合起来要问五趟,问的是同一张单的同一批记录。
依赖表只写 ``oa_task_completed``:本次请求把当前这一环办结时写过它,那份就当场作废、
下一回重新问一次库,所以省掉的是重复,不是新鲜度。
"""
return readcache.get(
db,
("oa_task_completed",),
("engine.completed_rows", str(work_id)),
lambda: list(
db.execute(
select(models.TaskCompleted)
.where(models.TaskCompleted.work == work_id)
.order_by(models.TaskCompleted.completed_time.desc())
).scalars().all()
),
)
def _task_rows(db: Session, work_id: str) -> list[tuple[str, str, str, str]]:
"""这张单现有的待办 ``(账号, 姓名, 状态, 环节)``,一次取完并在同一个 Session 里复用。
「本环节有哪些人要办」(:func:`_sync_work_cursor` 要写的游标两列)与「这些人里谁手上
还有活」(:func:`_busy_identities` 拿来挡重复抄送)问的是同一批行,只是筛法不同。
一次审批里两问落在同一个库状态上——新待办已经刷出去,中间不再写 ``oa_task``——
第二问就不必再排一次队。依赖表只写 ``oa_task``:谁写了待办这一份就当场作废、下一回
重新问一次库,所以省掉的是重复,不是新鲜度(``check_readcache.py`` 守这一条)。
取的是列值而不是 ORM 对象:两张名单都只读不写,没必要把整批待办挂进身份映射。
"""
return readcache.get(
db,
("oa_task",),
("engine.task_rows", str(work_id)),
lambda: [
(str(row[0]), str(row[1] or ""), str(row[2] or ""), str(row[3] or ""))
for row in db.execute(
select(
models.Task.identity,
models.Task.identity_name,
models.Task.status,
models.Task.activity,
).where(models.Task.work == work_id)
).all()
],
)
def _recent_identities(db: Session, work: models.Work, limit: int = 1) -> list[models.TaskCompleted]:
out: list[models.TaskCompleted] = []
seen: set[str] = set()
for row in _completed_rows(db, work.id):
# 与原来那句 SQL 同口径:只算办结成功的(``completed`` 为假与空的都不算),每人只取最新那条
if not row.completed or row.identity in seen:
continue
seen.add(row.identity)
out.append(row)
if len(out) >= limit:
break
return out
def _expire_minutes(config: dict) -> int:
try:
value = int(config.get("expireValue") or 0)
except (TypeError, ValueError):
return 0
if value <= 0:
return 0
# 设计器写的是复数(minutes / hours / days),历史数据里单复数都有,
# 这里统一掉,否则「30 分钟」会被当成 30 小时算。
unit = str(config.get("expireType") or "hour").lower().rstrip("s")
return value * 60 * 24 if unit == "day" else (value if unit == "minute" else value * 60)
def _task_arrived_extra(db: Session, work: models.Work, activity, tasks: list[models.Task]) -> dict:
"""``task.arrived`` 信封里补的那两样:待办本身(号 / 处理人 / 期限 / 出口)与
开了外部审批的接口卡片。对方收到「轮到某环了」就该拿到动手需要的全部东西。
取卡片失败不该让「发通知」这一件事挂掉:这里只做加法,任何异常都收敛成空信封。
"""
try:
from ..service import node_approve
return node_approve.task_arrived_extra(db, work, activity, tasks)
except Exception: # noqa: BLE001 - 通知是加法,不是闸
return {}
def _notify_task(db: Session, task: models.Task, work: models.Work, activity, actor: Actor | None) -> None:
sender = actor.person_name if actor else work.creator_person
# 退回到发起人的那条待办不是「又来一张要批的单」,正文得说清楚是退回来改的
body = (
f"{sender} 把《{work.title}》退回给你,请修改后重新提交。"
if activity.type == ACTIVITY_BEGIN
else f"{sender} 提交的《{work.title}》等待您在【{activity.name}】环节处理。"
)
notify(
db,
[task.identity],
type_="task",
title=f"您有新的待办:{work.title}",
body=body,
job=work.job,
work=work.id,
task=task.id,
process=work.process,
sender=sender,
)
events.emit(db, work, "task.arrived", activity_name=activity.name,
actor_name=sender, task=task.id,
extra={"identity": task.identity, **_task_arrived_extra(db, work, activity, [task])})
def _run_activity_script(
db: Session,
work: models.Work,
definition: ProcessDefinition,
activity,
actor: Actor | None,
*,
phase: str = "activity",
) -> None:
config = dict(activity.config or {})
script = str(config.get("script") or "")
if phase == "arrive":
script = str(config.get("afterArriveScript") or "")
if not script.strip():
return
try:
work.data = expressions.run_script(script, _context(db, work, actor))
except expressions.ExpressionError as exc:
logger.warning("activity script failed on %s: %s", activity.name, exc)
work.variables = {**(work.variables or {}), f"scriptError:{activity.id}": str(exc)}
def _run_invoke(db: Session, work: models.Work, definition: ProcessDefinition, activity, actor: Actor | None) -> None:
config = dict(activity.config or {})
url = str(config.get("url") or "").strip()
if not url:
return
method = str(config.get("method") or "POST").upper()
payload = {
"job": work.job,
"work": work.id,
"serial": work.serial,
"title": work.title,
"process": work.process,
"activity": {"id": activity.id, "name": activity.name},
"data": work.data or {},
"operator": {"identity": actor.ref if actor else work.creator_identity},
}
timeout = float(config.get("timeout") or 10)
headers = {"Content-Type": "application/json", **dict(config.get("headers") or {})}
try:
status_code, raw_body = http_request(method, url, payload, headers, timeout)
try:
body: object = json.loads(raw_body)
except (TypeError, ValueError):
body = raw_body
target_key = str(config.get("resultPath") or "invokeResult")
work.data = {
**(work.data or {}),
target_key: body,
f"{target_key}_status": status_code,
}
except Exception as exc: # pragma: no cover - network dependent
logger.warning("invoke failed on %s: %s", activity.name, exc)
work.data = {**(work.data or {}), f"{config.get('resultPath') or 'invokeResult'}_error": str(exc)}
def _arrive_embed(
db: Session,
work: models.Work,
definition: ProcessDefinition,
activity,
actor: Actor | None,
token: dict,
result: StepResult,
*,
route: definition_module.RouteNode | None,
) -> StepResult:
"""调用子流程:创建子工作并挂起当前 token,子流程办结后自动回跳."""
config = dict(activity.config or {})
child_process = str(config.get("process") or "").strip()
if not child_process:
raise EngineError(f"调用环节 {activity.name} 未配置子流程")
child = create_job(
db,
process_id=child_process,
actor=actor or Actor(person_id=work.creator, person_name=work.creator_person, ref=work.creator_identity),
data=dict(config.get("data") or work.data or {}),
title=str(config.get("title") or work.title),
work_create_type="embed",
parent_work=work.id,
parent_job=work.job,
embed_activity=activity.id,
# 这一张是引擎替父单开的,不是人在发起页按的「发起」:子流程自己那环上锁没锁
# 与父单这一段流转无关,别把父单卡在自己的调用环节里
via=VIA_EMBED,
)
work.tokens = [t for t in work.tokens if t.get("id") != token.get("id")]
work.tokens.append(token | {"embed_job": child.work.job if child.work else ""})
work.embed_target_job = child.work.job if child.work else ""
work.embed_activity = activity.id
# 父单这一挂往往就是整个子流程的时长,当前环节得停在调用环节上;
# 不刷游标的话在途列表还显示它上一个自动环节,看着像卡在那里。
_sync_work_cursor(db, work, definition)
db.flush()
result.tasks.extend(child.tasks)
result.notices.extend(child.notices)
return result
def resume_embed_parent(db: Session, parent_job: str, child_job: str) -> None:
"""子流程结束 -> 父流程继续流转."""
if not parent_job:
return
parent = db.execute(
select(models.Work).where(models.Work.job == parent_job)
).scalar_one_or_none()
if parent is None:
return
definition = definition_module.for_work(db, parent)
activity = definition.activity(parent.embed_activity or "")
token = next((t for t in parent.tokens if t.get("embed_job") == child_job), None)
if activity is None or token is None:
return
route = _single_route(definition, activity)
parent.embed_completed = child_job
_advance(
db,
parent,
definition,
from_activity=activity.id,
route=route,
actor=Actor(person_id=parent.creator, person_name=parent.creator_person, ref=parent.creator_identity),
opinion="子流程办结",
token=token,
log_type="embed",
via=VIA_EMBED,
)
# ---------------------------------------------------------------------------
# task operations
# ---------------------------------------------------------------------------
def get_task(db: Session, task_id: str, actor: Actor) -> models.Task:
task = db.get(models.Task, task_id)
if task is None:
raise EngineError("待办不存在或已被处理")
if not actor.is_admin and task.identity != actor.ref:
raise EngineError("该待办不属于当前身份")
return task
def execute_task(
db: Session,
*,
task_id: str,
actor: Actor,
route_name: str = "",
opinion: str = "",
data: dict | None = None,
media_opinion: str = "",
attachments: list[dict] | None = None,
#: 随审批意见一起发出的附件 id(前端先传 /attachment,再随单带上)
opinion_attachments: list[str] | None = None,
next_identities: list[str] | None = None,
#: 谁来按这颗钮:见模块头那四个 ``VIA_*``。默认 OA 界面,认锁
via: str = VIA_OA,
) -> StepResult:
task = get_task(db, task_id, actor)
work = db.execute(select(models.Work).where(models.Work.id == task.work)).scalar_one_or_none()
if work is None:
raise EngineError("单据不存在或已被删除")
if work.status != "running":
raise EngineError("流程已结束,无法继续处理")
_ensure_active(work)
if task.add_task_from == "before_pending":
raise EngineError("这条待办要等被加签人处理完才会生效")
definition = definition_module.for_work(db, work)
activity = definition.activity(task.activity)
if activity is None:
raise EngineError("环节定义已被删除,无法处理")
# 这一环的表态交给外部了?OA 这颗钮就别让点了(外部通道 with via=open/embed 原样放行)
_lock_guard(db, work.process, activity, "handle", via, definition)
# 环节字段权限 + 明细表整型 + 公式重算 + 必填校验,都排在路由判断之前:
# 条件分支读到的必须是本环节真正生效的数据(比如刚算出来的报销合计)。
activity_fields = _activity_form_fields(db, work, activity, definition)
form_incoming = {**(task.data_patch or {}), **(data or {})}
form_before = dict(work.data or {})
_apply_form_runtime(
db,
work,
actor,
activity,
activity_fields,
form_incoming,
)
form_changes = form_change_notes(activity_fields, form_before, work.data or {}, form_incoming)
# 本环节改了标题引用的字段就按同一规则重算:标题开了自动刷新时,
# 「张三的请假申请」补完事由该变成「张三的请假申请(出差上海)」。
# 表单里有「流程标题」字段时,办理人改了这个字段就等于改了标题,这里一并接住。
_refresh_title(db, work, definition, actor=actor, fields=activity_fields)
route = _resolve_route(definition, activity, route_name, work, data, db=db, actor=actor)
if route is None:
raise EngineError("请选择有效的流转路由")
# 这一次往外走算不算"往前走":退回(goBack)永远不算。被闸门与卡住的写回拦住的人,
# 手上最需要的动作恰恰是把单退回去补正——那两道闸都只挡"往前"(见 outbox.blocking)。
# 判据用 is_back_route(goBack / reject / 没标语义但绕回自己那条边):
# 「退回去补正」不该被写回卡住或闸门挡死,画成驳回的那条线也一样。
going_back = definition_module.is_back_route(definition, route)
# 「挡住处理人」(on_failure=block) 落在这一步:这张单上有配了 block 的写回还没落地时,
# 往前走不了,退得回去。抛 EngineError 即可——上面那次 _apply_form_runtime 没人提交,
# 会话在 get_db 关闭时整笔回滚,审批人这一格不会留下半个字。
# 只挡"往前"是有意的:写回卡住的时候,最不该被拦下的动作恰恰是把单退回、转办、加签、
# 撤回这些"把人叫回来一起收拾"的操作(见 docs/node-writeback-config.md §6)。
if not going_back:
blocked = outbox.blocking(db, job=work.job)
if blocked:
raise EngineError(outbox.blocking_note(db, blocked))
# 提交闸门:外部核验(票据初审那一类)没过,这一步就别想往前走。
# 位置是算过的:必须在路由判断之后(要知道点的是哪条出口、算不算退回),
# 也必须在 _apply_form_runtime 之后(公式、额度、阈值、必填都判完才轮到它,
# 免得为一张表单没填全的单白打一次外呼)。挡住就抛 EngineError,会话整笔回滚。
if not going_back:
gate.check(db, work, activity=activity, route=route, going_back=False,
actor=actor, fields=activity_fields)
now = datetime.now()
# 会签(all/join)与按比例会签(ratio)要的是每个人各自表态,一个人办了不能把
# 同环节其他人的待办一起结掉;或签(any)才是"一人办结、其余自动通过"。
mode = str((activity.config or {}).get("mode") or "any")
siblings = db.execute(
select(models.Task).where(
models.Task.work == work.id,
models.Task.activity == task.activity,
models.Task.activity_token == task.activity_token,
models.Task.status == "pending",
models.Task.id != task.id,
# 前置加签挂着的回转待办不属于"同级待办",顺手一起结掉就等于把加签人踢出流程
models.Task.add_task_from != "before_pending",
)
).scalars().all()
completed = _complete_task(db, task, actor, route, opinion, media_opinion, now, "normal", form_changes)
# 审批意见里贴的截图和附件挂在这条已办上,跟着这一步的审批历史一起看
completed.attachments = claim_attachments(
db,
ids=opinion_attachments,
actor=actor,
kind=ATTACHMENT_OPINION,
owner_id=completed.id,
work=work,
activity_id=activity.id,
activity_name=activity.name,
)
if mode not in {"all", "join", "ratio"}:
for sibling in siblings:
# 后置加签那条不算"其余人":加签的目的就是要他单独表一次态,
# 或签的「一人办结、其余自动结掉」把他一起结掉,等于当着人的面把待办变没。
if sibling.add_task_from in {"before_pending", "after"}:
continue
_complete_task(db, sibling, actor, route, "", "", now, "auto")
for payload in attachments or []:
_attach_payload(db, work, payload, actor, activity.id, activity.name)
work.manual_identity_list = [s.identity for s in siblings if s.id != task.id]
work.current_activity_names = activity.name
# 退回
if route.decision == "goBack" or (activity.config or {}).get("routeDecisions", {}).get(route.name) == "goBack":
return go_back(
db,
task_id=task_id,
actor=actor,
target=str((activity.config or {}).get("goBackTarget", {}).get(route.name, "")),
opinion=opinion,
way="step",
completed=completed,
# 设计器上这条线叫什么,报文里就写着什么:「退回修改」与「资料不齐退回」
# 是两个按钮,对面要分开处理时靠这一格,不靠猜
route_name=route.name,
route_alias=route.alias or "",
# 这一退是谁按的也要跟着下去:第三方回一句「不同意」、嵌页面里点一下、
# 外部表态后人在 OA 横幅上确认,走的都是这一条,不带下去就全记成 OA 界面点的
via=via,
)
# 按比例会签:同意票凑够配额就提前放行,还没表态的人自动结掉。
# 不同意依然走上面那条退回分支——一票否决与全会被签口径一致,
# 「比例」只决定同意要几个人,不改变"有人明确退回就立刻退回"。
if mode == "ratio":
agrees, total = _ratio_votes(db, work, task, activity, definition)
need = tickets.required_votes(
total,
int((activity.config or {}).get("passCount") or 0),
float((activity.config or {}).get("passRatio") or 0),
)
waiting = list(
db.execute(
select(models.Task).where(
models.Task.work == work.id,
models.Task.activity == task.activity,
models.Task.activity_token == task.activity_token,
models.Task.status == "pending",
models.Task.add_task_from != "before_pending",
)
).scalars().all()
)
if agrees < need and waiting:
db.flush()
return StepResult(work=work, tasks=waiting)
if agrees < need and not waiting:
# 票跑完仍没达标:不另找出口,就按最后一名审批人选的路由继续流转,
# 设计者在环节出口配好了"不通过"去哪,这里替不了他决定。
opinion = f"{opinion}\n(同意 {agrees}/{total} 票,未达放行线 {need} 票)".strip()
if agrees >= need:
opinion = f"{opinion}\n(同意 {agrees}/{total} 票,已达放行线 {need} 票)".strip()
for sibling in waiting:
_complete_task(db, sibling, actor, route, f"同意已达标({agrees}/{total} 票)", "", now, "auto")
# 会签:仍有未处理同级待办则等待
if mode in {"all", "join"}:
remaining = db.execute(
select(models.Task).where(
models.Task.work == work.id,
models.Task.activity == task.activity,
models.Task.activity_token == task.activity_token,
models.Task.status == "pending",
)
).scalars().all()
if remaining:
db.flush()
return StepResult(work=work, tasks=list(remaining))
# 依次审批:队列里还有人就把下一个提上来,本环节还没办完。
if mode == "serial":
nxt = _spawn_next_serial(db, work, activity, actor, task)
if nxt is not None:
db.flush()
return StepResult(work=work, tasks=[nxt])
# 前置串行加签:被加签人只是补个意见,办完把待办交还给加签人,去向由加签人定。
# 并行加签(together)没有回转待办,走下面的正常流转。
if task.add_task_from == "before":
pending_now = db.execute(
select(models.Task).where(
models.Task.work == work.id,
models.Task.activity == task.activity,
models.Task.activity_token == task.activity_token,
models.Task.status == "pending",
)
).scalars().all()
others = [item for item in pending_now if item.add_task_from != "before_pending"]
waiting = [item for item in pending_now if item.add_task_from == "before_pending"]
if others:
db.flush()
return StepResult(work=work, tasks=others)
if waiting:
for item in waiting:
item.add_task_from = "before_return"
item.start_time = now
item.start_time_month = now.strftime("%Y%m")
_notify_task_batch(db, waiting, work, activity, actor)
db.flush()
return StepResult(work=work, tasks=waiting)
# 后置加签的人还没开口,这一环就还没办完:停下等他,别把他要批的那一步推过去。
# 等他批完,去向由他选的路由定(见上面或签那段——他那条不会被别人的同意结掉)。
added_pending = db.execute(
select(models.Task).where(
models.Task.work == work.id,
models.Task.activity == task.activity,
models.Task.activity_token == task.activity_token,
models.Task.status == "pending",
models.Task.add_task_from == "after",
)
).scalars().all()
if added_pending:
db.flush()
return StepResult(work=work, tasks=list(added_pending))
apply_activity_cc(db, work, activity, actor, "complete")
token = next(
(t for t in work.tokens if t.get("activity") == task.activity and t.get("path") == task.activity_token),
None,
)
if token is None:
token = {
"id": uuid.uuid4().hex,
"activity": task.activity,
"path": task.activity_token or task.activity,
"join": _join_key_for_token(work, task),
}
if next_identities:
work.variables = {**(work.variables or {}), f"next:{activity.id}": list(next_identities)}
return _advance(
db,
work,
definition,
from_activity=activity.id,
route=route,
actor=actor,
opinion=opinion,
token=token,
via=via,
)
def _join_key_for_token(work: models.Work, task: models.Task) -> str:
"""Recover the enclosing join key for a task sitting on a forked branch."""
prefix = task.activity_token or task.activity
for key in (work.joins or {}):
if key.startswith(f"{prefix}/") or key.startswith(prefix + "|"):
return key
return ""
def route_guard_ok(db: Session, work: models.Work, route, actor: Actor | None = None) -> bool:
"""路由上写的适用条件当前是否成立;没写条件就算成立。
引擎放行与界面置灰必须共用这一个函数,否则迟早分裂成「界面让点、引擎报错」
或「界面藏了、引擎其实认」两种情况。条件算不出来按不成立处理——宁可拦住,
也不要让一条写坏的表达式把单据送到不该去的地方。
"""
expression = str(getattr(route, "expression", "") or "").strip()
if not expression:
return True
return expressions.evaluate_condition(expression, _context(db, work, actor))
def _condition_context(
db: Session | None,
work: models.Work,
data: dict | None,
actor: Actor | None,
) -> dict:
"""算路由条件用的上下文;没有会话时只能拿单据上的数据凑一份。"""
if db is not None:
return _context(db, work, actor)
return {
"data": {**(work.data or {}), **(data or {})},
"work": {"id": work.id, "job": work.job, "creator_identity": work.creator_identity},
"user": {},
}
def _route_by_condition(routes, context: dict) -> definition_module.RouteNode | None:
"""一批候选出口里挑一条:先取第一条条件成立的,都不成立取没写条件的那条。
分支环节选路、同名按钮选路共用这一条口径,两处不会各自长出一套规则。
一条都对不上就回 ``None``,由调用方决定是兜底还是报错。
"""
for candidate in routes:
expression = (candidate.expression or "").strip()
if expression and expressions.evaluate_condition(expression, context):
return candidate
for candidate in routes:
if not (candidate.expression or "").strip():
return candidate
return None
def _resolve_route(
definition: ProcessDefinition,
activity,
route_name: str,
work: models.Work,
data: dict | None,
db: Session | None = None,
actor: Actor | None = None,
) -> definition_module.RouteNode | None:
routes = definition.routes_from(activity.id)
if not routes:
return None
if route_name:
matched = definition.find_routes(activity.id, route_name)
if not matched:
raise EngineError(f"环节 {activity.name} 不存在路由 {route_name}")
if len(matched) == 1:
found = matched[0]
# 前端报了路由名不等于这条能走。条件分支之外的出口上也能写适用条件
# (「某几个部门可以跳过部门主管直接报总经理」就是这种),只拿它去界面上
# 过滤、引擎照单全收,等于任何人绕过界面就能跳过中间整段审批。
if db is not None and not route_guard_ok(db, work, found, actor):
raise EngineError(
f"流转路由「{found.name}」的适用条件当前不成立,这一单不能走这条"
)
return found
# 同名路由在界面上就是一个按钮,审批人没得选也不该选:这一单走哪条由
# 路由上写的条件决定,跟分支环节一个算法。条件全不命中又不留默认,那是
# 图画漏了,宁可根据当前数据报错,也不要闭眼挑一条把人送错地方。
picked = _route_by_condition(matched, _condition_context(db, work, data, actor))
if picked is None:
raise EngineError(
f"流转路由「{matched[0].name}」在这个环节有几条同名出口,"
f"这一单一条条件都没命中:请在环节 {activity.name} 的同名路由里留一条不写条件的当默认"
)
return picked
if len(routes) == 1:
return routes[0]
picked = _route_by_condition(routes, _condition_context(db, work, data, actor))
if picked is not None:
return picked
raise EngineError(f"环节 {activity.name} 存在多条路由,请指定流转路由")
def _route_is_back(definition: ProcessDefinition | None, activity, route_name: str) -> bool:
"""历史票上那条出口是不是「往回走」:退回 / 驳回 / 没标语义但绕回自己的那条线。
判据与图遍历、审批记录共用 :func:`definition.is_back_route`,不再各写一份。
以前这一处只认 ``decision == "goBack"``,可设计器那颗按钮的下拉里还有
``reject``(费用报销的「驳回」就是它)——只认 goBack 时,驳回的人在"谁批过"这一问里
被当成同意过的人,于是驳回之后重走,他签过的那一整条链全部自动通过。
"""
if definition is None or activity is None or not str(route_name or ""):
return False
for item in definition.routes_from(activity.id):
if route_name in (item.name, item.id, item.alias):
return definition_module.is_back_route(definition, item)
return False
def _route_decision(definition: ProcessDefinition, activity, route_name: str) -> str:
"""某条出口路由在这个环节上的决定语义(``goBack`` 或空)。
历史票只存了路由名,判定同意/不同意时得回定义里查一次;环节上的
``routeDecisions`` 覆盖优先,与 execute 当场判定退回用的是同一份配置。
"""
overrides = dict((activity.config or {}).get("routeDecisions", {}) or {})
if route_name in overrides:
return str(overrides[route_name])
for item in definition.routes_from(activity.id):
if route_name and route_name in (item.name, item.id, item.alias):
return item.decision or ""
return ""
def _ratio_votes(db: Session, work: models.Work, task, activity, definition: ProcessDefinition) -> tuple[int, int]:
"""按比例会签的当前票数,返回 ``(同意票数, 应到人数)``。
口径:只数本环节本次 token 上真 people 表过态的(``processing_type=normal``),
系统代办的自动结掉不算一票;应到人数 = 已表态 + 还没办的待办。
本轮的起点用 ``work.activity_arrived_time``:它只在到达人工环节时写,
所以退回重走本环节时会被刷新,上一轮的旧票自然不计入。
(``latest`` 不能用 —— 它是"整张单最后一条已办"的标记,一张单只有一行为真。)
会话是 ``autoflush=False``,而"刚办结的这张"是上一步 ``db.add`` 进去的:
不先 flush 就数票,会把刚刚投出来的这一票数没,比例永远凑不齐。
"""
db.flush()
clause = [
models.TaskCompleted.work == work.id,
models.TaskCompleted.activity == task.activity,
models.TaskCompleted.activity_token == task.activity_token,
models.TaskCompleted.processing_type == "normal",
]
if getattr(work, "activity_arrived_time", None) is not None:
clause.append(models.TaskCompleted.completed_time >= work.activity_arrived_time)
voted = db.execute(select(models.TaskCompleted.route_name).where(*clause)).scalars().all()
agrees = sum(1 for name in voted if _route_decision(definition, activity, str(name or "")) != "goBack")
pending = int(
db.execute(
select(func.count(models.Task.id)).where(
models.Task.work == work.id,
models.Task.activity == task.activity,
models.Task.activity_token == task.activity_token,
models.Task.status == "pending",
)
).scalar()
or 0
)
return agrees, len(voted) + pending
def _change_value_text(value: object) -> str:
"""把字段值压成一句看得懂的话,太长就截断——留痕是给人核对的,不是搬数据。"""
if value is None or value == "" or value == []:
return "(空)"
if isinstance(value, (list, tuple)):
parts = [_change_value_text(item) for item in value]
return "、".join(parts)
if isinstance(value, dict):
return json.dumps(value, ensure_ascii=False, default=str)
return str(value)
#: 这些字段的取值本质是一个数:``0.0`` 与 ``0``、``"4075.0"`` 与 ``4075`` 是同一笔钱。
NUMERIC_FIELD_TYPES = ("number", "money", "rate", "percent", "year", "formula")
def _number_of(value: object) -> Decimal | None:
"""看得成一个数的取值就取成 ``Decimal``,看不成的(空、文本、布尔、明细表)返回 ``None``。
走 ``Decimal`` 而不是 ``float``:那是钱,要比精确值,不能让用户输入里的尾零变成
「审批人改过金额」。
"""
if isinstance(value, bool) or value is None or isinstance(value, (list, tuple, dict, set)):
return None
if isinstance(value, (int, float)):
if isinstance(value, float) and not math.isfinite(value):
return None
try:
return Decimal(str(value))
except InvalidOperation:
return None
text = str(value).strip().replace(" ", "").replace(",", "")
if not text:
return None
try:
number = Decimal(text)
except InvalidOperation:
return None
return number if number.is_finite() else None
def _same_field_value(old_value: object, new_value: object, field_type: str) -> bool:
"""这一格算不算没动:先按原样比,数字型字段再按数值比一次。"""
if json.dumps(old_value, ensure_ascii=False, sort_keys=True, default=str) == json.dumps(
new_value, ensure_ascii=False, sort_keys=True, default=str
):
return True
if field_type not in NUMERIC_FIELD_TYPES:
return False
old_number, new_number = _number_of(old_value), _number_of(new_value)
return old_number is not None and new_number is not None and old_number == new_number
def form_change_notes(fields: list[dict], before: dict, after: dict, incoming: dict) -> list[dict]:
"""这一步把哪些表单字段从什么改成了什么。
环节没配字段权限时表单默认是开放的,审批人改经办人填的内容在设计上允许;
但改完得看得见——尤其「资质资料」「人员资料」这类还会驱动后续条件必批加签的字段,
中途被人改过又不留痕,等于流转方向被悄悄换了还没人负责。
只比本人这次交上来的那几项,公式重算出来的连带变化不算他改的,不往这里记。
下划线开头的键是系统留痕(``_fetch`` / ``_quota`` / ``_formulaErrors`` / ``_outbound``),
每次办理都会自己重写时间戳;审批页面把整份 ``data`` 回传时它们也在里面,照原样比就会
记出一条「办理人把留痕从 X 改成了 Y」的假变更——留痕恰恰是要拿去回答「当时为什么不
让我提交」的证据,写成人工改动等于把审计记录搅浑。
数字型字段按**数值**比,不按 JSON 字面比(见 :func:`_same_field_value`)。金额控件回传时
会把 ``0.0`` 送成 ``0``,照字面比就是四条「某人改了审定金额」,而那一环那几个字段
在设计器里是只读的——生产上撞到过(FYBX202611090003,2026-11-09 17:06,审定其他/差旅/
通讯/市内交通四条 ``0.0 → 0``;FYBX202611040001 的差旅费用 ``4075.0 → 4075`` 是同一条)。
钱真的变了照样记:认不出数是(``None``)与尾零改写之外的任何差异,都按改动处理。
"""
labels = {str(field.get("key") or ""): str(field.get("label") or field.get("key") or "") for field in fields or []}
types = {str(field.get("key") or ""): str(field.get("type") or "") for field in fields or []}
notes: list[dict] = []
for key in incoming or {}:
if not key or key.startswith("_") or key not in (after or {}):
continue
old_value = (before or {}).get(key)
new_value = after[key]
if _same_field_value(old_value, new_value, types.get(key, "")):
continue
notes.append(
{
"key": key,
"label": labels.get(key) or key,
"before": _change_value_text(old_value)[:200],
"after": _change_value_text(new_value)[:200],
}
)
return notes
def _complete_task(
db: Session,
task: models.Task,
actor: Actor,
route: definition_module.RouteNode | None,
opinion: str,
media_opinion: str,
now: datetime,
processing_type: str,
form_changes: list[dict] | None = None,
operator: Actor | None = None,
) -> models.TaskCompleted:
# 替这一步收尾的人:终止把还挂着的待办强行结掉时,行仍旧记在持有人名下(他的已办里
# 得看得见这张单),但要把"是谁按的终止"留在行上——不然审批记录读起来就是
# 「部门主管自己终止了这张单」,而那位主管连待办都没打开过。本人办的那些留空。
is_holder = operator is None or str(operator.ref or "") == str(task.identity or "")
operator_ref = "" if is_holder else str(operator.ref or "")
operator_name = "" if is_holder else str(operator.person_name or "")
completed = models.TaskCompleted(
task=task.id,
job=task.job,
work=task.work,
title=task.title,
completed=True,
process=task.process,
process_name=task.process_name,
category=task.category,
category_name=task.category_name,
serial=task.serial,
activity=task.activity,
activity_name=task.activity_name,
activity_type=task.activity_type,
activity_token=task.activity_token,
person=task.person or actor.person_id,
identity=task.identity,
identity_name=task.identity_name or actor.person_name,
unit=task.unit,
unit_name=task.unit_name,
empower_from_identity=task.empower_from_identity,
creator=task.creator,
creator_person=task.creator_person,
creator_identity=task.creator_identity,
creator_unit=task.creator_unit,
prev_task_identity=task.prev_task_identity,
prev_task_identity_list=list(task.prev_task_identity_list or []),
route_name=route.name if route else task.route_name,
route_alias=route.alias if route else "",
opinion=opinion if processing_type == "normal" else (opinion or task.opinion),
media_opinion=media_opinion,
form=task.form,
design_snapshot=task.design_snapshot,
form_changes=list(form_changes or []),
start_time=task.start_time,
completed_time=now,
processing_type=processing_type,
act=task.act,
label=task.label,
operator=operator_ref,
operator_name=operator_name,
latest=True,
press_count=task.press_count,
press_time=task.press_time,
view_time=task.view_time,
expired=task.expired,
)
db.add(completed)
db.delete(task)
# 事件订阅:这条待办办完了。processing_type 一并带上——订阅方要区分"人真点了同意"
# 和"会签够票后被系统自动结掉",两者对上游的含义不一样。
work_row = db.get(models.Work, task.work)
if work_row is not None:
events.emit(db, work_row, "task.completed", activity_name=task.activity_name,
actor_name=actor.person_name, task=task.id,
extra={"route": completed.route_name or "", "processingType": processing_type})
db.flush()
db.execute(
update(models.TaskCompleted)
.where(
models.TaskCompleted.work == completed.work,
models.TaskCompleted.id != completed.id,
# 已经是假的行本来就该是假的,不必再锁一遍再写一遍:一条单上 latest 为真
# 的顶多一行,这一句改之前要把整张单的已办全锁住
models.TaskCompleted.latest.is_(True),
)
.values(latest=False)
)
return completed
def go_back(
db: Session,
*,
task_id: str,
actor: Actor,
target: str = "",
opinion: str = "",
way: str = "step",
completed: models.TaskCompleted | None = None,
#: 谁来按那颗「退回」:见模块头那四个 ``VIA_*``
via: str = VIA_OA,
#: 按的是哪条出口(设计器上 ``decision=goBack`` 的那条线):只喂写回报文里的 ``{action.*}``。
#: 引擎自己合成那颗「退回」按钮时不传,报文里就写着「退回」。
route_name: str = "",
route_alias: str = "",
) -> StepResult:
"""退回:回到上一环节 / 指定环节,并记录回退信息以便 jump 直返.
「本环节被退回时」的写回挂在**按退回的这一环**上(``origin``),与「本环节审批通过后」
同一个归属:按钮归谁,配置归谁。这里是它唯一的触发点——待办上那颗「退回」、设计器里
``decision=goBack`` 的出口、超时自动退回、开放接口与第三方代点头,全都汇到这一处。
"""
task = db.get(models.Task, task_id)
if task is None and completed is None:
raise EngineError("待办不存在")
reference = task or completed
assert reference is not None
work = db.execute(select(models.Work).where(models.Work.id == reference.work)).scalar_one_or_none()
if work is None:
raise EngineError("单据不存在或已被删除")
_ensure_active(work)
definition = definition_module.for_work(db, work)
origin = definition.activity(reference.activity)
if origin is None:
raise EngineError("环节定义不存在")
if not bool(origin.config.get("allowGoBack", True)):
raise EngineError(f"环节 {origin.name} 不允许退回")
# 那颗「退回」走的是引擎合成的那条线,与设计器画的出口无关,归 goBack 这一栏管
_lock_guard(db, work.process, origin, "goBack", via, definition)
target_activity, candidates = _resolve_goback_target(db, work, definition, origin, target, reference)
if target_activity is None:
raise EngineError("这个环节没有可退回到的上游环节")
go_back_route = definition_module.RouteNode(
id="goBack",
name="退回",
alias="退回",
from_activity=origin.id,
to_activity=target_activity.id,
decision="goBack",
)
# 退回同样是这个人办完的一步,得进「我的已办」和审批记录,退回意见更要留痕。
# 从前只写一条 oa_work_log,界面两边都查不到这一步,等于退回了既找不到人、
# 也说不清为什么退。processing_type 用 goBack 而不是 normal:撤回是按「本人
# 那条已办」往回收的,用在退回上会把退回前后的待办同时留着,所以这条只留痕、不开撤回。
if task is not None:
completed = _complete_task(db, task, actor, go_back_route, opinion, "", datetime.now(), "goBack")
completed.label = "退回"
reference = completed
task = None
# 同环节其余待办跟着一起收掉:这一环整个退回重走了,留着别人那条就是重复待办。
# 只在「本人点退回」这条路里做——按路由退回那条路进来时待办已经被 execute 结清,
# 会签里合法的同伴待办不该被这段顺手删掉。
for sibling in db.execute(
select(models.Task).where(
models.Task.work == work.id,
models.Task.activity == reference.activity,
models.Task.activity_token == reference.activity_token,
)
).scalars().all():
db.delete(sibling)
db.flush()
# 清理该分支上后续产生的待办与 token(其它并行分支保持不变)
branch_prefix = (reference.activity_token or reference.activity or "")
followers = db.execute(
select(models.Task).where(models.Task.work == work.id)
).scalars().all()
for item in followers:
if task is not None and item.id == task.id:
continue
if (item.activity_token or "").startswith(branch_prefix) and item.activity != target_activity.id:
db.delete(item)
work.tokens = [
t for t in work.tokens
if not (
# 自己这一环的 token 要一起撤下:它已经不在路上了。留着的话
# current_activity_names 会一直挂着离开的环节,界面「当前环节」就多列一步。
# 只按本分支的 token 路径摘,并行里别的分支不能牵连。
t.get("activity") == origin.id
and str(t.get("path", "")).startswith(branch_prefix)
)
and (
not str(t.get("path", "")).startswith(f"{branch_prefix}/")
or t.get("activity") == target_activity.id
)
]
for key in list((work.joins or {}).keys()):
if key.startswith(f"{branch_prefix}/") or key.startswith(f"{branch_prefix}|"):
work.joins.pop(key, None)
db.flush()
if way == "jump":
work.go_back_store = {
"origin_activity": origin.id,
"origin_name": origin.name,
"origin_prefix": reference.activity_token,
"targets": [target_activity.id],
"identity": actor.ref,
}
else:
# 正常流转的退回要把上一次的「直返本环节」清掉:那条约定属于上一次退回,
# 留着会让这一次单据刚走到半路就被劫回旧环节。
work.go_back_store = {}
# 退回意味着这条路要重新走一遍:把「谁已经批过」的记忆清到此刻,
# 否则去重会把退回后本该重新表态的审批人也一起跳过。
work.variables = {**(work.variables or {}), DEDUP_SINCE_KEY: datetime.now().isoformat()}
_log(
db,
work,
definition,
from_activity=origin,
to_activity=target_activity,
route=go_back_route,
actor=actor,
opinion=opinion,
token={"id": uuid.uuid4().hex, "activity": target_activity.id, "path": target_activity.id},
log_type="goBack",
)
db.flush()
step = StepResult(work=work)
# L3 挂载点之三「本环节被退回时」:挂在被退回的这一环(origin)上,与「通过后」同一归属。
# 走不到 _advance,所以这一处就是它唯一的钩子;与退回本身同一事务——单子退回成功而
# 报文没落库,或者反过来,都不该出现。退回那一刻表单已按退回人这次的修改落库。
begin_id = definition.begin.id if definition.begin is not None else ""
outbox.enqueue_node(
db, work, origin, phase=outbox.TRIGGER_GOBACK, actor=actor,
action={
"route": route_name or go_back_route.name,
"route_alias": route_alias or go_back_route.alias,
"decision": "goBack",
"opinion": opinion,
# 落点(退到哪一环)也交给发件箱:规则块上的 goBackTo 按这三格筛,报文取
# {action.target} 那一组。两个布尔只给筛子用,不随报文落库——@starter 认
# 「落点是发起环节」,@prev 认「落点是候选清单第一个」,都与环节 id 无关。
"target": target_activity.id,
"target_name": target_activity.name,
"target_alias": target_activity.alias or "",
"is_starter": bool(begin_id) and target_activity.id == begin_id,
"is_prev": bool(candidates) and target_activity.id == candidates[0].id,
# 这一退是谁按的:第三方调 /open/* 退回来那一单与审批人点按钮那一单,规则上
# 那一格 goBackVia 把它们分开,报文里取 {action.via}。
"via": via,
},
)
step.tasks.extend(
_arrive_manual(
db,
work,
definition,
target_activity,
actor,
{"id": uuid.uuid4().hex, "activity": target_activity.id, "path": target_activity.id},
step,
via_goback=True,
)
)
return step
def _resolve_goback_target(
db: Session,
work: models.Work,
definition: ProcessDefinition,
origin,
target: str,
reference,
):
"""本次退回落到哪一环,连同这一环的候选清单一起回。
候选口径与界面下拉共用 :func:`goback_candidates`;那份清单也一并回出去,是因为
「退回到哪些环节才发」那条筛子里的 ``@prev`` 认的就是"落点是不是候选第一个"——
在这儿顺手给,省得调用方再问一遍图与流水。
"""
candidates = goback_candidates(db, work, definition, origin)
if not candidates:
return None, []
if target:
node = definition.activity_by_name(target)
if node is None:
raise EngineError(f"退回目标环节不存在: {target}")
if node.id not in {item.id for item in candidates}:
raise EngineError(
f"「{node.name}」不是「{origin.name}」的上游环节,退回不能把单据往前送"
)
return node, candidates
return candidates[0], candidates
def add_task(
db: Session,
*,
task_id: str,
actor: Actor,
identities: list[str],
way: str = "after",
mode: str = "together",
opinion: str = "",
#: 谁来按那颗「加签」:见模块头那四个 ``VIA_*``
via: str = VIA_OA,
) -> StepResult:
"""加签:在当前待办之前/之后插入其他人的待办."""
task = get_task(db, task_id, actor)
work = db.execute(select(models.Work).where(models.Work.id == task.work)).scalar_one_or_none()
if work is None:
raise EngineError("单据不存在或已被删除")
_ensure_active(work)
definition = definition_module.for_work(db, work)
activity = definition.activity(task.activity)
if activity is None:
raise EngineError("环节定义不存在")
if not bool(activity.config.get("allowAddTask", True)):
raise EngineError(f"环节 {activity.name} 不允许加签")
_lock_guard(db, work.process, activity, "addTask", via, definition)
resolved = org.resolve_identity_names(db, identities)
if not resolved:
raise EngineError("请选择加签人员")
now = datetime.now()
created: list[models.Task] = []
if way == "before":
_complete_task(
db, task, actor,
definition_module.RouteNode(id="addBefore", name="加签", alias="加签", from_activity=task.activity, to_activity=task.activity),
opinion or "加签", "", now, "addBefore",
)
for index, identity in enumerate(resolved):
ref = org.ref_for(db, identity)
created.append(
models.Task(
job=work.job,
work=work.id,
title=work.title,
process=work.process,
process_name=work.process_name,
category=work.category,
category_name=work.category_name,
serial=work.serial,
activity=task.activity,
activity_name=task.activity_name,
activity_type=ACTIVITY_MANUAL,
activity_token=task.activity_token,
activity_description=task.activity_description,
person=ref.person,
identity=identity,
identity_name=ref.name,
unit=ref.unit,
unit_name=ref.unit_name,
creator=work.creator,
creator_person=work.creator_person,
creator_identity=work.creator_identity,
creator_unit=work.creator_unit,
prev_task_identity=actor.ref,
route_list=list(task.route_list or []),
route_name_list=list(task.route_name_list or []),
route_opinion_list=list(task.route_opinion_list or []),
form=task.form,
design_snapshot=work.design_snapshot,
act="add",
act_person=actor.person_name,
label="加签",
order_number=task.order_number + index + 1,
start_time=now,
start_time_month=now.strftime("%Y%m"),
add_task_from=way,
)
)
db.add_all(created)
if way == "before" and mode == "serial":
# 串行加签:先由被加签人处理,处理完再回到加签人
db.add(
models.Task(
job=work.job,
work=work.id,
title=work.title,
process=work.process,
process_name=work.process_name,
category=work.category,
category_name=work.category_name,
serial=work.serial,
activity=task.activity,
activity_name=task.activity_name,
activity_type=ACTIVITY_MANUAL,
activity_token=task.activity_token,
person=actor.person_id,
identity=actor.ref,
identity_name=actor.person_name,
unit=actor.unit,
unit_name=actor.unit_name,
creator=work.creator,
creator_person=work.creator_person,
creator_identity=work.creator_identity,
creator_unit=work.creator_unit,
form=task.form,
design_snapshot=work.design_snapshot,
act="add",
act_person=actor.person_name,
label="加签回转",
start_time=now,
start_time_month=now.strftime("%Y%m"),
add_task_from="before_pending",
route_list=list(task.route_list or []),
route_name_list=list(task.route_name_list or []),
)
)
_notify_task_batch(db, created, work, activity, actor)
db.flush()
return StepResult(work=work, tasks=created)
def _notify_task_batch(db: Session, tasks: list[models.Task], work: models.Work, activity, actor: Actor) -> None:
notify(
db,
[t.identity for t in tasks],
type_="task",
title=f"您有新的待办:{work.title}",
body=f"{actor.person_name} 邀请您参与《{work.title}》在【{activity.name}】环节的处理。",
job=work.job,
work=work.id,
process=work.process,
sender=actor.person_name,
)
# 加签一次派出好几条:幂等键里带上第一条待办号与条数,同一环节再邀一轮也推得出去
events.emit(db, work, "task.arrived", activity_name=activity.name, actor_name=actor.person_name,
task=f"{tasks[0].id}+{len(tasks)}" if tasks else "",
extra={"identities": [t.identity for t in tasks],
**_task_arrived_extra(db, work, activity, tasks)})
def _owner_actor(db: Session, task: models.Task) -> Actor | None:
"""把记账身份换回待办真正的主人。管理员代为操作时用,历史里才不会记成管理员办的。"""
person_id = str(task.person or "")
person = db.get(models.User, int(person_id)) if person_id.isdigit() else None
if person is None:
return None
return Actor.from_ref(db, person, task.identity)
def transfer(
db: Session, *, task_id: str, actor: Actor, identities: list[str], opinion: str = "",
admin: bool = False, via: str = VIA_OA,
) -> StepResult:
"""转办/沟通:把待办转交给其他身份处理.
``admin=True`` 是流程监控里管理员替处理人改派:待办不在管理员手上,所以不查
「待办属于当前身份」,环节上勾了「不允许转办」也照样改得动——管理员存在的意义
就是把卡住的单子救活。但记账口径(谁转的、从谁手里出去)仍回到真正的处理人,
操作人另有操作日志兜着,审批记录不会平白多出管理员一笔。
"""
task = db.get(models.Task, task_id)
if task is None:
raise EngineError("待办不存在或已被处理")
label = "管理员改派" if admin else "转办"
if admin:
owner = _owner_actor(db, task)
if owner is not None:
actor = owner
else:
task = get_task(db, task_id, actor)
work = db.execute(select(models.Work).where(models.Work.id == task.work)).scalar_one_or_none()
if work is None:
raise EngineError("单据不存在或已被删除")
# 管理员在流程监控里改派是「救卡住的单子」,挂起中也得改得动:挂起往往正因为
# 要换人处理,先把人换好再恢复才顺。本人自己转办仍然挡住。
if not admin:
_ensure_active(work)
resolved = org.resolve_identity_names(db, identities)
if not resolved:
raise EngineError("请选择转办对象")
now = datetime.now()
definition = definition_module.for_work(db, work)
activity = definition.activity(task.activity)
if activity is not None and not admin and not bool(activity.config.get("allowTransfer", True)):
raise EngineError(f"环节 {activity.name} 不允许转办")
# 监控里管理员替处理人改派是干预动作,不看环节开关:那道闸只在本人自己转办时认
if not admin:
_lock_guard(db, work.process, activity, "transfer", via, definition)
_complete_task(
db, task, actor,
definition_module.RouteNode(id="transfer", name=label, alias=label, from_activity=task.activity, to_activity=task.activity),
opinion or label, "", now, "transfer",
)
created: list[models.Task] = []
for identity in resolved:
ref = org.ref_for(db, identity)
created.append(
models.Task(
job=work.job,
work=work.id,
title=work.title,
process=work.process,
process_name=work.process_name,
category=work.category,
category_name=work.category_name,
serial=work.serial,
activity=task.activity,
activity_name=task.activity_name,
activity_type=ACTIVITY_MANUAL,
activity_token=task.activity_token,
person=ref.person,
identity=identity,
identity_name=ref.name,
unit=ref.unit,
unit_name=ref.unit_name,
empower_from_identity=actor.ref,
creator=work.creator,
creator_person=work.creator_person,
creator_identity=work.creator_identity,
creator_unit=work.creator_unit,
prev_task_identity=actor.ref,
form=task.form,
design_snapshot=work.design_snapshot,
act="create",
label=label,
start_time=now,
start_time_month=now.strftime("%Y%m"),
route_list=list(task.route_list or []),
route_name_list=list(task.route_name_list or []),
route_opinion_list=list(task.route_opinion_list or []),
)
)
db.add_all(created)
if activity is not None:
_notify_task_batch(db, created, work, activity, actor)
db.flush()
return StepResult(work=work, tasks=created)
#: 图遍历的口径只有一份,放在流程定义那一侧(``engine`` 反过来被 ``definition``
#: 的使用者依赖,把遍历搬进引擎会让两边互相指):上游 / 下游 / 前瞻都绕开回头线,
#: 免得每条驳回线都把整条下游算成"上游"。引擎这里留着同名入口给老调用方与校色脚本。
BACK_DECISIONS = definition_module.BACK_DECISIONS
is_back_route = definition_module.is_back_route
def downstream_activities(definition: ProcessDefinition, activity_id: str) -> set[str]:
"""从某环节往前走能到的全部环节。撤回要靠它判断"我这一步已经带出去多远"。
回头线(退回 / 拒绝)不算带出去的那一段:那条线尽头是要退回去重走的地方,
不是被我这一步带出来的环节,照它走下去会把发起人的补正待办一起收掉。
"""
return definition_module.downstream_ids(definition, activity_id)
def upstream_activities(definition: ProcessDefinition, activity_id: str) -> set[str]:
"""正常路径上走在某环节前面的那些环节。退回只允许退到这些环节。
踩过的坑是费用报销那条「财务经理 --驳回--> 发起人」:不绕开回头线时发起人成了
部门主管的上游、被它带出来的财务经理也算,而候选又按"最近到达"排序,刚到达过的
财务经理排第一——部门主管点退回,单据被推到下一步,审批记录末尾那句就成了
「停在「财务经理」,等待 张梅 处理」。口径见 :func:`definition.upstream_ids`。
"""
return definition_module.upstream_ids(definition, activity_id)
def goback_candidates(
db: Session, work: models.Work, definition: ProcessDefinition, origin
) -> list:
"""这张单子可以退回到的环节,按"最近走过的"排在前面。
以前这里只看流水日志里最后到达过哪个人工环节,于是被两种情况带偏:
撤回只补一条 reset 日志,并不会把"我之前到过下游"那条记录抹掉;分支、
并行也会让下游环节比真正的上游更晚到达。两种情况下"上一环节"算出来是
往前的一步,点确定就把单据往前推、还多派一轮待办。所以候选一律先过
「上游可达」这道筛:退回永远只能往后退。这道筛自己也得绕开回头线,否则
配了「驳回」的流程会把整条下游算成上游,筛子等于没筛(见
:func:`upstream_activities`)。
"""
upstream = upstream_activities(definition, origin.id)
allowed = {node.id: node for node in definition.manual_activities if node.id in upstream}
def starter() -> list:
"""「退回发起人」这个落点:开始环节不是审批环节,进不了上面那份名单。
审批人常常要的就是「这单我不批,退回给提的人重填」,所以它与环节上
goBackConfig 选的是 prev / any / define 无关,永远挂在候选最后——那份配置
管的是「能退回到哪几个审批环节」,不该顺手把发起人一起关掉。
"""
node = definition.begin
if node is None or node.id == origin.id or node.id not in upstream:
return []
# 嵌入子流程是引擎替父单开的,没有「当场提交的人」可退;发起人身份丢了
# (组织数据被清过)也不能派一条没人办得动的待办。
if work.work_create_type == "embed" or not work.creator_identity:
return []
return [node]
def with_starter(nodes: list) -> list:
chosen = {node.id for node in nodes}
return nodes + [node for node in starter() if node.id not in chosen]
if not allowed:
return with_starter([])
config = dict(origin.config or {}).get("goBackConfig") or {}
kind = str(config.get("type") or "prev").lower()
if kind == "define":
picked = []
for item in config.get("data") or []:
node = definition.activity_by_name(str(item))
if node is not None and node.id in allowed and node.id != origin.id:
picked.append(node)
return with_starter(picked)
ordered: list = []
seen: set[str] = set()
logs = db.execute(
select(models.WorkLog)
.where(models.WorkLog.work == work.id, models.WorkLog.arrived_activity_type == ACTIVITY_MANUAL)
.order_by(models.WorkLog.arrived_time.desc())
).scalars().all()
for row in logs:
node = allowed.get(row.arrived_activity)
if node is None or node.id in seen:
continue
seen.add(node.id)
ordered.append(node)
if kind == "any":
for node in definition.manual_activities:
if node.id in allowed and node.id not in seen and node.id != origin.id:
seen.add(node.id)
ordered.append(node)
return with_starter(ordered)
def goback_universe(definition: ProcessDefinition) -> dict[str, list[str]]:
"""每一环**可能退回到哪些环节**:静态那份,不看这张单走过什么路。
与 :func:`goback_candidates` 同源——同一道「上游可达」筛(绕开回头线)、同一份
``goBackConfig`` 收窄、同样永远挂着发起人。差别只在候选要按这张单走过的路排序并受
``type=prev`` 那份"只给上一个"的收窄,而这里只回答"图上退得到退不到":``prev`` 到底会
落到谁身上取决于走过哪条路,静态收窄会误伤,所以按 ``any`` 的口径算全集。
设计期拿它挡「勾了一个这一环永远退不到的落点」那种死配置
(``docs/goback-target-writeback-design.md`` §8)。
"""
out: dict[str, list[str]] = {}
begin = definition.begin
for node in definition.manual_activities:
upstream = definition_module.upstream_ids(definition, node.id)
lands = [item.id for item in definition.manual_activities
if item.id in upstream and item.id != node.id]
config = dict(node.config or {}).get("goBackConfig") or {}
if str(config.get("type") or "prev").lower() == "define":
kept = {str(item) for item in (config.get("data") or [])}
narrowed = [land for land in lands
if land in kept or (definition.activity(land) is not None
and (definition.activity(land).name in kept
or definition.activity(land).alias in kept))]
lands = narrowed
if begin is not None and begin.id != node.id and begin.id in upstream:
lands.append(begin.id)
out[node.id] = lands
return out
def goback_universe_for(db: Session, process_id: str) -> dict[str, list[str]]:
"""库里现在这份设计里,每一环退得到哪些环节(:func:`goback_universe` 的读库那一层)。
环节行现查一遍:保存流程那一路刚把画布上这份写进库、还没 commit,同一 Session 里
现查才看得见(用刚传进来的那批行也行,但两处各拼一份图迟早拼歪,不如一处问库)。
"""
process = db.get(models.Process, process_id)
if process is None:
return {}
activities = list(db.scalars(
select(models.Activity).where(models.Activity.process == process_id)))
routes = list(db.scalars(
select(models.Route).where(models.Route.process == process_id)
.order_by(models.Route.order_number, models.Route.name)))
return goback_universe(definition_module.build(process, activities, routes))
#: 单据落定后的状态说法:撤回被拦下时要告诉人是哪一种
WORK_STATUS_LABELS = {"completed": "办结", "terminated": "终止", "cancelled": "作废"}
def reset_task(
db: Session,
*,
task_completed_id: str,
actor: Actor,
opinion: str = "",
#: 谁来按那颗「撤回」:见模块头那四个 ``VIA_*``
via: str = VIA_OA,
) -> StepResult:
"""撤回已办:仅在后续环节尚未查看/处理时允许."""
record = db.get(models.TaskCompleted, task_completed_id)
if record is None:
raise EngineError("已办记录不存在")
if not actor.is_admin and record.identity != actor.ref:
raise EngineError("只能撤回本人处理的待办")
if record.processing_type != "normal":
raise EngineError(f"{record.label or record.processing_type} 记录不支持撤回")
work = db.execute(select(models.Work).where(models.Work.id == record.work)).scalar_one_or_none()
if work is None:
# 办结 / 终止 / 作废那一刻整行搬进了 oa_work_completed,在途表里查不到。
# 这里要说清楚是「单子已经落定」而不是「单子没了」:归档的单据是账,
# 前面每个人的表态都进了台账,把最后一步撤回重办等于改掉已经归档的记录。
archived = db.get(models.WorkCompleted, record.work)
if archived is not None:
raise EngineError(f"流程已{WORK_STATUS_LABELS.get(archived.status, '办结')}并归档,无法撤回")
raise EngineError("单据不存在或已被删除")
if work.status != "running":
raise EngineError(f"流程已{WORK_STATUS_LABELS.get(work.status, '办结')},无法撤回")
if not actor.is_admin:
_ensure_active(work)
definition = definition_module.for_work(db, work)
recall_activity = definition.activity(record.activity)
if recall_activity is not None and not bool(recall_activity.config.get("allowRecall", True)):
raise EngineError(f"环节 {recall_activity.name} 不允许撤回")
_lock_guard(db, work.process, recall_activity, "recall", via, definition)
# 撤回条件:本环节之后没有人处理过,且当前待办的人还没有查看。
moment = record.completed_time or record.start_time or record.create_time
later = db.execute(
select(func.count(models.TaskCompleted.id)).where(
models.TaskCompleted.work == work.id,
models.TaskCompleted.id != record.id,
models.TaskCompleted.completed_time >= moment,
)
).scalar()
if later:
raise EngineError("后续环节已处理,无法撤回")
followers = db.execute(
select(models.Task).where(
models.Task.work == work.id,
models.Task.create_time >= moment,
)
).scalars().all()
for item in followers:
if item.identity != record.identity and item.view_time is not None:
raise EngineError("后续处理人已查看待办,无法撤回")
# 撤回只该把自己这一步往后的部分收回来:并行里的兄弟分支不能被牵连,
# 但从我这一步之后自动流转出去的环节(脚本 / 接口 / 延时 / 嵌入子流程)必须一起收回,
# 否则重办一次就会再派出第二条支线——实测多开出一个嵌入子流程。
downstream = downstream_activities(definition, record.activity)
dropped = [t for t in work.tokens if t.get("activity") in downstream]
for token in dropped:
child_job = str(token.get("embed_job") or "")
if child_job:
try:
terminate(db, job=child_job, actor=actor, opinion="父流程已撤回到上游环节,子流程一并终止",
enforce_starter_config=False)
except EngineError:
logger.exception("撤回时未能终止嵌入子流程 %s", child_job)
drop_ids = {t.get("id") for t in dropped}
work.tokens = [
t for t in work.tokens
if t.get("id") not in drop_ids and t.get("activity") != record.activity
]
if downstream:
db.execute(delete(models.Task).where(models.Task.work == work.id, models.Task.activity.in_(downstream)))
record.retract_time = datetime.now()
db.delete(record)
# 撤回等于这一步要重新表态:和「退回」一样把「谁已经批过」的记忆清到此刻,
# 否则流程级「前面批过就自动通过」会把撤回人自己跳过,单据就悬在半路没有待办了。
work.variables = {**(work.variables or {}), DEDUP_SINCE_KEY: datetime.now().isoformat()}
db.flush()
activity = definition.activity(record.activity)
if activity is None:
raise EngineError("环节定义不存在")
token = {"id": uuid.uuid4().hex, "activity": activity.id, "path": record.activity_token or activity.id}
work.tokens.append(token)
_log(
db,
work,
definition,
from_activity=definition.activity(record.activity),
to_activity=activity,
route=definition_module.RouteNode(
id="reset", name="撤回", alias="撤回", from_activity=record.activity, to_activity=activity.id
),
actor=actor,
opinion=opinion or "撤回",
token=token,
log_type="reset",
)
db.flush()
step = StepResult(work=work)
# L3 挂载点之四「本环节被撤回时」:挂在被撤回那条已办所属的环节上——那一刻这张单要
# 重新走一遍这一环,对面要么别再按刚才那条处理,要么把草稿撤掉。同样不经过 _advance,
# 所以这里是唯一钩子;与撤回同一事务。会签里一个人撤回自己那条也算一次,按撤回人入队。
outbox.enqueue_node(
db, work, activity, phase=outbox.TRIGGER_RECALL, actor=actor,
action={"route": "撤回", "route_alias": "撤回", "decision": "", "opinion": opinion,
# 第三方那边收回了自己的结论(/open/tasks/completed/{id}/recall)也算一次撤回:
# 谁按的交给规则去筛,报文里也取得到。
"via": via},
)
# via_goback:被撤回的那一步就是要本人重新处理,连「审批人就是发起人」也不跳过
step.tasks.extend(
_arrive_manual(db, work, definition, activity, actor, token, step, via_goback=True)
)
return step
def press(db: Session, *, task_id: str, actor: Actor, opinion: str = "") -> models.Task:
"""催办."""
task = db.get(models.Task, task_id)
if task is None:
raise EngineError("待办不存在")
work = db.execute(select(models.Work).where(models.Work.id == task.work)).scalar_one_or_none()
if work is None:
raise EngineError("单据不存在或已被删除")
_ensure_active(work)
press_activity = definition_module.for_work(db, work).activity(task.activity)
if press_activity is not None and not bool(press_activity.config.get("allowPress", True)):
raise EngineError(f"环节 {press_activity.name} 不允许催办")
task.urge_time = datetime.now()
task.urged = True
task.press_count = (task.press_count or 0) + 1
task.press_time = task.urge_time
notify(
db,
[task.identity],
type_="press",
title=f"催办提醒:{work.title}",
body=opinion or f"{actor.person_name} 提醒您尽快处理《{work.title}》。",
job=work.job,
work=work.id,
task=task.id,
process=work.process,
sender=actor.person_name,
)
db.flush()
return task
def terminate_facts(db: Session, work: models.Work) -> dict:
"""「现在还能不能终止」要看的那三份事实:到过哪些环节、别人办过没有、发起多久了。
``reached`` 取"到过"而不是"正停在哪一环":留痕里的到达记录 + 在路上的 token + 单据
游标三处并起来,单子从指定环节流走之后照样算"过线了"。
``handled_by_others`` 只认**别人办完过一步**(``processing_type=normal``):转办与自动结掉
都不算有人真表过态,而发起人自己填的那一步也不算——那张单还没落到任何人手上。
"""
reached: set[str] = set(
db.execute(select(models.WorkLog.arrived_activity).where(models.WorkLog.work == work.id))
.scalars()
)
reached.update(str(token.get("activity") or "") for token in (work.tokens or []))
reached.add(str(work.activity or ""))
handled = db.execute(
select(func.count(models.TaskCompleted.id)).where(
models.TaskCompleted.work == work.id,
models.TaskCompleted.processing_type == "normal",
models.TaskCompleted.identity != work.creator_identity,
)
).scalar() or 0
started = work.start_time or work.create_time or datetime.now()
return {
"reached": {item for item in reached if item},
"handled_by_others": bool(handled),
"elapsed_hours": max(0.0, (datetime.now() - started).total_seconds() / 3600.0),
}
def terminate_blocker(db: Session, work: models.Work, definition: ProcessDefinition, actor: Actor) -> str:
"""发起人在这一刻终止得动吗;回一句为什么动不了,能终止回空串。
判据只有一处(:func:`app.service.terminate.starter_blocker`),界面上那句提示与
引擎挡下时抛的那一句同源。**管理员不在约束范围内**:监控里的终止是干预手段,
流程那一格管的是"发起人能不能收拾自己已经交出去的单"。
"""
if actor.is_admin:
return ""
config = terminate_service.config_of(definition)
if not terminate_service.allowed_by_config(config):
# 钮都关了,三份事实不必再问库:这一句就是全部答案
return terminate_service.starter_blocker(config)
# 环节上那一格是硬闸:单据正停着的那一环关掉了终止钮,发起人这会儿就按不动
# (与「退回」「撤回」那两颗钮同一个开关家族,见 serializers_activity_brief)
current = definition.activity(str(work.activity or ""))
if current is not None and not bool((current.config or {}).get("allowTerminate", True)):
return f"「{current.name}」这一环关掉了终止,发起人不能再终止这张单;请联系流程管理员。"
if config["until"] == terminate_service.UNTIL_ALWAYS:
return "" # 没设窗口:一次库都不问
node = definition.activity(str(config.get("untilActivity") or ""))
facts = terminate_facts(db, work)
return terminate_service.starter_blocker(
config,
reached=facts["reached"],
handled_by_others=facts["handled_by_others"],
elapsed_hours=facts["elapsed_hours"],
activity_name=node.name if node is not None else "",
)
def terminate(db: Session, *, job: str, actor: Actor, opinion: str = "",
enforce_starter_config: bool = True) -> StepResult:
"""终止/作废流程.
终止是**整张单**的动作,不是当前那一环的表态:还挂着的待办会被强行结掉,那些行留在
原持有人名下(他的已办里要看得见这张单),但 ``operator`` 那一列写的是按终止的人,
并旁挂一条 :data:`LOG_TERMINATE` 留痕把操作人与原因落在单子上。
发起人这一路还要过流程自己那一格终止配置(谁能终止、到什么时候为止,
见 :mod:`app.service.terminate`);管理员与开放接口那两路只受"是不是发起人/管理员"约束。
``enforce_starter_config=False`` 留给**引擎替父单收尾**那两处级联(撤回时收回自动流转
出去的嵌入子流程、父单归档时带走还在跑的子单):那一格管的是"人能不能收拾自己交出去
的单",而级联是父单那一步已经合法走完之后的连带清理,按不住、也不该按不住——真挡住了
只会留下一张父单已归档、子单还挂着待办的孤儿单,而那两处又是 ``except EngineError``
只记日志的,失败悄无声息。
"""
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
raise EngineError("单据不存在或已被删除")
if work.status != "running":
raise EngineError("流程已结束")
if not (actor.is_admin or work.creator == actor.person_id):
raise EngineError("只有发起人或管理员可以终止流程")
definition = definition_module.for_work(db, work)
blocker = terminate_blocker(db, work, definition, actor) if enforce_starter_config else ""
if blocker:
raise EngineError(blocker)
now = datetime.now()
reason = (opinion or "").strip() or "流程终止"
pending = db.execute(select(models.Task).where(models.Task.work == work.id)).scalars().all()
# 待办一消失就得喊人:不然对方手上那条「等待您在 XX 环节处理」永远挂着,
# 点进去一张已归档的单,谁都不知道这张单还要不要办。
handlers = [item for item in dict.fromkeys(str(task.identity or "") for task in pending)
if item and item != str(actor.ref or "")]
for task in pending:
_complete_task(
db, task, actor,
definition_module.RouteNode(id="terminate", name="终止", alias="终止", from_activity=task.activity, to_activity=""),
reason, "", now, "terminate", operator=actor,
)
_event_log(
db, work, _cursor_activity(work, definition), actor,
f"{actor.person_name} 终止了流程:{reason}", LOG_TERMINATE,
)
# 归档那一刻 ``oa_work`` 整行搬走并删掉,通知要的这几样先抄下来
work_id, work_job, work_process, work_title = work.id, work.job, work.process, work.title
result = _finish_work(
db, work, definition, status="terminated", result=StepResult(), actor=actor,
opinion=reason, activity=None,
)
if handlers:
notify(
db, handlers,
type_=NOTIFY_CONTROL,
title=f"待办已终止:{work_title}",
body=f"{actor.person_name} 终止了《{work_title}》,你手上那条待办不再需要办理。原因:{reason}",
job=work_job,
work=work_id,
process=work_process,
sender=actor.person_name,
)
return result
#: 删除未发起的单时一起清掉的运行表。这张单从没进过任何人的办理,挂在它身上的只有
#: 发起人自己那几行,连行带号一起抹掉才算「没有这张单」;归档表(``oa_*_completed``)里
#: 那几行是已经落定的历史,删除这一条路不开到它们头上(那种单要的是终止)。
#: ``oa_attachment`` 删的是行:文件本体留在存放位置上,与终止归档时同一待遇,
#: 对不上主的对象由 ``scripts/audit_storage.py`` 去喊人,不在这里替人删文件。
_WORK_TRACE_MODELS = (
models.Task,
models.TaskCompleted,
models.WorkLog,
models.Read,
models.ReadCompleted,
models.WorkComment,
models.Attachment,
models.Notification,
# 嵌页面在第三方那边建出来的那一页的账(``oa_embed_page``):这张单都没了,
# 这一行留着只会让下一张单认到一条早就不存在的地址上。删单前已经先给第三方
# 补过那一句「这张单删了」(见 :func:`service.embed_session.abandon_on_work_deleted`)
models.EmbedPage,
)
class DeletedWork(NamedTuple):
"""删掉的那张单,只留界面与操作日志要复述的几样(实例本身已经不在库里了)。"""
job: str
work_id: str
serial: str
title: str
def unstarted_delete_reason(db: Session, work: models.Work, *, actor: Actor) -> str:
"""这一单能不能由眼前这个人删掉:能删回空串,不能删回那句「为什么不能」。
主线只有一条——**这一单还没发起**。还停在开始环节、没压在别人手上,删掉就等于
把一张没交出去的稿子扔进纸篓,谁都不受影响。已经流转出去的单删不得:别人手上的
已办与流转记录会跟着一起没,那种单要的是终止。
"""
if work.status != "running":
return "流程已结束,不能再删除"
if not (actor.is_admin or work.creator == actor.person_id):
return "只有发起人可以删除自己创建、还没发起的流程"
if work.paused:
return "这一单被挂起了,请等管理员恢复之后再处理"
definition = definition_module.for_work(db, work)
begin = definition.begin
if begin is None:
return "流程缺少开始环节,判断不了这一单发起没有"
if work.activity != begin.id or work.activity_type != ACTIVITY_BEGIN:
return "这一单已经发起流转,不能删除,请改用终止"
if _has_foreign_rows(db, models.Task, work):
return "这一单还有别人的待办没有办完,不能删除"
if _has_foreign_rows(db, models.Read, work, extra=(models.Read.requires_action.is_(True),)):
return "这一单还有别人要处理的抄送,不能删除"
if db.execute(
select(models.Work.job)
.where(models.Work.parent_job == work.job, models.Work.status == "running")
.limit(1)
).scalar_one_or_none() is not None:
return "这一单还挂着没走完的子流程,不能删除"
return ""
def _has_foreign_rows(db: Session, model, work: models.Work, *, extra: tuple = ()) -> bool:
"""这张单上有没有压在**发起人以外**的人手上的行(待办 / 需处理的抄送共用一句问法)。
认的是行上那一份 ``creator_identity`` 快照,不按人回查单据:这一行是谁创建的就该
还给谁,别人手上的活不该被创建人一次删除带走。
"""
stmt = select(model.id).where(
model.work == work.id, model.identity != work.creator_identity, *extra
).limit(1)
return db.execute(stmt).scalar_one_or_none() is not None
def delete_unstarted(db: Session, *, job: str, actor: Actor) -> DeletedWork:
"""删掉一张还没发起流转的单:发起人自己那张「填好了还没交出去」的单。
与 :func:`terminate` 的分别是**留不留这份档案**:终止把单子办完再整行搬进归档表,
别人手上的已办跟着留下,「我发起的」里也还看得见它终止了;删除是这张单从头到尾
没进过任何人的办理,连行带号从运行表里一起抹掉,界面上再也找不到它。判据全在
:func:`unstarted_delete_reason`,一句话:还停在开始环节、且没有别人压在上面。
四样收尾别漏:额度上压着的占用要还回去(与终止同一句),第三方还停在「等发起人
确认」的表态要作废,嵌页面那本「这一趟已经发起成一张单了」的账要收回——不收回,
对方拿同一个预受理号重发会被认成重复发起,而那张单已经不存在了;最后还得给第三方
补一句「这张单删了,你在这一趟里建的东西也删了吧」,参数与删草稿那一条腿同一个人
配的同一份(见 :func:`service.embed_session.abandon_on_work_deleted`)。
已经写回上游的报文不跟着单走:配了冲销模板就补一条反向消息,没配就在原消息上挂
「要人工去上游作废」的标记(见 :func:`service.outbox.handle_reversal`)。
"""
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
raise EngineError("单据不存在,或早已办结归档")
reason = unstarted_delete_reason(db, work, actor=actor)
if reason:
raise EngineError(reason)
deleted = DeletedWork(job=work.job, work_id=work.id, serial=work.serial, title=work.title)
quota.release_work(db, work, actor=actor, reason="单据删除(未发起),释放占用")
_invalidate_node_decisions(db, work.id, "terminated")
# 还没打出去的写回不再往外推;已经发出去的那几笔按终止那一档处理冲销
db.execute(
delete(models.OutboundMessage).where(
models.OutboundMessage.work == work.id,
models.OutboundMessage.status.in_(models.OutboundMessage.STATUS_OPEN),
)
)
outbox.handle_reversal(db, work, models.Integration.EVENT_TERMINATED, actor=actor)
# 第三方那一头也得知道这张单没了:嵌页面在他们那边建出来的东西(草稿、工单)只有 OA
# 报得出那个号,这一声不出对面就永远烂着一份。发出去的是**与删草稿同一套参数**的那一句
# (同一条地址、同一个方法、同一个号字段,号取这张单的单号,见
# :func:`service.embed_session.abandon_on_work_deleted`)。
# 必须排在收回 ``claim_job`` 与删单之前:那两步一过,这一趟还能不能算到这张单上就没人
# 答得出了。通知没发成**不挡删除**——那一路只记账、不抛错,缺的那一句有留痕可查。
# 局部导入:``service/embed_session`` 模块级要 import 本模块,反过来在模块级引会绕成环
from ..service import embed_session # noqa: PLC0415
embed_session.abandon_on_work_deleted(db, work, actor=actor)
for model in _WORK_TRACE_MODELS:
db.execute(delete(model).where(model.work == work.id))
db.execute(
update(models.EmbedSession)
.where(models.EmbedSession.claim_job == work.job)
.values(claim_job="", claim_serial="", claim_time=None)
)
db.delete(work)
db.flush()
logger.info("已删除未发起的单据 job=%s serial=%s 操作人=%s", deleted.job, deleted.serial, actor.ref)
return deleted
def deletable_task_ids(db: Session, tasks: Iterable[models.Task], *, identity: str) -> set[str]:
"""这一页待办里哪几条可以在列表上直接删。
判据与 :func:`unstarted_delete_reason` 同源,只是这里要一次问完一页:先按行上的
字段筛出「开始环节 + 发起人是我」的那几条,再一次查完这些单上有没有压在别人手上的
待办与抄送。逐条调 :func:`unstarted_delete_reason` 会变成每行读一遍流程定义。
"""
candidates = [
row for row in tasks
if row.activity_type == ACTIVITY_BEGIN and row.creator_identity == identity == row.identity
]
if not candidates:
return set()
work_ids = [row.work for row in candidates]
# 三种挡条并成一条语句问完(别人的待办 / 别人要处理的抄送 / 被管理员挂起的单):
# 这一页多数时候一条候选都没有,有候选时也不该让待办列表多排几次队
# (每接口的语句条数是当回归线守着的,见 scripts/perf_guard.py)
blocking = union(
select(models.Task.work).where(
models.Task.work.in_(work_ids), models.Task.identity != models.Task.creator_identity
),
select(models.Read.work).where(
models.Read.work.in_(work_ids),
models.Read.identity != models.Read.creator_identity,
models.Read.requires_action.is_(True),
),
select(models.Work.id).where(models.Work.id.in_(work_ids), models.Work.paused.is_(True)),
)
blocked = set(db.execute(blocking).scalars())
return {row.id for row in candidates if row.work not in blocked}
# ---------------------------------------------------------------------------
# 流程干预 (intervention): 挂起 / 恢复 / 改道 / 修正表单 / 整单催办与改派
# ---------------------------------------------------------------------------
class _StubActivity(NamedTuple):
"""环节定义已被删掉时的替身:流转日志只认 ``id`` / ``name`` / ``type`` 这三样。"""
id: str
name: str
type: str
def _ensure_active(work: models.Work) -> None:
"""挂起中的单据一律停止办理。
挂起是管理员按下的「先停在原地」:待办还挂在人手里,但这一环此刻不许动——
一边挂着调查一边被人批出去,挂起就白挂了。恢复之后一切照旧。
"""
if not work.paused:
return
who = f"{work.pause_actor} " if work.pause_actor else ""
when = f"{work.pause_time:%Y-%m-%d %H:%M}" if work.pause_time else ""
why = f":{work.pause_reason}" if work.pause_reason else ""
raise EngineError(f"流程已挂起({who}{when}{why}),请等管理员恢复之后再处理")
def _lock_guard(
db: Session, process_id: str, activity, action: str, via: str, definition=None,
starting: bool = False,
) -> None:
"""OA 界面那几颗钮的通道闸:位置与 :func:`_ensure_active` 同一姿态。
先看挂起、再看锁、最后才轮到路由、闸门与写回卡控——顺序要说得出理由:锁与点的
是哪条出口无关,越早说越省事,也不必为一张注定办不动的单跑一遍公式和外部核验外呼。
管理员的干预动作(监控改派、改道、终止)不调这一句:干预层不看环节开关,
那条口径早就写在 process-intervention-design.md §3。
要的是 ``process_id`` 而不是 ``work``:发起那一刻单子还没建出来,这一句也得能用
(见 :func:`create_job` 那一句 ``starting=True``)。
"""
from ..service import node_approve
if via not in node_approve.OA_VIAS or activity is None:
return
message = node_approve.check(
db, process_id, activity, action=action, via=via, process=definition,
starting=starting,
)
if message:
raise EngineError(message)
def _running_work(db: Session, job: str) -> models.Work:
"""按 job 取一张还在跑的单据,干预类动作都从这里进。"""
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
# 办结 / 终止之后 oa_work 那一行会被整体搬进归档表,这里是查不到的。可对管理员来说
# 「查无此单」和「这单早走完了」是两回事——前者是他输错了号,后者是他来晚了,
# 混成一句会让人回头去翻回收站。
archived = db.execute(
select(models.WorkCompleted.job).where(models.WorkCompleted.job == job).limit(1)
).scalar_one_or_none()
raise EngineError("这张单据已经办结或终止归档,不能再干预" if archived else "单据不存在或已被删除")
if work.status != "running":
raise EngineError("流程已结束,无法干预")
return work
def _pending_tasks(db: Session, work: models.Work) -> list[models.Task]:
"""这一单当前压在人手里的待办,顺序与待办列表一致。"""
return list(
db.execute(
select(models.Task)
.where(models.Task.work == work.id)
.order_by(models.Task.order_number, models.Task.start_time)
).scalars().all()
)
def running_embed_children(db: Session, work: models.Work) -> list[models.Work]:
"""这张单上还在跑的嵌入子流程。子单是独立实例,父单改道不会带着它们走。"""
return list(db.execute(
select(models.Work)
.where(models.Work.parent_job == work.job, models.Work.status == "running")
.order_by(models.Work.start_time)
).scalars().all())
def embed_blocker(db: Session, children: list[models.Work]) -> str:
"""改道撞上在跑子流程时那句话:报得出是哪几张子单、卡在谁手上、两条出路。"""
parts = []
for child in children[:3]:
names = [str(name or "").strip() for name in db.execute(
select(models.Task.identity_name).where(models.Task.work == child.id)
).scalars().all()]
holders = "、".join(dict.fromkeys(name for name in names if name))
here = str(child.current_activity_names or child.activity_name or "")
parts.append(f"《{child.title}》停在「{here}」" + (f"等 {holders} 办" if holders else ""))
# 子单不止三张时只念前三张:这句话是从接口抛出去的,全列出来会淹没后面那两条出路
listed = ";".join(parts) + (f";另有 {len(children) - 3} 张" if len(children) > 3 else "")
return (
f"这一单还挂着 {len(children)} 张在跑的子流程:{listed}。"
"改道会把父单等子流程回来那张票一起清掉,子单从此没人认领。"
"请先去收拾子单,或勾上「一并终止子流程」再改道。"
)
def _definition_of(db: Session, work: models.Work):
"""流程定义;定义后来被人删了的历史单据返回 ``None``,干预记录照样得写得出来。"""
try:
return definition_module.for_work(db, work)
except ValueError:
return None
def _activity_node(definition, activity_id: str):
return definition.activity(activity_id) if (definition is not None and activity_id) else None
def _cursor_activity(work: models.Work, definition):
"""日志上的「当前环节」:定义里查不到就退回单据上抄下来的那份名字。"""
node = _activity_node(definition, work.activity)
if node is not None:
return node
return _StubActivity(
id=work.activity, name=work.activity_name or "当前环节", type=work.activity_type or ""
)
def _event_log(
db: Session, work: models.Work, activity, actor: Actor, opinion: str, log_type: str
) -> None:
"""挂起 / 恢复 / 改数据这三条事件日志:不改变在路上的 token,只在当前环节旁挂一句。
出发地与到达地都写同一环、不给路由,审批记录把它渲染成一条旁挂的引擎事件,
「这单挂起过两天」这种问题才有地方可查。
"""
_log(
db, work, None,
from_activity=activity, to_activity=activity, route=None, actor=actor,
opinion=opinion, token=None, log_type=log_type,
)
def suspend(db: Session, *, job: str, actor: Actor, opinion: str = "") -> StepResult:
"""挂起:单据停在当前环节,待办办不动、超时不计时,恢复之后原地继续。
故意不动 ``work.status``:挂起不是流程的一种结局,只是运行中的一个冻住开关。
归档、统计、办结判定全都按 ``status`` 走,多认一个状态等于把这三处都改一遍。
"""
work = _running_work(db, job)
if work.paused:
raise EngineError("这张单据已经在挂起中")
reason = (opinion or "").strip() or "管理员挂起"
now = datetime.now()
work.paused = True
work.pause_reason = reason[:1000]
work.pause_actor = actor.person_name
work.pause_time = now
tasks = _pending_tasks(db, work)
for task in tasks:
task.pause = True
_event_log(db, work, _cursor_activity(work, _definition_of(db, work)), actor, reason, LOG_SUSPEND)
notify(
db,
[task.identity for task in tasks] + [work.creator_identity],
type_=NOTIFY_CONTROL,
title=f"流程已挂起:{work.title}",
body=f"{actor.person_name} 挂起了《{work.title}》,你手里的待办暂时不用办。原因:{reason}",
job=work.job,
work=work.id,
process=work.process,
sender=actor.person_name,
)
db.flush()
return StepResult(work=work, tasks=tasks)
def resume(db: Session, *, job: str, actor: Actor, opinion: str = "") -> StepResult:
"""恢复:解冻当前环节的待办,并把挂起占用的那段时间从时限里扣掉。
「挂起期间不计时」是挂起真正有用的前提:不挪时限的话,挂一周再恢复,
一睁眼每条待办都超时,催办和超时自动处理还会一起炸开。
"""
work = _running_work(db, job)
if not work.paused:
raise EngineError("这张单据没有在挂起中")
now = datetime.now()
frozen = now - (work.pause_time or now)
tasks = _pending_tasks(db, work)
for task in tasks:
task.pause = False
if task.expire_time is not None:
task.expire_time = task.expire_time + frozen
if work.expire_time is not None:
work.expire_time = work.expire_time + frozen
work.paused = False
work.pause_reason = ""
work.pause_actor = ""
work.pause_time = None
note = (opinion or "").strip() or "管理员恢复"
_event_log(db, work, _cursor_activity(work, _definition_of(db, work)), actor, note, LOG_RESUME)
notify(
db,
[task.identity for task in tasks],
type_=NOTIFY_CONTROL,
title=f"流程已恢复:{work.title}",
body=f"{actor.person_name} 恢复了《{work.title}》,请继续处理。说明:{note}",
job=work.job,
work=work.id,
process=work.process,
sender=actor.person_name,
)
db.flush()
return StepResult(work=work, tasks=tasks)
def move(
db: Session,
*,
job: str,
actor: Actor,
activity: str,
opinion: str = "",
cascade_children: bool = False,
) -> StepResult:
"""干预改道:把整张单据搬到指定环节重走。
跟审批人自己的「退回」是两把不同的刀——退回只能往上游走、且必须是这一环本人;
改道是管理员替一张卡死的单子换路,往前往后都去得。代价有三条,界面必须讲清楚:
* 当前所有待办一律结掉进「已办」,谁手里被收走了几条,审批记录里看得见;
* 并行 / 拆分还开着的时候不动刀。``work.joins`` 里还有没收的票箱,就说明此刻
有几条分支同时在路上,改道会把它们并成一条、剩下的分支从此没有归宿,
那种单子请先在出问题的分支上用「退回」。
* 还挂着在跑的嵌入子流程时也先停手。父单停在调用环节时**自己没有待办**,待办全在
子单上,而改道会把 ``work.tokens`` 里那张 ``embed_job`` 等待票一起清掉——子单从此
没人认领,它办完时 ``resume_embed_parent`` 认不出 token 就直接落空,子流程办出来的
结论对父单等于没发生。要么先去收拾子单,要么显式勾上 ``cascade_children``
一并终止:终止是不可逆的,不替管理员默认按下去。
"""
work = _running_work(db, job)
if work.joins:
raise EngineError(
"这张单据正走在并行 / 拆分的多条分支上,改道会把几条分支并成一条。"
"请先在出问题的那条分支上用「退回」处理,或等其余分支办完。"
)
children = running_embed_children(db, work)
if children and not cascade_children:
raise EngineError(embed_blocker(db, children))
definition = definition_module.for_work(db, work)
target = definition.activity(activity) or definition.activity_by_name(activity)
if target is None:
raise EngineError(f"目标环节不存在: {activity}")
if target.type != ACTIVITY_MANUAL:
raise EngineError(f"「{target.name}」不是人工审批环节,改道只能落到要人办的那一环")
reason = (opinion or "").strip() or "管理员干预改道"
origin = _cursor_activity(work, definition)
now = datetime.now()
route = definition_module.RouteNode(
id="move",
name="干预改道",
alias="干预改道",
from_activity=work.activity,
to_activity=target.id,
decision="move",
)
tasks = _pending_tasks(db, work)
held = [(task.identity, task.activity_name) for task in tasks]
for task in tasks:
# 收待办走的是「结掉进已办」而不是直接删:这张单上每个人手里的东西都得留痕,
# 事后才答得出「财务复核那条待办怎么没了」。``operator`` 必须给:不传就等于把
# 来人当持有人,陈鹏的「我的已办」里那一行会读成他自己同意的(终止那一步一直有给)。
_complete_task(db, task, actor, route, reason, "", now, LOG_MOVE, operator=actor)
# 换路之后这一段要重新表态:清掉「谁已经批过」的记忆,否则去重规则会把目标环节上
# 那位「前面批过」的审批人直接跳过,改道完单据自己就往前跑了。
variables = dict(work.variables or {})
for key in [name for name in variables if str(name).startswith(SERIAL_QUEUE_PREFIX)]:
variables.pop(key)
variables[DEDUP_SINCE_KEY] = now.isoformat()
work.variables = variables
work.tokens = []
work.joins = {}
work.go_back_store = {}
# 第三方停在半路等确认的那些表态一起作废:那是改道**之前**、按改道之前的表单说的,
# 改道回到同一环时它会突然冒出来等人点头。
from ..service import node_approve
node_approve.invalidate_for_work(
db, work.id, "rerouted",
note=f"单据已由 {actor.person_name} 改道到「{target.name}」,这一环的表态作废",
)
token = {"id": uuid.uuid4().hex, "activity": target.id, "path": target.id}
# 改道是直接落到目标环节、不走 _advance 那段派发,所以"到达本环节生成编号"这一档
# 要在派发待办之前自己补一次,否则管理员把单子挪到编号环节,新待办上还是空的单号。
if numbering.due_at(numbering.timing_of(definition), target.id, numbering.WHEN_ENTER):
issue_serial(db, work, definition, actor=actor)
_log(
db, work, definition,
from_activity=origin, to_activity=target, route=route, actor=actor,
opinion=reason, token=token, log_type=LOG_MOVE,
)
step = StepResult(work=work)
created = _arrive_manual(db, work, definition, target, actor, token, step)
if not created:
# 一个处理人都解析不出来:单据停在环上谁也都办不了,比原地不动危险得多,
# 宁可整笔回滚,让管理员去把这一环的审批人配好再来一次。
raise EngineError(f"「{target.name}」现在解析不到处理人,改道没有生效。请先确认这一环的审批人配置。")
if work.paused:
# 挂起中改的道:新待办跟着一起冻住,等恢复了才放行。
for task in created:
task.pause = True
held_identities = list(dict.fromkeys(identity for identity, _name in held))
for identity, activity_name in held:
notify(
db, [identity],
type_=NOTIFY_CONTROL,
# ``channel_event`` 与站内信类型分家:站内还是那条 control(说的是已经发生的
# 一件事,永远不跟着收尾),外发那一路是渠道能单独勾的 rerouted。存量渠道的
# events 里没这个值,于是默认一句都不往外推,谁要谁勾;深链自动落
# ``/work/<job>``——rerouted 不在 HUB_TASK_EVENTS 里,那条待办已经不在了。
channel_event="rerouted",
title=f"待办已随改道结束:{work.title}",
body=(
f"{actor.person_name} 将《{work.title}》从「{activity_name}」改到「{target.name}」,"
f"你手里那条待办已随之结束。原因:{reason}"
),
job=work.job, work=work.id, process=work.process, sender=actor.person_name,
)
if work.creator_identity not in set(held_identities):
notify(
db, [work.creator_identity],
type_=NOTIFY_CONTROL,
channel_event="rerouted",
title=f"流程被改道:{work.title}",
body=f"{actor.person_name} 将《{work.title}》改到「{target.name}」。原因:{reason}",
job=work.job, work=work.id, process=work.process, sender=actor.person_name,
)
# 被收走待办的人手里那句「您有新的待办」当场退场,不等他下次点开列表才收尾。
# 收尾是标已读、不删行,投递记录照旧回查得到(口径见 service/notify_settle.py)。
from ..service import notify_settle
for identity in held_identities:
notify_settle.settle(db, identity)
# 勾了一并终止才动子单,且放在改道之后:父单这边任何一步没成,都不会先把子单杀掉。
for child in children:
terminate(
db, job=child.job, actor=actor,
opinion=f"父流程已由 {actor.person_name} 改道到「{target.name}」,子流程一并终止",
enforce_starter_config=False,
)
db.flush()
return step
def fix_data(db: Session, *, job: str, actor: Actor, data: dict | None, opinion: str = "") -> StepResult:
"""修正表单数据:单据在路上填错了,改一处比退回重走省一整轮。
与审批人办单时改表单同一个口径(都只收页面交上来的那几项、都记下改了什么),
差别只在这里没有「环节字段权限」可依据,所以按表单字段整份比差异、
系统留痕(下划线开头那些)照旧由服务端自己写,页面盖不掉。
改完也要把标题对齐(:func:`_refresh_title`):表单里那格「流程标题」被管理员改了、
或者改的字段正被标题规则引用,``work.title`` 与在途的待办 / 待阅都跟着换一句——
这一层没做就是「面板里明明改好了,列表里还写着老那一句」。顺带把这一层修好之前留下的
歪账治好:那一格与 ``work.title`` 本来就对不上时,哪怕这次一个字没改也认下来,
不然老单子只能靠再改点别的才能把名字对齐。
"""
work = _running_work(db, job)
definition = _definition_of(db, work)
node = _activity_node(definition, work.activity)
fields = _activity_form_fields(db, work, node, definition)
before = dict(work.data or {})
incoming = without_trace_keys(data, fields)
if not incoming:
raise EngineError("没有要修正的表单内容")
changes = form_change_notes(fields, before, {**before, **incoming}, incoming)
work.data = {**before, **incoming}
# 标题跟着表单走:那一格归管理员改的就是标题,动了规则引用的字段也算改标题。
# 环节挂的是另一张表单、标题格还留在发起那张上时(面板上摆出来的可能就是发起表单),
# 把发起表单的字段一起摊进来认一次,认法同 titles.refresh 找落点时的那道回退。
shown = fields
if titles.form_title_field(fields) is None:
shown = [*fields, *titles.start_fields(db, work, definition)]
title_before = str(work.title or "")
renamed = _refresh_title(db, work, definition, actor=actor, fields=shown)
# 「没有变化」要等标题对齐之后再判:那一格与标题本来就对不上的老单子,
# 这次交上来的值跟库里一模一样,仍然有名字要对齐这一件事可做。
if not changes and not renamed:
raise EngineError("表单内容没有变化")
summary = ";".join(f"{item['label']}:{item['before']} → {item['after']}" for item in changes[:8])
if len(changes) > 8:
summary += f";等 {len(changes)} 处"
if not changes and renamed:
summary = f"标题:{title_before} → {work.title}"
note = f"{(opinion or '').strip() or '管理员修正表单数据'}({summary})"
_event_log(db, work, _cursor_activity(work, definition), actor, note[:1000], LOG_DATA_FIX)
notify(
db,
[task.identity for task in _pending_tasks(db, work)] + [work.creator_identity],
type_=NOTIFY_CONTROL,
title=f"表单数据被修正:{work.title}",
body=f"{actor.person_name} 修正了《{work.title}》的表单内容。原因:{note[:300]}",
job=work.job, work=work.id, process=work.process, sender=actor.person_name,
)
db.flush()
return StepResult(work=work)
def press_work(db: Session, *, job: str, actor: Actor, opinion: str = "") -> StepResult:
"""整单催办:这一单上压着的每一条待办都催一遍。"""
work = _running_work(db, job)
tasks = _pending_tasks(db, work)
if not tasks:
raise EngineError("这张单据当前没有待办,无需催办")
for task in tasks:
press(db, task_id=task.id, actor=actor, opinion=opinion)
db.flush()
return StepResult(work=work, tasks=tasks)
def transfer_work(
db: Session, *, job: str, actor: Actor, identities: list[str], opinion: str = ""
) -> StepResult:
"""整单改派:当前每一条待办都换成指定的人来办。
逐条走 :func:`transfer`(管理员口径),所以每一环各自留一条改派痕迹;
会签环节上三条待办改成同一个人,就会并成三条同名待办——这是管理员的权力,
界面上会先把「要动几条」说清楚。
"""
work = _running_work(db, job)
tasks = _pending_tasks(db, work)
if not tasks:
raise EngineError("这张单据当前没有待办,无法改派")
if not org.resolve_identity_names(db, identities):
raise EngineError("请选择改派对象")
created: list[models.Task] = []
for task in tasks:
step = transfer(
db, task_id=task.id, actor=actor, identities=identities, opinion=opinion, admin=True
)
created.extend(step.tasks)
if work.paused:
for task in created:
task.pause = True
db.flush()
return StepResult(work=work, tasks=created)
# ---------------------------------------------------------------------------
# completion
# ---------------------------------------------------------------------------
def _finish_if_idle(
db: Session,
work: models.Work,
definition: ProcessDefinition,
result: StepResult,
actor: Actor | None,
) -> None:
"""No tokens and no pending tasks left -> the work is finished."""
pending = db.execute(
select(models.Task.id).where(models.Task.work == work.id)
).scalars().all()
waiting_join = any(
int(state.get("arrived") or 0) < tickets.join_required(state)
for state in (work.joins or {}).values()
)
if pending or work.tokens or waiting_join:
_sync_work_cursor(db, work, definition)
return
_finish_work(
db, work, definition, status="completed", result=result, actor=actor,
opinion="", activity=None,
)
result.completed = True
# ---------------------------------------------------------------------------
# 抄送 / 转发 / 分享 / 批注:不参与流转的协同动作
# ---------------------------------------------------------------------------
CC_WHENS = ("arrive", "complete")
READ_KINDS = ("cc", "share", "comment")
READ_TITLES = {
"cc": "抄送给您:{title}",
"share": "分享给您的流程:{title}",
"comment": "{sender} 在《{title}》中批注并提到了您",
}
def _subject(row) -> dict:
"""Work / WorkCompleted share most of the fields a 待阅 needs."""
return {
"id": row.id,
"job": getattr(row, "job", "") or "",
"title": getattr(row, "title", "") or "",
"process": getattr(row, "process", "") or "",
"process_name": getattr(row, "process_name", "") or "",
"category": getattr(row, "category", "") or "",
"serial": getattr(row, "serial", "") or "",
"creator_identity": getattr(row, "creator_identity", "") or "",
"creator_person": getattr(row, "creator_person", "") or "",
"activity": getattr(row, "activity", "") or "",
"activity_name": getattr(row, "activity_name", "") or "",
"current_activity_name": getattr(row, "current_activity_names", "") or getattr(row, "activity_name", "") or "",
"archived": isinstance(row, models.WorkCompleted),
}
def cc_rules(activity, when: str) -> list[dict]:
"""抄送规则挂在环节 config 上,``arrive`` 是到达时抄送,``complete`` 是办完后抄送。"""
if activity is None:
return []
out: list[dict] = []
for rule in (activity.config or {}).get("ccRules") or []:
if isinstance(rule, dict) and str(rule.get("when") or "arrive") == when:
out.append(rule)
return out
def cc_context(db: Session, work, actor: Actor | None, activity) -> dict:
"""抄送规则共用的求值上下文:条件表达式与抄送对象解析都吃这一份,口径不会两处各写一半。"""
return _context(
db,
work,
actor,
{
"activity": {"id": activity.id if activity else "", "name": activity.name if activity else ""},
# 抄送对象也可以是「上一环节处理人的上级」,所以同样带上上一环节。
"prev_task_identity_list": [t.identity for t in _recent_identities(db, work)],
},
)
def cc_rule_matches(context: dict, rule: dict) -> bool:
"""这条抄送规则现在该不该发;没设条件就是常态——无条件照抄。
条件算不出来按「不抄」处理:抄送是多给人一份信息,表达式写错时宁可少发一份,
也不要把不该知道这单的人扫进来(与条件免审的容错方向一致,只是后果更轻)。
"""
expression = str(rule.get("expression") or "").strip()
if not expression:
return True
try:
return bool(expressions.evaluate(expression, context))
except expressions.ExpressionError as exc:
logger.warning("抄送条件算不出来,按不抄送处理:%s(%s)", expression, exc)
return False
def cc_identities(
db: Session,
work,
actor: Actor | None,
rule: dict,
activity,
context: dict | None = None,
) -> list[str]:
"""抄送对象复用审批人解析器,所以支持部门/角色/群组/表单字段/上级等全部写法。"""
context = cc_context(db, work, actor, activity) if context is None else context
config = {
"taskValues": rule.get("taskValues") or [],
"taskScript": str(rule.get("taskScript") or ""),
}
return org.resolve_task_identities(db, work.process, config, context)
def _busy_identities(db: Session, work, activity_id: str = "") -> set[str]:
"""本环节**还在手上**的处理人不用再接一份抄送;别的环节照常抄。
只算在途待办:办结后的抄送("已审,请补充意见"这类)要能发给刚办完的人,
把历史处理人也一起排除掉,那条规则就永远发不出去。
"""
# 口径照旧:只算在途待办,``activity_id`` 为空就是"本张单所有环节的在途"。
# 行是从 ``_task_rows`` 那份里筛的,两问之间没有 oa_task 写入时就是零趟。
return {
row[0]
for row in _task_rows(db, work.id)
if row[2] == "pending" and (not activity_id or row[3] == activity_id)
}
def _refresh_read(
row: models.Read,
activity,
subject: dict,
actor: "Actor | None",
opinion: str,
requires_action: bool,
) -> None:
"""把已有的那条待阅更新成最新一次的内容(同单同类的再抄不新增行,见 :func:`create_reads`)。
来龙去脉跟着最新一次走,但 ``start_time`` 不动:待阅列表按送达时间排,
把老那条挪到最新会把「压在列表下面很久没人看」这件事洗掉。
已经要求本人填处理意见的那条不会被降级成普通待阅。
"""
row.activity = activity.id if activity is not None else subject["activity"]
row.activity_name = activity.name if activity is not None else subject["activity_name"]
row.current_activity_name = subject["current_activity_name"]
row.completed = bool(subject["archived"])
row.work_completed = subject["id"] if subject["archived"] else ""
row.sender = actor.person_name if actor else subject["creator_person"]
row.source_identity = actor.ref if actor else subject["creator_identity"]
if opinion:
row.opinion = opinion
row.requires_action = bool(row.requires_action or requires_action)
def create_reads(
db: Session,
subject,
*,
actor: Actor | None,
identities: list[str],
activity=None,
kind: str = "cc",
requires_action: bool = False,
opinion: str = "",
held: list[models.Read] | None = None,
) -> list[models.Read]:
"""生成待阅。``requires_action`` 为真时必须由本人填写处理意见,点开看不算处理完。
``held`` 是给 :func:`apply_activity_cc` 的省往返口子:调用方已经把这张单上的抄送件
读回来了,就别再问一遍(那一批行它判"这个环节抄过谁"也要用)。只在 ``kind="cc"``
时生效,其余类型照旧自己问库。
"""
if kind not in READ_KINDS:
raise EngineError(f"未知的待阅类型: {kind}")
subject = _subject(subject)
now = datetime.now()
skip = {actor.ref} if (actor and kind != "cc") else set()
# 一个人、一张单据、一类待阅,只留一条在待阅里。抄送规则常常挂在不同环节上
# (进入财务经理时抄一次、归档时再抄一次),一人多环节就会堆出「同一个单子两条一模一样」,
# 看的人分不清哪条是新的。再抄一次改成把已有那条更新成最新一次的内容。
if held is not None and kind == "cc":
pending = {row.identity: row for row in held if row.read_type == kind}
else:
pending = {
row.identity: row
for row in db.execute(
select(models.Read)
.where(
models.Read.work == subject["id"],
models.Read.read_type == kind,
models.Read.identity.in_([i for i in identities if i]),
)
)
.scalars()
.all()
}
created: list[models.Read] = []
fresh: list[models.Read] = []
seen: set[str] = set()
for identity in identities:
if not identity or identity in seen or identity in skip:
continue
seen.add(identity)
existing = pending.get(identity)
if existing is not None:
_refresh_read(existing, activity, subject, actor, opinion, requires_action)
created.append(existing)
continue
ref = org.ref_for(db, identity)
fresh.append(
models.Read(
job=subject["job"],
work=subject["id"],
work_completed=subject["id"] if subject["archived"] else "",
completed=subject["archived"],
title=subject["title"],
process=subject["process"],
process_name=subject["process_name"],
category=subject["category"],
serial=subject["serial"],
activity=activity.id if activity is not None else subject["activity"],
activity_name=activity.name if activity is not None else subject["activity_name"],
current_activity_name=subject["current_activity_name"],
person=ref.person,
identity=identity,
identity_name=ref.name,
unit=ref.unit,
sender=actor.person_name if actor else subject["creator_person"],
creator_identity=subject["creator_identity"],
source_identity=actor.ref if actor else subject["creator_identity"],
opinion=opinion,
read_type=kind,
requires_action=bool(requires_action),
start_time=now,
)
)
created.extend(fresh)
db.add_all(fresh)
db.flush()
if created:
sender = actor.person_name if actor else subject["creator_person"]
head = READ_TITLES[kind].format(title=subject["title"], sender=sender)
if kind == "cc" and requires_action:
head = f"需要您处理:{subject['title']}"
body = opinion or f"{sender} 将《{subject['title']}》{('抄送给您处理' if requires_action else '抄送给您') }。"
if kind == "share":
body = opinion or f"{sender} 将《{subject['title']}》分享给您可以查看。"
if kind == "comment":
body = opinion
notify(
db,
[row.identity for row in created],
type_="read",
title=head,
body=body,
job=subject["job"],
work=subject["id"],
process=subject["process"],
sender=sender,
)
return created
def apply_activity_cc(db: Session, work, activity, actor: Actor | None, when: str) -> list[models.Read]:
"""环节自动抄送:到达、办完、办结(挂在结束环节上)都会走这里。
每条规则可以先设一个条件(与分支条件、条件免审同一套表达式),命中才抄这一条;
没设条件的规则照旧到点就抄,老流程的抄送行为不受影响。
"""
rules = cc_rules(activity, when)
if not rules:
return []
context = cc_context(db, work, actor, activity)
rules = [rule for rule in rules if cc_rule_matches(context, rule)]
if not rules:
return []
busy = _busy_identities(db, work, activity.id)
# 这张单上现有的抄送一次读回来:判"这个环节已经抄过谁"(下面那个 already)与
# create_reads 判"这个人手上已经有一条待阅"用的是同一批行,以前每条规则各问两遍
# ——R 条抄送规则就是 2R 趟,而一个环节上挂好几条规则是常事。
# 一次读回来 == 每条规则各问一次:这一趟到下一趟之间没人 flush(autoflush 关着),
# 库里的答案根本不会变。already 按刚读回来那一刻的 (人, 环节) 算,与"每条规则现问
# 一遍库"逐字相同——即便中途 create_reads 把某条待阅挪到了本环节,也不改变判定。
held: list[models.Read] | None = None
already: set[str] = set()
created: list[models.Read] = []
for rule in rules:
targets = [i for i in cc_identities(db, work, actor, rule, activity, context) if i not in busy]
if not targets:
continue
if held is None: # 真的要抄人了才问库:一条都没得抄时一趟都不许多付
held = list(db.execute(
select(models.Read).where(models.Read.work == work.id, models.Read.read_type == "cc")
).scalars().all())
already = {row.identity for row in held if row.activity == activity.id}
targets = [i for i in targets if i not in already]
busy.update(targets)
created.extend(
create_reads(
db,
work,
actor=actor,
identities=targets,
activity=activity,
kind="cc",
requires_action=bool(rule.get("requiresAction")),
opinion=str(rule.get("opinion") or ""),
held=held,
)
)
return created
def cc_task(db: Session, *, task_id: str, actor: Actor, identities: list[str], opinion: str = "", requires_action: bool = False) -> list[models.Read]:
"""抄送/转发当前待办:待办还在我手上,只是给别人一份。"""
task = get_task(db, task_id, actor)
work = db.execute(select(models.Work).where(models.Work.id == task.work)).scalar_one_or_none()
if work is None:
raise EngineError("单据不存在或已被删除")
definition = definition_module.for_work(db, work)
activity = definition.activity(task.activity)
if activity is not None and not bool(activity.config.get("allowCc", True)):
raise EngineError(f"环节 {activity.name} 不允许抄送")
resolved = org.resolve_identity_names(db, identities)
if not resolved:
raise EngineError("请选择抄送对象")
return create_reads(
db,
work,
actor=actor,
identities=resolved,
activity=activity,
kind="cc",
requires_action=requires_action,
opinion=opinion,
)
def share_work(db: Session, *, work_id: str, actor: Actor, identities: list[str], opinion: str = "") -> list[models.Read]:
"""分享:把单子发给别人看,不改变流转,也不要求对方处理。"""
work = db.execute(select(models.Work).where(models.Work.id == work_id)).scalar_one_or_none()
subject = work
if subject is None:
subject = db.get(models.WorkCompleted, work_id)
if subject is None:
raise EngineError("单据不存在或已被删除")
if work is not None:
definition = definition_module.for_work(db, work)
activity = definition.activity(work.activity)
if activity is not None and not bool(activity.config.get("allowShare", True)):
raise EngineError(f"环节 {activity.name} 不允许分享")
resolved = org.resolve_identity_names(db, identities)
if not resolved:
raise EngineError("请选择分享对象")
return create_reads(
db,
subject,
actor=actor,
identities=resolved,
activity=definition_module.ActivityNode(id=subject.activity, type=ACTIVITY_MANUAL, name=subject.activity_name) if work is not None else None,
kind="share",
requires_action=False,
opinion=opinion,
)
def _comment_blocker(activity) -> str:
"""环节那一格「允许批注」关掉了就回挡下的那句原话,没关(或认不出环节)回空串。"""
if activity is None or bool((activity.config or {}).get("allowComment", True)):
return ""
return f"环节 {activity.name} 不允许批注"
def comment_activity(db: Session, subject):
"""这一单"此刻停在那一环"的定义行;认不出来就回 ``None``。
在途件认 ``oa_work.activity``——就是当前压着没办的那一环,与界面上那份环节简报同源。
**归档件没有这一格可判**:``oa_work_completed`` 压根不落 ``activity``(单子已经走完,
"当前环节"对它没有意义;办结抄送用的那一环是 :func:`_finish_work` 当场拿到的参数,
没有存进归档行)。所以归档件走的是"认不出环节 → 放行"这一支,不是漏判:
设计器里那格「允许批注」管的是这一环还压在人手上时能不能补话,一张已经落定的单子
上没有这样一环。设计整个被删掉时同样回 ``None`` 放行——一句补充批注不该因为
图纸没了而发不出去,与 :func:`definition.for_work` 对老单的回退一个脾气。
"""
try:
definition = definition_module.for_work(db, subject)
except (ValueError, EngineError):
return None
return definition.activity(str(getattr(subject, "activity", "") or ""))
def comment_blocker(db: Session, subject) -> str:
"""在这张单上补批注会不会被挡、被什么挡。在途与归档走同一条判据。"""
return _comment_blocker(comment_activity(db, subject))
def list_comments(db: Session, work_id: str) -> list[models.WorkComment]:
rows = db.execute(
select(models.WorkComment).where(models.WorkComment.work == work_id).order_by(models.WorkComment.order_number)
).scalars().all()
return list(rows)
def add_comment(
db: Session,
*,
work_id: str,
actor: Actor,
content: str,
mentions: list[str] | None = None,
mention_action: bool = False,
#: 随批注一起发出的附件 id:截图、贴图、Word、Excel 都算
attachments: list[str] | None = None,
) -> models.WorkComment:
"""批注:补充说明,可以 @ 相关人;被 @ 的人收到待阅提醒。"""
text = (content or "").strip()
ids = [str(item) for item in (attachments or []) if str(item or "")]
if not text and not ids:
# 只贴一张截图也是有效批注,比如"看这个红框里的数字对不对"
raise EngineError("请先写点内容,或附上图片/文件")
work = db.execute(select(models.Work).where(models.Work.id == work_id)).scalar_one_or_none()
subject = work or db.get(models.WorkCompleted, work_id)
if subject is None:
raise EngineError("单据不存在或已被删除")
activity = None
if work is not None:
definition = definition_module.for_work(db, work)
activity = definition.activity(work.activity)
# 归档件也过同一道闸:以前只在途上判,办结之后那格「允许批注」等于失效,
# 关掉了照样能往里发批注。判据只有一处(``_comment_blocker``),界面与引擎同一句话。
blocker = _comment_blocker(activity if activity is not None else comment_activity(db, subject))
if blocker:
raise EngineError(blocker)
resolved = org.resolve_identity_names(db, mentions or [])
order = len(list_comments(db, work_id))
comment = models.WorkComment(
job=getattr(subject, "job", "") or "",
work=subject.id,
work_completed=subject.id if work is None else "",
completed=work is None,
process=getattr(subject, "process", "") or "",
process_name=getattr(subject, "process_name", "") or "",
title=getattr(subject, "title", "") or "",
activity=activity.id if activity is not None else getattr(subject, "activity", "") or "",
activity_name=activity.name if activity is not None else getattr(subject, "activity_name", "") or "",
person=actor.person_id,
identity=actor.ref,
identity_name=actor.person_name,
unit=actor.unit,
content=text[:4000],
mentions=list(resolved),
mention_names=[org.ref_for(db, i).name for i in resolved],
mention_action=bool(mention_action),
order_number=order,
)
db.add(comment)
db.flush()
comment.attachments = claim_attachments(
db,
ids=ids,
actor=actor,
kind=ATTACHMENT_COMMENT,
owner_id=comment.id,
# 在途认 oa_work,归档认 oa_work_completed:两种都要把附件行落到这一单上
work=work if work is not None else subject,
activity_id=comment.activity,
activity_name=comment.activity_name,
)
db.flush()
if resolved:
create_reads(
db,
subject,
actor=actor,
identities=resolved,
activity=activity,
kind="comment",
requires_action=mention_action,
# 只贴了图的批注也要有句话可看,不然被 @ 的人收到的待阅是一片空白
opinion=(text or f"(发来 {len(comment.attachments)} 个图片/文件)")[:500],
)
return comment
def remove_comment(db: Session, *, comment_id: str, actor: Actor) -> None:
row = db.get(models.WorkComment, comment_id)
if row is None:
raise EngineError("批注不存在")
if not actor.is_admin and row.identity != actor.ref:
raise EngineError("只能删除本人的批注")
release_attachments(db, list(row.attachments or []), row.id)
db.delete(row)
db.flush()
def get_read(db: Session, read_id: str, actor: Actor) -> models.Read:
row = db.get(models.Read, read_id)
if row is None:
raise EngineError("待阅不存在")
if not actor.is_admin and row.identity != actor.ref:
raise EngineError("该待阅不属于当前身份")
return row
def mark_read(
db: Session,
*,
read_id: str,
actor: Actor,
opinion: str = "",
handling: bool = False,
attachments: list[str] | None = None,
) -> models.ReadCompleted:
"""已阅登记。带 ``requires_action`` 的待阅必须走处理确认(``handling=True``)并留下处理意见。
``handling`` 那一趟还能带上图片或文件(``attachments`` 是前端先传好的附件 id),
与批注同一套认领口径:处理「抄送需处理」的人可以贴一张截图说清情况。
"""
row = get_read(db, read_id, actor)
now = datetime.now()
ids = [str(item) for item in (attachments or []) if str(item or "")]
if ids and not handling:
raise EngineError("填写处理意见时才能附上图片或文件")
if row.requires_action and handling:
if not (opinion or "").strip():
raise EngineError("请填写处理意见")
row.handle_time = now
elif row.requires_action:
raise EngineError("该待阅需要处理,请填写处理意见后确认")
if not row.view_time:
row.view_time = now
if opinion and not row.opinion:
row.opinion = opinion
archived = bool(row.completed)
done = models.ReadCompleted(
read=row.id,
job=row.job,
work=row.work,
work_completed=row.work_completed,
completed=archived,
title=row.title,
process=row.process,
process_name=row.process_name,
category=row.category,
serial=row.serial,
activity=row.activity,
activity_name=row.activity_name,
person=row.person,
identity=row.identity,
identity_name=row.identity_name,
unit=row.unit,
sender=row.sender,
creator_identity=row.creator_identity,
opinion=row.opinion,
read_type=row.read_type,
requires_action=row.requires_action,
attachments=list(row.attachments or []),
source_identity=row.source_identity,
handle_time=row.handle_time,
start_time=row.start_time,
view_time=row.view_time,
)
db.add(done)
db.delete(row)
db.flush()
if ids:
# 归属认到这条已阅记录上,附件行同时认到这一单(归档件也在里面)
subject = db.get(models.WorkCompleted, row.work_completed or row.work) if archived \
else db.get(models.Work, row.work)
done.attachments = claim_attachments(
db,
ids=ids,
actor=actor,
kind=ATTACHMENT_READ,
owner_id=done.id,
work=subject,
activity_id=row.activity,
activity_name=row.activity_name,
)
db.flush()
return done
def mark_reads_for_work(db: Session, *, job: str, actor: Actor) -> list[models.ReadCompleted]:
"""打开这一单的单据页就算已阅:把我在这一单上不要求处理的待阅一次登记完。
抄送有两条入口摆在界面上(首页待办中心的待阅、右上角通知),两边都各自记得调
「标记已阅」迟早会漏一条,干脆把口径收在打开单据这一处:人已经在看这张单子了。
要求填处理意见的那类不动,那种得本人写明意见才算处理完(见 :func:`mark_read`)。
"""
rows = db.execute(
select(models.Read)
.where(
models.Read.job == job,
models.Read.identity == actor.ref,
models.Read.requires_action.is_(False),
)
.order_by(models.Read.start_time)
).scalars().all()
return [mark_read(db, read_id=row.id, actor=actor) for row in rows]
def _invalidate_node_decisions(db: Session, work_id: str, status: str) -> None:
"""这一单落定后,``oa_node_decision`` 里还停着的表态就地作废(同一事务)。"""
try:
from ..service import node_approve
node_approve.invalidate_for_work(db, work_id, status)
except Exception: # noqa: BLE001 - 表态作废是收尾,不该拦归档
pass
def _finish_work(
db: Session,
work: models.Work,
definition: ProcessDefinition,
*,
status: str,
result: StepResult,
actor: Actor | None,
opinion: str,
activity,
) -> StepResult:
now = datetime.now()
# 从同一份已办清单里挑:办结时间从新到旧的第一条「正常办结」(口径见 _completed_rows)
latest = next(
(row for row in _completed_rows(db, work.id) if row.processing_type == "normal"), None
)
archived = models.WorkCompleted(
id=work.id,
job=work.job,
serial=work.serial,
title=work.title,
status=status,
process=work.process,
process_name=work.process_name,
process_alias=work.process_alias,
category=work.category,
category_name=work.category_name,
form=work.form,
# 冻结设计跟着单据一起归档:这张单在界面上呈现的那一版图,从发起到归档都是同一份
design_snapshot=work.design_snapshot,
data=dict(work.data or {}),
creator=work.creator,
creator_person=work.creator_person,
creator_identity=work.creator_identity,
creator_identity_name=work.creator_identity_name,
creator_unit=work.creator_unit,
creator_unit_name=work.creator_unit_name,
result={"completed": "agree", "terminated": "terminated", "canceled": "canceled"}.get(status, status),
result_opinion=opinion or (latest.opinion if latest else ""),
current_activity_names=activity.name if activity else work.current_activity_names,
start_time=work.start_time,
finish_time=now,
expire_time=work.expire_time,
work_create_type=work.work_create_type,
parent_work=work.parent_work,
)
db.merge(archived)
# 单据落定(办结 / 终止 / 作废)那一刻,还停在「等处理人点头」的外部表态一并作废:
# 单都归档了,审批页再亮着那条横幅就是死人说话。留痕记的是为什么作废,不是谁点的。
_invalidate_node_decisions(db, work.id, status)
db.execute(
update(models.TaskCompleted)
.where(models.TaskCompleted.work == work.id)
.values(work_completed=work.id, completed=True, current_activity_name=archived.current_activity_names)
)
db.execute(
update(models.WorkLog)
.where(models.WorkLog.work == work.id)
.values(work_completed=work.id, completed=True)
)
db.execute(
update(models.Attachment)
.where(models.Attachment.work == work.id)
.values(completed=True, work_completed=work.id)
)
# 额度进终态:办结把在途占用转成核销(可用额度不变,变的是钱的性质),
# 终止与作废把占用还回去;由单据生成的额度(备用金)在办结这一刻长出来。
# 必须在 ``db.delete(work)`` 之前——归档之后 oa_work 那行就没了。
if status == "completed":
quota.settle_work(db, work, actor=actor, activity=activity)
quota.issue_from_work(db, work, actor=actor, activity=activity)
else:
quota.release_work(db, work, actor=actor, activity=activity,
reason="单据终止,释放占用" if status == "terminated" else "单据作废,释放占用")
# 写回业务系统:与上面额度、下面归档搬运同一事务。放在 ``db.delete(work)`` 之前是因为
# 报文要在这一刻用 work.data 渲染并快照进发件箱——归档之后 oa_work 那行就没了。
# 渲染失败不往外抛:审批人不该被集成配置写错卡在页面上,落一条死信让集成页喊人。
if status in models.Integration.TERMINAL_EVENTS:
# 事件订阅:与写回同一时刻、同一事务。放在 ``db.delete(work)`` 之前是硬要求——
# 归档之后 oa_work 那行就没了,快照只能在这一刻抄。
events.emit(db, work, f"work.{status}",
activity_name=getattr(work, "activity_name", "") or "",
actor_name=getattr(actor, "person_name", "") or "系统")
outbox.enqueue_event(db, work, status, actor=actor)
# 终止还有流程自己那一格:终止不是画布上的环节,挂不到任何一环上,
# 「这一条流程被终止时另外通知一声」只能配在流程上(service/terminate.py)。
if status == "terminated":
outbox.enqueue_terminate(
db, work, terminate_service.writeback_mount(terminate_service.config_of(definition)),
actor=actor,
)
# 终止/作废还要处理"上游已经有一张凭证了":配了冲销模板就自动发反向消息,
# 没配就只在原消息上挂一个人工待处理标记,机器不猜该不该作废(§6)
outbox.handle_reversal(db, work, status, actor=actor)
reads = db.execute(select(models.Read).where(models.Read.work == work.id)).scalars().all()
for read in reads:
if not read.view_time:
# 压根没打开过的待阅不搬进已阅档。``oa_read_completed.view_time`` 是 NOT NULL,
# 搬过去就得替人编一个「已阅时间」,等于把没看过的事记成看完了,档案里再也
# 分不出「看过」和「没打开」,勾了「需处理」的抄送还会被悄悄勾掉。让它留在
# 待阅里等本人来读,待遇与下面办结环节现抄的抄送件一致:只打归档标记,行不动。
read.completed = True
read.work_completed = work.id
continue
db.add(
models.ReadCompleted(
read=read.id,
job=read.job,
work=read.work,
work_completed=work.id,
completed=True,
title=read.title,
process=read.process,
process_name=read.process_name,
category=read.category,
serial=read.serial,
activity=read.activity,
activity_name=read.activity_name,
person=read.person,
identity=read.identity,
identity_name=read.identity_name,
unit=read.unit,
sender=read.sender,
creator_identity=read.creator_identity,
opinion=read.opinion,
read_type=read.read_type,
requires_action=read.requires_action,
# 处理意见随附的图片/文件跟着那条待阅一起搬档,不然办结之后回看只剩一段文字
attachments=list(read.attachments or []),
source_identity=read.source_identity,
handle_time=read.handle_time,
start_time=read.start_time,
# 能走到这儿说明本人真的打开过:view_time 是 mark_read 落的真实时间
view_time=read.view_time,
)
)
db.delete(read)
# 办结抄送排在归档搬运之后,收件人的待阅列表里才看得到这条
for read in apply_activity_cc(db, work, activity, actor, "arrive"):
read.completed = True
read.work_completed = work.id
notify(
db,
[work.creator_identity],
type_="completed",
title=f"流程已办结:{work.title}",
body=f"《{work.title}》已{('办结' if status == 'completed' else '终止')}。",
job=work.job,
work=work.id,
process=work.process,
sender="系统",
)
parent_job = work.parent_job
child_job = work.job
owner = Actor(person_id=work.creator, person_name=work.creator_person, ref=work.creator_identity)
# 实例都归档了,还挂在 oa_task 里的待办就是幽灵:列表里点不开,也永远清不掉。
db.execute(delete(models.Task).where(models.Task.work == work.id))
embed_children = list(db.execute(
select(models.Work.job).where(models.Work.parent_job == child_job, models.Work.status == "running")
).scalars())
db.delete(work)
db.flush()
result.completed = True
result.status = status
result.work_id = work.id
result.work_job = child_job
result.work = None
result.notices.append(f"work {child_job} {status}")
if parent_job:
resume_embed_parent(db, parent_job, child_job)
# 嵌入子流程是独立实例,父单走了它们不会自己消失,界面上就留下"父单已归档、
# 子单还在等人办"的孤儿待办。父单不管是因为办结、作废还是终止走的,都带上它们。
cascade_actor = actor or owner
for orphan in embed_children:
try:
terminate(db, job=orphan, actor=cascade_actor,
opinion=f"父流程已{('办结' if status == 'completed' else '终止')},子流程一并终止",
enforce_starter_config=False)
except EngineError:
logger.exception("嵌入子流程 %s 未能随父单收尾", orphan)
return result
# ---------------------------------------------------------------------------
# bookkeeping helpers
# ---------------------------------------------------------------------------
def _sync_work_cursor(db: Session, work: models.Work, definition: ProcessDefinition) -> None:
"""Keep ``work.activity*`` + the current handler text in sync with tokens."""
tokens = list(work.tokens or [])
if not tokens:
return
last = tokens[-1]
node = definition.activity(last.get("activity", ""))
if node is not None:
work.activity = node.id
work.activity_name = node.name
work.activity_type = node.type
work.activity_token = last.get("path", "")
# 同一批行还挡着抄送去重(``_busy_identities``),所以走那个共享装载器
identities = _task_rows(db, work.id)
work.manual_identity_list = [row[0] for row in identities]
# manual_identity_text 是给"干预订单"那一屏看的人名清单:列上存了姓名就用,
# 没存到的(老数据、脚本插的)按引用批量补一次,别在循环里逐条问库
missing = sorted({str(row[0]) for row in identities if not row[1] and row[0]})
named = {key: ref.name for key, ref in org.refs_for(db, missing).items()}
work.manual_identity_text = ",".join(
dict.fromkeys(row[1] or named.get(str(row[0]), str(row[0])) for row in identities)
)
names = ",".join(
dict.fromkeys(
definition.activity(t.get("activity", "")).name
for t in tokens
if definition.activity(t.get("activity", "")) is not None
)
)
if names != work.current_activity_names:
# 待阅行上那份「当前环节」是抄送那一刻抄下来的快照,只有再抄一次或归档才动。
# 于是「这张单停在哪个环节」这一列会在每一次前进之后慢慢说谎——改道把它摆得
# 格外显眼而已。挂在游标这一句里而不是挂在改道里:每一次前进都该刷。
# 只刷没读的那批:已阅是历史快照,那个人当时看到的就是那一句。
db.execute(
update(models.Read)
.where(models.Read.work == work.id, models.Read.completed.is_(False))
.values(current_activity_name=names)
)
work.current_activity_names = names
def _jump_redirect(db: Session, work: models.Work, definition: ProcessDefinition, target):
"""「直返本环节」的落地:这一环只是补正后重走上来的路过点就直接跳过。
退回时选了「直返本环节」,意思是「单据改完不用再一环一环重新审,回到我这来」。
这份约定从前只写进 ``go_back_store``,谁来读它的人一个也没有,于是那个选项点了
等于没点。这里补上读的一侧:还在回退点到退回环节之间的路上,中间环节一律跳过;
一旦走到退回环节本身、或者已经偏出这条回程路线,就把约定清掉。
"""
store = dict(work.go_back_store or {})
origin_id = str(store.get("origin_activity") or "")
if not origin_id or target is None:
return None
origin = definition.activity(origin_id)
if origin is None:
work.go_back_store = {}
return None
if target.id == origin_id:
work.go_back_store = {}
return None
on_the_way_back = target.id in upstream_activities(definition, origin_id)
from_fallback_point = any(
target.id == start or target.id in downstream_activities(definition, start)
for start in (store.get("targets") or [])
)
if on_the_way_back and from_fallback_point:
return origin
work.go_back_store = {}
return None
#: 本次事务里为每张单写过的最后一条流转留痕的到达时间:``{work.id: arrived_time}``。
_LAST_LOG_TIME = "engine.last_log_time"
def _whole_second(value):
"""按 ``datetime`` 列(整秒)在库里会变成什么值来算:MySQL 是四舍五入,不是截断。
留在内存里的那份带着微秒,库里存的是整秒,直接拿来当"上一条留痕的时间"会让
下一跳的 ``from_time`` 与上一条留痕自己落库的那一毫秒对不上,差出一秒。所以留在
Session 上之前先按库的口径化一遍。
"""
if value is None or not value.microsecond:
return value
rounded = value.replace(microsecond=0)
if value.microsecond >= 500_000:
rounded += timedelta(seconds=1)
return rounded
@event.listens_for(Session, "after_flush")
def _remember_log_time(session: Session, flush_context) -> None:
"""本次事务写过的留痕,把到达时间留在 Session 上,省掉下一条的回库捞。"""
for obj in session.new:
if isinstance(obj, models.WorkLog) and obj.work:
session.info.setdefault(_LAST_LOG_TIME, {})[str(obj.work)] = _whole_second(obj.arrived_time)
@event.listens_for(Session, "after_begin")
def _forget_log_time(session: Session, transaction, connection) -> None:
"""换了事务就忘掉:新事务的快照看得到这期间别人写的留痕,内存里那份不作数。"""
session.info.pop(_LAST_LOG_TIME, None)
def _previous_log_time(db: Session, work: models.Work):
"""这张单"上一条流转留痕"的到达时间,只为填下一跳的 ``from_time``。
一次审批里 ``_log`` 要跑五趟(每个流转一条),每趟都问一遍"上一条留痕是哪条",
而上一条几乎总是本次请求自己刚刚写下的那一条。留痕经 ``after_flush`` 留在 Session 上,
本事务写过的每一条都在里面;库跑在 REPEATABLE READ 上,本次事务本来就看不见别的事务
在这之间提交的新行,所以这份内存里的"最后一条"与再问一趟库是同一个答案。
本次事务还没写过这张单的留痕时照旧问库(只取 ``arrived_time`` 那一列)。
"""
memo = db.info.get(_LAST_LOG_TIME)
if memo:
stored = memo.get(str(work.id))
if stored is not None:
return stored
last = db.execute(
select(models.WorkLog.arrived_time)
.where(models.WorkLog.work == work.id)
.order_by(models.WorkLog.arrived_time.desc())
.limit(1)
).scalar_one_or_none()
return last if last is not None else work.start_time
def _log(
db: Session,
work: models.Work,
definition: ProcessDefinition,
*,
from_activity,
to_activity,
route: definition_module.RouteNode | None,
actor: Actor | None,
opinion: str,
token: dict | None,
log_type: str = "normal",
split_value: str = "",
) -> models.WorkLog:
now = datetime.now()
previous_time = _previous_log_time(db, work)
row = models.WorkLog(
job=work.job,
work=work.id,
completed=False,
process=work.process,
process_name=work.process_name,
from_activity=from_activity.id if from_activity else "",
from_activity_name=from_activity.name if from_activity else "",
from_activity_type=from_activity.type if from_activity else "",
from_activity_token=(token or {}).get("path", ""),
from_identity=actor.ref if actor else work.creator_identity,
from_identity_name=(actor.person_name if actor else work.creator_identity_name),
from_person_name=(actor.person_name if actor else work.creator_person),
from_opinion=opinion,
from_time=previous_time,
arrived_activity=to_activity.id,
arrived_activity_name=to_activity.name,
arrived_activity_type=to_activity.type,
arrived_activity_token=(token or {}).get("path", to_activity.id),
arrived_time=now,
route=route.id if route else "",
route_name=route.name if route else "",
type=log_type,
connected=bool(route),
split_value=split_value,
split_token=(token or {}).get("split_value", ""),
)
db.add(row)
# 只刷这一条留痕,别把 Session 里顺带脏掉的单据行一起刷出去:调用处往往先改了
# ``tokens`` / ``manual_identity_list`` 再落留痕,``db.flush()`` 会把它们提前写成
# 一条 ``UPDATE oa_work``,紧接着游标那一写又把**同样的那几列**再写一遍——前一条
# 的内容被后一条整个盖掉,纯属白排一次队(2026-10 逐条对语句量出来的)。
# 这里必须留一次 flush:同一个请求里后面还要按留痕找"上一环节"(``_recent_identities``
# 那类),autoflush 是关着的,不刷出去它们就读到本次之前那一份。
# 只刷传入对象是安全的:``oa_work_log.work`` 是普通列加索引,没有外键,
# 发起那一趟即使 ``oa_work`` 还是待插入的新行也不会撞约束。
db.flush([row])
return row
def wake_delays(db: Session, limit: int = 50) -> int:
"""Scheduler entry: release parked delay activities whose time has come.
一条延时只能被捞起来一次:整表扫完后统一提交等于把认领窗口开到整个扫描期间,
多起一个进程(或多开一个 worker)就会有两个调度器同时看到同一条到期 token,
各派发一遍——实测一张单子被同一条延时唤起了 3 次、开出 3 个子流程。
所以改成按单加锁认领:锁不到(别人在办)就跳过,锁到了再复核一次是否真到期,
并且一张单一个事务,token 一落库就算认领完成。
"""
now = datetime.now()
woken = 0
candidates = db.execute(
select(models.Work.job)
.where(models.Work.status == "running")
# 挂起中的单据连延时都不醒:干预期间整条路是冻住的,醒过来也只会开出一批办不动的待办
.where(models.Work.paused.is_(False))
.where(cast(models.Work.tokens, String).like("%wake_time%"))
.limit(500)
).scalars().all()
for job in candidates:
work = db.execute(
select(models.Work).where(models.Work.job == job).with_for_update(skip_locked=True)
).scalar_one_or_none()
if work is None:
continue
due = [t for t in (work.tokens or []) if t.get("wake_time") and str(t["wake_time"]) <= now.isoformat()]
if not due:
db.rollback()
continue
try:
definition = definition_module.for_work(db, work)
for token in due:
work.tokens = [t for t in work.tokens if t.get("id") != token.get("id")]
activity = definition.activity(token.get("activity", ""))
if activity is None:
continue
_advance(
db,
work,
definition,
from_activity=activity.id,
route=_single_route(definition, activity),
actor=Actor(
person_id=work.creator, person_name=work.creator_person,
ref=work.creator_identity,
),
opinion="延时到期自动流转",
token=token,
log_type="delay",
)
woken += 1
db.commit()
except Exception:
# 一张单起不来(子流程必填没凑齐、脚本抛错…)只算它自己的事:
# 回滚这一单的认领,让下一轮还能重试,别把后面几百条延时一起拖死。
db.rollback()
logger.exception("延时唤醒失败,本单留到下一轮重试: %s", job)
if woken >= limit:
return woken
return woken
TIMEOUT_ACTIONS = {"notify", "autoPass", "autoReject"}
def _actor_of(db: Session, task: models.Task) -> Actor:
"""超时自动处理以「环节处理人自己」的身份落账,流转日志里看不出是定时器点的。"""
return Actor(
person_id=task.person or task.creator,
person_name=task.identity_name or task.person or "系统",
ref=task.identity,
unit=task.unit,
unit_name=task.unit_name,
is_admin=False,
)
def _timeout_route(definition: ProcessDefinition, activity, action: str, preferred: str) -> str:
"""挑一条超时要走的路由:优先环节上指定的,否则正向取第一条非退回路由,
反向取第一条退回路由;挑不出来就什么也不做(宁可停着等人,不要瞎走)。"""
if preferred:
return preferred
routes = definition.routes_from(activity.id)
if action == "autoReject":
for item in routes:
if item.decision == "goBack":
return item.name
return ""
for item in routes:
if item.decision != "goBack":
return item.name
return ""
def mark_expired(db: Session) -> int:
"""Scheduler entry: flag overdue todos, then run the overdue action of each step.
环节上的 ``timeoutAction`` 取值:``notify``(默认,只提醒)、``autoPass``(超时
自动通过)、``autoReject``(超时自动退回)。自动动作先把到期标记落库再执行,
避免同一条待办被下一轮定时器重复处理。
锁上的那一环**不代办**:让定时器绕过自己的锁去表态,等于把刚关上的那扇门从后面
踹开——第三方还在等这一环的结论,OA 却自己把它办掉了。超时照常计时,只是改成给
处理人与管理员各发一条待阅,说清「这一环的审批已交给 X,超时不自动办」。
"""
from ..service import node_approve
now = datetime.now()
rows = db.execute(
select(models.Task).where(
models.Task.expired.is_(False),
models.Task.expire_time.isnot(None),
models.Task.expire_time < now,
# 挂起期间不计时:待办跟着单据一起冻住,恢复时 :func:`resume` 会把时限整体往后挪
models.Task.pause.is_(False),
)
).scalars().all()
pending: list[tuple[str, str, str, str]] = []
for task in rows:
task.expired = True
notify(
db,
[task.identity],
type_="expire",
title=f"待办已超时:{task.title}",
body=f"【{task.activity_name}】环节的待办已超过处理时限。",
job=task.job,
work=task.work,
task=task.id,
process=task.process,
sender="系统",
)
# 事件订阅:超时。带上了到达时间与已等时长,订阅方可以直接排一条"催办"任务
expired_work = db.get(models.Work, task.work)
if expired_work is not None:
events.emit(db, expired_work, "work.overdue", activity_name=task.activity_name,
actor_name="系统",
extra={
"identity": task.identity,
"arrivedAt": task.start_time.strftime("%Y-%m-%d %H:%M:%S") if task.start_time else "",
"dueAt": task.expire_time.strftime("%Y-%m-%d %H:%M:%S") if task.expire_time else "",
"waitedMinutes": int((now - task.start_time).total_seconds() // 60) if task.start_time else 0,
})
try:
definition = definition_module.for_work(db, task)
except ValueError:
continue
activity = definition.activity(task.activity)
if activity is None:
continue
config = dict(activity.config or {})
action = str(config.get("timeoutAction") or "notify")
if action not in TIMEOUT_ACTIONS or action == "notify":
continue
locked = node_approve.check(
db, task.process, activity,
action="goBack" if action == "autoReject" else "handle",
process=definition,
)
if locked:
notify(
db, [ref for ref in [task.identity, _fallback_admin_ref(db)] if ref],
type_="expire", title=f"待办已超时(这一环在外部系统审批):{task.title}",
body=f"【{activity.name}】已超过处理时限。{locked}",
job=task.job, work=task.work, task=task.id, process=task.process,
sender="系统",
)
continue
pending.append((task.id, task.identity, action, _timeout_route(
definition, activity, action, str(config.get("timeoutRoute") or "")
)))
db.commit()
for task_id, identity, action, route_name in pending:
task = db.get(models.Task, task_id)
if task is None:
continue
if not route_name:
notify(
db, [identity], type_="expire", title=f"待办超时且无法自动流转:{task.title}",
body="该环节配置了超时自动处理,但没有可用的流转路由,请人工处理。",
job=task.job, work=task.work, task=task.id, process=task.process, sender="系统",
)
continue
actor = _actor_of(db, task)
opinion = "超时自动通过" if action == "autoPass" else "超时自动退回"
try:
if action == "autoReject":
definition = definition_module.for_work(db, task)
# 只在本环节的出口里找:整条流程里叫「退回」的路由往往不止一条,
# 全流程按名字捞会把单子退到别的环节去。
picked = definition.find_route(task.activity, route_name) if route_name else None
go_back(
db, task_id=task_id, actor=actor,
target=picked.to_activity if picked is not None else "",
opinion=opinion,
route_name=picked.name if picked is not None else "",
route_alias=picked.alias if picked is not None else "",
)
else:
execute_task(
db, task_id=task_id, actor=actor, route_name=route_name,
opinion=opinion, data={},
)
db.commit()
except EngineError as exc:
db.rollback()
logger.warning("timeout action %s failed on task %s: %s", action, task_id, exc)
notify(
db, [identity], type_="expire", title=f"待办超时自动处理失败:{task.title}",
body=f"{opinion} 没有执行成功:{exc}。请人工处理这条待办。",
job=task.job, work=task.work, task=task.id, process=task.process, sender="系统",
)
db.commit()
return len(rows)