unis-oa/backend/app/api/runtime.py

3107 lines
145 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.

"""Run time endpoints: job / work / task / task completed / read / work log."""
from __future__ import annotations
import logging
import time
from collections.abc import Callable
from datetime import datetime, timedelta
from fastapi import APIRouter, Depends, Query, Request
from sqlalchemy import and_, func, literal, or_, select
from sqlalchemy.exc import OperationalError
from sqlalchemy.orm import Session, defer
from .. import models, parallel, permissions, schemas, serializers
from ..db import get_db
from ..deps import CurrentUser, actor_of, client_ip, current_user, require_permission
from ..service import autofill, completed as completed_service, dicts, flowmap, formruntime, numbering
from ..service import outbox, personref, starters, terminate as terminate_service, titles
from ..service import embed_session, external_check, gate, linkfill, node_approve, org
from ..engine import definition as definition_module
from ..engine import engine
from ..envelope import bad_request, forbidden, not_found, ok
from ..query import count_of, tri_state
router = APIRouter(tags=["runtime"])
logger = logging.getLogger("unisoa.runtime")
#: 一次批量审批的条数上限。批量是为了省事,不是为了绕开界面逐条确认,
#: 上限既能挡住误选全表,也让一次请求的耗时可控。
BATCH_LIMIT = 50
#: InnoDB 的死锁错误号,MySQL 自己的提示就是"try restarting transaction"。
DEADLOCK_ERRNO = 1213
#: 撞上死锁之后最多再试几次(含首次)。
DEADLOCK_ATTEMPTS = 3
def _log_operation(db: Session, user: CurrentUser, action: str, target: str, detail: str, request: Request | None) -> None:
db.add(
models.OperationLog(
action=action,
target=target,
detail=detail,
person=user.person_id,
person_name=user.display_name,
identity=user.ref,
ip=client_ip(request) if request else "",
)
)
def _actor(user: CurrentUser) -> engine.Actor:
return actor_of(user)
def _is_deadlock(exc: BaseException) -> bool:
"""判断是不是 InnoDB 挑中本事务当死锁牺牲品(不是超时、不是连不上)。"""
original = getattr(exc, "orig", None)
args = getattr(original, "args", ()) or ()
if args and args[0] == DEADLOCK_ERRNO:
return True
return "Deadlock found" in str(original if original is not None else exc)
def _retry_on_deadlock(db: Session, action, *, what: str):
"""跑一段引擎写入,撞上死锁就从头再来一遍。
两个人(或一个审批人加一个调度器)同时动同一张单据时,引擎会连着写
``oa_task`` / ``oa_task_completed`` / ``oa_work``:加锁顺序天然会交错,
MySQL 便挑一笔事务回滚。回滚掉的是**整笔事务**,所以这里能安全地从头再跑一次:
要么这次办成,要么撞上"后续环节已处理,无法撤回"这类正常业务提示,
总好过把一笔本来能做成的操作甩成一个 500。
"""
attempts = 0
while True:
try:
return action()
except OperationalError as exc:
attempts += 1
if not _is_deadlock(exc) or attempts >= DEADLOCK_ATTEMPTS:
raise
db.rollback() # 库那边已经整笔回滚,这里只是把 ORM 里的脏状态收干净
logger.warning("「%s」撞上数据库死锁(多半是同时有人在办同一张单),第 %d 次重试",
what, attempts)
time.sleep(0.05 * attempts)
def _ensure_in_scope(db: Session, user: CurrentUser, identity: str) -> None:
"""管理员操作也要落在自己的数据范围内。"""
values = permissions.scope_person_refs(db, user)
if values is not None and identity not in values:
raise forbidden("该流程不在你的数据范围内")
def _error(result: engine.StepResult) -> None:
raise bad_request(";".join(result.notices) or "流转失败", reason="ENGINE_ERROR")
# ---------------------------------- job ----------------------------------
@router.post("/job")
def create_job(
body: schemas.JobBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
process = db.get(models.Process, body.process)
if process is None:
raise not_found("流程不存在")
if not process.enabled:
raise bad_request("流程未发布,无法发起")
# 发起范围配在流程定义上,口径见 service/starters.py:开放发起人人能发,
# 限定了范围就按名单算(部门含下级、岗位角色、分组都算数),管理员不受限。
if not starters.allowed(
db, process, identities=starters.actor_identities(db, user), is_admin=user.is_admin
):
raise bad_request(
f"「{process.name}」限定了可发起的人员,你的账号不在发起范围内",
reason="START_FORBIDDEN",
)
data = dict(body.data or {})
if not data and process.data_template:
data = dict(process.data_template)
draft = db.get(models.Draft, body.draft_id) if body.draft_id else None
# 只有本人的草稿才算数(下面合并 data 也是这个条件):别人那张草稿上占的号不能挪过来用
reserved = str(getattr(draft, "serial", "") or "") if draft is not None and draft.person == user.person_id else ""
if not reserved and body.serial_ticket:
# 「新建填单就占号」:填写页先亮出来的那个号在这儿正式落定。凭条过期或被人
# 交过两次就当没预约过,发起这一刻照常排号(引擎会把表单那一格一起改过来)。
reserved = numbering.claim_reservation(db, body.process, body.serial_ticket)
if draft is not None and draft.person == user.person_id:
data = {**(draft.data or {}), **data}
try:
result = _retry_on_deadlock(
db,
lambda: engine.create_job(
db,
process_id=body.process,
actor=_actor(user),
data=data,
# 只把发起人自己敲的那句带进去;没写就由标题规则生成(见 service/titles.py)。
title=body.title.strip(),
attachments=body.attachments,
# 草稿阶段占下的号原样交给引擎,别在发起这一刻又排一个新号(流程配了
# 「存草稿就生成编号」时 draft.serial 才非空,见 service/drafts.py)
serial=reserved,
),
what="发起流程",
)
except engine.EngineError as exc:
# 发起时的表单校验、找人失败都是业务原因,不能报 500;
# 抛出去还会留下半个实例,回滚干净再把原因说给人听。
db.rollback()
raise bad_request(str(exc), reason="ENGINE_ERROR") from exc
if draft is not None:
db.delete(draft)
# 这一趟是从哪几个嵌进来的第三方页面上发的:把这张新单记回那些趟上,第三方拿同一个
# 预受理号再来发就被认成重复。记不上(号不认识、是别人的号)不拦这一次发起——
# 判据与理由见 service/embed_session.py:claim_by_prekey
if body.prekeys:
try:
embed_session.claim_by_prekeys(
db, list(body.prekeys), user.person_id,
job=str(result.work.job if result.work else result.work_job or ""),
serial=str(result.work.serial if result.work else ""),
# 主键也要给:提交之后界面把他送到单据页,那一页是按主键找回这一趟的。
# 少了这一个,"提交后重新打开就换了一页"就还在
work_id=str(result.work.id if result.work else ""),
)
except Exception: # noqa: BLE001 - 记这本账绝不值得把一次已成功的发起赔进去
logger.warning("发起时回填嵌入会话失败 prekeys=%s", body.prekeys, exc_info=True)
_log_operation(db, user, "create_job", result.work.serial if result.work else "", f"发起流程:{process.name}", request)
return ok(_commit(db, lambda: _create_payload(result)))
@router.post("/job/serial/reserve")
def reserve_job_serial(
body: schemas.SerialReserveBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""新建填写页先占一个号:单子还没创建,但「单据编号」那一格当场就要看得见。
只有把编号时机配成「新建填单时就生成」的流程才给占——这一档的代价是**打开填写页
又放弃的人也会把号吃掉**,配在别的时机上等于让人白跳一批号,所以当场挡住。
取回来的凭条(``ticket``)在提交或存草稿时原样交回,那个号才正式落定;
凭条过期就当没预约过,发起那一刻重新排号,界面上那一格会被引擎改成真号。
"""
process = db.get(models.Process, body.process)
if process is None:
raise not_found("流程不存在")
if not process.enabled:
raise bad_request("流程未发布,无法发起")
if not starters.allowed(
db, process, identities=starters.actor_identities(db, user), is_admin=user.is_admin
):
raise forbidden("你的账号不在这条流程的发起范围内")
timing = numbering.timing_of(process)
if timing["at"] != numbering.TIMING_CREATE:
raise bad_request(
f"这条流程的编号时机是「{timing['at']}」,不是「新建填单时就生成」,不用提前占号",
reason="SERIAL_TIMING_MISMATCH",
)
fields = autofill.form_fields(db, process.latest_form)
# 号在这儿要**当场真的取走**,所以必须提交:只 flush 就返回的话,请求一结束事务就回滚,
# 计数器原地不动,下一次占号还是同一个号——同一张单号会发给好几个人,凭条也就形同虚设。
# 「放弃也跳号」正是这一档的代价;不提交就没有代价,只有撞号。
return ok(_commit(db, lambda: numbering.reserve(db, process.id, numbering.serial_rule_of(fields))))
@router.post("/job/title/preview")
def preview_job_title(
body: schemas.TitlePreviewBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""发起页的标题实时预览:按当前填的表单数据算一句标题给人看。
规则在流程定义上,真正生效的是引擎发起时算的那一次;这里只是把同一个
口径提前算给人看,所以两处都必须走 ``service/titles.py``,不许各写一份。
发起页传 ``use_sample=false``,要的是"就这么发出去会长什么样"的真实结果。
"""
process = db.get(models.Process, body.process)
if process is None:
raise not_found("流程不存在")
# 不带 title_config 时传空:让 titles.preview 自己按「流程规则 > 表单字段规则 > 老口径」挑,
# 这里替它挑成流程规则,会把表单里自带的那条规则看漏。
config = body.title_config or {}
return ok(
titles.preview(
db,
process,
config,
data=body.data,
actor=_actor(user),
use_sample=body.use_sample,
)
)
@router.post("/job/{job}/title/preview")
def preview_work_title(
job: str,
body: schemas.WorkTitlePreviewBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""办理页 / 干预面板的标题实时预览:改字段时,告诉他提交后标题会变成哪一句。
与发起页那只输入框不同,这一页的改动还没落库、标题也归引擎在提交时按
``refresh`` 开关重算,所以这里只**算给人看**,一个字都不写回单据
(写了就等于替审批人改了一次标题,回头查不到是谁改的)。口径仍走
``service/titles.py``,与提交那一刻引擎算的是同一段代码。
"""
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
raise not_found("单据不存在或已被删除")
# 只有在这张单上有事做的人看得见:手里有待办的、发起人本人、管理员;
# 再加上监控页动得了这张单的人——干预面板改表单时也要预告标题会换成哪一句,
# 可见范围与 /admin/work/{job}/data 用同一道数据范围筛。
if user.can("monitor:work"):
_ensure_in_scope(db, user, work.creator_identity)
elif work.creator != user.person_id and not db.execute(
select(models.Task.id).where(
models.Task.work == work.id, models.Task.identity == user.ref,
models.Task.status == "pending",
).limit(1)
).first():
raise forbidden("这张单据不在你的待办里")
definition = definition_module.for_work(db, work)
activity = definition.activity(work.activity)
fields = autofill.form_fields(
db, (activity.form if activity else "") or work.form, definition
)
return ok(
titles.preview_refresh(db, work, definition, data=body.data, actor=_actor(user), fields=fields)
)
@router.get("/job/{job}")
def get_job(job: str, db: Session = Depends(get_db), user: CurrentUser = Depends(current_user)) -> dict:
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is not None:
return _job_response(db, user, job, work, running=True)
completed = db.execute(
select(models.WorkCompleted).where(models.WorkCompleted.job == job)
).scalar_one_or_none()
if completed is None:
raise not_found("单据不存在或已被删除")
return _job_response(db, user, job, completed, running=False)
def _job_response(db: Session, user: CurrentUser, job: str, row, *, running: bool) -> dict:
"""单据详情页那一整包响应(``GET /job/{job}`` 与 ``GET /work/{id}`` 共用,含统一信封)。
``row`` 是在途的 ``oa_work`` 还是归档的 ``oa_work_completed``,由调用方用 ``running``
说清:两个入口本来就都先按自己的键拿到了这一行,再按 ``job`` 问第二趟纯属重复
(``/work/{id}`` 原先正是这么干的,多付一趟往返)。
"""
assert row is not None
# 根这一条必须先问:后面每一块都要知道这是"在途"还是"已归档",流程定义也挂在它身上。
# 需要它的字段先在这里读成普通值,工作线程不碰主 Session 的 ORM 对象。
process_id = row.process
# 在途与归档一起问:谁身上有冻结引用就先问它自己那一版设计(口径见 definition.for_work)。
# 归档这一半是新补的——以前只认在途行,于是同一张单跨越办结那道坎就换了一版图:办结之前
# 怎么改流程都拽不动它,办结之后回头打开详情,环节名、表单字段、能不能撤回又全跟着新设计跑,
# 连流程被删掉都能把一张已经落定的单的"图"抹平。冻过结就整份从快照里来——快照不可变,
# 进程内那份缓存命中之后一条 SQL 都不必排,下面那三趟设计查询和那条表单清单查询干脆不摊出去;
# 没冻过(老单)或快照行没了,照旧走当前设计。
# ``getattr`` 而不是直接点:老库里的归档行可能还没这一列,而"归档行当在途传进来"
# 这条退化入口是有调用方的(自检就靠它验那句「流程不存在」),不该先撞属性名。
frozen = None
if str(getattr(row, "design_snapshot", "") or ""):
try:
candidate = definition_module.for_work(db, row)
except ValueError:
# 快照行丢了、流程也跟着被删了:在途单照旧把这句喊出去(数据坏了要人管),
# 归档单不能因此看不到单据本身——交给下面 ``process_block`` 那一支空定义收尾。
if running:
raise
candidate = None
frozen = candidate if candidate is not None and candidate.pinned else None
# 冻过结的在途单要把"此刻那张表改成什么样了"也带一份出去(手机端审批版式读它,
# 口径见 ``forms_live``),所以要先把冻结定义里那几张表单的 id 摘出来。
# 没冻过的不用问:``forms`` 本来就是现读的那一张。
live_form_ids = list(dict.fromkeys(frozen.form_ids())) if frozen is not None and running else []
archived_definition_fields = {
"process_id": process_id,
"name": row.process_name,
"alias": row.process_name,
"category": row.category,
"category_name": row.category_name,
}
# 流程定义先问共享缓存:设计发布之后就不再动,命中了这三趟一次都不必排。
# 这一读走 Redis(本部署一趟 9~20ms),过去**串在并发块前面**:实测每开一次详情页
# 就先白等它一趟(``GET /job/{job}`` 的时间线里,第 30ms 到第 54ms 那一段全是它)。
# 它与下面几块互不相干,于是也当成一块塞进同一次 gather 里并发。只有"没命中"那一支
# 要多等一轮——那三块得听这一块的答复才跑;而命中是常态(设计发布之后不再动),
# 没命中才付那一轮,且那一轮里三块照样并发。
def detached(stmt):
"""查一批行、和这条 Session 脱钩之后交出去。
列值留在对象上,照样能读;但块用的那条 Session 一出块就关了,不 expunge 的话
对象回到主线程碰一下就 detached。expunge 之后要是有人去碰没查过的懒加载关系,
会当场炸在自检里,而不是等生产上偶发 —— 这个端点的报文是逐字节比过的。
"""
def run(session: Session):
rows = list(session.execute(stmt).scalars().all())
for item in rows:
session.expunge(item)
return rows
return run
def process_block(session: Session):
"""流程定义那一行。归档在前的历史单据允许查不到——怎么收尾在并发跑完之后统一判。
查不到不该直接抛错把人锁在门外:单据本身和流转历史照样得能打开,
只是不再有环节图、路由与表单可用。
"""
process_row = session.get(models.Process, process_id)
if process_row is not None:
session.expunge(process_row)
return process_row
def design_block(session: Session):
"""只问共享缓存那一读(不碰数据库,用不到传进来的 Session)。"""
if frozen is not None:
return frozen
return definition_module.cached_design(process_id)
def activities_block(session: Session):
"""环节行,只认 ``process_id``。
以前这一块顺手把表单清单也问了(两条语句串在一块里):现在表单清单命中与否都要
问、也与环节行互不相干,于是单独成一块(:func:`forms_block`),两条各占一个并发位。
没命中那一支的语句条数因此一个字没变——只是这两条不再挤在同一块里串着跑。
"""
rows = list(
session.execute(
select(models.Activity).where(models.Activity.process == process_id)
).scalars().all()
)
for item in rows:
session.expunge(item)
return rows
def forms_block(session: Session):
"""这个流程用到的表单清单(在 SQL 里算,不等环节行,也不等流程行)。
定义与表单清单本来就各读各的:命中时定义来自缓存、清单来自这条查询;没命中时
清单与环节行分在两个并发位、两条 Session 上。两个口径本来就不同源,
``_ordered_forms`` 只按定义里列出的顺序去这批行里取,取不到的丢掉。
冻结定义那一支不在这里问:表单内容本来就存在快照里(``_snapshot_forms``),
现读回来的那张新表单反而是错的。
"""
if frozen is not None:
return []
return _process_form_rows(session, process_id)
def live_forms_block(session: Session):
"""这一张单挂的那几张表单**此刻**的内容(``form_id -> content``)。
只有冻过结的在途单要问:没冻的单,上面 ``forms_block`` 回的就是当前那一张。
读的是 :func:`app.service.autofill.form_content` 那一层进程内快照——没人改表单时
一条 SQL 都不排,改过之后当场作废重读,界面上保存即见效;真的没命中,那一趟
也只排在这个并发位里,不给详情页添串行的往返。
"""
out: dict[str, dict] = {}
for form_id in live_form_ids:
content = autofill.form_content(session, form_id)
if content:
out[form_id] = content
return out
def live_perms_block(session: Session):
"""这一单走过的环节**此刻**的字段权限(``activity_id -> form_perms``)。
跟 ``live_forms_block`` 同一件事的另一半:审批人在手机上看的格子,一半由表单上
那几栏展示配置定,一半由环节那一格「字段权限」定(隐藏 / 只读 / 可编辑 / 必填)。
两张都冻在快照里,改了都得等这张单走完才见效。
环节行本来就在 ``activities_block`` 里问,但冻过结那一支整支都跳过了,
所以这里单独问一次(只认 ``process_id``,一个并发位,不串行)。
"""
if frozen is None or not running:
return {}
return {
row.id: formruntime.perms_of(row.config)
for row in session.execute(
select(models.Activity).where(models.Activity.process == process_id)
).scalars().all()
}
def live_design_block(session: Session):
"""当前那一版设计的版本号,以及它最后一次被改动的时间(三张设计表取最晚)。
只看版本号不够:设计器改一笔环节配置并不会让 ``oa_process.version`` 动,那个号
只在发布时跳。所以再问一次"这三张表最近被动过吗"——比单据发起时刻晚,就说明
有人在这张单出发之后动过设计,而这一单照旧走它自己那一版。
"""
moment = None
for stmt in (
select(models.Process.update_time).where(models.Process.id == process_id),
select(func.max(models.Activity.update_time)).where(models.Activity.process == process_id),
select(func.max(models.Route.update_time)).where(models.Route.process == process_id),
):
for value in session.execute(stmt).scalars().all():
if isinstance(value, datetime) and (moment is None or value > moment):
moment = value
version = session.execute(
select(models.Process.version).where(models.Process.id == process_id)
).scalar_one_or_none()
return {"version": version, "touched": moment}
def writeback_block(session: Session):
# 写回卡控:这张单上要是有配了「挡住处理人」的写回还没落地,办单的人得在点同意之前
# 就知道为什么办不动,而不是点完看一屏红。只回两句话,报文详情留在「集成写回」页——
# 那边的错误原文是给集成管理员看的,不该顺着单据详情页漏给发起人。
blocked = outbox.blocking(session, job=job) if running else []
return {"blocked": bool(blocked), "note": outbox.blocking_note(session, blocked) if blocked else ""}
# 这几块互相之间没有依赖,交给 parallel.gather 并发跑:本部署到库一趟 9~20ms,
# 原来十二趟串在一条线上就是 400ms 上下,慢的是排队不是 SQL(见 app/parallel.py)。
# 流程定义也摊开问:流程行 / 环节+表单 / 路由都只认 process_id,串在一条线上
# 是四趟(实测这一段 57ms,是整页的关键路径),摊开之后和别的块一起排队。
blocks: dict = {
"logs": detached(
select(models.WorkLog).where(models.WorkLog.job == job).order_by(models.WorkLog.arrived_time)
),
"task_completed": detached(
select(models.TaskCompleted)
.where(models.TaskCompleted.job == job)
.order_by(models.TaskCompleted.completed_time)
),
# 与 GET /attachment 同口径:批注和审批意见随附的图片/文件跟着那条记录显示,
# 不进这份单据附件清单。
"attachments": detached(
select(models.Attachment)
.where(
models.Attachment.job == job,
models.Attachment.type.notin_(list(models.Attachment.KIND_LINKED)),
)
.order_by(models.Attachment.order_number)
),
"writeback": writeback_block,
# 命中与否都要问,所以先摊出去,不等缓存的答复
"forms": forms_block,
# 冻过结的在途单另问一份"此刻那张表改成什么样了"(只给手机端审批版式用)。
# 与 forms 一样是个并发位:命中缓存时一条 SQL 都不排,没命中也不挡别的路。
"live_forms": live_forms_block,
# 同上,问的是环节那一格「字段权限」此刻是什么(只回与冻结那一版不一样的环节)
"live_perms": live_perms_block,
# 外部审批锁此刻是什么状态:这一格是闸口不是图纸,管理员当场改了就得当场见效,
# 所以它不吃设计缓存、也不吃单据冻的那一版,照实库那一行算。命中与否都要问,
# 于是与 forms 同批摊出去;回库那一支因此多读一遍环节行(并发位,不串行)。
"oa_locks": lambda session: node_approve.lock_states_for_process(session, process_id),
}
if running:
blocks["tasks"] = detached(
select(models.Task).where(models.Task.job == job).order_by(models.Task.order_number)
)
# 这一层整个不参与(没配 Redis、或 ``OA_DESIGN_CACHE=off``)时那一读必然回空:
# 让它占一个并发位、再把那三块拖到第二轮去,纯属自己给自己加一轮排队。
# 于是这一趟干脆照原样把三块摊在第一轮里,一次 gather 跑完。
cachable = definition_module.design_cache_enabled() or frozen is not None
if not cachable:
blocks.update({
"def_process": process_block,
"def_activities": activities_block,
"def_routes": detached(
select(models.Route)
.where(models.Route.process == process_id)
.order_by(models.Route.order_number, models.Route.name)
),
})
# 缓存那一读放在最后加:几块同时炸时 ``gather`` 按键序挑第一个错报出去,
# 不该让一个缓存读抢在别人前面定义"这次失败长什么样"。
if cachable:
blocks["design"] = design_block
if frozen is not None:
# 只为详情页那半句"别人改过设计了,这一单没跟着改":现版版本号 + 这三张设计表
# 最后一次被动过的时刻。与其余各块并发跑,不给这一页加往返。
blocks["live_design"] = live_design_block
loaded = parallel.gather(db, blocks)
tasks = loaded.get("tasks", [])
logs = loaded["logs"]
done = loaded["task_completed"]
attachments = loaded["attachments"]
form_rows = loaded["forms"]
design = loaded.get("design")
if design is not None:
definition = design
else:
if cachable:
# 真没命中才补这三块:三条查询都只认 process_id,互相不依赖,仍旧并发跑一轮
loaded.update(parallel.gather(db, {
"def_process": process_block,
"def_activities": activities_block,
"def_routes": detached(
select(models.Route)
.where(models.Route.process == process_id)
.order_by(models.Route.order_number, models.Route.name)
),
}))
process_row = loaded["def_process"]
activity_rows = loaded["def_activities"]
if process_row is None:
# 在途的单必须有定义,没有就是数据坏了,按原样把错抛出去;归档单照旧空着定义打开。
if running:
raise ValueError(f"流程不存在: {process_id}")
definition = definition_module.ProcessDefinition(**archived_definition_fields)
else:
routes = loaded["def_routes"]
definition = definition_module.build(process_row, activity_rows, routes)
# 这三趟既然都问了,存下来:下一张同流程的单就不必再问(刚改过设计时存不进去)
definition_module.cache_design(process_row, activity_rows, routes)
forms = _snapshot_forms(definition) if frozen is not None else _ordered_forms(definition, form_rows)
# 只装"与发起那一刻冻住的那一张真的不一样了"的那几张:没改就是空对象,
# 报文与改动前逐字节相同,前端也就不会为了同一份内容摆两遍。
forms_live = _forms_live(forms, loaded.get("live_forms") or {})
# 逐环节的锁状态来自上面那一块(实库此刻那一行),与引擎判据同一个口径。
# 环节是冻结那一版里的环节,锁是当下的锁:中途把外部审批关掉,横幅当场消失。
locks = loaded.get("oa_locks") or {}
activity_nodes = {
a.id: serializers_activity_brief(a, definition.approval, process=definition, lock=locks.get(a.id))
for a in definition.activities.values()
}
# 环节字段权限此刻被改成什么样了:只回**与冻结那一版不一样**的那几个环节,
# 没人动过就是空对象(报文与改动前逐字节一致)。口径见 ``_perms_live``。
activity_perms_live = _perms_live(activity_nodes, loaded.get("live_perms") or {})
# 终止那颗钮给不给这个人看:管理员恒给;发起人除了"是自己发起的",还要过流程那一格
# 终止配置(整个关掉、或已经过了"什么时候为止"那条线)。判据只有一处
# (engine.terminate_blocker),界面显示与引擎放行说的必须是同一句话。
starter_blocker = ""
if running and not user.is_admin and row.creator == user.person_id:
# 只有发起人本人才需要知道"我为什么按不动":别人来看这张单,这一格留空,
# 也省掉一次没意义的判据查询(管理员恒能终止,同样不必问)。
starter_blocker = engine.terminate_blocker(db, row, definition, _actor(user))
# 这一单上能不能补批注:环节那一格「允许批注」+「这一单与你有关」。
# 有关的四档里前三档用的行报文里本来就读回来了(当前办理人、办过的人、发起人),
# 只有"被抄送/分享/@ 到过"这一档要现问,于是排在最后——自己的单、自己办过的单
# 一次库都不多问。开关取上面那份环节简报,与引擎写路径读的是同一格配置;
# 归档件没有 ``activity`` 这一列,取不到环节就是默认放行(见 engine.comment_activity)。
related = (
user.is_admin
or row.creator == user.person_id
or any(task.identity == user.ref for task in tasks)
or any(item.identity == user.ref for item in done)
)
if not related:
related = _received_reads(db, row.id, user.ref)
node_allows_comment = bool(
(activity_nodes.get(getattr(row, "activity", "") or "") or {}).get("allow_comment", True)
)
return ok(
{
**serializers.work(row),
"tasks": [serializers.task(t) for t in tasks],
"work_logs": [serializers.work_log(l) for l in logs],
"task_completed": [serializers.task_completed(t) for t in done],
"attachments": [serializers.attachment(a) for a in attachments],
"forms": forms,
# 上面那一份是这张单出发那一刻冻住的表单,这一份是**此刻**那一张的内容,
# 只给手机端审批那一屏用(摆哪些格、什么顺序、每格怎么摆按当下的配置走)。
# 只在冻过结的在途单上可能有东西,而且只装真改了的那几张;桌面、打印、
# 导出、必填校验读的还是 ``forms``。口径见 ``_forms_live``。
"forms_live": forms_live,
# 这张单走在哪一版设计上。``design_pinned`` 为真时 ``design_version`` 是它发起
# 那一刻的那一版、``process_version`` 是流程现在的版本号:改流程改表单的人
# 该看得见"这张还在走的单用的是旧图",办单的人才不至于被换掉的图晃到。
"design_version": definition.version,
"design_pinned": definition.pinned,
"process_version": (loaded.get("live_design") or {}).get("version") or definition.version,
"design_touched_after_start": _design_touched_after_start(
row, loaded.get("live_design"), definition
),
"activities": [
{"id": a.id, "name": a.name, "type": a.type, "alias": a.alias}
for a in definition.activities.values()
],
"activity_nodes": activity_nodes,
# 与 ``forms_live`` 配成一对:表单那几栏展示配置 + 环节那一格字段权限,
# 两块合起来才是"这一屏该露哪几格"。都只给手机端审批那一屏当摆法用。
"activity_perms_live": activity_perms_live,
# 轨迹图:环节坐标 + 每环节/每路由的实时状态,前端照着上色就能画出
# 「走过哪条线、停在哪一环、谁还没办」,不用自己拿流水日志反推。
"flow": flowmap.build(definition, row, list(tasks), list(logs), list(done)),
"routes": [
{
"id": r.id,
"name": r.name,
"alias": r.alias,
"from": r.from_activity,
"to": r.to_activity,
"decision": r.decision,
# 出口上的适用条件原样带给界面:界面据此置灰,引擎据此放行,
# 两边读的是同一句表达式。
"expression": r.expression,
}
for r in definition.routes
],
"can_terminate": running and (user.is_admin or (row.creator == user.person_id and not starter_blocker)),
# 挡下的那句原话:按钮不显示时,页面得有个地方说清"为什么不能终止"
"terminate_hint": starter_blocker,
# 单据详情页那颗「补充批注」给不给这个人按(在途与归档同一条判据)
"can_comment": related and node_allows_comment,
"writeback": loaded["writeback"],
# 开始环节停在等提交的那一单(第三方审批:hold 建单):界面上要看得出
# 「这一单还没提交出去」,并且该谁按那颗钮、谁已经替他备好了表态。
# 归档行(oa_work_completed)没有这两列,一律按「不是开始环节」处理。
"at_begin": running and getattr(row, "activity_type", "") == "begin",
"can_start": running and getattr(row, "activity_type", "") == "begin"
and (user.is_admin or row.creator == user.person_id),
"node_decisions": [
node_approve.view(item)
for item in node_approve.staged_for_work(db, row.id, getattr(row, "activity", ""))
] if running and getattr(row, "activity_type", "") == "begin" else [],
}
)
def _received_reads(db: Session, work_id: str, ref: str) -> bool:
"""这一单上有没有发给我的待阅 / 已阅(抄送、分享、批注 @ 我都算)。
只在发起人、当前办理人、经办人对不上时才问这一趟(:func:`_job_response` 里那点判断),
两张表并成一句问完。两条都认 ``identity`` 打头的那个索引,不顺着 ``work`` 扫表。
"""
stmt = (
select(models.Read.id).where(models.Read.work == work_id, models.Read.identity == ref)
.union_all(
select(models.ReadCompleted.id).where(
models.ReadCompleted.work == work_id, models.ReadCompleted.identity == ref
)
)
.limit(1)
)
return db.execute(stmt).first() is not None
def serializers_activity_brief(
node,
approval: dict | None = None,
*,
process=None,
lock: dict | None = None,
) -> dict:
"""环节简报。``lock`` 是实库此刻那一行的锁状态(``node_approve.lock_states_for_process``
一次查库算好的);只有它没有这一环(冻结设计里有、实库已删)才现算一份兜底,
这时读的是 ``process`` 与环节自己那一份配置。"""
flags = engine.approval_flags(node.config or {}, approval or {})
return {
"id": node.id,
"name": node.name,
"type": node.type,
"form": node.form,
# 开始环节是「退回发起人」的落脚点,不是办理点:它没有上游可退,
# 按钮摆在那儿只会让人点一次才知道退不了
"allow_go_back": bool(node.type != "begin" and node.config.get("allowGoBack", True)),
"allow_add_task": bool(node.config.get("allowAddTask", True)),
"allow_terminate": bool(node.config.get("allowTerminate", True)),
"allow_transfer": bool(node.config.get("allowTransfer", True)),
"allow_recall": bool(node.config.get("allowRecall", True)),
"allow_press": bool(node.config.get("allowPress", True)),
"allow_cc": bool(node.config.get("allowCc", True)),
"allow_share": bool(node.config.get("allowShare", True)),
"allow_comment": bool(node.config.get("allowComment", True)),
"cc_rules": node.config.get("ccRules") or [],
"go_back_config": node.config.get("goBackConfig") or {},
"mode": node.config.get("mode") or "any",
# 环节字段权限:前端按这份渲染,服务端提交时按同一份把关。
"form_perms": formruntime.perms_of(node.config),
# 去重开关按「环节显式配置 -> 流程级默认」的优先级算出本环真正生效的值,
# 前端拿到的就是运行时口径,不会界面说一套引擎做一套。
"skip_starter": flags.skip_starter,
"skip_approved": flags.skip_approved,
"skip_ahead": flags.skip_ahead,
# 上面三个开关在界面上是一档策略(每次签 / 只签第一次 / 只签最后一次 / 只签一次)
"repeat_policy": engine.repeat_policy(node.config or {}, approval or {}),
# 外部审批锁住了 OA 侧哪几颗钮、去哪儿办、那句说明。继承规则(流程默认档 →
# 环节覆盖)只在后端算一遍,前端拿到的就是运行时口径。
"oa_lock": lock if lock is not None else node_approve.lock_view(
node_approve.effective_config(process, node), activity_type=str(node.type or "")
),
}
def _process_form_rows(db: Session, process_id: str) -> list[models.FormElement]:
"""一个流程会用到的表单,一次问完:环节上挂的 + 流程自己的 ``latest_form``。
清单在 SQL 里算出来,这一句才不用等流程行和环节行先回来——详情页因此能把它和那两块
并发掉。原来是一个表单一趟 ``db.get``,环节挂三个表单就是三趟串行的往返。
这里那个并集必须与 ``ProcessDefinition.form_ids()`` 保持一个口径,改一边记得改另一边。
"""
ids = select(models.Activity.form).where(
models.Activity.process == process_id, models.Activity.form != ""
).union(
select(models.Process.latest_form).where(
models.Process.id == process_id, models.Process.latest_form != ""
)
)
rows = db.execute(select(models.FormElement).where(models.FormElement.id.in_(ids))).scalars().all()
return list(rows)
def _ordered_forms(
definition: definition_module.ProcessDefinition, rows: list[models.FormElement]
) -> list[dict]:
"""把查回来的一批表单按流程里列出的顺序排好、去重,认不出 id 的丢掉。
顺序口径与原来逐条 ``db.get`` 时一字不差:先 ``latest_form``,再按环节顺序,重复只留第一次。
"""
by_id = {row.id: row for row in rows}
out: list[dict] = []
seen: set[str] = set()
for form_id in definition.form_ids():
if form_id in seen:
continue
seen.add(form_id)
form_row = by_id.get(form_id)
if form_row is not None:
out.append(serializers.form(form_row))
return out
def _design_touched_after_start(row, live: dict | None, definition) -> bool:
"""这张单出发之后,有没有人又动过这个流程的设计(改图、改表单规则、发布新版)。
只在冻过结的在途单上有意义——回答的是界面上一句很自然的疑问:"我改的那些生效了吗?"
答的是"对这一单没生效,对它之后发起的单生效了"。判据取两条:版本号跳了,
或那三张设计表最后一次被动过的时刻晚于这张单的发起时刻。
"""
if not getattr(definition, "pinned", False) or not live:
return False
version = live.get("version")
if isinstance(version, int) and version != definition.version:
return True
moment, started = live.get("touched"), getattr(row, "start_time", None)
return bool(isinstance(moment, datetime) and isinstance(started, datetime) and moment > started)
def _snapshot_forms(definition: definition_module.ProcessDefinition) -> list[dict]:
"""冻结定义里那几张表单的出参,顺序与去重口径同 :func:`_ordered_forms`。
内容来自 ``oa_process_snapshot``,不是 ``oa_form``:一张走到一半的单看到的表单,
就该是它出发那一刻的那一张。
"""
out: list[dict] = []
seen: set[str] = set()
for form_id in definition.form_ids():
if form_id in seen:
continue
seen.add(form_id)
node = definition_module.form_node(definition, form_id)
if node is not None:
out.append(serializers.form(node))
return out
def _forms_live(forms: list[dict], live: dict[str, dict]) -> dict[str, dict]:
"""手机端那一屏要用的"此刻那份表单配置":只收与冻住的那一张真改了的表单。
为什么只有手机端跟:单据是凭证,桌面详情页、打印单、导出、必填校验、引擎落库
读的都必须是这张单出发那一刻冻住的那一版(``check_design_pin.py`` 钉的就是这一条),
否则一张走到一半的单会因为别人改了表单而当场换掉该填什么。而审批的人手机上看的
是"这一屏该给他看哪几格"——配表的人刚把某一格勾上「展示」、把明细改成逐条展开、
把显示条件改了,手机上还要等这张单走完才见效,等于那份配置白改。
所以这里只多一份**展示**用的内容,不动 ``forms``:
* 认的是同一张表(同一个 ``form_id``)。设计器里就地改表单是更新这一行,id 不变,
这正是"改配置马上影响在途单"的那条路;把环节换成另一张表(id 变了)不算调整,
在途单照旧看自己冻住那一张,不跟着换表。
* 内容没动就不进这份报文(``{}``),报文与改动前逐字节一致,前端也不会为
同一份内容摆两遍。
* 表被删了 / 快照里本来就没这张表:``live`` 里没有这一项,前端回落到冻住的那一张。
"""
out: dict[str, dict] = {}
for item in forms:
form_id = str(item.get("id") or "")
content = live.get(form_id)
if content and content != (item.get("content") or {}):
out[form_id] = content
return out
def _perms_live(nodes: dict[str, dict], live: dict[str, dict]) -> dict[str, dict]:
"""环节字段权限**此刻**那份与冻结那份的差异:只回改过的环节(``activity_id -> form_perms``)。
与 :func:`_forms_live` 是一对:审批人在手机上看见哪几格,一半写在表单那几栏展示配置里,
一半写在流程设计器「环节 → 字段权限」那一格里(生产上 2026-11 那批在途报销单就是这一处——
管理员把 ``checkTotal`` 那几个审定格从「隐藏」改成「只读」,手机上那一屏照旧不露,
因为那张单冻的还是「隐藏」。)
判据与环节简报里那份 ``form_perms`` 同一句(都过 :func:`app.service.formruntime.perms_of`),
不许前端再拿 ``config.formPerms`` 自己拼一遍。冻结简报里没有的环节(发过新版之后新加的环节)
不进这份报文:那张单脚下没这一环,给它是多余的。
"""
out: dict[str, dict] = {}
for activity_id, brief in nodes.items():
perms = live.get(activity_id)
if perms and perms != (brief.get("form_perms") or {}):
out[activity_id] = perms
return out
@router.patch("/job/{job}")
def update_job(
job: str,
body: schemas.JobUpdateBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
raise not_found("单据不存在或已被删除")
if not (user.is_admin or work.creator == user.person_id):
raise bad_request("只有发起人可以修改")
if body.title is not None:
work.title = body.title[:500]
if body.data is not None:
# 系统留痕(_fetch / _quota 这类下划线键)由引擎在链路里自己写:改单页手里是打开
# 那一刻的旧快照,整格收下来会把已落地的留痕盖回旧的一份。这条口不走环节规则,
# 拿不到表单字段清单,按下划线前缀整档处理即可——设计器不生成这种键名。
payload = engine.without_trace_keys(body.data)
# 这条口不走环节规则,字段清单得自己按单据挂的表单取一次,只为把选人那一格
# 洗成账号(这一格只认账号;换成主键或别的写法交上来,落库之后这格就谁也认不出是谁)
definition = definition_module.for_work(db, work)
fields = autofill.form_fields(db, work.form, definition)
work.data = {**(work.data or {}), **formruntime.normalize_person_values(db, fields, payload)}
return ok(_commit(db, lambda: serializers.work(work)))
@router.post("/job/{job}/terminate")
def terminate_job(
job: str,
body: schemas.TerminateBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
# 原因必填:终止把别人手上的待办直接抹掉,档案里只留一句系统兜底的「流程终止」,
# 事后谁也说不清是谁为什么撤了这张单(2026-11 那条报销单就是这么变成一笔糊涂账的)。
reason = str(body.opinion or "").strip()
if not reason:
raise bad_request("请先写一句终止原因:这句话会进审批记录,也会随通知发给被终止掉待办的人")
result = _retry_on_deadlock(
db,
lambda: engine.terminate(db, job=job, actor=_actor(user), opinion=reason),
what="终止流程",
)
_log_operation(db, user, "terminate_job", job, f"终止流程:{reason}", request)
db.commit()
return ok({"status": result.status})
@router.post("/job/{job}/delete")
def delete_job(
job: str,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""删掉一张还没发起流转的单:本人创建、还停在开始环节、没压在别人手上。
与上面 ``/terminate`` 的分别是**留不留这份档案**:终止把单子办完再归档,界面上
还能看见它终止了;删除是这张单从头到尾没进过任何人的办理,连行带号一起抹掉。
判据与三样收尾(额度、外部表态、嵌页面那本账)都在 ``engine.delete_unstarted``。
所以这里没有「终止原因」那一栏——这张单没交出去过,无需向谁交代。
"""
deleted = _engine_value(engine.delete_unstarted, db, job=job, actor=_actor(user))
_log_operation(db, user, "delete_job", deleted.serial or deleted.job,
f"删除未发起的流程:{deleted.title}", request)
return ok(_commit(db, lambda: {
"job": deleted.job, "serial": deleted.serial, "title": deleted.title
}))
# --------------------------- 外部核验(票据初审) --------------------------
#
# 这一组接口只管"送出去 / 问一次 / 撤回 / 应急放行"四个动作,**没有任何一个能改结论**:
# 结论只能由核验系统经 ``POST /open/checks/report`` 回传,或由现场回源问回来。
# 人在表单上点一下就能把初审变成"通过",闸门等于没装。
def _work_or_404(db: Session, job: str) -> models.Work:
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
raise not_found("单据不存在或已被删除")
return work
def _check_target(db: Session, job: str, *, action: bool = False):
"""核验这一组接口要操作的那张单:在跑的与已归档的都认。
单子一办结,那行就从 ``oa_work`` 搬进 ``oa_work_completed``(``id`` / ``job`` 不变,
台账按 ``work`` 存的也还是同一个 id)。**右栏那块面板与打印件在办结之后照样要看**——
"这张单当初是怎么过初审的、谁审的、哪几张票"是报销单归档件的一部分,只认在跑那张表
会让已办结的单子张口说"单据不存在"。
``action=True`` 是送审 / 撤回 / 重新核验 / 应急放行这四个动作:单子都结束了还送什么审,
直接说清楚,别用"单据不存在或已被删除"把人往"数据被人删了"那个方向引。
"""
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
archived = db.execute(
select(models.WorkCompleted).where(models.WorkCompleted.job == job)
).scalar_one_or_none()
if archived is None:
raise not_found("单据不存在或已被删除")
if action:
raise bad_request("这张单已经办结或终止,没什么可送审的,也不需要放行")
return archived
return work
def _ensure_party(db: Session, user: CurrentUser, work: models.Work) -> None:
"""能不能替这张单点「送审 / 撤回」:发起人、手上还有待办的人、管理员。
这三个动作都会往外部系统打一次招呼并留下批次,不该让一个与这张单无关的人代点。
"""
if user.is_admin or work.creator == user.person_id:
return
held = db.execute(
select(models.Task.id).where(
models.Task.work == work.id,
models.Task.status == "pending",
models.Task.person == user.person_id,
).limit(1)
).first()
if held is None:
raise forbidden("只有发起人或当前处理人能替这张单操作核验")
@router.get("/job/{job}/external-check")
def get_external_check(
job: str,
scene: str = Query(""),
db: Session = Depends(get_db),
_: CurrentUser = Depends(current_user),
) -> dict:
"""这一单的核验状态:当前那一批 + 历史 + 本环节配没配闸门。
任何登录用户可读——审批页、填单页、打印预览都要靠它说清"这一单现在卡在哪"。
真正的**判定**不在这儿:这里只是把台账念一遍,提交时判的是 ``service/gate.py``。
"""
work = _check_target(db, job)
activity, cfg = external_check.config_for_scene(db, work, scene)
rows = external_check.history(db, scene=str(cfg.get("scene") or scene), work=work)
current = rows[0] if rows else None
files = external_check.attachments_of(db, work)
return ok({
"scene": str(cfg.get("scene") or scene or ""),
"configured": bool(cfg),
"summary": external_check.view(current) if current is not None else None,
"items": [external_check.view(row) for row in rows],
"fileCount": len(files),
# 送审之后又换了附件:判定会挡(``gate.files_drift``),界面也得提前说同一句话,
# 否则会出现"右栏写着已通过、点提交却被挡"这种两张皮
"filesChanged": gate.files_drift(db, work, current) is not None,
"gate": {
"mode": str(cfg.get("mode") or gate.MODE_BLOCK),
"flag": str(cfg.get("flag") or ""),
"activity": str(getattr(activity, "name", "") or ""),
"canRefresh": bool((cfg.get("query") or {}).get("source")),
"canWithdraw": bool(str(cfg.get("withdrawTemplate") or "").strip()),
"summary": gate.summary_of(cfg),
# 逐票清单那一行读哪三个子字段:界面据此通用画法,不再写死发票那套
"item": external_check.item_shape(str(cfg.get("scene") or scene or ""), cfg),
},
})
@router.post("/job/{job}/external-check/submit")
def submit_external_check(
job: str,
body: schemas.ExternalCheckBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""送审:把这张单的附件清单送去核验系统,结论回来之前界面一直是"核验中"。
清单没变就把上一批还回去(不重复骚扰对方);清单变了自动另起一版并把旧版作废。
"""
work = _check_target(db, job, action=True)
_ensure_party(db, user, work)
activity, cfg = external_check.config_for_scene(db, work, body.scene)
if not external_check.enabled_in(cfg):
raise bad_request("这一环没配外部核验闸门,没什么可送的")
try:
row = external_check.submit(db, work, cfg=cfg, scene=body.scene, actor=_actor(user),
activity=activity)
except external_check.CheckError as exc:
raise bad_request(str(exc)) from exc
_log_operation(db, user, "external_check_submit", job,
f"送审 {row.scene} 批次 {row.biz_key}({row.revision} 版 / "
f"{len(external_check.attachments_of(db, work))} 个附件)", request)
db.commit()
return ok({"summary": external_check.view(row)})
@router.post("/job/{job}/external-check/withdraw")
def withdraw_external_check(
job: str,
body: schemas.ExternalCheckBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""撤回送审。没配撤回报文时**不改状态**,只把"对方那边会留下孤儿任务"这句话回给人看。"""
work = _check_target(db, job, action=True)
_ensure_party(db, user, work)
_activity, cfg = external_check.config_for_scene(db, work, body.scene)
if not external_check.enabled_in(cfg):
raise bad_request("这一环没配外部核验闸门,没什么可撤回的")
try:
row, note = external_check.withdraw(db, work, cfg=cfg, scene=body.scene,
actor=_actor(user), reason=body.reason)
except external_check.CheckError as exc:
raise bad_request(str(exc)) from exc
if row is None:
raise bad_request(note or "这一单还没送审")
_log_operation(db, user, "external_check_withdraw", job,
f"撤回送审 {row.biz_key}:{body.reason or note}", request)
db.commit()
return ok({"summary": external_check.view(row), "note": note})
@router.post("/job/{job}/external-check/refresh")
def refresh_external_check(
job: str,
body: schemas.ExternalCheckBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""重新核验:按批次号现问一次,回结论**不抛错**。
与提交链路里那次现场回源的区别只有一个:这里问不到只是"这次没问到",
不该把界面变成一个红框。所以失败原因走 ``note`` 回给界面。
"""
work = _check_target(db, job, action=True)
_ensure_party(db, user, work)
activity, cfg = external_check.config_for_scene(db, work, body.scene)
row = external_check.latest(db, scene=str(cfg.get("scene") or body.scene), work=work)
if row is None:
raise bad_request("这一单还没送审,没有可以重新核验的批次")
if not (cfg.get("query") or {}).get("source"):
raise bad_request("没配查询接口(gate.query.source),问不到,只能等对方回传")
row, note = external_check.refresh(db, row, cfg=cfg,
origin=models.ExternalCheck.ORIGIN_MANUAL,
actor=_actor(user), activity=activity)
_log_operation(db, user, "external_check_refresh", job,
f"重新核验 {row.biz_key}:{note or external_check.status_label(row.status)}", request)
db.commit()
return ok({"summary": external_check.view(row), "note": note})
@router.post("/job/{job}/external-check/pass", dependencies=[Depends(require_permission("work:gatePass"))])
def pass_external_check(
job: str,
body: schemas.ExternalCheckBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""应急放行:核验系统挂了、业务又必须今天报账时的那一条口子。
它比闸门本身更难按:单独一档权限(``work:gatePass``)、理由不少于十个字、
三处留痕一次不少(审批记录 / 操作日志 / 站内信)。**放行不是抹掉闸门**,
是把责任换个人背并且写进凭证里——所以这一句会永久留在审批记录与台账上。
"""
work = _check_target(db, job, action=True)
if work.status != "running":
raise bad_request("这张单已经结束了,没有需要放行的提交")
activity, cfg = external_check.config_for_scene(db, work, body.scene)
row = external_check.latest(db, scene=str(cfg.get("scene") or body.scene), work=work)
if row is None:
raise bad_request("这一单还没送审:没有批次可放行,先送审,或先补附件")
try:
row = external_check.override(db, row, actor=_actor(user), reason=body.reason)
except external_check.CheckError as exc:
raise bad_request(str(exc)) from exc
# 留痕之一:审批记录。放行这个动作本身就是一条事件,不等那次提交(提交可能根本不会发生)
definition = engine._definition_of(db, work)
node = engine._activity_node(definition, str(work.activity or ""))
engine._event_log(
db, work, node, _actor(user),
f"应急放行({external_check.label_of(row.scene)} / 批次 {row.biz_key}):{row.override_reason}",
engine.LOG_GATE_PASS,
)
# 留痕之二:操作日志(谁、哪张单、什么时候);留痕之三:知会发起人与闸门配的那些角色
_log_operation(db, user, "external_check_pass", job,
f"应急放行 {row.biz_key}:{row.override_reason}", request)
identities = [work.creator_identity]
for name in [str(item or "").strip() for item in (cfg.get("notifyRoles") or [])]:
identities.extend(org.role_members(db, name) or [])
engine.notify(
db, [item for item in identities if item], type_=engine.NOTIFY_CONTROL,
title=f"外部核验被人工放行:{work.title}",
body=f"{user.display_name} 放行了《{work.title}》的{external_check.label_of(row.scene)}"
f"(批次 {row.biz_key},当前状态 {external_check.status_label(row.status)})。"
f"理由:{row.override_reason}",
job=work.job, work=work.id, process=work.process, sender=user.display_name,
)
db.commit()
return ok({"summary": external_check.view(row)})
# ------------------------------ created work -----------------------------
@router.get("/work/created")
def list_created(
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
keyword: str = Query(""),
process: str = Query(""),
status: str = Query(""),
start_date: str = Query(""),
end_date: str = Query(""),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=200),
with_data: bool = Query(True, description="0=不回表单正文,只要列表行;列表页用它省掉整列 data"),
) -> dict:
"""我发起的:默认合并运行中与已办结两类工作,按时间倒序分页。
``with_data=0`` 时 ``data`` 固定回空对象,同时查询里 defer 掉 ``data`` 列:表单正文
是整行里最宽的一列,列表页一行只看标题、状态、时间,详情页另走 ``/work/{id}``。
默认值不变,导出与老调用方照旧拿到完整行。
"""
parts: list = []
if status in ("", "running"):
parts.append(_work_key_part(
models.Work, "running",
_created_clause(models.Work, user, keyword, process, status, start_date, end_date),
))
if status in ("", "completed", "terminated", "canceled"):
parts.append(_work_key_part(
models.WorkCompleted, "archived",
_created_clause(models.WorkCompleted, user, keyword, process, status, start_date, end_date),
))
if not parts:
return ok(serializers.page([], 0, page, page_size))
rows, total = _work_union_page(
db, parts, offset=(page - 1) * page_size, limit=page_size, with_data=with_data
)
items = [serializers.work(row, with_data=with_data) for row in rows]
# 列表上那颗「终止」跟着流程那一格开关走:关了就整颗不摆,别让人点一次才知道不让。
# 窗口类判据(走到哪一环之后、过了多少小时)不在这里算——那要按每张单到过的环节现查,
# 一行一次往返为了一颗按钮不值当,那些留给详情页与引擎去判。
allowed = _starter_terminate_flags(db, rows)
for item, row in zip(items, rows):
item["terminate_allowed"] = bool(allowed.get(str(row.process or ""), True))
return ok(serializers.page(items, total, page, page_size))
def _starter_terminate_flags(db: Session, rows) -> dict[str, bool]:
"""这批单据各自那条流程开没开「发起人终止」:一页一条 SQL,按流程 id 去重回表。"""
ids = {str(getattr(row, "process", "") or "") for row in rows}
ids.discard("")
if not ids:
return {}
out: dict[str, bool] = {}
for process_id, config in db.execute(
select(models.Process.id, models.Process.terminate_config).where(models.Process.id.in_(ids))
).all():
out[str(process_id)] = terminate_service.allowed_by_config(terminate_service.clean(config or {}))
return out
def _created_clause(model, user, keyword, process, status, start_date, end_date):
"""「我发起的」的过滤条件,两张表、两种取法共用一份口径。
单独摆出来是因为同一套条件现在有两个消费者:导出要整行(:func:`_created_query`),
列表页只要本页主键(:func:`_work_key_part`)。各写一遍迟早漂开,漂开的结果是
列表页看见的单和导出的单不是同一批人。
"""
clauses = [model.creator_identity == user.ref]
if status:
clauses.append(model.status == status)
if keyword:
like = f"%{keyword}%"
clauses.append(or_(model.title.like(like), model.serial.like(like), model.process_name.like(like)))
if process:
clauses.append(model.process == process)
column = _created_date_column(model)
if start_date:
clauses.append(column >= _parse_date(start_date))
if end_date:
clauses.append(column < _parse_date(end_date, add_day=True))
return and_(*clauses)
def _created_query(model, user, keyword, process, status, start_date, end_date, db: Session,
*, with_data: bool = True):
stmt = select(model).where(_created_clause(model, user, keyword, process, status, start_date, end_date))
if not with_data:
# 别把整列表单正文拖回 Python,序列化时才不会顺手补一次查询
stmt = stmt.options(defer(model.data))
return db.execute(stmt).scalars().all()
def _work_key_part(model, table: str, clause):
"""并页用的窄投影:一行只出 (主键, 来源表, 排序时间) 三列。
``sort_time`` 就是以前在 Python 里排的那句 ``finish_time or start_time or create_time``,
搬进 SQL 才谈得上让数据库去排序和切片。来源表标签沿用 ``_MONITOR_WORK_TABLES``,
把主键还原成 ORM 行时靠它认表。
"""
stmt = select(
model.id.label("work_id"),
literal(table).label("work_table"),
func.coalesce(model.finish_time, model.start_time, model.create_time).label("sort_time"),
)
return stmt if clause is None else stmt.where(clause)
def _work_union_page(db: Session, parts: list, *, offset: int, limit: int, with_data: bool = True):
"""在途与已办结两张同形表并成一页:数据库排序、切片、数总数,只回本页主键。
这两张表存的是同一种单据(办结就整行搬进归档表),所以「我发起的」「关联单搜索」
这类列表都得并起来看。老写法是把两张表**整批**拉回 Python 再 sort / len / 切片:
一个人压了几千张单,就是每翻一页把全部历史连 ``data`` 那列表单正文一起搬回来,
总数和页数还算在应用进程里。并成 UNION ALL 之后数据库只回这一页的
``(主键, 来源表)``,回来的行数与页大小同量级。
``count(*) OVER ()`` 是 LIMIT 之前算的,所以本页行和总数一次问完;翻过末尾那一页
没有行、窗口值也拿不到,那种页再单独补一次 COUNT。
"""
merged = parts[0].union_all(*parts[1:]).subquery()
rows = db.execute(
select(merged.c.work_id, merged.c.work_table, func.count().over().label("_total"))
# 时间相同就按来源表和主键定个死序:老写法在 Python 里 sort,同序没有保证,
# 翻页时同一行可能出现两次、也可能一次都不出现。
.order_by(merged.c.sort_time.desc(), merged.c.work_table, merged.c.work_id)
.offset(offset)
.limit(limit)
).all()
total = int(rows[0][2]) if rows else int(
db.execute(select(func.count()).select_from(merged)).scalar() or 0
)
return _monitor_work_rows(db, [(row[0], row[1]) for row in rows], with_data=with_data), total
def _created_date_column(model):
return model.finish_time if model is models.WorkCompleted else model.start_time
# ------------------------- 关联审批单(跨单据引用) -------------------------
#
# 「关联审批单」字段存的是对方单据的 job。这里给前端两个口:
# 一个是挑选时的搜索(只给看得见相关的单子),一个是回显时按 job 批量取摘要,
# 详情/打印/导出都靠后者把一串 id 变成人看得懂的标题。
def _visible_work_filter(model, user: CurrentUser):
"""当前用户「看得见」的单据:自己发起的、自己办过的、被抄送过的,并集。
管理员不受限制。关联字段是给人用来引用历史单的,把范围收在"与我相关"
比全库可搜更符合直觉,也避免把导出当成翻别人单据的口子。
"""
if user.is_admin:
return None
return or_(
model.creator_identity == user.ref,
model.job.in_(select(models.Task.job).where(models.Task.identity == user.ref)),
model.job.in_(select(models.TaskCompleted.job).where(models.TaskCompleted.identity == user.ref)),
model.job.in_(select(models.Read.job).where(models.Read.identity == user.ref)),
model.job.in_(select(models.ReadCompleted.job).where(models.ReadCompleted.identity == user.ref)),
)
def _relation_summary(row) -> dict:
return {
"job": row.job,
"serial": row.serial,
"title": row.title,
"process": row.process,
"process_name": row.process_name,
"status": row.status,
"creator_person": row.creator_person,
"creator_unit_name": row.creator_unit_name,
"start_time": serializers.dt(row.start_time),
"finish_time": serializers.dt(getattr(row, "finish_time", None)),
"current_activity_names": row.current_activity_names,
}
@router.get("/work/related")
def search_related_works(
keyword: str = Query(""),
process: str = Query(""),
status: str = Query(
"",
description="逗号分隔的状态档位:completed=归档通过 / running=在办 / closed=已终止或作废。"
"留空或三档都给等于不限;传单据状态原值(terminated、canceled…)也认。",
),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100),
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""关联审批单选择器:在我发起 / 我办过 / 我抄送过的单子里搜,按档位收状态。
挑哪几档由字段上那一份 ``relationStatuses`` 说了算(口径在 ``service/dicts``,
前端镜像在 ``utils/optionSource.ts``),这一层只照档位挑表、挑状态:默认只给归档通过的,
免得分诊到一半被终止的单子也挂得上去。这一档只管**候选列不列它**——已选中的单据
后来被终止,回显走 ``/work/summaries``,照样念得出标题与「已终止」那个角标。
"""
buckets = dicts.relation_status_query(status)
running_statuses, archived_statuses = dicts.relation_status_tables(buckets)
parts = [
_work_key_part(model, table, _related_clause(model, user, keyword, process, statuses))
for model, table, statuses in (
(models.Work, "running", running_statuses),
(models.WorkCompleted, "archived", archived_statuses),
)
# 没限档时两张表都查;限了档就只查沾得上的那一张,另一张连问都不问
if not buckets or statuses is not None
]
# 关联单选择器只要标题和时间这些摘要,正文那一列从头到尾没人读
rows, total = _work_union_page(
db, parts, offset=(page - 1) * page_size, limit=page_size, with_data=False
)
return ok(serializers.page([_relation_summary(row) for row in rows], total, page, page_size))
def _related_clause(model, user, keyword, process, statuses):
"""关联审批单搜索的过滤条件:看得见(我发起/我办过/我抄送过)AND 勾选的那几项。
``statuses`` 是这一张表要挑的单据状态(``None`` = 这一张表不加状态条件)。
"""
clauses = []
visible = _visible_work_filter(model, user)
if visible is not None:
clauses.append(visible)
if process:
clauses.append(model.process == process)
if statuses:
clauses.append(model.status.in_(statuses))
if keyword:
like = f"%{keyword}%"
clauses.append(or_(model.title.like(like), model.serial.like(like)))
return and_(*clauses) if clauses else None
@router.get("/work/summaries")
def work_summaries(
jobs: str = Query("", description="逗号分隔的 job 列表"),
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""按 job 批量取单据摘要;看不见的、已经不在了的,静默少返回几条即可。"""
wanted = [item.strip() for item in jobs.split(",") if item.strip()]
if not wanted:
return ok([])
found: dict[str, dict] = {}
for model in (models.Work, models.WorkCompleted):
stmt = select(model).where(model.job.in_(wanted))
clause = _visible_work_filter(model, user)
if clause is not None:
stmt = stmt.where(clause)
for row in db.execute(stmt).scalars().all():
found.setdefault(row.job, _relation_summary(row))
# 按请求里的顺序回,界面不用再排一次
return ok([found[job] for job in wanted if job in found])
def _works_linked_on(db: Session, job: str, wanted: list[str]) -> list[str]:
"""正在填的那张单上此刻存着的那几串值里,有本次要问的哪几张单。
只看**存着**的那几串:预览要多认的那一档就这么多——挂在正在填的这一单上的那些单,
填单的人本来就有权看见(是上一环或他自己挑上来的),不必再要求他与对方单据直接相关。
"""
for model in (models.Work, models.WorkCompleted):
row = db.execute(select(model).where(model.job == job)).scalars().first()
if row is None:
continue
wanted_set = set(wanted)
found: set[str] = set()
def walk(node: object) -> None:
if len(found) == len(wanted_set):
return
if isinstance(node, dict):
for one in node.values():
walk(one)
elif isinstance(node, list):
for one in node:
walk(one)
elif isinstance(node, str) and node.strip() in wanted_set:
found.add(node.strip())
walk(row.data or {})
return sorted(found)
return []
@router.post("/work/relation-values")
def relation_fill_values(
body: schemas.RelationFillBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""填单页面上「关联带出」的即时预览:按挂着的那几张单,回每一条 ``pick`` 取到的值。
只用来显示。提交时引擎自己按同一份配置再算一遍并覆盖(``service/linkfill.apply``),
和外部取数那一格是同一分寸,所以这里少一张单、慢一点都不影响单据里的数。
路径解析只有后端一份实现(``fetch.pick_path``),前端不再镜像那份路径语言。
**显示这一路带可见性闸**,分寸照 ``GET /work/summaries``(那一格的回显本来就走它):
与他相关的那几张才回,加上多认一档「确实挂在他正在填的那张单上的」(``work`` 给了才
认得出来)——办理环节的人常常与对方那张单无关,而那些单是发起那一环替他挂上的。看不见的静默少回,
这一格不解释为什么少一张,免得它变成翻别人单据的口子。引擎那一份**不带**这道闸
(``linkfill.works_by_values``),否则第二环提交会把带出来的值算空。
"""
picks = [item for item in (str(one or "").strip() for one in body.picks or []) if item][:60]
wanted = [item for item in (str(one or "").strip() for one in body.values or []) if item]
wanted = wanted[: linkfill.MAX_LINKS]
if not picks or not wanted:
return ok({"items": []})
stored = _works_linked_on(db, str(body.work or "").strip(), wanted)
def gate(model):
clauses = []
visible = _visible_work_filter(model, user)
if visible is not None:
clauses.append(visible)
if stored:
clauses.append(or_(model.job.in_(stored), model.serial.in_(stored)))
if not clauses:
return None
return clauses[0] if len(clauses) == 1 else or_(*clauses)
return ok({"items": linkfill.values_of(db, wanted, picks, extra=gate)})
@router.get("/work/{work_id}")
def get_work(work_id: str, db: Session = Depends(get_db), user: CurrentUser = Depends(current_user)) -> dict:
work = db.get(models.Work, work_id)
if work is not None:
return _job_response(db, user, work.job, work, running=True)
completed = db.get(models.WorkCompleted, work_id)
if completed is None:
raise not_found("单据不存在或已被删除")
return _job_response(db, user, completed.job, completed, running=False)
# --------------------------------- tasks ---------------------------------
@router.get("/task/processing")
def list_processing(
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
keyword: str = Query(""),
process: str = Query(""),
category: str = Query(""),
activity: str = Query(""),
expired: str = Query(""),
start_date: str = Query(""),
end_date: str = Query(""),
order_by: str = Query("start_time"),
order: str = Query("desc"),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=200),
) -> dict:
stmt = _task_filter(models.Task, user, keyword, process, category, activity, expired, start_date, end_date)
total = count_of(db, stmt)
column = getattr(models.Task, order_by if hasattr(models.Task, order_by) else "start_time")
stmt = stmt.order_by(column.desc() if order == "desc" else column.asc())
rows = db.execute(stmt.offset((page - 1) * page_size).limit(page_size)).scalars().all()
# 这一环的表态在外部发生:列表上挂个标签,批量办理也默认不勾这些行
flags = node_approve.lock_flags(db, [(row.process, row.activity) for row in rows])
# 「本人创建、还没发起」的那几条待办能在列表上直接删(判据与删除接口同一把尺)
deletable = engine.deletable_task_ids(db, rows, identity=user.ref)
items = []
for row in rows:
payload = serializers.task(row)
payload["oa_locked"] = bool((flags.get((row.process, row.activity)) or {}).get("locked"))
payload["deletable"] = row.id in deletable
items.append(payload)
return ok(serializers.page(items, total, page, page_size))
@router.get("/task/processing/count")
def count_processing(user: CurrentUser = Depends(current_user), db: Session = Depends(get_db)) -> dict:
total = int(
db.execute(
select(func.count(models.Task.id)).where(models.Task.identity == user.ref)
).scalar()
or 0
)
expired_count = int(
db.execute(
select(func.count(models.Task.id)).where(
models.Task.identity == user.ref, models.Task.expired.is_(True)
)
).scalar()
or 0
)
return ok({"total": total, "expired": expired_count})
def _task_filter(
model,
user: CurrentUser,
keyword: str = "",
process: str = "",
category: str = "",
activity: str = "",
expired: str = "",
start_date: str = "",
end_date: str = "",
date_field: str = "start_time",
):
return select(model).where(
*_task_conditions(
model, user, keyword, process, category, activity, expired, start_date, end_date, date_field
)
)
def _task_conditions(
model,
user: CurrentUser,
keyword: str = "",
process: str = "",
category: str = "",
activity: str = "",
expired: str = "",
start_date: str = "",
end_date: str = "",
date_field: str = "start_time",
) -> list:
"""待办 / 已办共用的那套行级过滤条件,原样摊成一个列表。
摊开是为了「按单折叠」那一路(:mod:`app.service.completed`)能把**同一套**条件
先拿去 ``GROUP BY``、再原样拿回来捞代表行。条件一旦有两份写法,折叠出来的行
和列表筛出来的行迟早对不上,界面上就是「共 N 条」与真能翻到的条数各说一套。
"""
conditions: list = [model.identity == user.ref]
if hasattr(model, "add_task_from"):
# 前置加签回转的待办在被激活前是挂起态,别让它出现在待办里
conditions.append(model.add_task_from != "before_pending")
if keyword:
like = f"%{keyword}%"
conditions.append(
or_(model.title.like(like), model.process_name.like(like), model.serial.like(like), model.activity_name.like(like))
)
if process:
conditions.append(model.process == process)
if category:
conditions.append(model.category == category)
if activity:
conditions.append(model.activity == activity)
expired_flag = tri_state(expired)
if expired_flag is not None:
conditions.append(model.expired.is_(expired_flag))
column = getattr(model, date_field, model.start_time)
if start_date:
conditions.append(column >= _parse_date(start_date))
if end_date:
conditions.append(column < _parse_date(end_date, add_day=True))
return conditions
def _parse_date(value: str, add_day: bool = False) -> datetime:
"""Parse ``YYYY-MM-DD`` (optionally +1 day, for exclusive upper bounds)."""
value = (value or "").strip()
try:
parsed = datetime.fromisoformat(value)
except ValueError:
try:
parsed = datetime.strptime(value, "%Y-%m-%d")
except ValueError as exc:
raise bad_request(f"日期格式错误: {value}", reason="INVALID_DATE") from exc
if add_day and len(value) == 10:
parsed = parsed + timedelta(days=1)
return parsed
@router.get("/task/completed")
def list_completed(
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
keyword: str = Query(""),
process: str = Query(""),
category: str = Query(""),
start_date: str = Query(""),
end_date: str = Query(""),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=200),
) -> dict:
"""我的已办:**一张单只摆一条**,摆的是最近那次表态。
底层 ``oa_task_completed`` 依旧一次表态一行(审批记录、会签计票、撤回已办都按行算),
折叠发生在读这一侧,理由与那三个坑见 :mod:`app.service.completed`。每行带一个
``handle_count`` 说明这张单被本人办过几次,历次表态在单据详情的审批记录里一条不少。
``total`` 跟着一起换成「办过几张不同的单」,否则页眉的条数比翻得到的多。
"""
conditions = _task_conditions(
models.TaskCompleted, user, keyword, process, category, "", "", start_date, end_date,
date_field="completed_time",
)
total = completed_service.count_works(db, conditions)
groups = completed_service.collapse(db, conditions, offset=(page - 1) * page_size, limit=page_size)
rows = [group.row for group in groups]
flags = _recall_flags(db, rows)
items = []
for group in groups:
payload = serializers.task_completed(group.row)
# handle_count:这张单被本人办过几次。折叠成一条之后总得让人知道底下还有几次,
# 否则「我明明退回去过一次,怎么少了一条」就只能靠点进详情自己数。
payload["handle_count"] = group.handles
payload.update(flags.get(group.row.id, {"recallable": None, "recall_blocker": ""}))
items.append(payload)
return ok(serializers.page(items, total, page, page_size))
def _recall_flags(db: Session, rows: list[models.TaskCompleted]) -> dict[str, dict]:
"""逐条判断这一条已办还能不能撤回,口径与 ``engine.reset_task`` 保持一致。
按钮在前端摆着、点下去被后端拒,是最让人窝火的一种"能干"。归档的单据尤其要在这里
就收掉:办结 / 终止 / 作废的那一瞬间整行搬进了 ``oa_work_completed``,每个人
的表态都随单据进了台账,把最后一步收回来重办等于改动一份已经归档的记录。
``recallable`` 为 ``None`` 表示这一条本来就谈不上撤回(不是本人最后一步、或者
是转办加签这类记录),前端什么都不摆;``False`` 时带一句 ``recall_blocker``
说明为什么不能撤,免得人对着一个没有按钮的空格猜。
"""
candidates = [row for row in rows if row.latest and row.processing_type == "normal"]
if not candidates:
return {}
work_ids = {row.work for row in candidates}
running = set(
db.execute(select(models.Work.id).where(models.Work.id.in_(work_ids))).scalars().all()
)
archived = {
row.id: row.status
for row in db.execute(
select(models.WorkCompleted).where(models.WorkCompleted.id.in_(work_ids))
).scalars().all()
}
# 缓存键带上冻结引用:同一个流程可以有在途单走在不同版设计上,只按流程号去重会把
# 别人那一版图安在这张单头上。
definitions: dict[tuple[str, str], object] = {}
flags: dict[str, dict] = {}
# 锁上的那一环同样撤不动:表态归外部系统,OA 这边把已办收回来等于两边各说一套
locks = node_approve.lock_flags(db, [(row.process, row.activity) for row in candidates])
for row in candidates:
if row.id in flags:
continue
status = archived.get(row.work)
if status is not None:
flags[row.id] = {
"recallable": False,
"recall_blocker": f"流程已{engine.WORK_STATUS_LABELS.get(status, '办结')}并归档",
}
continue
if row.work not in running:
flags[row.id] = {"recallable": False, "recall_blocker": "单据已不存在"}
continue
key = (row.process, str(getattr(row, "design_snapshot", "") or ""))
definition = definitions.get(key, False)
if definition is False:
try:
definition = definitions[key] = definition_module.for_work(db, row)
except Exception: # noqa: BLE001 - 流程定义读不到不该拖垮整个列表
definition = definitions[key] = None
activity = definition.activity(row.activity) if definition is not None else None
if activity is not None and not bool(activity.config.get("allowRecall", True)):
flags[row.id] = {"recallable": False, "recall_blocker": f"环节「{activity.name}」不允许撤回"}
continue
blocker = str(((locks.get((row.process, row.activity)) or {}).get("blockers") or {}).get("recall") or "")
if blocker:
flags[row.id] = {"recallable": False, "recall_blocker": blocker}
continue
flags[row.id] = {"recallable": True, "recall_blocker": ""}
return flags
#: 一条待办是怎么离开人手的:取值与 ``oa_task_completed.processing_type`` 一致。
#: 这几档前端 ``TaskDetailView`` / ``MobileTaskView`` 那张「去向卡」有专门文案,
#: 一处定死,别在两处各写一套。认不出的取值(加签那两档、以后新增的)原样退回
#: ``unknown``:那一行已办只说得出"这条待办结束了",说不出是谁点的头。
VANISHED_KINDS = ("move", "terminate", "transfer", "auto", "normal", "goBack", "reset")
def _vanished_task_view(db: Session, task_id: str, user: CurrentUser) -> dict | None:
"""这条待办已经不在了:能答出它怎么结束的吗?答不出就回 ``None``(照旧 404)。
数据本来就在库里,一处不用加表:按待办号回查 ``oa_task_completed`` 拿得到原环节、
原因、是谁替这一步收的尾、它属于哪张单;再看那张单现在停在哪个环节、压在谁手上。
查无这条已办(号是编的)照旧回 ``None``,界面上还是那句"待办不存在或已被处理";
认得出下场的七档按 ``VANISHED_KINDS`` 给专门文案,认不出的回 ``unknown``。
可见范围收得很紧:**当时那条待办的持有人**本人,或者看得见监控的人。别人拿一个
待办号来问,连标题都不该跟着掉出来。
"""
done = db.execute(
select(models.TaskCompleted).where(models.TaskCompleted.task == task_id)
).scalars().first()
if done is None:
return None
kind = str(done.processing_type or "")
if kind not in VANISHED_KINDS:
kind = "unknown"
if str(done.identity or "") != str(user.ref or "") and not user.can("monitor:work"):
return None
# 那张单可能已经归档(搬进 oa_work_completed),两种都要认:办结的单子点开旧提醒
# 也是这条路上的人,不能说"单据不存在"
row = db.execute(select(models.Work).where(models.Work.id == done.work)).scalar_one_or_none()
archived: models.WorkCompleted | None = None
if row is None:
archived = db.execute(
select(models.WorkCompleted).where(models.WorkCompleted.id == done.work)
).scalar_one_or_none()
if row is None and archived is None:
return None
return {
"task": task_id,
"kind": kind,
"job": done.job,
"title": done.title,
"serial": done.serial,
"process_name": done.process_name,
"activity": done.activity,
"activity_name": done.activity_name,
"handled_by": done.identity_name or done.identity,
# 这一步是谁替持有人收的尾(改道 / 终止那类);本人自己办完的那一步留空
"operator": done.operator,
"operator_name": done.operator_name,
"route": done.route_name,
"opinion": done.opinion,
"handled_at": done.completed_time.strftime("%Y-%m-%d %H:%M") if done.completed_time else "",
# 归档件回的是它自己的终态(completed / terminated / canceled),前端那一串
# 状态文案本来就有这三档,不必再造一个 "archived" 让人去猜
"work_status": str(getattr(archived if archived is not None else row, "status", "") or ""),
"current_activity_names": str(
getattr(row, "current_activity_names", "") or getattr(archived, "current_activity_names", "") or ""
),
"current_handlers": str(getattr(row, "manual_identity_text", "") or ""),
}
@router.get("/task/{task_id}")
def get_task_detail(task_id: str, db: Session = Depends(get_db), user: CurrentUser = Depends(current_user)) -> dict:
task = db.get(models.Task, task_id)
if task is None:
# 已推送出去的消息里那条链接是永久有效的(企微卡片尤其如此),点开时那条待办
# 早就没了是常态而不是异常。一句"已被处理"回答不了"那是谁干的、为什么、这张单
# 现在归谁",人只会去问管理员。认得出下场就照实回(口径见 _vanished_task_view)。
vanished = _vanished_task_view(db, task_id, user)
if vanished is None:
raise not_found("待办不存在或已被处理")
return ok({"vanished": vanished})
detail = get_job(task.job, db, user)
payload = detail["data"]
payload["task"] = serializers.task(task)
payload["can_process"] = (task.identity == user.ref) or user.is_admin
# 本环节每条出口路由当前走不走得通。引擎提交时会再按同一口径拦一次,
# 这里只是让人在点之前就看清楚「部门豁免」为什么不能选。
work = db.execute(select(models.Work).where(models.Work.id == task.work)).scalar_one_or_none()
guards: dict[str, bool] = {}
if work is not None:
try:
definition = definition_module.for_work(db, task)
except ValueError:
definition = None
if definition is not None:
for item in definition.routes_from(task.activity):
guards[item.id] = engine.route_guard_ok(db, work, item, _actor(user))
payload["route_guards"] = guards
# 第三方服务端替这一环备好、还在等点头的表态:审批页亮横幅,确认走原来那颗钮同一条引擎路。
payload["node_decisions"] = [node_approve.view(row) for row in node_approve.staged_for_task(db, task.id)]
return ok(payload)
@router.post("/task/{task_id}/view")
def view_task(task_id: str, db: Session = Depends(get_db), user: CurrentUser = Depends(current_user)) -> dict:
task = db.get(models.Task, task_id)
if task is None:
raise not_found("待办不存在或已被处理")
if task.view_time is not None:
return ok(serializers.task(task))
task.view_time = datetime.now()
return ok(_commit(db, lambda: serializers.task(task)))
@router.post("/task/{task_id}/execute")
def execute_task(
task_id: str,
body: schemas.ExecuteBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
result = _run_engine(
engine.execute_task,
db,
task_id=task_id,
actor=_actor(user),
route_name=body.route_name,
opinion=body.opinion,
data=body.data,
media_opinion=body.media_opinion,
attachments=body.attachments,
opinion_attachments=body.opinion_attachments,
next_identities=body.next_identities,
)
_log_operation(db, user, "execute_task", task_id, f"处理待办,路由:{body.route_name}", request)
return ok(_commit_step(db, result))
def _node_decision_row(db: Session, task_id: str, decision_id: str, user: CurrentUser, task: models.Task) -> models.NodeDecision:
"""把一条表态从「等点头」挪出之前要过的那几道闸:行在不在、停没停、是不是这条待办的、
单据还走不走得动、来的人是不是这条待办的处理人。有一道不过就当场说清楚。"""
row = db.get(models.NodeDecision, decision_id)
if row is None or row.task != task_id:
raise not_found("这条表态不存在,或者不属于这条待办")
if row.status != models.NodeDecision.STATUS_STAGED:
raise bad_request("这条表态已经处理过了,不能重复确认")
work = db.get(models.Work, row.work)
if work is None or work.status != "running":
label = {"completed": "办结", "terminated": "终止", "canceled": "作废"}.get(
getattr(work, "status", "") or "", "落定")
row.status = models.NodeDecision.STATUS_EXPIRED
row.confirm_note = f"单据已{label},表态一并作废"
db.commit()
raise bad_request(f"单据已{label},这条表态作废了")
if task.status != "pending":
row.status = models.NodeDecision.STATUS_EXPIRED
row.confirm_note = "这条待办已经换了主人或办掉了,表态一并作废"
db.commit()
raise bad_request("这条待办已经不在处理人手上了,表态作废,请第三方重新表态")
if not ((task.identity == user.ref) or user.is_admin):
raise forbidden("只有这条待办的处理人才能替他确认表态")
return row
@router.post("/task/{task_id}/node-decision/{decision_id}/confirm")
def confirm_node_decision(
task_id: str,
decision_id: str,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""处理人点头:第三方替这一环备好的表态,走原来那颗提交钮同一条引擎路办下去。
点头之前把出口再验一遍:表态备好之后流程图改了的单,不该按旧图走——出口不在了就
让第三方重新表态,不替它猜一条新的。数据与意见都用表态那一刻那份,环节字段权限、
必填、公式、额度、外部核验闸门一条不少。
"""
task = db.get(models.Task, task_id)
if task is None:
raise not_found("待办不存在或已被处理")
row = _node_decision_row(db, task_id, decision_id, user, task)
definition = definition_module.for_work(db, task)
activity = definition.activity(task.activity)
names = [r.name for r in definition.routes_from(task.activity)] if activity is not None else []
if row.route not in names:
row.status = models.NodeDecision.STATUS_EXPIRED
row.confirm_note = "出口已不存在(流程图改动),表态作废,等第三方重新表态"
db.commit()
raise bad_request(
f"这条表态指向的出口「{row.route}」已经不在了(流程图改过)。这一环现在的出口是:"
f"{'、'.join(names) or '没有了'}。请让第三方重新表态"
)
result = _run_engine(engine.execute_task, db, task_id=task_id, actor=_actor(user),
route_name=row.route, opinion=row.opinion, data=dict(row.data or {}),
via=engine.VIA_OA_CONFIRM)
row.status = models.NodeDecision.STATUS_HANDLED
row.confirm_by = str(user.person_id)
row.confirm_name = user.display_name
row.confirm_at = datetime.now()
row.confirm_note = "处理人确认"
_log_operation(db, user, "node_decision_confirm", row.id,
f"确认外部表态:{row.app_name or row.app} 请求「{row.route}」", request)
return ok(_commit_step(db, result))
@router.post("/task/{task_id}/node-decision/{decision_id}/reject")
def reject_node_decision(
task_id: str,
decision_id: str,
body: schemas.OpinionBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""处理人不认这笔表态:作废它,待办留在手上,第三方那句 bizKey 再调也只会收到「已驳回」。"""
task = db.get(models.Task, task_id)
if task is None:
raise not_found("待办不存在或已被处理")
row = _node_decision_row(db, task_id, decision_id, user, task)
row.status = models.NodeDecision.STATUS_REJECTED
row.confirm_by = str(user.person_id)
row.confirm_name = user.display_name
row.confirm_at = datetime.now()
row.confirm_note = str(body.opinion or "处理人驳回").strip()[:500]
_log_operation(db, user, "node_decision_reject", row.id,
f"驳回外部表态:{row.app_name or row.app}", request)
db.commit()
return ok({"rejected": True, "decision": node_approve.view(row)})
def _begin_decision_row(db: Session, work: models.Work, decision_id: str, user: CurrentUser) -> models.NodeDecision:
"""开始环节那条表态从「等点头」挪走之前要过的闸:行在不在、停没停、是不是这张单的、
单据还走不走得动、来的人是不是发起人。与待办那版的口径一字不差,只是把「处理人」
换成了「发起人」——开始环节没有待办,这颗钮属于建单的那个人。"""
row = db.get(models.NodeDecision, decision_id)
if row is None or row.work != work.id:
raise not_found("这条表态不存在,或者不属于这张单")
if row.status != models.NodeDecision.STATUS_STAGED:
raise bad_request("这条表态已经处理过了,不能重复确认")
if work.status != "running":
label = {"completed": "办结", "terminated": "终止", "canceled": "作废"}.get(
getattr(work, "status", "") or "", "落定")
row.status = models.NodeDecision.STATUS_EXPIRED
row.confirm_note = f"单据已{label},表态一并作废"
db.commit()
raise bad_request(f"单据已{label},这条表态作废了")
if not (user.is_admin or work.creator == user.person_id):
raise forbidden("只有这张单的发起人(或管理员)能替他确认表态")
return row
def _begin_work(db: Session, job: str) -> models.Work:
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
raise not_found("单据不存在或已被删除")
if work.status != "running":
label = {"completed": "办结", "terminated": "终止", "canceled": "作废"}.get(work.status, "落定")
raise bad_request(f"流程已{label},不能再提交")
if work.activity_type != "begin":
raise bad_request("这张单已经离开开始环节,不能再从这里提交")
return work
@router.post("/job/{job}/start")
def start_work_at_begin(
job: str,
body: schemas.WorkStartBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""发起人亲按那颗「提交」钮:停在开始环节的单据真正流转出去。
与确认第三方备好的表态走**同一条引擎路**(``engine.start_from_begin``):字段权限、
必填、公式、额度、外部核验闸门一条不少。不是发起人就不给按——开始环节没有别的
办理人,这颗钮属于建单那个人。
"""
work = _begin_work(db, job)
if not (user.is_admin or work.creator == user.person_id):
raise forbidden("只有这张单的发起人(或管理员)能提交这张单")
result = _run_engine(engine.start_from_begin, db, work=work, actor=_actor(user),
route_name=body.route, opinion=body.opinion, data=body.data)
_log_operation(db, user, "work_start", work.id, "提交停在开始环节的单据", request)
return ok(_commit_step(db, result))
@router.post("/job/{job}/node-decision/{decision_id}/confirm")
def confirm_begin_decision(
job: str,
decision_id: str,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""发起人点头:第三方替这一单备好的提交,走发起人自己按那颗钮同一条引擎路办下去。
点头之前把出口再验一遍:表态备好之后流程图改了的单,不该按旧图走——出口不在了就
让第三方重新表态,不替它猜一条新的。数据与意见都用表态那一刻那份。
"""
work = _begin_work(db, job)
row = _begin_decision_row(db, work, decision_id, user)
definition = definition_module.for_work(db, work)
activity = definition.activity(row.activity)
names = [r.name for r in definition.routes_from(row.activity)] if activity is not None else []
if row.route not in names:
row.status = models.NodeDecision.STATUS_EXPIRED
row.confirm_note = "出口已不存在(流程图改动),表态作废,等第三方重新表态"
db.commit()
raise bad_request(
f"这条表态指向的出口「{row.route}」已经不在了(流程图改过)。这一环现在的出口是:"
f"{'、'.join(names) or '没有了'}。请让第三方重新表态"
)
result = _run_engine(engine.start_from_begin, db, work=work, actor=_actor(user),
route_name=row.route, opinion=row.opinion, data=dict(row.data or {}),
via=engine.VIA_OA_CONFIRM)
row.status = models.NodeDecision.STATUS_HANDLED
row.confirm_by = str(user.person_id)
row.confirm_name = user.display_name
row.confirm_at = datetime.now()
row.confirm_note = "发起人确认提交"
_log_operation(db, user, "node_decision_confirm", row.id,
f"确认外部表态:{row.app_name or row.app} 请求「{row.route}」", request)
return ok(_commit_step(db, result))
@router.post("/job/{job}/node-decision/{decision_id}/reject")
def reject_begin_decision(
job: str,
decision_id: str,
body: schemas.OpinionBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""发起人不认这笔表态:作废它,单据仍停在开始环节,第三方那句 bizKey 再调也只会收到「已驳回」。"""
work = _begin_work(db, job)
row = _begin_decision_row(db, work, decision_id, user)
row.status = models.NodeDecision.STATUS_REJECTED
row.confirm_by = str(user.person_id)
row.confirm_name = user.display_name
row.confirm_at = datetime.now()
row.confirm_note = str(body.opinion or "发起人驳回").strip()[:500]
_log_operation(db, user, "node_decision_reject", row.id,
f"驳回外部表态:{row.app_name or row.app}", request)
db.commit()
return ok({"rejected": True, "decision": node_approve.view(row)})
@router.post("/task/batch-execute")
def batch_execute_task(
body: schemas.BatchExecuteBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""批量处理待办:逐条复用单条 execute,不另开一条批量流转路径。
一次选中十几条同流程的报销单一起同意,是待办列表最高频的省事的动作。
这里刻意「一条一次事务」:某条因为必填项没填、路由要多选而失败时,
只回滚那一条,其余照常办结;失败原因原样带回去,界面逐条列给人看,
而不是整批回滚让人从头猜。
"""
task_ids = [str(item) for item in body.task_ids if str(item or "").strip()][:BATCH_LIMIT]
if not task_ids:
raise bad_request("请先选择要处理的待办", reason="EMPTY_SELECTION")
actor = _actor(user)
succeeded: list[dict] = []
failed: list[dict[str, str]] = []
for task_id in task_ids:
try:
result = _run_engine(
engine.execute_task,
db,
task_id=task_id,
actor=actor,
route_name=body.route_name,
opinion=body.opinion,
)
except Exception as exc: # noqa: BLE001 - 单条失败不能带走整批
db.rollback()
failed.append({"id": task_id, "message": _failure_message(exc)})
continue
_log_operation(db, user, "batch_execute_task", task_id, f"批量处理待办,路由:{body.route_name}", request)
succeeded.append(_commit_step(db, result))
return ok(
{
"succeeded": len(succeeded),
"failed": len(failed),
"results": succeeded,
"errors": failed,
}
)
def _failure_message(exc: Exception) -> str:
"""把单条失败原因收成一句人话:HTTPException 取 detail,其余取异常文本。"""
detail = getattr(exc, "detail", None)
if isinstance(detail, dict):
return str(detail.get("message") or detail.get("msg") or exc)
if detail:
return str(detail)
return str(exc) or "处理失败"
@router.post("/task/{task_id}/goback")
def go_back_task(
task_id: str,
body: schemas.GoBackBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
task = db.get(models.Task, task_id)
if task is None:
raise not_found("待办不存在或已被处理")
result = _run_engine(
engine.go_back,
db,
task_id=task_id,
actor=_actor(user),
target=body.activity,
opinion=body.opinion,
way=body.way,
)
_log_operation(db, user, "goback_task", task_id, f"退回到 {body.activity or '上一环节'}", request)
return ok(_commit_step(db, result))
@router.post("/task/{task_id}/addtask")
def add_task(
task_id: str,
body: schemas.AddTaskBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
result = _run_engine(
engine.add_task,
db,
task_id=task_id,
actor=_actor(user),
identities=body.identities,
way=body.way,
mode=body.mode,
opinion=body.opinion,
)
_log_operation(db, user, "add_task", task_id, f"加签 {len(body.identities)} 人", request)
return ok(_commit_step(db, result))
@router.post("/task/{task_id}/transfer")
def transfer_task(
task_id: str,
body: schemas.TransferBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
result = _run_engine(
engine.transfer, db, task_id=task_id, actor=_actor(user), identities=body.identities, opinion=body.opinion
)
_log_operation(db, user, "transfer_task", task_id, f"转办 {len(body.identities)} 人", request)
return ok(_commit_step(db, result))
@router.post("/task/{task_id}/press")
def press_task(
task_id: str,
body: schemas.OpinionBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
task = engine.press(db, task_id=task_id, actor=_actor(user), opinion=body.opinion)
return ok(_commit(db, lambda: serializers.task(task)))
@router.get("/task/{task_id}/goback-targets")
def goback_targets(
task_id: str, db: Session = Depends(get_db), user: CurrentUser = Depends(current_user)
) -> dict:
task = db.get(models.Task, task_id)
if task is None:
raise not_found("待办不存在或已被处理")
definition = definition_module.for_work(db, task)
origin = definition.activity(task.activity)
if origin is None:
return ok([])
work = db.execute(select(models.Work).where(models.Work.id == task.work)).scalar_one_or_none()
if work is None:
return ok([])
# 候选口径交给引擎(engine.goback_candidates):界面下拉与真正执行退回必须问同一个人,
# 否则会出现下拉里给了「总经理」、点确定却报不是上游环节,或者反过来把单据往前推。
candidates = engine.goback_candidates(db, work, definition, origin)
begin_id = definition.begin.id if definition.begin is not None else ""
kind = str(((origin.config or {}).get("goBackConfig") or {}).get("type") or "prev").lower()
if kind == "prev":
# 「只给上一环节」收的是审批环节那一头:退回到发起人永远留着。上一环节就是第一个
# 审批环节时,发起人恰恰是那个最该被退回去的人。
head = candidates[:1]
kept = {node.id for node in head}
candidates = head + [node for node in candidates if node.id == begin_id and node.id not in kept]
return ok(
[
{"id": node.id, "name": node.name, "is_starter": bool(begin_id) and node.id == begin_id}
for node in candidates
]
)
def _step_payload(result: engine.StepResult) -> dict:
work = result.work
return {
"tasks": [serializers.task(t) for t in result.tasks],
"completed": result.completed,
"status": result.status or (work.status if work else ""),
# 办结时活动实例已经归档删掉,这里退回归档件的主键,前端还能跳去详情。
"job": work.job if work else result.work_job,
"work": work.id if work else result.work_id,
}
def _create_payload(result: engine.StepResult) -> dict:
"""发起接口那份报文;字段跟老写法逐字一样,只是挪到提交之前去算。"""
work = result.work
return {
"job": work.job if work else result.work_job,
"work": work.id if work else result.work_id,
"serial": work.serial if work else "",
"title": work.title if work else "",
"status": result.status or (work.status if work else ""),
"tasks": [serializers.task(t) for t in result.tasks],
}
def _reads_payload(rows: list[models.Read]) -> dict:
"""抄送/分享回的那一沓待阅。"""
return {"count": len(rows), "reads": [serializers.read_row(r) for r in rows]}
def _commit(db: Session, build: Callable[[], object] | None = None):
"""提交事务,但响应体在**提交之前**拼好。
``SessionLocal`` 开着 ``expire_on_commit``(默认值):一提交,Session 里全部
对象都被标记成过期,紧跟着的 ``serializers.xxx(row)`` 就得逐行回库再问一条
SELECT。一次审批因此白问两条(当值那条待办 + 这张单子),发起、改派、抄送、
评论每一处都是同一笔。这里先 flush(本项目的 Session 关着 autoflush,
Python 侧的默认值要靠它落到对象上)、趁对象还在身份映射里把报文拼出来,
最后才提交:报文一字不差,语句少下来。
两条前提写在 ``models`` 的口径里,改表时要一起看:运行中的那几张表
(work/task/read/work_comment/operation_log)没有一列用 ``server_default``,
所以 flush 之后不需要再回库取数据库生成的值;拼报文只读列属性,不碰关系,
不会因为拼报文本身又问出 SELECT 来。
副作用是拼报文时出的 bug 会连带把这次操作回滚掉——宁可让人重试,
也不想看到"报了错、单子在库里已经走完"那种两头不靠的局面。
"""
db.flush()
payload = build() if build is not None else None
db.commit()
return payload
def _commit_step(db: Session, result: engine.StepResult) -> dict:
"""``_commit`` + ``_step_payload``:引擎流转类接口的统一收尾。"""
return _commit(db, lambda: _step_payload(result))
def _run_engine(func_, db: Session, **kwargs) -> engine.StepResult:
try:
return _retry_on_deadlock(db, lambda: func_(db, **kwargs),
what=getattr(func_, "__name__", "流程操作"))
except engine.EngineError as exc:
raise bad_request(str(exc), reason="ENGINE_ERROR") from exc
def _engine_value(func_, db: Session, **kwargs):
"""Same guard as _run_engine for the协同 helpers that do not return a StepResult."""
try:
return _retry_on_deadlock(db, lambda: func_(db, **kwargs),
what=getattr(func_, "__name__", "流程协同操作"))
except engine.EngineError as exc:
raise bad_request(str(exc), reason="ENGINE_ERROR") from exc
# --------------------------- 抄送 / 分享 / 批注 ---------------------------
@router.post("/task/{task_id}/cc")
def cc_task(
task_id: str,
body: schemas.CcBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
rows = _engine_value(
engine.cc_task,
db,
task_id=task_id,
actor=_actor(user),
identities=body.identities,
opinion=body.opinion,
requires_action=body.requires_action,
)
_log_operation(db, user, "cc_task", task_id, f"抄送 {len(rows)} 人", request)
return ok(_commit(db, lambda: _reads_payload(rows)))
@router.post("/work/{work_id}/share")
def share_work(
work_id: str,
body: schemas.ShareBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
rows = _engine_value(
engine.share_work, db, work_id=work_id, actor=_actor(user), identities=body.identities, opinion=body.opinion
)
_log_operation(db, user, "share_work", work_id, f"分享 {len(rows)} 人", request)
return ok(_commit(db, lambda: _reads_payload(rows)))
@router.get("/work/{work_id}/comments")
def list_work_comments(
work_id: str, db: Session = Depends(get_db), user: CurrentUser = Depends(current_user)
) -> dict:
return ok([serializers.work_comment(row) for row in engine.list_comments(db, work_id)])
@router.post("/work/{work_id}/comments")
def add_work_comment(
work_id: str,
body: schemas.CommentBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
row = _engine_value(
engine.add_comment,
db,
work_id=work_id,
actor=_actor(user),
content=body.content,
mentions=body.mentions,
mention_action=body.mention_action,
attachments=body.attachments,
)
_log_operation(db, user, "comment_work", work_id, (body.content or "")[:120], request)
return ok(_commit(db, lambda: serializers.work_comment(row)))
@router.delete("/work/comments/{comment_id}")
def remove_work_comment(
comment_id: str,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
_engine_value(engine.remove_comment, db, comment_id=comment_id, actor=_actor(user))
_log_operation(db, user, "delete_comment", comment_id, "", request)
db.commit()
return ok({"success": True})
# --------------------------------- reads ---------------------------------
@router.get("/read/processing/count")
def count_read(user: CurrentUser = Depends(current_user), db: Session = Depends(get_db)) -> dict:
total = int(
db.execute(
select(func.count(models.Read.id)).where(models.Read.identity == user.ref)
).scalar()
or 0
)
need = int(
db.execute(
select(func.count(models.Read.id)).where(
models.Read.identity == user.ref, models.Read.requires_action.is_(True)
)
).scalar()
or 0
)
return ok({"total": total, "need": need})
@router.get("/read/processing")
def list_read(
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
keyword: str = Query(""),
kind: str = Query(""),
action: str = Query(""),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=200),
) -> dict:
stmt = select(models.Read).where(models.Read.identity == user.ref)
if keyword:
stmt = stmt.where(models.Read.title.like(f"%{keyword}%"))
if kind:
stmt = stmt.where(models.Read.read_type == kind)
if action == "need":
stmt = stmt.where(models.Read.requires_action.is_(True))
elif action == "none":
stmt = stmt.where(models.Read.requires_action.is_(False))
total = count_of(db, stmt)
rows = db.execute(
stmt.order_by(models.Read.start_time.desc()).offset((page - 1) * page_size).limit(page_size)
).scalars().all()
return ok(serializers.page([serializers.read_row(r) for r in rows], total, page, page_size))
@router.get("/read/completed")
def list_read_completed(
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
keyword: str = Query(""),
kind: str = Query(""),
action: str = Query(""),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=200),
) -> dict:
stmt = select(models.ReadCompleted).where(models.ReadCompleted.identity == user.ref)
if keyword:
stmt = stmt.where(models.ReadCompleted.title.like(f"%{keyword}%"))
if kind:
stmt = stmt.where(models.ReadCompleted.read_type == kind)
if action == "need":
stmt = stmt.where(models.ReadCompleted.requires_action.is_(True))
elif action == "none":
stmt = stmt.where(models.ReadCompleted.requires_action.is_(False))
total = count_of(db, stmt)
rows = db.execute(
stmt.order_by(models.ReadCompleted.view_time.desc()).offset((page - 1) * page_size).limit(page_size)
).scalars().all()
return ok(serializers.page([serializers.read_row(r) for r in rows], total, page, page_size))
@router.post("/read/view")
def view_reads_of_work(
body: schemas.ReadWorkBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""打开单据页即登记已阅:返回这一单上被登记掉的待阅条数。"""
rows = _engine_value(engine.mark_reads_for_work, db, job=body.job, actor=_actor(user))
db.commit()
return ok({"count": len(rows)})
@router.post("/read/{read_id}/view")
def view_read(
read_id: str,
body: schemas.ReadViewBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
_engine_value(
engine.mark_read,
db,
read_id=read_id,
actor=_actor(user),
opinion=body.opinion,
attachments=body.attachments,
)
db.commit()
return ok({"success": True})
@router.post("/read/{read_id}/handle")
def handle_read(
read_id: str,
body: schemas.ReadViewBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""抄送需处理:必须填写处理意见(可附图片/文件),登记后进已阅。"""
row = _engine_value(
engine.mark_read,
db,
read_id=read_id,
actor=_actor(user),
opinion=body.opinion,
handling=True,
attachments=body.attachments,
)
_log_operation(db, user, "handle_read", read_id, (body.opinion or "")[:120], request)
return ok(_commit(db, lambda: serializers.read_row(row)))
# ------------------------------- work logs -------------------------------
@router.get("/worklog")
def list_work_logs(
work: str = Query(...),
db: Session = Depends(get_db),
_: CurrentUser = Depends(current_user),
) -> dict:
rows = db.execute(
select(models.WorkLog).where(models.WorkLog.work == work).order_by(models.WorkLog.arrived_time)
).scalars().all()
return ok([serializers.work_log(r) for r in rows])
@router.post("/taskcompleted/{task_completed_id}/reset")
def reset_completed(
task_completed_id: str,
body: schemas.OpinionBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
result = _run_engine(engine.reset_task, db, task_completed_id=task_completed_id, actor=_actor(user), opinion=body.opinion)
_log_operation(db, user, "reset_task", task_completed_id, "撤回已办", request)
return ok(_commit_step(db, result))
# ---------------------------- admin management ---------------------------
#: 流程监控里「所有流程」要跨的两张表:``oa_work`` 只放**在途**单据,办结 / 终止 /
#: 作废的那一刻引擎把整行搬进 ``oa_work_completed``(``engine._finish_work``),在途表
#: 里就再也查不到它了。所以监控只盯着 ``Work`` 看的话,办完的单子等于从监控里消失,
#: 页面永远只有「正在跑的」——这里把两张表并起来,状态筛选才有意义。
_MONITOR_WORK_TABLES: tuple[tuple[str, type], ...] = (("running", models.Work), ("archived", models.WorkCompleted))
def _status_filter(status: str) -> list[str]:
"""状态筛选:留空表示不限,其余支持逗号分隔(``completed,terminated``)。"""
return [chunk.strip() for chunk in (status or "").split(",") if chunk.strip()]
def _work_search_clause(model, like: str):
"""关键字命中标题、单号、流程名与发起人——监控里问得最多的一句就是「谁发的」。"""
return or_(
model.title.like(like),
model.serial.like(like),
model.process_name.like(like),
model.creator_person.like(like),
)
def _monitor_work_part(
user, values, table: str, model, keyword, process, statuses, start_date, end_date, expired, paused: str = "",
*, processes: list[str] | None = None, creator_refs: list[str] | None = None,
archive_start: datetime | None = None, archive_end: datetime | None = None, extra=None,
):
"""一张流程表在监控列表上的取数,只取「主键 + 排序时间 + 来源表」三列。
只 SELECT 三列是有意为之:监控范围最大的能盖住全公司,归档表攒上一年就是几十万行,
连 ``data`` 那坨表单 JSON 一起拉进 Python 再切片,等于每翻一页搬一次全表。
最后那几个关键字参数是给**流程明细导出**开的一档(``service/detail_export.py``),
默认值下行为与原来一字不差。开在这儿、而不是让导出另写一份查询,理由与
:func:`_created_clause` 摆出来给两个消费者共用是同一条:同一套条件写两遍迟早漂开,
漂开的结果是监控页上看得见的单导不出来。
- ``processes``:流程多选;
- ``creator_refs``:创建人账号白名单;空列表是谁都不命中,与 :func:`permissions.scoped`
对空清单的处理同口径;
- ``archive_start`` / ``archive_end``:归档日期。本平台办结 / 终止 / 作废那一刻整行搬进
归档表(``engine._finish_work``),所以归档日期说的就是归档表的 ``finish_time``。在途表
上这一列压根没写值,按列去比只会得到一片 ``NULL`` 假空集,报错方向还指着日期格式;
直接把「在途单没有归档日期可筛」写进 SQL,与下面 ``paused`` 处理缺列那一句同构;
- ``extra``:调用方算好的附加条件,条件对象或 ``model -> 条件`` 的可调用者。待办 / 待阅
那类要按 ``job`` 关联到本行的 ``EXISTS``,两张表得各关联一遍,所以留了可调用者这一档。
"""
stmt = select(
model.id.label("work_id"),
model.start_time.label("sort_time"),
literal(table).label("work_table"),
)
stmt = permissions.scoped(stmt, user, model.creator_identity, values)
if keyword:
stmt = stmt.where(_work_search_clause(model, f"%{keyword}%"))
if process:
stmt = stmt.where(model.process == process)
if statuses:
# 状态不落在这张表的取值上就是查不到,不用特殊跳过:两张表各查各的,并起来正好对
stmt = stmt.where(model.status.in_(statuses))
if start_date:
stmt = stmt.where(model.start_time >= _parse_date(start_date))
if end_date:
stmt = stmt.where(model.start_time < _parse_date(end_date, add_day=True))
expired_flag = tri_state(expired)
if expired_flag is not None:
# 「超时」记在环节待办上:在途单看 oa_task,归档单看 oa_task_completed
task_model = models.Task if model is models.Work else models.TaskCompleted
# 必须关联到本行 job:写成 job IN (子查询) 再取反,SQLAlchemy 会把取反后的
# 条件铺成两张表的笛卡尔积,「只看没超时的」反而每行冒出好几份。
overdue = select(task_model.id).where(
task_model.job == model.job, task_model.expired.is_(True)
).exists()
stmt = stmt.where(overdue if expired_flag else ~overdue)
paused_flag = tri_state(paused)
if paused_flag is not None:
if not hasattr(model, "paused"):
# 挂起只可能发生在在途单上:归档表里没有这一列。问「挂起的单子」就是空集,
# 问「没挂起的」则等于不限——两张表并起来查时这个差别必须说清楚。
if paused_flag:
stmt = stmt.where(literal(False))
else:
stmt = stmt.where(model.paused.is_(paused_flag))
if processes:
stmt = stmt.where(model.process.in_(processes))
if creator_refs is not None:
stmt = stmt.where(model.creator_identity.in_(creator_refs or ["__none__"]))
if archive_start or archive_end:
if table == "running":
stmt = stmt.where(literal(False))
else:
if archive_start:
stmt = stmt.where(model.finish_time >= archive_start)
if archive_end:
stmt = stmt.where(model.finish_time < archive_end)
if extra is not None:
stmt = stmt.where(extra(model) if callable(extra) else extra)
return stmt
def _monitor_work_rows(db: Session, pairs: list[tuple[str, str]], *, with_data: bool = True) -> list:
"""把分页拿到的 (主键, 来源表) 还原成 ORM 对象,顺序仍按数据库排好的来。"""
wanted: dict[str, list[str]] = {}
for work_id, table in pairs:
wanted.setdefault(table, []).append(work_id)
loaded: dict[tuple[str, str], object] = {}
for table, model in _MONITOR_WORK_TABLES:
ids = wanted.get(table)
if not ids:
continue
stmt = select(model).where(model.id.in_(ids))
if not with_data:
stmt = stmt.options(defer(model.data)) # 监控列表不填表,正文留在库里
for row in db.execute(stmt).scalars().all():
loaded[(table, row.id)] = row
return [loaded[(table, work_id)] for work_id, table in pairs if (table, work_id) in loaded]
def _admin_work_page(
db: Session,
user: CurrentUser,
*,
keyword: str = "",
process: str = "",
status: str = "",
start_date: str = "",
end_date: str = "",
expired: str = "",
paused: str = "",
offset: int = 0,
limit: int = 20,
with_data: bool = True,
processes: list[str] | None = None,
creator_refs: list[str] | None = None,
archive_start: datetime | None = None,
archive_end: datetime | None = None,
extra=None,
) -> tuple[list, int]:
"""监控范围内所有流程的一页数据 + 总条数(在途与归档并起来按发起时间倒序)。
``with_data=False`` 只给列表行,不回表单正文;导出走的是默认值,照旧是完整行。
最后那五个参数是给流程明细导出开的一档,口径见 :func:`_monitor_work_part`。
"""
values = permissions.scope_person_refs(db, user)
statuses = _status_filter(status)
parts = [
_monitor_work_part(
user, values, table, model, keyword, process, statuses, start_date, end_date, expired, paused,
processes=processes, creator_refs=creator_refs,
archive_start=archive_start, archive_end=archive_end, extra=extra,
)
for table, model in _MONITOR_WORK_TABLES
]
# 并页口径与「我发起的」完全一致,直接复用 _work_union_page:``count(*) OVER ()``
# 把总条数和本页主键一次问回来(少一趟数据库来回),发起时间相同的行再按来源表与
# 主键定死顺序——监控页翻页时同一张单既不该出现两次,也不该一次都不出现。
return _work_union_page(db, parts, offset=offset, limit=limit, with_data=with_data)
def _overdue_counts(db: Session, rows: list) -> dict[str, int]:
"""这一页单据各自「还压着几个超时候办」,监控页才好一眼看出哪张单卡住了。
只数在途待办:归档单子的超时候办早就办完了,再标一个红点只会指错方向。
"""
jobs = [row.job for row in rows]
if not jobs:
return {}
return dict(
db.execute(
select(models.Task.job, func.count(models.Task.id))
.where(models.Task.job.in_(jobs), models.Task.expired.is_(True))
.group_by(models.Task.job)
).all()
)
def _admin_task_stmt(
db: Session,
user: CurrentUser,
*,
keyword: str = "",
process: str = "",
category: str = "",
identity: str = "",
expired: str = "",
start_date: str = "",
end_date: str = "",
):
"""监控范围(不是本人)内的待办查询条件;列表与导出共用,两边看到的必然是同一批。"""
stmt = permissions.scoped(
select(models.Task),
user,
models.Task.identity,
permissions.scope_person_refs(db, user),
)
# 前置加签在激活前是挂起态,还没真正到人手上,与本人待办列表口径保持一致
stmt = stmt.where(models.Task.add_task_from != "before_pending")
if keyword:
like = f"%{keyword}%"
stmt = stmt.where(
or_(
models.Task.title.like(like),
models.Task.serial.like(like),
models.Task.process_name.like(like),
models.Task.activity_name.like(like),
models.Task.creator_person.like(like),
)
)
if process:
stmt = stmt.where(models.Task.process == process)
if category:
stmt = stmt.where(models.Task.category == category)
if identity:
# 这一列存的是账号;传进来的可能写着 users.id,先归一再比(认不出来就原样比,
# 让"筛出来是空"这件事留在调用方能看懂的地方)
stmt = stmt.where(models.Task.identity == (personref.account_of(db, identity) or identity))
expired_flag = tri_state(expired)
if expired_flag is not None:
stmt = stmt.where(models.Task.expired.is_(expired_flag))
if start_date:
stmt = stmt.where(models.Task.start_time >= _parse_date(start_date))
if end_date:
stmt = stmt.where(models.Task.start_time < _parse_date(end_date, add_day=True))
return stmt
@router.get("/admin/task/processing")
def admin_list_processing(
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("monitor:work")),
keyword: str = Query(""),
process: str = Query(""),
identity: str = Query(""),
expired: str = Query(""),
start_date: str = Query(""),
end_date: str = Query(""),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=200),
) -> dict:
"""流程监控「全部待办」:数据范围内所有人手里还没办完的待办。"""
stmt = _admin_task_stmt(
db, user, keyword=keyword, process=process, identity=identity,
expired=expired, start_date=start_date, end_date=end_date,
)
total = count_of(db, stmt)
rows = db.execute(
stmt.order_by(models.Task.start_time.desc()).offset((page - 1) * page_size).limit(page_size)
).scalars().all()
return ok(serializers.page([serializers.task(r) for r in rows], total, page, page_size))
@router.get("/admin/work/list")
@router.get("/admin/work/processing", include_in_schema=False) # 旧地址,改名前的调用方还能用
def admin_list_works(
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("monitor:work")),
keyword: str = Query(""),
process: str = Query(""),
status: str = Query("", description="留空=全部;running / completed / terminated / canceled,可逗号分隔"),
start_date: str = Query(""),
end_date: str = Query(""),
expired: str = Query("", description="1=只看手里压着超时候办的单子"),
paused: str = Query("", description="1=只看在途被挂起的单子;0=排除被挂起的"),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=200),
with_data: bool = Query(True, description="0=不回表单正文,只要列表行;监控页用它省掉整列 data"),
) -> dict:
"""流程监控:数据范围内的**所有**流程,在途与已办结 / 已终止 / 已作废一起看。
状态留空时两张表并起来查,所以「办完的单子」不会再凭空消失;筛选与分页都留在
数据库里做,监控范围再大也只是多走几条索引。
"""
rows, total = _admin_work_page(
db, user, keyword=keyword, process=process, status=status,
start_date=start_date, end_date=end_date, expired=expired, paused=paused,
offset=(page - 1) * page_size, limit=page_size, with_data=with_data,
)
items = [serializers.work(row, with_data=with_data) for row in rows]
overdue = _overdue_counts(db, rows)
for item in items:
item["expired_tasks"] = int(overdue.get(item["job"], 0))
return ok(serializers.page(items, total, page, page_size))
@router.post("/admin/work/{job}/terminate")
def admin_terminate(
job: str,
body: schemas.TerminateBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
raise not_found("单据不存在或已被删除")
_ensure_in_scope(db, user, work.creator_identity)
result = _run_engine(engine.terminate, db, job=job, actor=_actor(user), opinion=body.opinion or "管理员终止")
_log_operation(db, user, "admin_terminate", job, body.opinion, request)
db.commit()
return ok({"status": result.status})
@router.post("/admin/scheduler/run", dependencies=[Depends(require_permission("system:setting"))])
def run_scheduler_now(db: Session = Depends(get_db)) -> dict:
"""立刻跑一遍定时器(唤醒定时环节 + 处理超时待办)。
后台线程每 60 秒自己跑一次,这里给运维一个手动触发口:刚配好「超时自动处理」
想马上看到效果,不用守着表等下一轮。
"""
woken = engine.wake_delays(db)
expired = engine.mark_expired(db)
return ok({"woken": woken, "expired": expired})
@router.post("/admin/task/{task_id}/press")
def admin_press(
task_id: str,
body: schemas.OpinionBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
) -> dict:
existing = db.get(models.Task, task_id)
if existing is None:
raise not_found("待办不存在")
_ensure_in_scope(db, user, existing.identity)
task = engine.press(db, task_id=task_id, actor=_actor(user), opinion=body.opinion)
return ok(_commit(db, lambda: serializers.task(task)))
@router.post("/admin/task/{task_id}/transfer")
def admin_transfer(
task_id: str,
body: schemas.TransferBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""流程监控里替处理人改派待办。
监控页写着「管理员可干预全部流程与待办」,可除了催办和终止以外,卡住的单子
只能等处理人自己动、或者整条作废:人请假了、离职了、当初派错了,管理员一律
使不上劲。数据范围与终止同一道筛;记账身份仍是被替的那位,操作人落在操作日志里。
"""
existing = db.get(models.Task, task_id)
if existing is None:
raise not_found("待办不存在或已被处理")
_ensure_in_scope(db, user, existing.identity)
result = _run_engine(
engine.transfer, db, task_id=task_id, actor=_actor(user),
identities=body.identities, opinion=body.opinion, admin=True,
)
_log_operation(
db, user, "admin_transfer", task_id,
f"改派给 {len(body.identities)} 人:{'、'.join(body.identities)[:200]}", request,
)
return ok(_commit_step(db, result))
# --------------------------- 流程干预 (intervention) ---------------------------
def _admin_work_or_404(db: Session, user: CurrentUser, job: str):
"""干预类接口共用的一次取数:按 job 找单、并落在操作人的数据范围内。
数据范围跟「终止」用同一道筛:能看见这张单的人才动得了它,不然监控页的
数据范围筛选就成了摆设——列表里查不到,却还能凭一个 job 串改到别人头上。
"""
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
if work is None:
raise not_found("单据不存在或已被删除")
_ensure_in_scope(db, user, work.creator_identity)
return work
@router.post("/admin/work/{job}/suspend")
def admin_suspend(
job: str,
body: schemas.OpinionBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""挂起:单据停在当前环节,待办办不动、超时不计时。
没有挂起这一档时,管理员手里其实只有两件能用的事——催办和把整条流程作废。
「材料要重新核一下、这两天先别往下走」这种最常见的诉求只能靠作废硬扛,
而作废是不可逆的:核完还想接着走,就得让发起人重新填一张单。
"""
work = _admin_work_or_404(db, user, job)
result = _run_engine(engine.suspend, db, job=job, actor=_actor(user), opinion=body.opinion)
_log_operation(db, user, "admin_suspend", job, body.opinion, request)
return ok(_commit(db, lambda: {
"paused": bool(work.paused),
"tasks": len(result.tasks),
**serializers.work(work),
}))
@router.post("/admin/work/{job}/resume")
def admin_resume(
job: str,
body: schemas.OpinionBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""恢复:解冻待办继续流转,挂起占用的那段时间不计算成超时。"""
work = _admin_work_or_404(db, user, job)
result = _run_engine(engine.resume, db, job=job, actor=_actor(user), opinion=body.opinion)
_log_operation(db, user, "admin_resume", job, body.opinion, request)
return ok(_commit(db, lambda: {
"paused": bool(work.paused),
"tasks": len(result.tasks),
**serializers.work(work),
}))
@router.post("/admin/work/{job}/move")
def admin_move(
job: str,
body: schemas.MoveBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""干预改道:把这张单子搬到指定环节重走。
这一档从前是真空地带:走错了环、环节配错人、审批人点了「不同意」却需要重走
某一环——退回只能由当值审批人自己点、而且只能往上游;管理员要么改派要么作废。
改道往前往后都去得,代价写在界面上(当前待办全部结掉进已办、并行分支不接受改道、
挂着在跑的子流程要先表个态),引擎里也照样守得住那道:``work.joins`` 还有没收的票箱
就拒,``cascadeChildren`` 没勾而子单还在跑也拒。
"""
work = _admin_work_or_404(db, user, job)
result = _run_engine(
engine.move, db, job=job, actor=_actor(user), activity=body.activity,
opinion=body.opinion, cascade_children=body.cascade_children,
)
_log_operation(
db, user, "admin_move", job,
f"改道到 {body.activity}:{body.opinion}"
+ ("(一并终止子流程)" if body.cascade_children else ""),
request,
)
return ok(_commit(db, lambda: {
**_step_payload(result),
"current_activity_names": serializers.work(result.work)["current_activity_names"],
}))
@router.get("/admin/work/{job}/reroute-blockers")
def admin_reroute_blockers(
job: str,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
) -> dict:
"""改道页签打开时问一句:这一单上还有什么会跟着一起被搬走。
两件只有管理员该先看见的事:还在跑的嵌入子流程(父单改道会把等它们回来那张票清掉,
子单上那条待办会就此没人认领),以及第三方停在半路等点头的表态(改道一并作废)。
单是面板上那些待办本来就列得出来,不在这里重复。**只读**,一个字段都不改。
"""
work = _admin_work_or_404(db, user, job)
children = engine.running_embed_children(db, work)
staged = node_approve.staged_for_any_activity(db, work.id)
def holders_of(child: models.Work) -> list[str]:
"""这张子单此刻压在谁手上:预检那句话说得出人,管理员才知道该先去找谁。"""
names = {str(name or "").strip() for name in db.execute(
select(models.Task.identity_name).where(models.Task.work == child.id)
).scalars().all()}
return sorted(name for name in names if name)
return ok({
"children": [{
"job": row.job,
"serial": row.serial,
"title": row.title,
"activity_name": row.current_activity_names or row.activity_name,
"holders": holders_of(row),
} for row in children],
# 那句话由引擎说:预检与真动手撞上同一句判据,界面上不会与引擎各讲一套
"blocker": engine.embed_blocker(db, children) if children else "",
"staged_decisions": [
{"app_name": row.app_name, "activity_name": row.activity_name, "decision": row.decision}
for row in staged
],
})
@router.post("/admin/work/{job}/data")
def admin_fix_data(
job: str,
body: schemas.JobDataBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""修正表单数据:金额多打一个 0,不必为了改一位数把整条流程退回重走。
改了什么以「字段:旧值 → 新值」写进流转日志,同时知会当下手里有待办的人与发起人——
单据内容被人改过却查不到痕迹,比填错一位数严重得多。
"""
work = _admin_work_or_404(db, user, job)
result = _run_engine(
engine.fix_data, db, job=job, actor=_actor(user), data=body.data, opinion=body.opinion
)
_log_operation(
db, user, "admin_fix_data", job,
"、".join(list(body.data.keys())[:20]), request,
)
return ok(_commit(db, lambda: serializers.work(result.work)))
@router.post("/admin/work/{job}/press")
def admin_press_work(
job: str,
body: schemas.OpinionBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""整单催办:并行 / 会签一次卡住好几条待办时,逐条点催办不是人干的事。"""
work = _admin_work_or_404(db, user, job)
result = _run_engine(engine.press_work, db, job=job, actor=_actor(user), opinion=body.opinion)
_log_operation(db, user, "admin_press_work", job, f"催办 {len(result.tasks)} 条待办", request)
db.commit()
return ok({"tasks": len(result.tasks)})
@router.post("/admin/work/{job}/transfer")
def admin_transfer_work(
job: str,
body: schemas.TransferBody,
user: CurrentUser = Depends(require_permission("monitor:work")),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""整单改派:把当前每一条待办都换成指定的人办(如整个部门接手)。"""
work = _admin_work_or_404(db, user, job)
result = _run_engine(
engine.transfer_work, db, job=job, actor=_actor(user),
identities=body.identities, opinion=body.opinion,
)
_log_operation(
db, user, "admin_transfer_work", job,
f"整单改派给 {len(body.identities)} 人,动了 {len(result.tasks)} 条待办", request,
)
return ok(_commit_step(db, result))