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

3943 lines
190 KiB
Python
Raw Permalink 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, Iterable
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, inbox as inbox_service, numbering
from ..service import outbox, personref, starters, terminate as terminate_service, titles
from ..service import embed_session, external_check, gate, linkfill, node_approve, org, processdata
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`` 本来就是现读的那一张。
# 在途与办结一起算(这一版改的正是这里):手机端在审批那一屏看的是"此刻"那份配置,
# 单子一办结原本就断档——同一块内容当场从"跟配置"掉回"跟发起那一刻的快照",配表的人在
# 手机端配的「哪几格展示 / 什么顺序 / 每格怎么摆 / 显示条件」在办结回看里全不认,
# 看过的格子平白换一批(2026-11 那句「办结后手机端展示和审批时不一样」缺的就是这一寸)。
# 凭证那一寸照旧不动:``forms``(桌面详情 / 打印 / 导出 / 引擎认值)仍是冻结那一版,
# 这一份只多给手机端当摆法用。口径见 :func:`_forms_live`、docs/mobile-approval-layout.md §4.5。
live_form_ids = list(dict.fromkeys(frozen.form_ids())) if frozen is not None 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``,一个并发位,不串行)。
在途与办结一起算(与 ``live_forms_block`` 配成一对):审批人在手机上看见哪几格,
一半写在表单那几栏展示配置里、一半写在环节这一格;办结之后只放开前一半,
那一环本来被「隐藏」按住的格子会在回看屏上凭空冒出来,同一屏照样对不上号。
"""
if frozen is None:
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)
),
# 抄送:轨迹图上「这一环抄给了谁、他看没看」读的就是这两张表(口径见
# ``service/flowmap.attach_cc``)。两张都按 ``job`` 问、都走各自的索引,与
# 待阅列表那个 ``identity`` 打头的索引互不相干——这里问的是"这一单的",
# 不是"这个人的"。办结搬档时没打开过的那几条留在 ``oa_read`` 里(见
# ``engine._finish_work``),所以归档件也两张都要问,只问已阅会漏掉"抄了没人看"。
"cc_reads": detached(
select(models.Read).where(models.Read.job == job).order_by(models.Read.start_time)
),
"cc_reads_completed": detached(
select(models.ReadCompleted)
.where(models.ReadCompleted.job == job)
.order_by(models.ReadCompleted.start_time)
),
"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,
# 轨迹图:环节坐标 + 每环节/每路由的实时状态,前端照着上色就能画出
# 「走过哪条线、停在哪一环、谁还没办」,不用自己拿流水日志反推。
# 抄送只把 ``cc`` 那一类交给 flowmap(分享 / 批注 @ 我 不是环节配出来的),
# 两张表并一份传进去:待阅是"抄了还没看",已阅是"看过了/办过了"。
"flow": flowmap.build(
definition,
row,
list(tasks),
list(logs),
list(done),
reads=list(loaded["cc_reads"]) + list(loaded["cc_reads_completed"]),
),
"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,
# 办结之后那颗「转发」给不给这个人按:只在**已归档**这一张单上、且只有发起人
# 本人(管理员通吃)。在途件一律不给——那一路走待办上的「抄送」(cc_task 认环节
# 配置),这条通道只补办结之后的缺口。判据与 engine.forward_completed 里那道
# 身份闸同一句话,改了必须两边一起改,否则按钮摆出来一点就是一个 ENGINE_ERROR。
"can_forward": (not running) and (user.is_admin or row.creator == user.person_id),
"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)),
# 这一步归发起人自己、办它叫「提交」(开始环节 / 起草环节),审批环节办它才叫
# 表态。判据在 engine.is_starter_step 那一处,界面上那颗主按钮叫什么、手机上快批
# 那一屏说什么,全认这一格——见前端 utils/taskAction.ts。
"is_starter_step": engine.is_starter_step(node),
"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_scope_clause(model, user: CurrentUser, scope: str):
"""这一格的候选按「这是谁发起的」收:``created`` 只给自已发起的,``related`` 回到「看得见」那一片。
``created`` 这一档**管理员也一样**:``_visible_work_filter`` 放过管理员,说的是他
**看得见**别人的单;这一档问的是「这张单算不算你发起的」,那是一条事实,跟谁在查没关系。
放过管理员会让同一只挑选器在管理员和普通人口中列出两批单子,配的人在自己账号下
试出来的手感就骗人。
"""
if scope == dicts.RELATION_SCOPE_CREATED:
return model.creator_identity == user.ref
return _visible_work_filter(model, user)
def _relation_summary(row, form: dict | None = None) -> dict:
"""关联单选择器与回显共用的那一份摘要:单据本体那几列,外加按需点名的表单那几列。
``form`` 是 :class:`app.service.processdata.FormDisplay` 取出来的那一份(键是字段名,
可能嵌一层),挂在 ``data`` 下回:前端 ``utils/optionMap.ts`` 读 ``data.报销金额``
走的就是点路径,两边不用再造一套写法。没点列就整个键都不回,摘要还是那份轻摘要。
"""
out = {
"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,
}
if form:
out["data"] = dict(form)
return out
@router.get("/work/related")
def search_related_works(
keyword: str = Query(""),
process: str = Query(""),
status: str = Query(
"",
description="逗号分隔的状态档位:completed=归档通过 / running=在办 / closed=已终止或作废。"
"留空或三档都给等于不限;传单据状态原值(terminated、canceled…)也认。",
),
scope: str = Query(
"",
description="候选范围档位:created=只给自已发起的(默认)/ related=与我相关"
"(我发起、我办过、我被抄送)。字段上那一句 ``relationScope`` 原样传过来。",
),
fields: str = Query(
"",
description="逗号分隔的点路径,把 ``optionMap`` / ``picker`` 里那些 ``data.x`` 列名原样传。"
"点了哪几列,摘要里就多一个 ``data``,回的是这几列落成文本的样子;没点不多读表单正文。",
),
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``,照样念得出标题与「已终止」那个角标。
``scope`` 是另一档,问的是「这张单算不算你的」:默认 ``created`` 只列我自己提过的那几张,
不再混进一批我只是批过 / 被抄送过的别人的单(原话:**「选择流程范围不应该是已办,
而是只有我发起的流程」**)。想回到老口径就在设计器里选「与我相关」。
``fields`` 点了哪几列,才把表单正文那一列读回来、只留点名的那几列(见
:class:`app.service.processdata.FormDisplay`):候选行上想写「报销金额 12,000」这种一句,
靠的就是这一句;没点列时摘要还是那份不碰正文的轻摘要。
"""
buckets = dicts.relation_status_query(status)
running_statuses, archived_statuses = dicts.relation_status_tables(buckets)
wanted_scope = scope.strip() if scope.strip() in dicts.RELATION_SCOPES else dicts.RELATION_SCOPE_DEFAULT
form_view = processdata.FormDisplay(db, dicts.clean_relation_display_paths(fields))
parts = [
_work_key_part(model, table, _related_clause(model, user, keyword, process, statuses, wanted_scope))
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=form_view.active
)
return ok(serializers.page(
[_relation_summary(row, form_view.of(row)) for row in rows], total, page, page_size
))
def _related_clause(model, user, keyword, process, statuses, scope=dicts.RELATION_SCOPE_DEFAULT):
"""关联审批单搜索的过滤条件:那一片人(默认=我发起的)AND 那几档状态 AND 关键词。
``statuses`` 是这一张表要挑的单据状态(``None`` = 这一张表不加状态条件)。
``scope`` 是「这一格算谁的单」那一档,见 :func:`_relation_scope_clause`。
"""
clauses = []
in_scope = _relation_scope_clause(model, user, scope)
if in_scope is not None:
clauses.append(in_scope)
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
#: 「按对方表单里那一格认」时点路径里不许出现的写法:筛选(``[k=v]``)、聚合(``.sum(x)``)
#: 那些段是取数那一头的语法,MySQL 的 JSON 路径点不动,认不了就当这一档没配。
_FORM_PATH_BAD = "[]().=~^"
def _form_json_path(path: str) -> str:
"""点路径 → MySQL 的 JSON 路径(``立项编号`` → ``$."立项编号"``);认不了回空串。
只走对象键与数组下标这两段,与 ``fetch.pick_path`` 那一套里「界面存值可能用到的那部分」对齐:
存值列写的是 ``data.某列``,能存下值的也就是这么一格,筛行/聚合那几段存不出值来。
"""
steps = [seg.strip() for seg in (path or "").split(".")]
if not all(steps) or any(seg.strip(_FORM_PATH_BAD) != seg for seg in steps):
return ""
return "$" + "".join('."%s"' % seg.replace('"', "") for seg in steps)
def _form_value_of(row, path: str) -> str:
"""这一行表单正文里那一格的**原文**(回显要把存的值认回这张单,比的就是这一句)。"""
from ..service import fetch # 延迟导入:与 processdata.FormDisplay 同一分寸
value = fetch.pick_path(getattr(row, "data", None) or {}, path)
return "" if isinstance(value, (dict, list)) else str(value or "").strip()
@router.get("/work/summaries")
def work_summaries(
jobs: str = Query("", description="逗号分隔的单据标识:job、单号、或表单里那一格的值都认,混着传也行"),
by: str = Query(
"",
description="这一格存的是哪一列(字段上那份 ``optionMap.valueKey`` 原样传):"
"``job``(默认)/ ``serial`` / ``data.某列``。传了才按存的那一列认回单据。",
),
process: str = Query(
"",
description="字段上限定关联哪一条流程(``relationProcess``)。只有按 ``data.某列`` 认时"
"用得上:把范围收到那一条流程里(``process`` 上有索引),不在两张表上现扫 JSON 正文。",
),
fields: str = Query(
"",
description="与 ``/work/related`` 同一份点路径清单:只读回显也要在标签牌上写出表单里那几列。",
),
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
) -> dict:
"""按 job 批量取单据摘要;看不见的、已经不在了的,静默少返回几条即可。
这一句**不跟着 ``relationScope`` 收窄**:范围那一档只管候选列表列不列它。已经挂在单上的
那几张单(改版前挑的、或别人代挑的)回显还得念得出名字,不能因为挑不进来了就念成一串
job。与状态那三档同一个分寸。
**job 与单号两个名字都认**:``optionMap.valueKey`` 把这一格的存值列改成 ``serial``(设计器里
那句「存为 · 单据编号」)之后,界面上存的就不是 job 而是单号,回显只能拿单号来问。以前只按
``job`` 查,这一格于是念不出标题、也就挂不上 ``/work/:job`` 那个落点——屏幕上摆着一串读得懂、
点不动的单号(见 ``docs/option-source-design.md`` §10)。认的时候 **job 在前、单号在后**:
万一有人把单号起成了别张单的 job,认 job 的那一格不该翻到错的那张单上。已挂上的关联单据
九成套在归档表里,所以那条按单号走的查询要索引,见 ``models.WorkCompleted.serial``。
还有第三种:``by=data.某列``(「关联立项单,存它的立项编号」那一档,只有**限定了流程**的字段
挑得到这一列)。这一档拿 ``by`` + ``process`` 一起来问,就在**那一条流程**的单据里按表单正文
那一格等值认(``process`` 有索引,范围收得住)。认的是那一格的**原文**:字典、附件、明细那几类
「库里存码、界面念名」的列,存下来的与正文里那个不是同一个字,认不到就照旧少回一条——
界面上念得出存着的值、点不开,也比点进一张不相干的单强。
``fields`` 点的那几列走 :class:`app.service.processdata.FormDisplay`,与候选列表同一份取法:
只读那一排标签牌也要写出「报销金额 12,000」,不然编辑态看得见、只读态看不见。
"""
wanted = [item.strip() for item in jobs.split(",") if item.strip()]
if not wanted:
return ok([])
form_view = processdata.FormDisplay(db, dicts.clean_relation_display_paths(fields))
form_path = dicts.form_column_path(dicts.SOURCE_PROCESS, by)
json_path = _form_json_path(form_path) if form_path and process.strip() else ""
wanted_process = process.strip()
by_job: dict[str, dict] = {}
by_serial: dict[str, dict] = {}
by_form: dict[str, dict] = {}
for model in (models.Work, models.WorkCompleted):
# 三个名字都认:存 job、存单号、存对方表单里那一格的值(见函数上那三句)
conds = [model.job.in_(wanted), model.serial.in_(wanted)]
if json_path:
conds.append(
and_(model.process == wanted_process,
func.json_unquote(func.json_extract(model.data, literal(json_path))).in_(wanted))
)
stmt = select(model).where(or_(*conds))
clause = _visible_work_filter(model, user)
if clause is not None:
stmt = stmt.where(clause)
for row in db.execute(stmt).scalars().all():
summary = _relation_summary(row, form_view.of(row) if form_view.active else None)
by_job.setdefault(row.job, summary)
if row.serial:
by_serial.setdefault(row.serial, summary)
if json_path and row.process == wanted_process:
value = _form_value_of(row, form_path)
if value:
by_form.setdefault(value, summary)
# 认的顺序就是准的那一头在前:job > 单号 > 表单里那一格
found = {**by_form, **by_serial, **by_job}
# 按请求里的顺序回,界面不用再排一次;同一张单被两个名字各认中一次也只回一条
out: list[dict] = []
seen: set[str] = set()
for key in wanted:
summary = found.get(key)
if summary is None or summary["job"] in seen:
continue
seen.add(str(summary["job"]))
out.append(summary)
return ok(out)
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(""),
viewed: str = Query(""),
work_status: str = Query(
"",
description=(
"所属单据的流程状态,逗号分隔:running / completed / terminated / canceled,"
"另认 paused 一档(被管理员挂起、暂时办不动的那几条)。留空=不限"
),
),
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, viewed=viewed, work_status=work_status)
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),
inbox: bool = Query(
True,
description="True=统一待办那一张列表的数(含抄送/转发);False=只数我自己的待办(老口径)",
),
) -> dict:
"""待办角标的数。
默认给的是**统一待办**那一张列表的口径:我自己的待办 + 抄送需处理 + 抄送无需处理
(见 :mod:`app.service.inbox`)。``total`` 是侧边栏与底部标签栏那个角标,
``unread`` 是其中"还没点开过"的条数——页眉上「N 条未读」与那颗筛选钮都吃它,
红点本身逐条在列表里给(每行一格 ``unread``)。
``inbox=false`` 退回从前那一句只数 ``oa_task`` 的算法:手机首页那几张卡、流程监控
那些"就看压在手上的真待办"的调用方还在用它,抄送并进来了反而会把数报大。
"""
if not inbox:
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})
counts = inbox_service.count_breakdown(db, identity=user.ref, filters=inbox_service.Filters())
return ok(
{
"total": counts["total"],
"expired": counts["expired"],
"unread": counts["unread"],
"approval": counts["approval"],
"cc_action": counts["cc_action"],
"cc_read": counts["cc_read"],
}
)
# ---------------------- 统一待办(我自己的 + 抄送 / 转发给我的) ----------------------
def _inbox_filters(
*,
keyword: str,
process: str,
category: str,
activity: str,
kinds: str,
source: str,
viewed: str,
expired: str,
work_status: str,
start_date: str,
end_date: str,
) -> inbox_service.Filters:
"""把查询串收成一份 :class:`inbox_service.Filters`,两边各自翻译给自己的表。
``viewed`` 沿用待办列表原来那个参数名(前端早就在用这一串):``0`` = 只看没点开过的,
``1`` = 只看点开过的。它翻成 filters 里反向的那一格 ``unread``——待办认 ``view_time``、
抄送认 ``seen_time``,两张表各自的"看没看过",界面上是同一枚红点。
"""
return inbox_service.Filters(
keyword=(keyword or "").strip(),
process=(process or "").strip(),
category=(category or "").strip(),
activity=(activity or "").strip(),
kinds=tuple(chunk.strip() for chunk in (kinds or "").split(",") if chunk.strip()),
source=(source or "").strip(),
unread={True: False, False: True}.get(tri_state(viewed)),
expired=tri_state(expired),
work_status=tuple(chunk.strip() for chunk in (work_status or "").split(",") if chunk.strip()),
start_from=_parse_date(start_date) if start_date else None,
start_to=_parse_date(end_date, add_day=True) if end_date else None,
)
@router.get("/task/inbox")
def list_inbox(
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
keyword: str = Query(""),
process: str = Query(""),
category: str = Query(""),
activity: str = Query(""),
kind: str = Query("", description="档位,逗号分隔:approval / cc_action / cc_read;留空=全摆"),
source: str = Query("", description="抄送来源:cc / share / comment(只对抄送那两档有效)"),
viewed: str = Query("", description="0=只看未读(红点还亮着),1=只看点开过的"),
expired: str = Query(""),
work_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),
) -> dict:
"""待办列表:我自己的待办,加上抄送 / 转发给我的那几条,并成一页按送达时间倒序摆。
2026-11 的口径(见 :mod:`app.service.inbox` 篇首):抄送需处理、转发需处理都推进待办,
与我自己那一档共用同一套批量操作;不需要处理的抄送 / 转发也在这一张列表里,
看过之后直接归进已阅列表,界面上不再有单独的「待阅」。每行带 ``unread`` 画那枚红点。
"""
filters = _inbox_filters(
keyword=keyword, process=process, category=category, activity=activity, kinds=kind,
source=source, viewed=viewed, expired=expired, work_status=work_status,
start_date=start_date, end_date=end_date,
)
rows, total = inbox_service.page(
db, identity=user.ref, filters=filters, offset=(page - 1) * page_size, limit=page_size
)
items = [inbox_service.payload(row) for row in rows]
# 外部闸门与"就地删除"那两格只对我自己的待办有意义(抄送没有环节可锁、也没有单据可删)
flags = node_approve.lock_flags(
db, [(row.row.process, row.row.activity) for row in rows if row.kind == "approval"]
)
deletable = engine.deletable_task_ids(
db, [row.row for row in rows if row.kind == "approval"], identity=user.ref
)
for item, row in zip(items, rows):
if row.kind == "approval":
item["oa_locked"] = bool((flags.get((row.row.process, row.row.activity)) or {}).get("locked"))
item["deletable"] = row.row.id in deletable
return ok(serializers.page(items, total, page, page_size))
def _inbox_scope(
db: Session, user: CurrentUser, scope: dict, *, unread_only: bool
) -> tuple[list[tuple[str, str]], int]:
"""「按当前筛选全选这一片」→ ``[(来源表, 主键), ...]`` + 留在上限外面的条数。
``unread_only`` 与待办那一路同一个用意:「全选后批量标记已读」默认只取红点还亮着的
那几条,早被点开的那几条没活干,别把 ``BATCH_LIMIT`` 的额度占住把真要处理的挤成超限。
"""
scope = scope if isinstance(scope, dict) else {}
filters = _inbox_filters(
keyword=str(scope.get("keyword") or ""),
process=str(scope.get("process") or ""),
category=str(scope.get("category") or ""),
activity=str(scope.get("activity") or ""),
kinds=str(scope.get("kind") or scope.get("kinds") or ""),
source=str(scope.get("source") or ""),
viewed="0" if unread_only else str(scope.get("viewed") or ""),
expired=str(scope.get("expired") or ""),
work_status=str(scope.get("work_status") or ""),
start_date=str(scope.get("start_date") or ""),
end_date=str(scope.get("end_date") or ""),
)
return inbox_service.ids_for_scope(db, identity=user.ref, filters=filters, limit=BATCH_LIMIT)
def _inbox_selection(
db: Session, user: CurrentUser, ids: list[str], scope: dict, *, unread_only: bool
) -> tuple[list[tuple[str, str]], int]:
"""把「勾了哪几条 / 按筛选全选了这一片」折成 ``[(来源表, 主键)]`` + 超限条数。
两个都给了以 ``ids`` 为准(屏幕上勾着什么就动什么),与 ``_batch_selection`` 同一分寸。
勾上来的 id 认不出归哪张表:按两张表各问一条 ``IN``(这一页最多 50 条,两条 IN 不贵)。
两张表都认不出的原样按待办交下去,由逐条那一路报「不存在或不是本人名下」——
条数不吞,界面上说得出是哪一条。
"""
picked = _clean_ids(ids)
if picked:
tasks = set(
db.execute(
select(models.Task.id).where(models.Task.id.in_(picked), models.Task.identity == user.ref)
).scalars().all()
)
reads = set(
db.execute(
select(models.Read.id).where(models.Read.id.in_(picked), models.Read.identity == user.ref)
).scalars().all()
)
pairs = [("task", item) for item in picked if item in tasks]
pairs += [("read", item) for item in picked if item in reads]
pairs += [("task", item) for item in picked if item not in tasks and item not in reads]
return pairs, 0
return _inbox_scope(db, user, scope, unread_only=unread_only)
@router.post("/task/inbox/seen")
def mark_inbox_seen(
body: schemas.InboxSeenBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""批量"看过了":勾到的那几条红点熄灭,行照旧留在待办里(不表态、不流转)。
口径与逐条的 ``POST /task/{id}/view`` 一字不差。并页之后一次勾选可能同时含我自己的
待办与抄送需处理,两边动的是两张表、两个时间戳列,这里按档位分开走再并成一份账单——
界面上报的还是那一句「标了 8 条,2 条早就标过」。只需阅那几条顺手登记已阅
(点开即走,单独标"看过"没意义),那几条算在 ``marked`` 里、当场离开待办进已阅。
"""
pairs, truncated = _inbox_selection(db, user, body.ids, body.scope, unread_only=True)
if not pairs:
raise bad_request("请先选择要标记的待办", reason="EMPTY_SELECTION")
actor = _actor(user)
marked = already = failed = 0
errors: list[dict] = []
task_ids = [row_id for table, row_id in pairs if table == "task"]
read_ids = [row_id for table, row_id in pairs if table == "read"]
if task_ids:
result = _engine_value(engine.mark_tasks_viewed, db, task_ids=task_ids, actor=actor)
marked += result.marked
already += len(result.already)
failed += len(result.failed)
errors.extend(result.failed)
if read_ids:
result = _engine_value(engine.mark_reads_seen, db, read_ids=read_ids, actor=actor)
marked += result.marked
already += len(result.already)
failed += len(result.failed)
errors.extend(result.failed)
if marked:
_log_operation(
db, user, "batch_seen_inbox", str(marked),
f"批量标记待办已读:{marked} 条,早已标记 {already} 条,超限未处理 {truncated} 条", request)
return ok(_commit(db, lambda: {
"marked": marked,
"failed": failed,
"already": already,
"errors": errors,
"truncated": truncated,
}))
@router.post("/task/inbox/execute")
def execute_inbox_batch(
body: schemas.InboxExecuteBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""统一待办上的批量"处理":我自己的待办逐条流转,抄送需处理的那几条登记处理意见。
一张列表里混着两档要动手的东西,出口不一样:待办要选走哪条路由、要过表单必填校验;
抄送需处理只要本人点一次「处理」(引擎 ``mark_read`` 认的是这一颗钮,随附的那句
意见可留空)。这里按档位分开走、并成一份账单——人不必为"这批里混了三条抄送"再挑一遍。
逐条口径与两条老路一字不差:待办走 :func:`engine.execute_task`(一条一个存档点,
某条因必填没填而失败只回滚那一条);抄送走 :func:`engine.mark_read` 的 ``handling``
那一趟(这一档办完的行离开待办,界面上归**已办**,见 :mod:`app.service.completed`)。
老的 ``/task/batch-execute`` 留着不动:流程监控与单据页那些只动待办的调用方不必跟着改。
"""
pairs, truncated = _inbox_selection(db, user, body.ids, body.scope, unread_only=False)
if not pairs:
raise bad_request("请先选择要处理的待办", reason="EMPTY_SELECTION")
actor = _actor(user)
succeeded: list[dict] = []
failed: list[dict[str, str]] = []
# 处理意见改成选填之后这一档恒为空:留着这个口子是给"下一条要求表态、又不许空着办"
# 的那种动作,账单的形状(succeeded / failed / skipped / truncated)不因此改
skipped: list[dict] = []
opinion = (body.opinion or "").strip()
for table, row_id in pairs:
if table == "read":
try:
done = _engine_value(
engine.mark_read,
db,
read_id=row_id,
actor=actor,
opinion=opinion,
handling=True,
attachments=body.attachments,
)
except Exception as exc: # noqa: BLE001 - 一条失败不能带走整批
db.rollback()
failed.append({"id": row_id, "message": _failure_message(exc)})
continue
# 一条一个存档点,与待办那一路同样收尾:mark_read 只 flush,提交在这儿。
# 少这一句就是"报了成功、库里那条还躺在待阅里"——一批里全是抄送时后面再没有
# 别的提交点,整批随请求收尾一起回滚,人只在下一屏发现那几条红点和行都还在。
_log_operation(db, user, "batch_handle_inbox", row_id, opinion[:120], request)
succeeded.append(_commit(db, lambda done=done: {
"id": row_id, "job": done.job, "work": done.work, "read": True
}))
continue
try:
result = _run_engine(
engine.execute_task,
db,
task_id=row_id,
actor=actor,
route_name=body.route_name,
opinion=body.opinion,
)
except Exception as exc: # noqa: BLE001 - 单条失败不能带走整批
db.rollback()
failed.append({"id": row_id, "message": _failure_message(exc)})
continue
_log_operation(
db, user, "batch_execute_inbox", row_id, f"批量处理待办,路由:{body.route_name}", request)
succeeded.append(_commit_step(db, result))
return ok(
{
"succeeded": len(succeeded),
"failed": len(failed),
"results": succeeded,
"errors": failed,
# 一条都没动的抄送(选填意见之后通常是空):不是失败,界面上单独说
"skipped": len(skipped),
"skipped_items": skipped,
"truncated": truncated,
}
)
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",
viewed: str = "",
work_status: str = "",
):
return select(model).where(
*_task_conditions(
model, user, keyword, process, category, activity, expired, start_date, end_date,
date_field, viewed, work_status,
)
)
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",
viewed: str = "",
work_status: str = "",
) -> 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))
viewed_flag = tri_state(viewed) if hasattr(model, "view_time") else None
if viewed_flag is not None:
# 读没读过:待办列表要按它筛「只看没点开过的」,批量标记已读那一路更要按它取范围
# (否则「全选当前筛选」会把刚标过的那几条再盖一次章,界面上白报几条)。
# 已办行上也带这一列(抄自待办),所以只有认得出这一列的模型才吃这个条件。
conditions.append(
model.view_time.is_not(None) if viewed_flag else model.view_time.is_(None))
conditions.extend(_task_work_status_conditions(model, work_status))
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
#: 待办 / 已办上「流程状态」这一档认的取值:四个流程状态 + 干预那一档的冻结标记,
#: 与流程监控、「我发起的」、流程明细导出用的是同一套词(那一份多选把 paused 与四个
#: 状态并列摆着,见 ``service/detail_export.status_filter``),别在这里另立一套名字。
TODO_WORK_STATUSES = ("running", "completed", "terminated", "canceled", "paused")
def _task_work_status_conditions(model, work_status: str) -> list:
"""按**所属单据**的流程状态筛待办 / 已办;留空 = 不限,其余逗号分隔(``running,paused``)。
待办行自己那一份 ``status`` 只有 ``pending`` 一个值,说的是这条待办办没办完,
不是流程走到了哪儿;流程状态住在 ``oa_work.status`` 上,而办结 / 终止 / 作废那一刻
整行搬进 ``oa_work_completed``、``oa_task`` 里那些行跟着删掉(``engine._finish_work``
末尾那句清的就是幽灵行)。所以「在途」= 这张单的 ``work`` 还在运行表里,
「已办结 / 已终止 / 已作废」= 它已经在归档表里且 ``status`` 对得上。两张表各挂一条
相关 EXISTS 并成一串 OR 塞进同一条语句——按 ``work`` 比主键、走各自的唯一索引,
一次来回都不多(每接口的语句条数是当回归线守着的,见 scripts/perf_guard.py)。
认不出的取值不掺进任何一档。健康库里待办只会落在「在途」上,那三档归档
状态是给没清干净的幽灵行与已办列表留的口子:已办行底下那张单早就可能已经走完,
「我办过的那些单,现在都办结了么」问的就是这一档。
``paused`` 不在 ``status`` 里(挂起是运行中的冻住开关,不是流程的一种结局,
见 :func:`app.engine.engine.suspend`),判据与列表上「已挂起」那枚角标同一份
(``Task.pause``:挂起时引擎跟着盖、恢复时跟着摘),筛出来的与画出来的必然同一批。
"""
wanted = _status_filter(work_status)
if not wanted:
return []
values = [item for item in wanted if item in TODO_WORK_STATUSES]
statuses = [item for item in values if item != "paused"]
branches: list = []
if "running" in statuses:
branches.append(select(models.Work.id).where(models.Work.id == model.work).exists())
archived = [item for item in statuses if item != "running"]
if archived:
branches.append(
select(models.WorkCompleted.id)
.where(models.WorkCompleted.id == model.work, models.WorkCompleted.status.in_(archived))
.exists()
)
if "paused" in values and hasattr(model, "pause"):
branches.append(model.pause.is_(True))
# 一个都落不到这张表上(已办行没有挂起这一列,或对方传了个认不出的状态):
# 宁可对出一张空列表,也不要在"筛了"这件事上静默回一份没筛过的全量。
return [or_(*branches)] if branches else [literal(False)]
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
def _done_filters(
user: CurrentUser, keyword: str, process: str, category: str,
start_date: str, end_date: str,
) -> completed_service.DoneFilters:
"""已办那一份筛选:列表、导出、首页面板共用一句话,两张表各自翻译。
日期解析留在这里(而不是 ``DoneFilters`` 里):格式不对要回的是那句
「日期格式错误」,那是接口层的话术,服务层只管按 datetime 筛。
"""
return completed_service.DoneFilters(
identity=user.ref,
keyword=keyword,
process=process,
category=category,
start_from=_parse_date(start_date) if (start_date or "").strip() else None,
start_to=_parse_date(end_date, add_day=True) if (end_date or "").strip() else None,
)
@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`` 说明这一档被本人办过几次,历次表态在单据详情的审批记录里一条不少。
这一屏读的是**两本账**(2026-11 口径):环节上的表态,加上办完的「抄送 / 转发
需处理」(``oa_read_completed`` 上 ``requires_action=1`` 的那几条,出参多带
``done_source="cc"``)。不需处理的那几条不在这里——它们看过就算完,归**已阅**
(``GET /read/completed`` 那一侧同一格反向筛)。判据在库里本来就有,所以历史上
早就办完、一直躺在已阅里的那几条,今天自动挪到这儿来,不用回填。
``total`` 跟着一起换成「办过几个组」,否则页眉的条数比翻得到的多。
每一行还带这张单**此刻**的去处:``work_status`` / ``current_activity_name`` /
``current_handlers`` / ``work_paused``。已办行上冻着的那一份 ``current_activity_name``
只在归档那一刻才写,在途单读出来是空串,所以这三格现问单据本尊(口径见
:func:`app.service.completed.progress`)——「我办过的那几步,现在都走到哪儿了」
问的就是它,界面上那一列叫「当前环节」。
"""
filters = _done_filters(user, keyword, process, category, start_date, end_date)
groups, total = completed_service.collapse(
db, filters, offset=(page - 1) * page_size, limit=page_size
)
# 只有环节上的表态谈得上撤回:抄送处理没有出口,撤它等于改动一份已归档的表态
flags = _recall_flags(
db, [group.row for group in groups if group.source == completed_service.SOURCE_APPROVAL]
)
states = completed_service.progress(db, [group.work for group in groups])
items = []
for group in groups:
is_cc = group.source == completed_service.SOURCE_CC
payload = (
serializers.read_completed_as_done(group.row) if is_cc
else serializers.task_completed(group.row)
)
# handle_count:这一档被本人办过几次。折叠成一条之后总得让人知道底下还有几次,
# 否则「我明明退回去过一次,怎么少了一条」就只能靠点进详情自己数。
payload["handle_count"] = group.handles
payload["done_source"] = group.source
payload.update(_progress_fields(states.get(group.work), payload))
if not is_cc:
payload.update(flags.get(group.row.id, {"recallable": None, "recall_blocker": ""}))
items.append(payload)
return ok(serializers.page(items, total, page, page_size))
def _progress_fields(state, payload: dict) -> dict:
"""把「这张单此刻走到哪儿」摊成已办出参那几格。
``state`` 为 ``None`` 是两张单据表里都找不到这张单(删掉的、历史脏数据):
留着行上那份旧快照说事儿,不把它抹成空串——空得越彻底,人越分不清「没走到」
和「查不着」。
"""
stale = str(payload.get("current_activity_name") or "")
if state is None:
return {
"work_status": "",
"current_activity_name": stale,
"current_handlers": "",
"work_paused": False,
}
return {
"work_status": state.status,
"current_activity_name": state.activity_names or stale,
"current_handlers": state.handlers,
"work_paused": state.paused,
}
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)})
def _clean_ids(raw: Iterable[str]) -> list[str]:
"""去空白、去重复,顺序照人勾选的次序留着(界面按这个次序回逐条原因)。"""
out: list[str] = []
for item in raw or []:
value = str(item or "").strip()
if value and value not in out:
out.append(value)
return out
def _batch_window(ids: list[str]) -> tuple[list[str], int]:
"""切出这一次真正要动的条数,并回被上限留下的条数。
超出 ``BATCH_LIMIT`` 的那几条不是「办完了」也不是「办砸了」,是一条都没碰。从前静悄悄
切掉,界面上就成了「勾 60 条回 50 条成功」,剩下 10 条谁也没提,人以为整批都办了。
这里把差额原样回出来让他再勾一批;不直接 400——勾上就是想要整批办掉,先让他看见差多少。
"""
return ids[:BATCH_LIMIT], max(0, len(ids) - BATCH_LIMIT)
def _task_scope_ids(db: Session, user: CurrentUser, scope: dict, *, unread_only: bool) -> list[str]:
"""「按当前筛选全选」解析成待办 id:用的就是 ``GET /task/processing`` 那一份筛选。
界面上「全选」这个动作有两种做法:一种只勾当前这一页(翻页翻走的几条漏办),另一种把
筛选条件交回服务端取整片。批量是体力活的省力开关,漏办比多问一次库严重得多,所以走后者。
条件只有一份(:func:`_task_conditions`),列表筛出几条、批量就动几条,不会出现「页眉写着
12 条、批量只办了 8 条」;身份也只认这一份 —— 别人的单子筛不到,也就批量不到。
``unread_only``:「全选后批量标记已读」默认只取没点开过的那几条。整片里早被点开的那些
本来就没什么可动的,留着它们只会把 50 条的额度占住,把真要处理的几条挤成 ``truncated``。
"""
scope = scope if isinstance(scope, dict) else {}
stmt = _task_filter(
models.Task, user,
keyword=str(scope.get("keyword") or ""),
process=str(scope.get("process") or ""),
category=str(scope.get("category") or ""),
activity=str(scope.get("activity") or ""),
expired=str(scope.get("expired") or ""),
start_date=str(scope.get("start_date") or ""),
end_date=str(scope.get("end_date") or ""),
viewed="0" if unread_only else str(scope.get("viewed") or ""),
work_status=str(scope.get("work_status") or ""),
)
rows = db.execute(
stmt.order_by(models.Task.start_time.desc(), models.Task.id.desc()).limit(BATCH_LIMIT)
).scalars().all()
# 这一沓原样交出去,**不**在这里替人筛掉「表态已交给外部系统」的那几条:列表上那些行
# 的勾是灰的,但批量这一路逐条回的原因里写清了去哪儿办(与「手动硬勾上照样提交」同一条
# 口径)。在这里悄悄筛掉,报出来的就成了「几条没动」,人还得自己猜为什么。
# 被上限挡在外面的条数照实报(整片可能几百条,只报「1 条超限」是骗人):数的是同一条
# WHERE,所以「列表上共几条」与「动了的几条 + 留下的几条」永远对得平。
return [row.id for row in rows], max(0, count_of(db, stmt) - len(rows))
def _read_scope_ids(db: Session, user: CurrentUser, scope: dict) -> tuple[list[str], int]:
"""待阅那一路的「按筛选取整片」,筛选条件与 ``GET /read/processing`` 一字不差。"""
scope = scope if isinstance(scope, dict) else {}
conditions: list = [models.Read.identity == user.ref]
keyword = str(scope.get("keyword") or "").strip()
if keyword:
conditions.append(models.Read.title.like(f"%{keyword}%"))
kind = str(scope.get("kind") or "").strip()
if kind:
conditions.append(models.Read.read_type == kind)
action = str(scope.get("action") or "").strip()
if action == "need":
conditions.append(models.Read.requires_action.is_(True))
elif action == "none":
conditions.append(models.Read.requires_action.is_(False))
stmt = select(models.Read.id).where(*conditions)
rows = db.execute(
stmt.order_by(models.Read.start_time.desc(), models.Read.id.desc()).limit(BATCH_LIMIT)
).scalars().all()
total = int(db.execute(select(func.count()).select_from(stmt.subquery())).scalar() or 0)
return [str(row) for row in rows], max(0, total - len(rows))
def _batch_selection(
db: Session, user: CurrentUser, ids: list[str], scope: dict, *, kind: str, unread_only: bool
) -> tuple[list[str], int]:
"""把「勾了哪几条 / 按筛选全选了这一片」两种说法折成一份待办清单 + 超限条数。
两个都给了以 ``ids`` 为准:屏幕上勾着什么就动什么,比再问一遍库更贴近人看见的那几行
(筛选在勾选这段时间里可能被别人改过,库里的答案不一定是他勾的那几行)。
"""
picked = _clean_ids(ids)
if picked:
return _batch_window(picked)
scope = scope if isinstance(scope, dict) else {}
if not scope:
return [], 0
resolved, spilled = (_task_scope_ids(db, user, scope, unread_only=unread_only)
if kind == "task" else _read_scope_ids(db, user, scope))
# 按筛选取的整片已经在库里切到上限,``spilled`` 是留在外面的条数(要照实报给人看)
return resolved, max(0, spilled)
@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, truncated = _batch_selection(
db, user, body.task_ids, body.scope, kind="task", unread_only=False)
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,
# 超出单次上限被留下的条数:一条都没动,所以既不在 succeeded 也不在 failed 里
"truncated": truncated,
}
)
@router.post("/task/view/batch")
def view_tasks_batch(
body: schemas.TaskViewBatchBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""批量标记待办已读:勾几条、或按当前筛选全选这一片,把没点开过的补上已读时间。
待办列表上那一格「已读」以前只能靠进详情页顺带盖上(见 ``POST /task/{id}/view``),
一屏十几条要点十几下。这一条与待阅那个 ``POST /read/view/batch`` 同一分寸:**只盖章、
不表态**——单子还压在手上,出口、超时、审批记录一概不动,所以「我已经看过了、待会儿再批」
这种真实节奏第一次有地方落。也正因为不表态,它比批量审批安全得多:不需要共同出口、
不撞必填校验,误操作最多是已读时间提前了几分钟。
逐条口径照单条那一条(``engine.mark_tasks_viewed``):已有已读时间的原样不动、算
``already`` 不算失败;不存在或不是本人名下的进 ``failed`` 并带逐条原因。
"""
task_ids, truncated = _batch_selection(
db, user, body.task_ids, body.scope, kind="task", unread_only=True)
if not task_ids:
raise bad_request("请先选择要标记的待办", reason="EMPTY_SELECTION")
result = _engine_value(
engine.mark_tasks_viewed, db, task_ids=task_ids, actor=_actor(user))
if result.marked:
_log_operation(
db, user, "batch_view_task", str(result.marked),
f"批量标记待办已读:{result.marked} 条,早已标记 {len(result.already)} 条,"
f"超限未处理 {truncated} 条", request)
return ok(_commit(db, lambda: {
"marked": result.marked,
"failed": len(result.failed),
"already": len(result.already),
"already_items": result.already,
"errors": result.failed,
"truncated": truncated,
}))
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.post("/work/{work_id}/forward")
def forward_completed(
work_id: str,
body: schemas.ForwardBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""转发一张**已办结**的单据:发起人把它再交给若干人看,每人一条待阅。
鉴权挂法与 /work/{work_id}/share 一字不差——只要求登录(current_user),不挂权限点:
这张单能不能由这个人转发,认的是"是不是发起人本人(或管理员)",那是数据级的所有权
判断,归引擎那道身份闸(engine.forward_completed),不是一个可以在菜单里勾的功能点。
界面那侧看详情报文里的 can_forward 决定按钮摆不摆。
"""
rows = _engine_value(
engine.forward_completed,
db,
work_id=work_id,
actor=_actor(user),
identities=body.identities,
opinion=body.opinion,
requires_action=body.requires_action,
)
_log_operation(db, user, "forward_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(""),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=200),
) -> dict:
"""我的已阅:**只剩「无需处理」那一档**。
2026-11 口径分家:抄送 / 转发**不需处理**的那几条看过就算完,归这一屏;
**需处理**的那几条办完之后归**已办**(``GET /task/completed``,判据同一个
``requires_action``,两边各认一半、加起来就是全部归档行)。所以这一屏不再收
``action`` 那只筛选钮——留着一档永远为空的选项比少一个选项更绕。
"""
stmt = select(models.ReadCompleted).where(
models.ReadCompleted.identity == user.ref,
models.ReadCompleted.requires_action.is_(False),
)
if keyword:
stmt = stmt.where(models.ReadCompleted.title.like(f"%{keyword}%"))
if kind:
stmt = stmt.where(models.ReadCompleted.read_type == kind)
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/view/batch")
def view_reads_batch(
body: schemas.ReadBatchBody,
user: CurrentUser = Depends(current_user),
db: Session = Depends(get_db),
request: Request = None, # type: ignore[assignment]
) -> dict:
"""批量登记待阅:一次勾几条,逐条成事,坏一条不带走整批。
一屏待阅多数是“这些我都扫过了”,一条条点「标记已阅」要点十几下。口径与单条一字不差:
不要求处理的直接登记;要求处理的那几条看 ``handling``:这一趟是「批量处理」就一起办掉
(那句共用的处理意见**可以留空**,2026-11 改的),这一趟只是「标记已读」就原样留着
(``skipped`` 报的是哪几条、为什么),绝不替人把该表的态表掉。
办完的那几条界面上归**已办**,看过的那几条归**已阅**,同一张归档表按
``requires_action`` 分家(读法见 :mod:`app.service.completed`)。
不存在、或不是本人名下的那几条只算它们自己失败,其余照常登记。另报两档:勾到时早已
在本人已阅里的那几条归 ``already``(列表页被页签缓存住,刚在单据页看过的那一条
还挂在勾选里,那是办完了不是办砸了);超过单次上限被切掉的条数归 ``truncated``,
那几条一条都没碰,不进 marked/handled/skipped/failed 任何一档。
"""
# 勾上来的那几条优先;一条没勾但给了筛选,就按待阅列表那一份筛选取整片
ids, truncated = _batch_selection(db, user, body.ids, body.scope, kind="read", unread_only=True)
if not ids:
raise bad_request("请先选择要登记的待阅", reason="EMPTY_SELECTION")
result = _engine_value(
engine.mark_reads_batch,
db,
read_ids=ids,
actor=_actor(user),
opinion=body.opinion,
handling=body.handling,
attachments=body.attachments,
)
if result.marked or result.handled:
_log_operation(
db, user, "batch_view_read", str(result.marked + result.handled),
f"批量登记待阅:已阅 {result.marked} 条,处理 {result.handled} 条,"
f"早已登记 {len(result.already)} 条,超限未处理 {truncated} 条", request)
return ok(_commit(db, lambda: {
"marked": result.marked,
"handled": result.handled,
"skipped": len(result.skipped),
"failed": len(result.failed),
# 勾到时已经在本人已阅里的那几条:单列一档,界面才报得准(它们是办完了,不是失败)
"already": len(result.already),
"already_items": result.already,
# 逐条原因带回去:界面上“跳过了 2 条”要说得出是哪两条、为什么
"skipped_items": result.skipped,
"errors": result.failed,
# 被上限切掉的条数:一条都没登记,所以也不在以上任何一档里
"truncated": truncated,
}))
@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:
"""抄送 / 转发需处理:本人点一次「处理」就算办完,意见**选填**(可附图片/文件)。
办完这一条在界面上归**已办**(``GET /task/completed`` 里 ``done_source="cc"`` 的那些),
不再躺在已阅里;不需处理的那几条走的还是「点开单据页即已阅」那一条路。
"""
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))