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

1861 lines
92 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.

"""开放平台 -- 给外部系统的两套接口,写在一个文件里是因为它们共用一套鉴权与留痕。
分成两半:
* ``router``:**管理面**(``/design/open/*``),本系统界面上用,权限码 ``design:openapi``。
* ``open_router``:**数据面**(``/open/*``),外部系统用,用应用令牌鉴权,不走本系统的
登录会话,也不吃菜单权限码——否则对方要做的第一件事就是"给这个机器人建一个员工账号"。
**对外契约与内部视图刻意分开**:内部列表接口改字段是常事,外部对接一改就要拉对方一起
发版。所以这里的响应字段是自己定、自己稳的一份,宁可有冗余也不跟着内部结构漂。
"""
from __future__ import annotations
import re
import time
from datetime import datetime, timedelta
from typing import Any
from fastapi import APIRouter, Depends, Query, Request, Response
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from sqlalchemy import func, or_, select
from sqlalchemy.orm import Session
from .. import dbconfig, models, schemas
from ..db import get_db
from ..deps import CurrentUser, client_ip, current_user, require_permission
from ..engine import definition as definition_module, engine
from ..envelope import ApiError, bad_request, forbidden, not_found, ok, unauthorized
from ..security import hash_token
from ..service import (autofill, drafts, embed_session, events, external_check, node_approve, numbering, openauth, org, personref, starters, tasktrail)
from ..storage import StorageError, resolve_uri
from ..storage.http import download_response, storage_error
router = APIRouter(tags=["open-platform"])
open_router = APIRouter(tags=["open"])
CODE_RE = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
LIST_LIMIT = 200
bearer = HTTPBearer(auto_error=False, description="POST /open/token 换来的访问令牌")
def _stamp(value: datetime | None) -> str:
return value.strftime("%Y-%m-%d %H:%M:%S") if value else ""
def _log(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 app_view(db: Session, row: models.OpenApp) -> dict:
usage = openauth.usage(db, row.code)
return {
"id": row.id,
"code": row.code,
"name": row.name,
"enabled": row.enabled,
"appKey": row.app_key,
"secretHint": row.secret_hint,
"scopes": list(row.scopes or []),
"rateLimitQpm": row.rate_limit_qpm,
"tokenTtlSeconds": row.token_ttl_seconds,
"remark": row.remark,
"creatorName": row.creator_name,
"createTime": _stamp(getattr(row, "create_time", None)),
"lastUsedAt": _stamp(row.last_used_at),
"updateTime": _stamp(getattr(row, "update_time", None)),
**usage,
}
def get_app(db: Session, code: str) -> models.OpenApp | None:
return db.execute(select(models.OpenApp).where(models.OpenApp.code == str(code).strip())).scalar_one_or_none()
def _clean_app(body: schemas.OpenAppBody) -> dict:
scopes = [str(item) for item in (body.scopes or []) if str(item) in openauth.SCOPE_KEYS]
if not str(body.name or "").strip():
raise bad_request("要给这个应用起个名字,调用记录里认得出是谁")
qpm = int(body.rate_limit_qpm or 0)
if not 0 <= qpm <= 100000:
raise bad_request("每分钟调用上限需要在 0-100000 之间(0 = 不限)")
ttl = int(body.token_ttl_seconds or 7200)
if not 60 <= ttl <= 86400:
raise bad_request("访问令牌有效期需要在 60-86400 秒之间")
return {
"name": str(body.name).strip(),
"enabled": bool(body.enabled),
"scopes": scopes or list(openauth.DEFAULT_SCOPES),
"rate_limit_qpm": qpm,
"token_ttl_seconds": ttl,
"remark": str(body.remark or "").strip(),
}
@router.get("/design/open/catalog")
def catalog(_: CurrentUser = Depends(require_permission("design:openapi"))) -> dict:
"""界面上所有下拉与文档内容:授权范围、事件清单、接口清单。"""
return ok({
"scopes": [{"value": key, "label": label, "api": api} for key, label, api in openauth.SCOPES],
"defaultScopes": list(openauth.DEFAULT_SCOPES),
"events": [{"value": key, "label": label, "when": when} for key, label, when in events.CATALOG],
"apis": [
{"method": "POST", "path": "/api/v1/open/token", "scope": "", "title": "换访问令牌"},
{"method": "GET", "path": "/api/v1/open/processes", "scope": "process:read", "title": "可发起的流程"},
{"method": "POST", "path": "/api/v1/open/works", "scope": "work:write", "title": "发起单据"},
{"method": "POST", "path": "/api/v1/open/drafts", "scope": "draft:write", "title": "建流程草稿(任意类型)"},
{"method": "GET", "path": "/api/v1/open/drafts", "scope": "draft:read", "title": "查某个人的草稿"},
{"method": "GET", "path": "/api/v1/open/works", "scope": "work:read", "title": "查单据列表"},
{"method": "GET", "path": "/api/v1/open/works/{job}", "scope": "work:read", "title": "查单据详情、流转与已办台账(撤回已办的 id 在这儿)"},
{"method": "POST", "path": "/api/v1/open/works/{job}/terminate", "scope": "work:write", "title": "终止单据"},
{"method": "GET", "path": "/api/v1/open/tasks", "scope": "task:read", "title": "查某个人的待办"},
{"method": "POST", "path": "/api/v1/open/tasks/{task_id}/execute", "scope": "task:write", "title": "处理一条待办"},
{"method": "POST", "path": "/api/v1/open/nodes/locate", "scope": "task:read", "title": "拉取式定位:按单号或查找字段取回当前所在流程与环节(带 detail=full 才回接口卡片)"},
{"method": "POST", "path": "/api/v1/open/nodes/{flow_no}/{activity_id}/decide", "scope": "task:write", "title": "按下审批按钮(主写法):环节 id 从 locate 或事件信封里现取,别抄死"},
{"method": "POST", "path": "/api/v1/open/nodes/{flow_no}/decide", "scope": "task:write", "title": "按下审批按钮(省掉环节那一段):OA 认这张单当前停着的那一环,认不出唯一一环就回候选"},
{"method": "GET", "path": "/api/v1/open/events", "scope": "", "title": "事件清单与推送格式"},
],
"signature": {
"header": "X-Unisoa-Signature",
"format": "t=<时间戳>,v1=sha256=<HMAC-SHA256(secret, \"t.<原始请求体>\")>",
"tip": "校验时把时间戳与当前时间比一次(建议 ±300 秒),否则对方可以拿一条旧签名无限重放",
},
})
@router.get("/design/open/apps")
def list_apps(db: Session = Depends(get_db), _: CurrentUser = Depends(require_permission("design:openapi"))) -> dict:
rows = list(db.execute(select(models.OpenApp).order_by(models.OpenApp.code)).scalars().all())
return ok({"items": [app_view(db, row) for row in rows]})
@router.post("/design/open/apps")
def create_app(
body: schemas.OpenAppBody,
request: Request = None,
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
"""新建应用。**密钥只在这一次返回**,界面必须当场让人复制走。"""
code = str(body.code or "").strip()
if not CODE_RE.match(code):
raise bad_request("应用编码只允许字母、数字、下划线和短横线(1-64 位)")
if get_app(db, code) is not None:
raise bad_request(f"应用编码 {code} 已经存在")
app_key, secret = openauth.new_credentials()
row = models.OpenApp(
code=code, app_key=app_key, secret_hash=hash_token(secret),
secret_hint=openauth.secret_hint(secret), creator=user.person_id, creator_name=user.display_name,
**_clean_app(body),
)
db.add(row)
_log(db, user, "open_app_create", code, f"新建开放平台应用:{row.name}", request)
db.commit()
db.refresh(row)
view = app_view(db, row)
view["appSecret"] = secret
view["secretOnce"] = True
return ok(view)
@router.put("/design/open/apps/{code}")
def update_app(
code: str,
body: schemas.OpenAppBody,
request: Request = None,
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
row = get_app(db, code)
if row is None:
raise bad_request("应用不存在")
for key, value in _clean_app(body).items():
setattr(row, key, value)
if not row.enabled:
# 停用是"立刻不让调",不是"下次令牌过期后不让调":已发出去的令牌一起作废
openauth.revoke_tokens(db, row.code)
_log(db, user, "open_app_update", code, f"修改开放平台应用:{row.name}", request)
db.commit()
db.refresh(row)
return ok(app_view(db, row))
@router.post("/design/open/apps/{code}/secret")
def rotate_secret(
code: str,
request: Request = None,
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
"""换一把密钥。旧密钥当场失效,所以界面上要先说清楚"对方系统要同步改配置"。"""
row = get_app(db, code)
if row is None:
raise bad_request("应用不存在")
_, secret = openauth.new_credentials()
row.secret_hash = hash_token(secret)
row.secret_hint = openauth.secret_hint(secret)
openauth.revoke_tokens(db, row.code)
_log(db, user, "open_app_secret", code, f"重置开放平台应用密钥:{row.name}", request)
db.commit()
db.refresh(row)
view = app_view(db, row)
view["appSecret"] = secret
view["secretOnce"] = True
return ok(view)
@router.delete("/design/open/apps/{code}")
def delete_app(
code: str,
request: Request = None,
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
row = get_app(db, code)
if row is None:
raise bad_request("应用不存在")
db.delete(row)
openauth.revoke_tokens(db, code)
_log(db, user, "open_app_delete", code, f"删除开放平台应用:{row.name}", request)
db.commit()
return ok({"code": code})
# ===========================================================================
# 管理面:事件订阅与投递记录
# ===========================================================================
def hook_view(row: models.OpenWebhook) -> dict:
return {
"id": row.id,
"code": row.code,
"name": row.name,
"enabled": row.enabled,
"url": row.url,
"secretSet": bool(str(row.secret or "").strip()),
"events": list(row.events or []),
"processes": list(row.processes or []),
"sendData": bool(row.send_data),
"timeoutSeconds": row.timeout_seconds,
"retries": row.retries,
"remark": row.remark,
"creatorName": row.creator_name,
"lastSentAt": _stamp(row.last_sent_at),
"lastStatus": row.last_status,
"lastError": row.last_error,
"updateTime": _stamp(getattr(row, "update_time", None)),
}
def get_hook(db: Session, code: str) -> models.OpenWebhook | None:
return db.execute(select(models.OpenWebhook).where(models.OpenWebhook.code == str(code).strip())).scalar_one_or_none()
def _clean_hook(body: schemas.OpenWebhookBody) -> dict:
url = str(body.url or "").strip()
if not url:
raise bad_request("要填回调地址")
if not url.startswith(("http://", "https://")):
raise bad_request("回调地址要以 http:// 或 https:// 开头")
wanted = [str(item) for item in (body.events or []) if str(item) in events.EVENT_KEYS]
if not wanted:
raise bad_request("至少勾一个要接收的事件")
timeout = int(body.timeout_seconds or 10)
if not 1 <= timeout <= 120:
raise bad_request("超时秒数需要在 1-120 之间")
retries = int(body.retries or 5)
if not 0 <= retries <= 10:
raise bad_request("重试次数需要在 0-10 之间")
return {
"name": str(body.name or "").strip() or "未命名订阅",
"enabled": bool(body.enabled),
"url": url,
"events": wanted,
"processes": [str(item) for item in (body.processes or []) if str(item)],
"send_data": bool(body.send_data),
"timeout_seconds": timeout,
"retries": retries,
"remark": str(body.remark or "").strip(),
}
@router.get("/design/open/webhooks")
def list_hooks(db: Session = Depends(get_db), _: CurrentUser = Depends(require_permission("design:openapi"))) -> dict:
rows = list(db.execute(select(models.OpenWebhook).order_by(models.OpenWebhook.code)).scalars().all())
return ok({"items": [hook_view(row) for row in rows]})
@router.post("/design/open/webhooks")
def create_hook(
body: schemas.OpenWebhookBody,
request: Request = None,
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
code = str(body.code or "").strip()
if not CODE_RE.match(code):
raise bad_request("订阅编码只允许字母、数字、下划线和短横线(1-64 位)")
if get_hook(db, code) is not None:
raise bad_request(f"订阅编码 {code} 已经存在")
values = _clean_hook(body)
row = models.OpenWebhook(code=code, secret=str(body.secret or "").strip(),
creator=user.person_id, creator_name=user.display_name, **values)
db.add(row)
_log(db, user, "open_webhook_create", code, f"新增事件订阅:{row.name} → {row.url}", request)
db.commit()
db.refresh(row)
return ok(hook_view(row))
@router.put("/design/open/webhooks/{code}")
def update_hook(
code: str,
body: schemas.OpenWebhookBody,
request: Request = None,
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
row = get_hook(db, code)
if row is None:
raise bad_request("订阅不存在")
for key, value in _clean_hook(body).items():
setattr(row, key, value)
# 密钥留空表示不改(界面上看不到明文,不可能原样提交回来)
if str(body.secret or "").strip():
row.secret = str(body.secret).strip()
_log(db, user, "open_webhook_update", code, f"修改事件订阅:{row.name}", request)
db.commit()
db.refresh(row)
return ok(hook_view(row))
@router.delete("/design/open/webhooks/{code}")
def delete_hook(
code: str,
request: Request = None,
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
row = get_hook(db, code)
if row is None:
raise bad_request("订阅不存在")
db.delete(row)
_log(db, user, "open_webhook_delete", code, f"删除事件订阅:{row.name}", request)
db.commit()
return ok({"code": code})
@router.post("/design/open/webhooks/{code}/test")
def test_hook(
code: str,
db: Session = Depends(get_db),
_: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
"""立刻往回调地址发一条**结构完全相同的假事件**,并当场把对方的返回带回来。
这是"配完就等真实事件出问题时才发现地址不通"的解药:签名、字段、返回码,一次看清。
"""
row = get_hook(db, code)
if row is None:
raise bad_request("订阅不存在")
if not row.url:
raise bad_request("还没填回调地址")
delivery = models.OpenEvent(
webhook=row.code, event="work.submitted", job="TEST", title="这是一条测试事件",
payload=events.test_payload(row), idem=f"{row.code}:test:{int(time.time())}",
)
db.add(delivery)
db.commit()
result = events.deliver(db, delivery, hook=row)
if result.status == models.OpenEvent.STATUS_SUCCESS:
return ok({"status": result.status, "response": dict(result.response or {}), "ms": result.ms})
reason = result.last_error or "对方没有正常应答"
raise bad_request(f"没送达:{reason}(响应 {dict(result.response or {}).get('httpStatus', '—')})",
reason="WEBHOOK_TEST_FAILED")
@router.get("/design/open/events")
def list_events(
webhook: str = Query(""),
status_filter: str = Query("", alias="status"),
job: str = Query(""),
keyword: str = Query(""),
limit: int = Query(80, ge=1, le=LIST_LIMIT),
db: Session = Depends(get_db),
_: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
stmt = select(models.OpenEvent).order_by(models.OpenEvent.id.desc()).limit(limit)
if webhook:
stmt = stmt.where(models.OpenEvent.webhook == webhook)
if status_filter:
stmt = stmt.where(models.OpenEvent.status == status_filter)
if job:
stmt = stmt.where(models.OpenEvent.job == job)
if keyword:
like = f"%{keyword}%"
stmt = stmt.where(models.OpenEvent.title.like(like) | models.OpenEvent.job.like(like)
| models.OpenEvent.serial.like(like))
rows = list(db.execute(stmt).scalars().all())
return ok({"items": [event_view(row) for row in rows]})
def event_view(row: models.OpenEvent, *, full: bool = False) -> dict:
item = {
"id": row.id,
"webhook": row.webhook,
"event": row.event,
"eventLabel": events.EVENT_LABELS.get(row.event, row.event),
"job": row.job,
"serial": row.serial,
"title": row.title,
"activity": row.activity,
"status": row.status,
"attempts": row.attempts,
"nextAttemptAt": _stamp(row.next_attempt_at),
"sentAt": _stamp(row.sent_at),
"createTime": _stamp(getattr(row, "create_time", None)),
"lastError": row.last_error,
"response": dict(row.response or {}),
"ms": row.ms,
"shadowed": row.shadowed,
}
if full:
item["payload"] = dict(row.payload or {})
return item
@router.post("/design/open/events/{event_id}/replay")
def replay_event(
event_id: str,
reason: str = Query(""),
db: Session = Depends(get_db),
user: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
"""人工重推一条事件(改完地址或对方恢复之后)。"""
row = db.get(models.OpenEvent, event_id)
if row is None:
raise bad_request("事件不存在")
row.status = models.OpenEvent.STATUS_PENDING
row.attempts = 0
row.next_attempt_at = datetime.now().replace(microsecond=0)
row.last_error = f"人工重推({(reason or '未填原因')[:120]})"
_log(db, user, "open_event_replay", f"{row.webhook}/{row.event}", f"重推事件 {row.id}", None)
db.commit()
return ok(event_view(row))
# ===========================================================================
# 数据面:外部系统调的接口
# ===========================================================================
def open_person(db: Session, identity: str) -> models.User:
"""开放接口收到的 ``identity`` 参数 -> 人员行。
这一层是**输入侧的宽容**:库里认人只存登录账号,但外部系统手里的写法五花八门
(账号、姓名、老的身份 DN 都有),按 :mod:`app.service.personref` 的口径统一认一次。
认不出来直接报错,绝不悄悄换成别人。
"""
value = str(identity or "").strip()
if not value:
raise bad_request("要带 identity:说明这条调用是以谁的身份发生的")
person = org.person_by_identity(db, value)
if person is None:
raise bad_request(f"身份 {value} 在本系统里不存在")
return person
class OpenContext:
"""一次外部调用:哪把钥匙、哪个应用。``acting`` 由接口按 identity 参数解析出来。"""
def __init__(self, app: models.OpenApp) -> None:
self.app = app
self.actor: engine.Actor | None = None
self.person: models.User | None = None
def need(self, scope: str) -> None:
if scope not in list(self.app.scopes or []):
raise forbidden(f"这个应用没有被授予「{openauth.SCOPE_LABELS.get(scope, scope)}」权限")
def as_actor(self, db: Session, identity: str = "") -> engine.Actor:
"""以某个人的身份执行。这个人必须在系统里存在——**不做"以管理员身份"这种兜底**,
否则一把泄露的密钥就能以最高权限办单。"""
person = open_person(db, identity)
# 停用的人不能被"以他的身份"办单;查他自己的历史是另一回事(读侧不卡状态)
if int(getattr(person, "status", 0) or 0) not in models.UserStatus.LOGIN_ALLOWED:
raise bad_request(f"{person.display_name} 的账号已停用")
self.person = person
self.actor = engine.Actor.from_ref(db, person, personref.ref_of(person))
return self.actor
def _unauthorized(message: str) -> ApiError:
return unauthorized(message)
def open_context(
request: Request,
db: Session = Depends(get_db),
credentials: HTTPAuthorizationCredentials | None = Depends(bearer),
) -> OpenContext:
"""校验访问令牌并顺手限流。令牌无效一律 401,不区分"不存在"与"已过期"。"""
token = credentials.credentials if credentials else ""
if not token:
raise _unauthorized("缺少访问令牌:先调 POST /api/v1/open/token")
app, _row = openauth.app_of_token(db, token)
if app is None:
raise _unauthorized("访问令牌无效或已过期")
limited = openauth.rate_limited(db, app)
if limited:
# 429 而不是 400:对方脚本看到 429 才知道要退避,看到 400 会照原样重试
raise ApiError(limited, 429, "RATE_LIMITED", http_status=429)
app.last_used_at = datetime.now()
db.commit()
request.state.open_app = app
request.state.open_token_hint = token[:8]
context = OpenContext(app)
return context
@open_router.post("/open/token")
def issue_open_token(
body: schemas.OpenTokenBody,
request: Request = None,
db: Session = Depends(get_db),
) -> dict:
"""用 app_key + app_secret 换一把短期访问令牌。
口令错与应用不存在回同一句话,别把"哪些 app_key 存在"变成可枚举的信息。
"""
app_key = str(body.app_key or "").strip()
app = db.execute(select(models.OpenApp).where(models.OpenApp.app_key == app_key)).scalar_one_or_none()
if app is None or not app.enabled or not openauth.verify_secret(app, str(body.app_secret or "")):
raise _unauthorized("app_key 或 app_secret 不正确")
token, expires = openauth.issue_token(db, app)
return ok({
"accessToken": token,
"tokenType": "Bearer",
"expiresAt": expires.strftime("%Y-%m-%d %H:%M:%S"),
"expiresIn": max(60, int(app.token_ttl_seconds or 7200)),
"scopes": list(app.scopes or []),
})
@open_router.get("/open/events")
def open_event_catalog(db: Session = Depends(get_db), _: OpenContext = Depends(open_context)) -> dict:
"""给对接方看的事件清单:事件名、含义、信封长什么样。省掉一份会过期的对接文档。"""
sample = {
"event": "work.completed",
"eventLabel": "单据办结",
"occurredAt": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
"work": {"job": "...", "id": "...", "serial": "...", "title": "...", "status": "completed",
"process": "...", "processName": "...", "creator": "...", "creatorName": "..."},
"activity": "总经理审批",
"operator": "张三",
"link": "https://oa.example.com/work/...",
}
return ok({
"events": [{"value": key, "label": label, "when": when} for key, label, when in events.CATALOG],
"envelope": sample,
"headers": {
"X-Unisoa-Event": "事件名",
"X-Unisoa-Delivery": "本次投递 id(重推时不变,可用来去重)",
"X-Unisoa-Timestamp": "签名时间戳(秒)",
"X-Unisoa-Signature": "t=<ts>,v1=sha256=<HMAC-SHA256(secret, \"ts.原始请求体\")>",
},
"rules": [
"请在 3 秒内返回 2xx;返回非 2xx 或超时都会按退避重投(60s / 5min / 15min / 1h / 4h)。",
"同一张单的事件按发生顺序投递,前一条没成功不会投后一条,可放心按顺序处理。",
"重投可能产生重复,请用 X-Unisoa-Delivery 自己做一次去重。",
],
})
def _process_view(row: models.Process, startable: bool) -> dict:
return {
"process": row.id,
"name": row.name,
"alias": row.alias,
"category": row.category,
"categoryName": row.category_name,
"form": row.latest_form,
"formName": row.latest_form_name,
"startable": startable,
"description": row.description,
}
@open_router.get("/open/processes")
def open_processes(
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
identity: str = Query(""),
) -> dict:
"""已发布的流程清单。带 identity 时额外标出这个人能不能发起。"""
rows = list(db.execute(
select(models.Process).where(models.Process.enabled.is_(True), models.Process.published.is_(True))
.order_by(models.Process.name)
).scalars().all())
context.need("process:read")
identities: list[str] = []
if identity:
# 发起范围里存的是账号,所以这里换算成账号再比,别把对方传来的原始写法直接拿去比
identities = [personref.ref_of(open_person(db, identity))]
can = starters.startable_map(db, rows, identities=identities)
return ok({"items": [_process_view(row, bool(can.get(row.id, False))) for row in rows]})
def _work_view(row, *, with_data: bool = False) -> dict:
return {
"job": row.job,
"id": row.id,
"serial": row.serial,
"title": row.title,
"status": row.status,
"process": row.process,
"processName": row.process_name,
"activity": getattr(row, "activity_name", "") or "",
"creator": row.creator,
"creatorName": row.creator_person,
"creatorIdentity": row.creator_identity,
"startTime": _stamp(getattr(row, "start_time", None)),
"finishTime": _stamp(getattr(row, "finish_time", None)),
"data": dict(row.data or {}) if with_data else None,
}
@open_router.get("/open/works")
def open_works(
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
identity: str = Query(""),
process: str = Query(""),
status_filter: str = Query("", alias="status"),
keyword: str = Query(""),
limit: int = Query(50, ge=1, le=200),
) -> dict:
"""查单据。运行中的查 ``oa_work``,已办结的查归档表,两边合起来给,对方不该关心这张表搬走了没有。"""
context.need("work:read")
limit = min(limit, LIST_LIMIT)
items: list[dict] = []
for model, finished in ((models.Work, False), (models.WorkCompleted, True)):
stmt = select(model)
if identity:
stmt = stmt.where(model.creator_identity == personref.ref_of(open_person(db, identity)))
if process:
stmt = stmt.where(model.process == process)
if status_filter and (finished or status_filter != "completed"):
stmt = stmt.where(model.status == status_filter)
if keyword:
like = f"%{keyword}%"
stmt = stmt.where(or_(model.title.like(like), model.serial.like(like)))
stmt = stmt.order_by(model.id.desc()).limit(limit)
items.extend(_work_view(row) for row in db.execute(stmt).scalars().all())
items.sort(key=lambda item: item.get("startTime") or "", reverse=True)
return ok({"items": items[:limit]})
@open_router.get("/open/works/{job}")
def open_work_detail(
job: str,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
with_data: bool = Query(False),
) -> dict:
"""单据详情 + 流转记录。``with_data=1`` 才带表单数据(字段口径由表单决定,对方要自己认)。"""
context.need("work:read")
work = db.execute(select(models.Work).where(models.Work.job == job)).scalar_one_or_none()
archived = 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 ApiError("单据不存在", 404, "WORK_NOT_FOUND", http_status=404)
row = work or archived
logs = list(db.execute(
select(models.WorkLog).where(models.WorkLog.job == job).order_by(models.WorkLog.arrived_time)
).scalars().all())
# 已办台账:撤回那条接口(/open/tasks/completed/{id}/recall)要点的就是这一行。
# flow 里只有"谁把单子走到了哪儿",撤哪一次点不出名——对方拿不到这个 id 就只能
# 回来问 OA 要号,那条本来设计成第三方自己就能收尾的接口等于白给。
handled_rows = list(db.execute(
select(models.TaskCompleted).where(models.TaskCompleted.job == job)
.order_by(models.TaskCompleted.completed_time, models.TaskCompleted.id)
).scalars().all())
return ok({
"work": _work_view(row, with_data=with_data or bool(work is None)),
"flow": [{
"fromActivity": log.from_activity_name,
"toActivity": log.arrived_activity_name,
"route": log.route_name,
"operator": log.from_identity_name or log.from_person_name,
"opinion": log.from_opinion,
"arrivedAt": _stamp(log.arrived_time),
} for log in logs],
"handled": [{
"id": item.id,
"activity": item.activity_name,
"identity": item.identity,
"identityName": item.identity_name,
"route": item.route_name,
"opinion": item.opinion,
"completedAt": _stamp(item.completed_time),
} for item in handled_rows],
})
def _result_work(db: Session, result: engine.StepResult) -> dict:
"""把一次流转的结果翻成对外响应里的单据。
``StepResult.work`` 在办结之后是 ``None``——实例已经搬进归档表并被删掉了,
这时候只能拿 ``work_id`` 回查 ``oa_work_completed``。直接挂着一个可能为 None 的
实例去读字段,就是"最后一道审批办完反而报 500"的来路。
"""
work = result.work
if work is None and result.work_id:
work = db.get(models.WorkCompleted, result.work_id)
if work is None:
return {"job": result.work_job, "id": result.work_id, "status": result.status, "done": result.completed}
return _work_view(work)
@open_router.post("/open/works")
def open_create_work(
body: schemas.OpenWorkBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""以某个人的身份发起一张单。校验与界面发起走的是同一个 ``engine.create_job``,
所以必填校验、公式重算、额度控制这些一条都不会少。
带上 ``bizKey``(嵌页面那一趟的预受理号)时多挡一件事:**这一趟已经发起过了就不再新建**。
嵌着第三方页面的发起页会有这个需要——人在 OA 里开着发起页、ERP 那边从自己服务端也发起了
一张,两个人各自点一次就是两张单。退单、终止、留痕、通知哪一样都比回一句
"已经有了,单号是 X"贵,所以这一句必须说。见 ``docs/embed-action-design.md`` §4.3。
"""
context.need("work:write")
actor = context.as_actor(db, body.identity)
process = db.get(models.Process, str(body.process or "").strip())
if process is None or not process.enabled or not process.published:
raise bad_request("流程不存在或尚未发布")
if not starters.allowed(db, process, identities=[actor.ref]):
raise forbidden("这个人不在该流程的发起范围里")
session = embed_session.by_prekey(db, body.biz_key) if str(body.biz_key or "").strip() else None
if session is not None and session.claim_job:
done = tasktrail.work_of(db, session.claim_job) or db.execute(
select(models.Work).where(models.Work.job == session.claim_job)
).scalar_one_or_none()
return ok({
"work": _work_view(done) if done is not None else {"job": session.claim_job,
"serial": session.claim_serial,
"status": ""},
"tasks": [], "alreadyStarted": True,
"note": f"这一趟({session.prekey})已经发起过一张单了"
f"(单号 {session.claim_serial or session.claim_job}),本次调用没有新建任何东西",
})
# 这一趟在发起页上占过号(第三方手里那个号就是它),建单时接过来:
# 另排一个新号会让对面记的那个号当场作废,之后的回写全撞在"没这张单"上
result = engine.create_job(db, process_id=process.id, actor=actor,
data=_trip_start_data(db, session, process,
dict(body.data or {})),
title=str(body.title or ""),
attachments=list(body.attachments or []),
serial=embed_session.reserved_serial(db, session),
hold_at_begin=bool(body.hold),
# 第三方建单不受 OA 按钮锁定影响:这一条本来就是交出去的那一半
via=engine.VIA_OPEN)
if session is not None:
embed_session.apply_start(db, session, **embed_session.claim_of_result(result))
db.commit()
if body.hold:
return ok({"work": _result_work(db, result), "tasks": [],
"note": "这张单停在开始环节等提交:调该环节的 decide 表态,或发起人到单据页确认"})
return ok({"work": _result_work(db, result),
"tasks": [{"id": task.id, "activity": task.activity_name,
"identity": task.identity} for task in result.tasks]})
@open_router.post("/open/works/{job}/terminate")
def open_terminate_work(
job: str,
body: schemas.OpenCancelBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""终止一张单。以谁的身份终止,就得是谁有权限——管理员权限不由开放平台默认给。"""
context.need("work:write")
actor = context.as_actor(db, body.identity)
result = engine.terminate(db, job=job, actor=actor, opinion=str(body.opinion or "外部系统终止"))
db.commit()
return ok({"work": _result_work(db, result)})
def _draft_view(row: models.Draft, *, with_data: bool = True) -> dict:
"""草稿在开放接口上的样子。字段自己定、自己稳,不跟着 ``serializers.draft`` 漂。"""
return {
"id": row.id,
"title": row.title,
"process": row.process,
"processName": row.process_name,
"category": row.category,
"categoryName": row.category_name,
"form": row.form,
"identity": row.identity,
"personName": row.person_name,
"data": dict(row.data or {}) if with_data else None,
# 把人引回他自己那半张单:这是本站相对路径,拼上站点地址就能点开
"pagePath": drafts.page_path(row.process, row.id),
"createTime": _stamp(row.create_time),
"updateTime": _stamp(row.update_time),
}
@open_router.post("/open/drafts")
def open_create_draft(
body: schemas.OpenDraftBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""以某个人的身份建一张流程草稿:草稿落在他名下,他在草稿箱里能翻出来接着填。
与 ``POST /open/works`` 的差别只在"发不发起":草稿不卡必填,流程也不开始流转。
上游系统替员工铺一张待提交的单就用这个,别为了省事硬凑一份假数据直接发起——
发出去的单子要退回、要终止,比多存一张草稿麻烦得多。
``process`` 认五种写法(id / 名称 / 别名 /「分类/流程名」/ 关键词),要传哪些参数
先查 ``GET /open/processes`` 里那条流程的清单;还没发布的流程一律建不了草稿。
"""
context.need("draft:write")
actor = context.as_actor(db, body.identity)
process = drafts.resolve_process(db, body.process, category=body.category)
drafts.guard_startable(db, process, actor)
row, inspection = drafts.create(
db, process=process, actor=actor, data=dict(body.data or {}), title=str(body.title or "")
)
db.commit()
return ok({"draft": _draft_view(row), "notices": inspection.notices})
@open_router.get("/open/drafts")
def open_drafts(
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
identity: str = Query(""),
limit: int = Query(50, ge=1, le=LIST_LIMIT),
) -> dict:
"""某个人草稿箱里的草稿。``identity`` 必填,口径与「查某个人的待办」那条一致。"""
context.need("draft:read")
person = open_person(db, identity)
rows = list(db.execute(
select(models.Draft)
.where(personref.clause(
models.Draft.identity, [personref.ref_of(person), str(person.id)]
) | (models.Draft.person == str(person.id)))
.order_by(models.Draft.update_time.desc()).limit(min(limit, LIST_LIMIT))
).scalars().all())
return ok({"items": [_draft_view(row) for row in rows]})
@open_router.get("/open/tasks")
def open_tasks(
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
identity: str = Query(""),
limit: int = Query(50, ge=1, le=200),
) -> dict:
"""某个人的待办。``identity`` 必填:开放接口没有"当前登录人"这个概念。"""
context.need("task:read")
account = personref.ref_of(open_person(db, identity))
rows = list(db.execute(
select(models.Task).where(models.Task.identity == account, models.Task.status == "pending")
.order_by(models.Task.start_time.desc()).limit(min(limit, LIST_LIMIT))
).scalars().all())
return ok({"items": [{
"id": task.id,
"job": task.job,
"serial": task.serial,
"title": task.title,
"activity": task.activity_name,
"identity": task.identity,
"identityName": task.identity_name,
"arrivedAt": _stamp(task.start_time),
"dueAt": _stamp(task.expire_time),
"expired": bool(task.expired),
"routes": list(task.route_name_list or []),
} for task in rows]})
@open_router.post("/open/tasks/{task_id}/execute")
def open_execute_task(
task_id: str,
body: schemas.OpenTaskExecuteBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""处理一条待办。只有这条待办的处理人(或其代理人)自己的身份能办,
引擎的 ``get_task`` 会挡住冒名顶替,这里不额外开后门。"""
context.need("task:write")
actor = context.as_actor(db, body.identity)
# 待办已经不在手上了:先看看是不是**被人办掉了**。这一条有两个入口(OA 审批页与
# 这里),"两边同时点"是方案 §6.3 里就有的用法,后到的那一次什么都改不了——
# 把它报成失败,对方的集成就得天天为"其实没事"报警。
if db.get(models.Task, task_id) is None:
handled = _already_handled(db, task_id, actor.ref)
if handled is not None:
return ok(handled)
result = engine.execute_task(db, task_id=task_id, actor=actor,
route_name=str(body.route or ""), opinion=str(body.opinion or ""),
data=dict(body.data or {}), via=engine.VIA_OPEN)
db.commit()
return ok({
"work": _result_work(db, result),
# 单据是否已经走完:外部系统多半要在"办结"这一刻去上游做下一步动作
"done": bool(result.completed),
"tasks": [{"id": task.id, "activity": task.activity_name, "identity": task.identity}
for task in result.tasks],
})
def _already_handled(db: Session, task_id: str, ref: str) -> dict | None:
"""这条待办被谁办掉了:回那份"已经办过"的响应,回 ``None`` 表示这真是个错单号。
为什么是 200 而不是 400:闸门那条待办有两个入口(方案 §6.3、契约 §8.5),嵌页面那条
回写通道更是明摆着的第三个入口(``docs/embed-action-design.md`` §5),谁先办谁生效、
后到的改不动任何东西,这是**设计里就有的正常结局**。把正常结局报成失败,对方的机器人
就会对着一堆"其实没事"重试到把限流打满,最后被人把重试整段删掉——那才是真事故。
信息给足(谁、什么时候、走了哪条出口),要不要记一笔由调用方定。
只回答"这条待办自己的处理人":换个身份来问就还是原来那句「待办不存在或已被处理」,
免得一把 ``task:write`` 的钥匙拿别人的待办号来翻审批记录。判据与 :func:`_already_handled`
一起搬进 ``service/tasktrail.py`` 了,那边嵌页面回写走的是同一条尺子。
"""
row = tasktrail.handled_of(db, task_id, ref)
if row is None:
return None
stamp = row.completed_at.strftime("%Y-%m-%d %H:%M:%S") if row.completed_at else ""
note = (
f"这条待办在同环节已被其他处理人办掉({stamp}),本次调用没有改动任何东西" if row.auto else
f"这条待办已由 {row.identity_name or row.identity} 于 {stamp} 办掉"
f"(出口「{row.route}」),本次调用没有改动任何东西"
)
work = tasktrail.work_of(db, row.work)
return {
"work": _work_view(work) if work is not None else {"job": row.job, "id": row.work,
"status": "", "done": False},
"done": str(getattr(work, "status", "")) not in ("", "running"),
"tasks": [],
"alreadyHandled": True,
"handledBy": row.identity_name,
"handledIdentity": row.identity,
"handledAt": stamp,
"activity": row.activity,
"route": row.route,
"note": note,
}
# ===========================================================================
# 环节审批的对外接口:设计器在环节上「定义接口」,第三方服务端按卡调 OA 的审批按钮
#
# 凭据不加新东西(开放平台那条访问令牌),出口不由第三方指定(三种结论 + 最长匹配),
# 白名单在进引擎之前筛。判据全部在 service/node_approve.py,与嵌入回写同一把尺。
# ===========================================================================
@open_router.post("/open/nodes/locate")
def open_node_locate(
body: schemas.NodeLocateBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""拉取式定位:不订阅事件,拿单号或查找字段,把这张单现在停在哪个环节取回来。
与 decide 的分工——locate 只「指路」不「按钮」:凭据要 ``task:read``(默认就有)。
默认这份是**瘦的**(``detail=brief``):是哪张单、停在哪个流程哪个环节、还能不能表态,
对方拿 ``work.serial`` 与 ``activity.id`` 拼出 decide 的地址就行——环节 id 该这样每次
现取,而不是在设计器里看一眼就抄进配置。那张填好号的现成端点、决策词表、可写字段白名单、
全套对接清单在 ``openApprove`` 里,带 ``detail=full`` 才回(那几样配一次看一次,
不该跟着每次表态前的定位跑几十趟)。真按下那颗钮才要 ``task:write``。
两条路加法不互斥:推的(``task.arrived`` 事件,信封里自带卡片)与拉的(本端点)各管各的,
凭据同一把访问令牌。指不出来就不猜:查找字段没配过、对上了不止一张单、单不在跑,
都点名说清,不硬造。
"""
context.need("task:read")
return ok(node_approve.locate(db, body.work, body.keys, body.detail,
app_code=context.app.code))
def _decision_hint(problem: str, config: dict) -> str:
"""结论词翻不出来时,把这一环**认得的那些词**一并念回去。
默认的 ``locate`` 不再每次都带 ``decisions`` 那张表(配一次看一次的东西,§4.5),
这一句就是那张表在报错时的替身:对方不必为了知道自己该发什么词,专门再调一次 full。
"""
# 用原始那份词表而不是归一化后的:对方要照抄的是自己发的那个写法(大写那种)
raw = (config or {}).get("decisions")
words = raw if isinstance(raw, dict) else node_approve.decisions_map(config)
if not words or "这一环认得的结论词" in problem:
return problem
listed = "、".join(f"{word}→{embed_session.DECISION_LABELS.get(str(kind).strip().casefold(), kind)}"
for word, kind in sorted(words.items(), key=lambda item: str(item[0])))
return f"{problem}。这一环认得的结论词:{listed}"
def _work_definition(db: Session, work):
"""这张单**出发时那一版**设计(口径同引擎执行那一步);读不到回 ``None``。
回 ``None`` 时下面的取值一律退回当前设计那套读法,行为与"在途单冻结设计"之前一字不差。
"""
try:
return definition_module.for_work(db, work)
except ValueError:
return None
def _route_names_of(db: Session, definition, process_id: str, activity_id: str) -> list[str]:
"""这一环真实存在的出口名。有冻结定义就读它那一版图,否则照旧问 ``oa_route``。"""
if definition is not None:
return [str(item.name) for item in definition.routes_from(activity_id)]
return node_approve.route_names(db, process_id, activity_id)
def _form_id_of(definition, activity, work) -> str:
"""这一环用哪张表单:冻结定义里那一环绑的 > 这张单实际用的 > 定义里的默认表单。"""
if definition is None:
return str(getattr(activity, "form", "") or "") or str(getattr(work, "form", "") or "")
node = definition.activity(str(getattr(activity, "id", "") or ""))
return ((str(node.form or "") if node is not None else "")
or str(getattr(work, "form", "") or "")
or str(definition.latest_form or ""))
@open_router.post("/open/nodes/{flow_no}/{activity_id}/decide")
def open_node_decide(
flow_no: str,
activity_id: str,
body: schemas.NodeDecideBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""第三方服务端替某个环节按下审批按钮。设计见 docs/node-open-approve-design.md。
地址里那一段放的是**流程编号**(单子上印的那个号,``work.serial``),job 号同样认——
对方手里只有这两种号,``oa_process.id`` 那种内部 id 他们既拿不到也不该抄。这一环属于
哪条流程以环节自己记的那条为准,不采信对方写的号;老卡片上写的流程定义 id 继续认,
只是那种写法必须靠报文里的 ``work`` 说清是哪张单。
关着的环节与没对当前应用开口的环节回**笼统话**(与 404 同宽),且这一关排在查单之前:
这条端点不该成为「哪些单在跑、哪些应用配过」的探针。出口只认三种结论,匹不唯一就回候选
不猜;会签多条待办没点名也回候选。已办过的回 200 + alreadyHandled——两个入口同时表态
是正常结局,不是事故。``bizKey`` 幂等:同一趟两次表态只办一次。
主写法就是这一条:``activityId`` 由 ``locate`` 或事件信封每次递过来,改图换号也接得上。
嫌多传一段的对接方走 ``POST /open/nodes/{流程编号}/decide``(环节由这边认),
两条地址除了"环节谁说了算",往后每一步都是同一个函数在办。
"""
context.need("task:write")
activity = db.get(models.Activity, str(activity_id or "").strip())
if activity is None:
raise not_found("环节不存在")
process = db.get(models.Process, str(activity.process or "").strip())
if process is None:
raise not_found("流程不存在")
config = node_approve.effective_config(process, activity)
if not node_approve.is_enabled(config):
raise not_found("这一环没开审批接口")
apps = node_approve.allowed_apps(config)
if apps and context.app.code not in apps:
raise forbidden("这一环没对当前应用开审批接口")
start_note = ""
alias_note = ""
try:
work = node_approve.work_from_path(db, flow_no, body.work, process_id=process.id)
except ApiError as exc:
started = _begin_start_from_decide(db, process, activity, config, body, context, exc,
refs=(flow_no, body.work))
if started is None:
raise
if started.get("replay") is not None:
return ok(started["replay"])
work = started["work"]
start_note = str(started.get("note") or "")
alias_note = str(started.get("alias") or "")
if work.status != "running":
label = {"completed": "办结", "terminated": "终止", "canceled": "作废"}.get(work.status, work.status)
raise bad_request(f"流程已{label}并归档,无法再表态", reason="NODE_WORK_NOT_RUNNING")
# 幂等只认 bizKey,可对方那个号是按**报销记录**编的,会被反复用到同一张单同一环上:
# 表态之后单子又被退回到这一环、那一环重新有人等,就得按新表态再办一次。少了这一条,
# 那张单永远停在开始环节出不去,而对方每次都被回一句 alreadyHandled、日志写着 succeeded。
existing = node_approve.find_by_biz(db, context.app.code, work, activity.id, body.biz_key)
if existing is not None and not node_approve.decision_superseded(db, existing):
return ok(node_approve.replay(existing, db=db))
resume_note = node_approve.supersede_note(db, existing) if existing is not None else ""
if alias_note and alias_note not in resume_note:
# 复用那张单时点名的号与它印出去的号不是同一个,这一句要跟着回包说清
resume_note = f"{resume_note}{alias_note}"
if activity.type == "begin":
return _open_node_decide_begin(db, process, activity, config, work, body, context,
start_note=start_note, resume_note=resume_note)
task, candidates = node_approve.resolve_task(db, work, activity.id, body.identity)
if task is None:
if candidates:
names = "、".join(c.identity_name or c.identity for c in candidates)
raise bad_request(
f"环节「{activity.name}」现在有多条未办待办({names}),"
"请带上 identity 说清替哪一条表态",
reason="NODE_TASK_AMBIGUOUS",
)
done = db.execute(
select(models.TaskCompleted)
.where(models.TaskCompleted.work == work.id, models.TaskCompleted.activity == activity.id)
.order_by(models.TaskCompleted.completed_time.desc())
).scalars().first()
if done is not None:
payload = _already_handled(db, done.task, "")
if payload is not None:
return ok(payload)
stamp = done.completed_time.strftime("%Y-%m-%d %H:%M:%S") if done.completed_time else ""
return ok({
"alreadyHandled": True, "activity": activity.name, "route": done.route_name,
"handledBy": done.identity_name or done.identity, "handledAt": stamp,
"work": _work_view(work), "done": False, "tasks": [],
"note": "这一环已经办过了,本次调用没有改动任何东西",
})
raise bad_request(
f"环节「{activity.name}」此刻没有未办的待办:这一环还没轮到,或者已经过了",
reason="NODE_NOT_PENDING",
)
kind = embed_session.decision_kind(body.result, node_approve.decisions_map(config))
# 出口清单按这张单那一版图数:中途改了流程图,第三方被钉住的那条线在这张单脚下
# 还在,就不该拿当前图纸上的名字把它挡掉(引擎走的也是这一版图)。
definition = _work_definition(db, work)
names = _route_names_of(db, definition, process.id, activity.id)
pinned = node_approve.routes_map(config).get(kind, "")
if pinned:
# 设计器钉住的出口:第三方说「驳回」,这一环必然走那条回到指定步骤的线。
# 图改到钉没了要当场报错,不悄悄退回按名匹配——那等于让驳回自己挑路。
if pinned in names:
route = pinned
else:
raise bad_request(
f"这一环把「{embed_session.DECISION_LABELS.get(kind, kind)}」钉在出口「{pinned}」上,"
f"但那条线已经不在了。这一环现在的出口是:{'、'.join(names) or '没有了'}。"
"请重新配置或让第三方重新表态",
reason="NODE_ROUTE_PIN_MISSING",
)
else:
route, problem = embed_session.match_route(names, decision=kind, activity=activity.name)
if problem is not None:
raise bad_request(_decision_hint(problem[0], config), reason=problem[1])
form_id = _form_id_of(definition, activity, work)
fields = autofill.form_fields(db, form_id, definition)
data, _dropped = node_approve.filter_data(body.data, config, fields)
opinion = str(body.opinion or "").strip() or node_approve.render_opinion(config, kind, work, data)
base = {
"app": context.app.code, "app_name": context.app.name,
"work": work.id, "job": work.job, "serial": work.serial,
"process": process.id, "process_name": process.name,
"activity": activity.id, "activity_name": activity.name,
"task": task.id, "task_identity": task.identity, "task_identity_name": task.identity_name,
"decision": str(body.result or ""), "kind": kind, "route": route,
"opinion": opinion, "data": data, "biz_key": str(body.biz_key or ""),
}
if node_approve.confirm_mode(config) == "auto":
# 当场办:以**这条待办的处理人**名义走引擎原来那条路,字段权限、必填、公式、
# 额度、外部核验闸门一条不少。冒名顶替由引擎那句「该待办不属于当前身份」挡。
actor = context.as_actor(db, task.identity)
try:
result = engine.execute_task(db, task_id=task.id, actor=actor,
route_name=route, opinion=opinion, data=data,
via=engine.VIA_OPEN)
except engine.EngineError as exc:
raise bad_request(str(exc)) from exc
work_view = _result_work(db, result)
payload = {
"handled": True, "route": route, "activity": activity.name,
"status": work_view["status"], "done": bool(result.completed),
"work": work_view,
"tasks": [{"id": t.id, "activity": t.activity_name, "identity": t.identity} for t in result.tasks],
"note": f"{resume_note}已按环节「{activity.name}」的外部审批配置自动办理",
}
node_approve.record(db, base, status=node_approve.STATUS_HANDLED, response=payload)
db.commit()
return ok(payload)
row = node_approve.record(
db, base, status=node_approve.STATUS_STAGED,
expires_at=datetime.now() + timedelta(seconds=node_approve.ttl_seconds()))
db.commit()
return ok({
"staged": True,
"decisionId": row.id,
"decision": node_approve.view(row),
"route": route,
"activity": activity.name,
"work": _work_view(work),
"note": f"{resume_note}表态已备好,等这条待办的处理人确认后才真正办理",
})
@open_router.post("/open/nodes/{flow_no}/decide")
def open_node_decide_current(
flow_no: str,
body: schemas.NodeDecideBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""主写法省掉环节那一段的写法:第三方只报单号,OA 按这张单**此刻**停着的那一环按钮。
它把 ``activityId`` 从对方的代码里挪进了 OA:好处是少传一个参数,代价是"哪一环"
改由调用这一刻决定——报文晚到时,单子可能已经流到下一个同样开了接口的环节,这一次
表态就落在那一环上,而幂等按环节记,换个环节不算重复。所以默认仍推荐点名环节的
:func:`open_node_decide`,环节 id 每次从 ``locate`` / 事件信封里现取。环节开关、应用白名单、
幂等、出口匹配、确认模式这些判据一个都没另起炉灶:认出环节之后照样交回
:func:`open_node_decide` 办,两条地址往后走的是同一段代码。
认不出唯一一环就不猜(与 :func:`node_approve.resolve_task` 同一把尺):并行分支同时
停在两环上回 400 带候选与两条完整地址,让对方点名;停着的环节都没开接口回与长地址
同一句笼统话;开了但没对这个应用开口回 403。老写法(地址放流程定义 id + 报文带 work)
在这一条上不适用——光凭定义 id 认不出是哪张单,这一条只认单子上印的那个号与 job 号。
"""
context.need("task:write")
try:
work = node_approve.work_from_path(db, flow_no, body.work)
except ApiError as exc:
# 这一趟还没发起、而它该由开始环节直接接住:环节由 OA 认(这一档认得出——地址里
# 那个号是 OA 排出去的,按排号那本账能认回流程),认出之后交回主写法那一条,
# 往后每一步与长地址走的仍是同一段代码(§4.6.2)
target = (node_approve.unstarted_target(db, flow_no or str(body.work or ""), context.app.code)
if exc.reason in ("NODE_WORK_NOT_FOUND", node_approve.NOT_STARTED_REASON) else None)
if target is not None:
return open_node_decide(flow_no, target["activity"].id, body, context, db)
# 认不出号有两种:真给错了,和这张单已经办结 / 终止 / 作废搬进归档表了。
# 后者回「不用再表态」——机器人拿办结的单重试时,一句"没认出这张单"只会让它再试一次
note = (node_approve.archived_note(db, flow_no)
or node_approve.archived_note(db, body.work)) if exc.reason == "NODE_WORK_NOT_FOUND" else ""
if not note:
raise
raise bad_request(note, reason="NODE_WORK_NOT_RUNNING") from exc
if work.status != "running":
label = {"completed": "办结", "terminated": "终止", "canceled": "作废"}.get(work.status, work.status)
raise bad_request(f"流程已{label}并归档,无法再表态", reason="NODE_WORK_NOT_RUNNING")
targets, blocked = node_approve.open_targets(db, work, context.app.code)
if not targets:
if blocked:
raise forbidden("这一环没对当前应用开审批接口")
raise not_found("这张单当前停着的环节没开审批接口")
if len(targets) > 1:
ref = str(work.serial or work.job)
listed = "、".join(
f"{row.name}({node_approve.interface_path(ref, row.id).partition(' ')[2]})"
for row in targets
)
raise bad_request(
f"这张单当前同时停在 {len(targets)} 个开了审批接口的环节:{listed}。"
"把环节那一段加进地址,说清替哪一环表态",
reason="NODE_ACTIVITY_AMBIGUOUS",
)
return open_node_decide(flow_no=flow_no, activity_id=str(targets[0].id),
body=body, context=context, db=db)
def _oa_computed_keys(fields: list[dict]) -> set[str]:
"""系统自己带出的那几格:标题、单据编号、发起人这一类。
只读展示格(``type: auto`` / ``type: title``)与挂了自动带出的普通字段都算,
两处都认才不漏(与 :func:`app.service.autofill.serial_keys` 同一分寸)。
"""
out = {str(item.get("key") or "").strip() for item in fields or []
if str(item.get("type") or "") in ("auto", "title")}
out |= {key for key, _source in autofill.auto_fields(fields or [])}
out |= {key for key, _source, _ftype in autofill.typed_fields(fields or [])}
out.discard("")
return out
def _form_dropped_labels(db: Session, session, process) -> list[str]:
"""那份整张单快照因为太大被挤掉的格,换成人在屏幕上看到的名字。只给那句 400 用。"""
skipped = embed_session.trip_form_skipped(session)
if not skipped:
return []
fields = autofill.form_fields(db, str(getattr(process, "latest_form", "") or ""), None)
labels = {str(item.get("key") or ""): str(item.get("label") or "").strip()
for item in fields or []}
return [labels.get(key) or key for key in skipped]
def _trip_start_data(db: Session, session, process, incoming: dict) -> dict:
"""服务端建单时,把**这一趟 OA 手里已有的值**垫在报文底下。
厚此薄彼的顺序是有道理的:打开那一页时带进来的参数(:func:`embed_session.trip_args`)
与第三方后来回填进来的值(:func:`embed_session.staged_prefill`)都是这一趟早就送到 OA
手里的东西,而这次报文里显式给的 ``data`` 是**此刻**的话,以它为准。
最后一份是**发起页那一屏当下的表单值**(:func:`embed_session.trip_form`,由
``POST /embed/launch`` 每次打开与每次 ``refresh`` 留下来)。它排在草稿之上:草稿是那个人
上一次按下的那一份,这一份是他刚才敲的。真实报销单八格必填,而那一格通常只引用申请人、
单号、核算项目那几格,收款方式这种没被引用的必填格靠这一份才到得了服务端——
否则"人明明都填了、服务端手里却是空的"这件事只能由第三方再送一遍值来兜,
而那一句回写里本来就只有结论词。
**OA 从那张表单上拿到的这几份压在报文 ``data`` 之上**(参数、草稿、那一屏那份):
这些值本来就是这张 OA 表单上的,以 OA 中的为准;报文里那一格给空串、给假值都盖不掉它。
排在最底下的反而是第三方早先随回写攒下的那几格(:func:`embed_session.staged_prefill`)——
那也是对方说的话,该被对方这一次说的话覆盖。``data`` 真正干的是**补 OA 手里没有的那几格**,
这也是它对第三方唯一的用处:一句回写里不必把 OA 自己有的数再送一遍。
只垫表单真定义的那几格:``work.data`` 会原样收下拉里没定义的键,第三方那个参数表
将来加一个 ``hide_title`` 之类的展示参数,不该顺手变成单据数据。至于"这一格这一环
到底收不收",仍由引擎按环节权限判(回源带出那几格会被它退回去自己取)。
"""
if session is None:
return dict(incoming or {})
fields = autofill.form_fields(db, str(getattr(process, "latest_form", "") or ""), None)
known = {str(item.get("key") or "") for item in fields or []}
# OA 从这张表单上拿到的那三份,由旧到新叠:打开那一页带的参数 → 挂着的草稿
# → 发起页那一屏此刻的值
#
# 参数那一份**不能占住系统自己带出的那几格**:它是拼给对方看的一句人话
# (选人格拼成账号、日期拼成话),不是存储形状。而 :func:`app.service.autofill.apply_form`
# 的规矩是"只补空值"——这句话一占位,「申请人」就会留下一个字符串而不是那串人员引用,
# 详情页与后面按人找事的环节都认不出它。那一屏上的表单值不受此限:那本来就是存储形状。
own = _oa_computed_keys(fields)
held: dict[str, Any] = {key: value
for key, value in embed_session.trip_args(session).items()
if key not in own}
# 那一趟还挂着一张草稿时,草稿是**那个人自己存的那一份**,压过打开时带的那几格参数:
# 他在发起页上存过草稿又走掉了,第三方回写要的就是他存的那个样子。
# 只读,不删——删人的草稿这件事留给他自己按的那一次发起去做
draft_id = str(getattr(session, "draft", "") or "")
draft = db.get(models.Draft, draft_id) if draft_id else None
if draft is not None and str(draft.person or "") == str(getattr(session, "person", "") or ""):
held.update(dict(draft.data or {}))
held.update(embed_session.trip_form(session))
# 攒着的回填是**对方**说的话,跟着报文 data 那一层走;OA 那三份压在最上面——
# 对方报文里那一格给空串还是给个假值,都盖不掉 OA 手里已有的那一份
merged = {key: value for key, value in embed_session.staged_prefill(session).items()
if key in known}
merged.update({key: value for key, value in dict(incoming or {}).items()
if str(key or "").strip()})
merged.update({key: value for key, value in held.items()
if key in known and value not in (None, "", [], {})})
return merged
def _start_data_error(text: str, prefix: str = "", dropped: list[str] | None = None) -> ApiError:
"""发起那一步抱怨必填时,把话翻成第三方看得懂该往哪儿补的一句。
引擎那句只念格名(「表单校验未通过:报销月份」)。界面里的人看得见那一格,
而服务端到服务端的调用方手里只有一句日志——真实报销单有八九格必填,缺哪一格、
值该放进哪个字段、这一趟库里留没留下东西,都得在这一句里说清,否则对方只能回来问。
非必填那些抱怨(额度、闸门、图没了)原样交回去,不套这层壳。
"""
if "表单校验" not in text:
return bad_request(f"{prefix}{text}" if prefix else text)
# 这一趟其实有过值、只是太大没进底稿的那种缺,必须在这一句里说出口:
# 否则对方与管理员两头都只看见"OA 手里没有",而真相是"那一屏上有,只是没存下"
note = (f"(其中 {'、'.join(list(dropped)[:6])} 这一趟在发起页上本来有值,"
"只是那一格太大没进底稿)" if dropped else "")
return bad_request(
f"{prefix}{text}{note}。这些格 OA 这一趟手里没有——OA 已经把这一趟攒下的都垫进去了"
"(打开那一页时带的参数、攒着的回填、挂着的草稿、发起页那一屏此刻的表单值),"
"还缺就这三条路:让发起人回到 OA 那一屏把这几格填上(这一份 OA 会自己接住,不必对方改报文);"
"随这次表态把它们放进报文的 data 里(键名用表单字段名);"
'或先调 POST /open/works(带 "hold": true)把值带进来。'
"这次调用没留下半张单,也没另排号,补齐后原样再发一次就行",
reason="NODE_START_DATA_INCOMPLETE",
)
def _alias_named_serial(db: Session, session, work: models.Work) -> str:
"""这一趟的号换过了(重开发起页会另占一个):把那张单的号跟着换过去,再把落点记上。
``bizKey`` 认的是同一趟,号认的是同一张单,两样都得对得上:对方手里只剩这一个号,
往后定位与表态都拿它说话。换号本身在 :func:`embed_session.retarget_serial`,这里额外
把这一趟认领到那张单上(会话页与单据页要能互相跳回去)。
"""
if session is None:
return ""
note = embed_session.retarget_serial(db, session, work)
embed_session.apply_start(db, session, job=str(work.job or ""),
serial=str(work.serial or ""), work_id=str(work.id or ""))
return note
def _begin_start_from_decide(
db: Session,
process: models.Process,
activity: models.Activity,
config: dict,
body: schemas.NodeDecideBody,
context,
exc: ApiError,
refs: tuple = (),
) -> dict | None:
"""开始环节没认出这张单时的那条岔路:**这一趟由这次表态代发**。
地址里已经点名是哪一个环节,而它是开始环节——"没有活动流程"于是不是"不知道该在哪儿表态",
而是这一趟还没人发起。这一环勾了「没有单据时代为发起」(:data:`node_approve.AUTO_START_KEY`)
时,OA 就地建一张停着的单(表单校验、编号、标题、自动带出、闸门照跑,只是先不流转),
再把这次表态按原来那条路办下去:``auto`` 当场提交,``confirm`` 停在发起人面前等他点头。
没勾就把原话交回去——那句里写着该怎么走。
三件事在这里钉住,少一件都比"多一张单"贵:
* **幂等**:代发必须有 ``bizKey``,且进来先按 (app, 环节, bizKey) 认一次。没有这一条,
对方网络重试一次就多发一张报销单,而那正是建单这件事最怕的事故;
* **号不许换**:报文里那位 ``bizKey`` 同时当预受理号认一次,认到就把那一趟占下的号接过来
(:func:`embed_session.reserved_serial`),对方记的那个号从此一直是这张单的号;
* **数据照发起那一路校验**:用的是引擎 ``create_job``,与界面发起、``POST /open/works``
同一把尺,必填、公式、额度、闸门一条不会因为"来的是一句表态"就少跑。
"""
if activity.type != "begin" or str(getattr(exc, "reason", "")) not in (
"NODE_WORK_NOT_FOUND", node_approve.NOT_STARTED_REASON):
return None
if not node_approve.auto_start_enabled(config):
raise bad_request(
f"{exc.detail}这一环如果就是要由第三方替发起人提交,去环节配置的「外部审批」里勾上"
"「没有单据时代为发起」,这一次调用就能把流程直接提交起来",
reason=str(exc.reason),
)
biz = str(body.biz_key or "").strip()
if not biz:
raise bad_request(
"代发这张单要带 bizKey:它是这一趟的幂等号,也是重复调用时唯一能认回同一趟的东西"
"——少了它,一次网络重试就是一张重复的单",
reason="NODE_START_BIZ_KEY_REQUIRED",
)
# 幂等只认**同一趟**:这次点名的号与那次表态记的号不是同一个,就不是重试。对方那套流水号
# 是按报销记录编的,同一条记录他们可以把发起页重开一次(OA 一页占一个号)再回写一次——
# 那是另一趟,该照这一趟建单。2026-10-27 生产上就是这里咬人的:第二趟(``FYBX…023``)那句
# 裸 AGREE 命中了十分钟前第一趟(``FYBX…020``)那条已办的记录,OA 回 200 加
# ``alreadyHandled``,对方日志写着 ``writeback succeeded``,而 OA 里那张新单压根没建起来。
#
# 收窄只对着**OA 自己排出去的号**做:对方自己编一个号(排号那本账认不出归属)时照旧只按
# ``bizKey`` 认趟——那种场合按号收窄会把一次正常重试打成第二张单,而多建一张比少建一张贵。
issued = {one for one in (str(item or "").strip() for item in refs)
if one and numbering.owners_of_serial(db, one)}
done = node_approve.find_by_app_biz(db, context.app.code, activity.id, biz, serials=issued)
if done is not None and not node_approve.decision_superseded(db, done):
return {"replay": node_approve.replay(done, db=db)}
# 认这一趟有两条来路,都走通才是真"不用第三方改一个字":bizKey 填的是预受理号(PRE…),
# 或者地址里那个号本来就是 OA 发起页占下的正式号(真实回写就是这一种——他们把
# oa_flow_number 填在地址里,bizKey 用的是自己那套流水号)。两条都认不出人,才要 identity。
session = embed_session.by_prekey(db, biz)
if session is None:
for ref in refs:
session = embed_session.by_serial(db, str(ref or "")) or embed_session.by_prekey(db, str(ref or ""))
if session is not None:
break
if done is None:
# 按号没对上,但同一个 bizKey 在**早先那个号**上留过表态,而那张单此刻还停在开始环节
# 等提交:这是同一趟的延续,不是新的一趟。2026-10-27 16:53 生产上撞的就是这一条——
# ``FYBX…020`` 15:48 被退回发起人,16:52 他们重开发起页占下 ``FYBX…026``,16:53 那句
# AGREE 于是建出第二张单,原本那张还停在发起人手里等人和他们任何一方处理
done = node_approve.find_superseded_by_biz(db, context.app.code, activity.id, biz)
# 翻篇了:同一个 bizKey 早先那一趟被退回到开始环节,这一趟照发(对方改完材料就是拿原号重推的)
resume_note = node_approve.supersede_note(db, done) if done is not None else ""
if done is not None:
# 那一张还停在开始环节等提交:复用比另起一张诚实。再建一张只多出一个谁都不知道的号,
# 库里还留下一张停在起点没人认领的单
prior = node_approve.work_of_decision(db, done)
if (prior is not None and str(prior.status or "") == "running"
and str(prior.activity or "") == str(activity.id)):
# 这一张不是新单,别再挂"由这次表态代发"那句;号换过的事单独说一句
return {"work": prior, "note": "",
"alias": _alias_named_serial(db, session, prior)}
# 同一个 bizKey 确实在**别的一个号**上办过,而那张单已经不在这一步了:这一趟照发
# (他们重开发起页要的就是这一张),但要把那一趟点出来——库里凭空多出一张同 bizKey 的单,
# 事后没人愿意靠猜
other = node_approve.find_by_app_biz(db, context.app.code, activity.id, biz)
if not process.enabled or not process.published:
raise bad_request("这条流程没启用或没发布,这张单发不起来",
reason="NODE_PROCESS_NOT_STARTABLE")
identity = str(body.identity or "").strip() or str(getattr(session, "person", "") or "")
if not identity:
raise bad_request(
"代发这张单要说是替谁发起:报文带上 identity(这个人在 OA 里得存在),"
"或把 bizKey 填成 OA 发起页给过的那趟预受理号(PRE…),那边认得出人",
reason="NODE_START_IDENTITY_REQUIRED",
)
actor = context.as_actor(db, identity)
if not starters.allowed(db, process, identities=[actor.ref]):
raise forbidden("这个人不在该流程的发起范围里")
try:
result = engine.create_job(db, process_id=process.id, actor=actor,
data=_trip_start_data(db, session, process,
dict(body.data or {})),
title="",
serial=embed_session.reserved_serial(db, session),
hold_at_begin=True,
via=engine.VIA_OPEN)
except engine.EngineError as exc:
raise _start_data_error(str(exc), prefix="代发这张单没建成:",
dropped=_form_dropped_labels(db, session, process)) from exc
if session is not None:
embed_session.apply_start(db, session, **embed_session.claim_of_result(result))
work = db.get(models.Work, str(result.work_id or ""))
if work is None:
raise bad_request("单子建出来了却没找到,这一趟请带 bizKey 重试", reason="NODE_WORK_NOT_FOUND")
note = f"{resume_note}这张单由这次表态代发(单号 {work.serial or work.job})"
if other is not None and str(other.serial or "") and str(other.serial) != str(work.serial or ""):
note += (f";提醒:这个 bizKey 之前在 {other.serial} 那张上办过一次"
f"({other.create_time},走的「{other.route or other.status}」),这次点名的号不同,按另一趟处理")
return {"work": work, "note": f"{note},"}
def _open_node_decide_begin(
db: Session,
process: models.Process,
activity: models.Activity,
config: dict,
work: models.Work,
body: schemas.NodeDecideBody,
context,
start_note: str = "",
resume_note: str = "",
) -> dict:
"""开始环节的表态只有一颗钮:**提交**。单据必须正停在开始环节(hold 建的那一单),
同意 / 不同意在这里没有可走的出口,当场说清楚。confirm 模式停在发起人确认,
auto 模式当场把这一单提交出去——与人工环节同一套账(NodeDecision、bizKey 幂等)。"""
if work.activity != activity.id or work.activity_type != "begin":
raise bad_request(
"这张单已经离开开始环节(在流转或已办结),不用再提交",
reason="NODE_WORK_PAST_BEGIN",
)
kind = embed_session.decision_kind(body.result, node_approve.decisions_map(config))
if kind != "submit":
label = embed_session.DECISION_LABELS["submit"]
word = str(body.result or "").strip()
if not word:
raise bad_request(
f"开始环节只认「{label}」这一种表态,这一趟没带结论词。"
"请让第三方把结论词填上(提交 / SUBMITTED,或这一环决策词表里映到提交的那一个)",
reason="NODE_BEGIN_SUBMIT_ONLY",
)
# 念对方自己发的那个写法,不念翻完的 kind:他要照抄的是自己那一列
raise bad_request(
f"开始环节只认「{label}」这一种表态,「{word}」在这里没有可走的出口。"
f"让第三方把这一趟的结论词改成提交,或在这一环的决策词表里加一行「{word} → {label}」"
"(表里配的词优先于内置那几个——第三方那一套词不肯改时,"
"AGREE 这种内置写法也能在这张表里改判成提交)",
reason="NODE_BEGIN_SUBMIT_ONLY",
)
# 出口清单按这张单那一版图数:中途改了流程图,第三方被钉住的那条线在这张单脚下
# 还在,就不该拿当前图纸上的名字把它挡掉(引擎走的也是这一版图)。
definition = _work_definition(db, work)
names = _route_names_of(db, definition, process.id, activity.id)
pinned = node_approve.routes_map(config).get("submit", "")
if pinned:
if pinned in names:
route = pinned
else:
raise bad_request(
f"这一环把「{embed_session.DECISION_LABELS['submit']}」钉在出口「{pinned}」上,"
f"但那条线已经不在了。这一环现在的出口是:{'、'.join(names) or '没有了'}。"
"请重新配置或让第三方重新表态",
reason="NODE_ROUTE_PIN_MISSING",
)
else:
route, problem = embed_session.match_route(names, decision=kind, activity=activity.name)
if problem is not None:
raise bad_request(_decision_hint(problem[0], config), reason=problem[1])
fields = autofill.form_fields(db, _form_id_of(definition, activity, work), definition)
data, _dropped = node_approve.filter_data(body.data, config, fields)
opinion = str(body.opinion or "").strip() or node_approve.render_opinion(config, kind, work, data)
# 代发那句与翻篇那句都要出现在响应里,但 startedFromDecision 只跟着代发——
# 退回到开始环节重办的那一张不是新单,标成"由表态发起"会让人以为又建了一张
lead = f"{start_note}{resume_note}"
base = {
"app": context.app.code, "app_name": context.app.name,
"work": work.id, "job": work.job, "serial": work.serial,
"process": process.id, "process_name": process.name,
"activity": activity.id, "activity_name": activity.name,
"task": "", "task_identity": "", "task_identity_name": "",
"decision": str(body.result or ""), "kind": kind, "route": route,
"opinion": opinion, "data": data, "biz_key": str(body.biz_key or ""),
}
if node_approve.confirm_mode(config) == "auto":
# 当场提交:以**建单那个人**的名义走引擎真正的那一步——字段权限、必填、
# 公式、额度、外部核验闸门一条不少(见 engine.start_from_begin)。
actor = context.as_actor(db, work.creator_identity)
try:
result = engine.start_from_begin(db, work=work, actor=actor,
route_name=route, opinion=opinion, data=data,
via=engine.VIA_OPEN)
except engine.EngineError as exc:
raise _start_data_error(str(exc)) from exc
work_view = _result_work(db, result)
payload = {
"handled": True, "route": route, "activity": activity.name,
"status": work_view["status"], "done": bool(result.completed),
"work": work_view,
"tasks": [{"id": t.id, "activity": t.activity_name, "identity": t.identity} for t in result.tasks],
"startedFromDecision": bool(start_note),
"note": f"{lead}已按开始环节「{activity.name}」的外部审批配置提交这张单",
}
node_approve.record(db, base, status=node_approve.STATUS_HANDLED, response=payload)
db.commit()
return ok(payload)
row = node_approve.record(
db, base, status=node_approve.STATUS_STAGED,
expires_at=datetime.now() + timedelta(seconds=node_approve.ttl_seconds()))
db.commit()
return ok({
"staged": True,
"decisionId": row.id,
"decision": node_approve.view(row),
"route": route,
"activity": activity.name,
"work": _work_view(work),
"startedFromDecision": bool(start_note),
"note": f"{lead}表态已备好,等发起人确认后这张单才会真正提交",
})
@open_router.post("/open/tasks/completed/{task_completed_id}/recall")
def open_recall_task(
task_completed_id: str,
body: schemas.OpenRecallBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""撤回一条已办:第三方自己那边收回了结论,同步到 OA 来。
与界面那条「撤回已办」同一口径:只有**处理那条待办的人自己**(或管理员)撤得动,
后续环节已经有人查看/处理过的撤不动,环节关掉 ``allowRecall`` 的也撤不动。
撤不撤得动由引擎说了算,这里不另开后门。
"""
context.need("task:write")
record = db.get(models.TaskCompleted, task_completed_id)
if record is None:
raise not_found("已办记录不存在或已被删除")
actor = context.as_actor(db, body.identity or record.identity)
try:
result = engine.reset_task(db, task_completed_id=task_completed_id, actor=actor,
opinion=str(body.opinion or "外部系统撤回"),
via=engine.VIA_OPEN)
except engine.EngineError as exc:
raise bad_request(str(exc)) from exc
db.commit()
return ok({
"work": _result_work(db, result),
"tasks": [{"id": task.id, "activity": task.activity_name, "identity": task.identity}
for task in result.tasks],
"note": "已撤回:这条待办重新回到处理人手上",
})
# ===========================================================================
# 数据面:外部核验(票据初审那一类)
#
# 三条通道里的一条在这里(回调),另外两条在自家:提交时现场回源(``service/gate``)
# 与定时对账(``main._scheduler_loop``)。三条都写 :func:`external_check.apply_verdict`
# 这一个收口点,所以"重复回传""迟到回传""单据已归档"这三种下场只有一套行为。
# ===========================================================================
@open_router.post("/open/checks/report")
def open_report_check(
body: schemas.ExternalCheckReportBody,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
) -> dict:
"""核验系统把结论回传进台账。**这里不碰流转**:OA 什么时候往下走由闸门判(§1.2 铁律)。
要"审完就让流程往下走"的,走现成的 ``POST /open/tasks/{id}/execute`` 把那条待办办掉,
两个入口共用同一条待办 → 谁先办谁生效,第二个必然被挡并被告知"已由谁处理",
不需要新建一套冲突协商。
返回值里的 ``changed`` 才说明这次真的改了状态。**重复与迟到都回 200**:
把重试当错误,对方只会一路重试到把限流打满,最后死信里全是假事故。
"""
context.need("check:write")
try:
report = external_check.apply_verdict(
db,
provider=body.provider, biz_key=body.biz_key, status=body.status,
reason=body.reason, items=list(body.items or []), checker=body.checker,
checker_name=body.checker, checked_at=body.checked_at, version=body.version,
external_ref=body.external_ref, serial=body.serial, scene=body.scene,
origin=models.ExternalCheck.ORIGIN_CALLBACK,
response=body.model_dump(mode="json"),
)
except external_check.CheckError as exc:
raise bad_request(str(exc), reason="CHECK_INVALID") from exc
db.commit()
row = report.row
note = (
"重复回传,已按首次结果返回" if report.duplicate else
# 迟到有两种:版本号比台账旧、以及这一批早就出过终态。对外只有一句"丢了",
# 对方排查时最想知道的其实是"那你现在算的是哪个结论",所以把台账现在的结论一起报出去
("这条比台账上的结论旧(或这一批已出过结论),已丢弃:台账仍是"
f"{external_check.status_label(row.status) if row else '未知'}") if report.late else
f"结论已记录:{external_check.status_label(row.status) if row else ''}"
)
return ok({
"bizKey": row.biz_key if row else body.biz_key,
"status": row.status if row else "",
"changed": report.changed,
"late": report.late,
"duplicate": report.duplicate,
# 不属于这张单的逐票记录被丢掉了:给个数量,对方能立刻看出是自己拼错了单
"droppedItems": report.dropped,
"note": note,
})
@open_router.get("/open/checks/files")
def open_check_files(
biz_key: str = Query("", alias="bizKey"),
exp: str = Query(""),
sig: str = Query(""),
ttl: int = Query(0, ge=0, le=3600),
db: Session = Depends(get_db),
) -> dict:
"""送审报文里那条**附件清单**入口:靠签名鉴权,不要访问令牌。
为什么单独有这一条:报文可能退避重试几小时,把 10 分钟就废的文件地址写进报文,
第一次没发出去就全废了。清单链接给七天,它只能换回"这一批有哪些文件",
而清单里每一条文件地址仍然只有 10 分钟——放宽的是"能再问一次清单",
不是"文件一直能下"。作废与已撤回的批次不再给(单都退回了,不该还能拖走影像)。
"""
row = external_check.find(db, biz_key=biz_key)
if row is None:
raise not_found(f"批次 {biz_key} 不存在")
problem = external_check.verify_link(f"manifest:{biz_key}", exp, sig)
if problem:
raise forbidden(problem, reason="CHECK_LINK_INVALID")
try:
return ok(external_check.manifest_of(db, row, ttl=ttl or external_check.FILE_TTL_SECONDS))
except external_check.CheckError as exc:
raise forbidden(str(exc), reason="CHECK_UNAVAILABLE") from exc
@open_router.get("/open/attachments/{attachment_id}/download")
def open_download_attachment(
attachment_id: str,
request: Request,
job: str = Query(""),
exp: str = Query(""),
sig: str = Query(""),
db: Session = Depends(get_db),
) -> Response:
"""取附件字节:签名 + 期限 + **绑死在这张单上**,支持 ``Range``(几十兆的扫描件套件)。
与自家那个 ``GET /attachment/{id}/download`` 是两条完全不同的门:那条认登录态,
这条认一条 HMAC 签名,签名里绑了 ``附件 id + 单号 + 过期时间``。换单、换附件、改时间
这三个动作里任何一个都会验不过——不是"记得去查一下",是签名压根算不出来。
每次调用都进 ``oa_open_call``(中间件统一留痕,失败的那一次最需要留痕)。
"""
row = db.get(models.Attachment, attachment_id)
if row is None:
raise not_found("附件不存在")
problem = external_check.verify_link(f"file:{attachment_id}:{job}", exp, sig)
if problem:
raise forbidden(problem, reason="CHECK_LINK_INVALID")
if str(row.job or "") != str(job or ""):
raise forbidden("这条下载地址与附件所属的单据对不上", reason="CHECK_LINK_INVALID")
try:
return download_response(
resolve_uri(row.storage), row.storage, row.name,
"application/octet-stream", range_header=request.headers.get("range"),
)
except StorageError as exc:
raise storage_error(exc) from exc
@open_router.get("/open/checks/{biz_key}")
def open_get_check(
biz_key: str,
context: OpenContext = Depends(open_context),
db: Session = Depends(get_db),
provider: str = Query(""),
) -> dict:
"""查一个核验批次:对方对账时用,"你到底收到我上次那句没有"。
顺带把附件清单也带上(现签一批 10 分钟地址),省一次往返。
"""
context.need("check:read")
row = external_check.find(db, provider=provider, biz_key=biz_key)
if row is None:
raise not_found(f"批次 {biz_key} 不存在")
payload = external_check.view(row)
payload.pop("override", None) # 谁给这张单放的行是内部责任信息,不给对方看
payload["files"] = external_check.manifest_of(db, row)["files"]
return ok(payload)
@router.get("/design/open/calls")
def list_calls(
app_code: str = Query("", alias="app"),
keyword: str = Query(""),
limit: int = Query(80, ge=1, le=LIST_LIMIT),
db: Session = Depends(get_db),
_: CurrentUser = Depends(require_permission("design:openapi")),
) -> dict:
"""开放接口的调用留痕。对方说"你那天给我返回错了",就翻这一张表。"""
stmt = select(models.OpenCall).order_by(models.OpenCall.id.desc()).limit(limit)
if app_code:
stmt = stmt.where(models.OpenCall.app == app_code)
if keyword:
like = f"%{keyword}%"
stmt = stmt.where(models.OpenCall.path.like(like) | models.OpenCall.app_name.like(like))
rows = list(db.execute(stmt).scalars().all())
return ok({"items": [{
"id": row.id,
"app": row.app,
"appName": row.app_name,
"method": row.method,
"path": row.path,
"statusCode": row.status_code,
"code": row.code,
"error": row.error,
"tokenHint": row.token_hint,
"ip": row.ip,
"ms": row.ms,
"createTime": _stamp(row.create_time),
} for row in rows]})
@router.get("/design/open/summary")
def open_summary(db: Session = Depends(get_db), _: CurrentUser = Depends(require_permission("design:openapi"))) -> dict:
"""开放平台首页那一排数字,顺带告诉用户总闸开没开。"""
counts = dict(db.execute(
select(models.OpenEvent.status, func.count(models.OpenEvent.id)).group_by(models.OpenEvent.status)
).all())
return ok({
"apps": int(db.execute(select(func.count(models.OpenApp.id))).scalar_one() or 0),
"webhooks": int(db.execute(select(func.count(models.OpenWebhook.id))).scalar_one() or 0),
"events": {key: int(counts.get(key, 0)) for key in models.OpenEvent.STATUSES},
"masterSwitch": bool(dbconfig.value("open_events_enabled", True)),
})