diff --git a/backend/app/api/notify.py b/backend/app/api/notify.py index 8702528a..95e73ea4 100644 --- a/backend/app/api/notify.py +++ b/backend/app/api/notify.py @@ -7,6 +7,11 @@ 个人渠道谁都能建(权限最低的使用者也能),地址另过一遍 SSRF 检查(tools/net.py,不开内网),保存和发送时各一次: 不然服务端替它往内网地址发 POST,测试接口交回的状态码和报错就成了探测内网的信号(A6.2:只有登记的端点能访问内网)。 全局、应用的渠道只有搭建者以上能建,和定时任务的 Webhook 同一个信任级别,地址照旧只查格式(内网的接收端很常见)。 + +邮件(第五种格式,notify/mail.py,04 细案 B2):个人邮件渠道不收地址,只发到本人在名录里的账号邮箱(能填任意地址的话,个人 +渠道就成了谁都能用的邮件中继);全局、应用的邮件渠道填固定的收件地址,最多 20 个。邮件服务(设置的 mail 一组)没启用时 +不收新的邮件渠道:建了也发不出去,就是「看着生效、其实没生效」。渠道列表另给 mail:邮件服务启没启用、本人的账号邮箱, +设置页据此决定列不列「邮件」这一格式、个人邮件渠道写「发到账号邮箱 …」。 """ from __future__ import annotations @@ -20,7 +25,7 @@ from app.api.deps import current_principal from app.core.crypto import encrypt from app.db.base import SessionLocal from app.db.models import NotifyChannel, NotifyDelivery -from app.notify import core +from app.notify import core, mail from app.notify.service import EVENTS, channel_out, subscribe_problem router = APIRouter(prefix="/api/notify", tags=["notify"]) @@ -64,25 +69,72 @@ async def _safe_personal(scope: str, url: str) -> None: def _validated(payload: ChannelIn, *, url: str | None, saved: list[str] | None = None) -> None: """saved 是渠道已经订阅着的事件:只核对这次新勾的(notify/service.subscribe_problem)。以前存下的照旧——当时界面对 哪种渠道都列全部事件,现在才按事件推给哪几条路核对,不能让这些渠道连开关、改名都 422。""" - if payload.format not in core.FORMATS: - raise HTTPException(422, f"消息格式只能是{'、'.join(core.FORMAT_LABEL.values())}之一") + if payload.format not in core.CHANNEL_FORMATS: + raise HTTPException(422, f"消息格式只能是{'、'.join(core.FORMAT_LABEL[f] for f in core.CHANNEL_FORMATS)}之一") for event in dict.fromkeys(payload.events): if event not in (saved or ()) and (problem := subscribe_problem(event, payload.scope)): raise HTTPException(422, problem) - if url is not None and (problem := core.format_problem(payload.format, url)): + if url is not None and payload.format != "email" and (problem := core.format_problem(payload.format, url)): raise HTTPException(422, problem) +#: 个人邮件渠道带了地址:不收(见模块说明) +PERSONAL_MAIL_NO_URL = "个人邮件渠道只发到你的账号邮箱,不用填地址" + + +async def _mail_target(scope: str, url: str | None, *, saved: str | None = None) -> str: + """邮件渠道 url 列存什么(明文,调用方加密):个人渠道存占位,全局、应用的是校验过的收件地址(逗号分隔)。 + url 没给、原来就是邮件渠道的(saved)沿用原来的地址。邮件服务没启用时不收(见模块说明)。""" + from app.db.base import SessionLocal + + async with SessionLocal() as session: + cfg = await mail.load_config(session) + if not cfg.enabled: + raise HTTPException(422, mail.NOT_ENABLED) + if scope == "user": + if url and url.strip(): + raise HTTPException(422, PERSONAL_MAIL_NO_URL) + return mail.PERSONAL_PLACEHOLDER + if not (url and url.strip()): + if saved: + return saved + raise HTTPException(422, "请填写收件地址,多个地址用逗号或换行分隔") + try: + return ", ".join(mail.parse_recipients(url)) + except ValueError as e: + raise HTTPException(422, str(e)) from e + + +async def _owner_emails(rows: list[NotifyChannel]) -> dict[str, str | None]: + """个人邮件渠道的拥有者 → 账号邮箱(channel_out 写「发到账号邮箱 …」用)。""" + from app.db.models import User + + owners = {r.owner_id for r in rows if r.scope == "user" and r.format == "email" and r.owner_id} + if not owners: + return {} + async with SessionLocal() as session: + found = (await session.execute(select(User.id, User.email).where(User.id.in_(owners)))).all() + return {uid: email for uid, email in found} + + @router.get("/channels") async def list_channels() -> dict[str, Any]: - """{items}:形状同前端的接口约定(frontend/src/api/capabilities.ts)。""" + """{items, mail}:形状同前端的接口约定(frontend/src/api/capabilities.ts)。mail 是邮件服务启没启用、本人的账号邮箱 + (关登录时没有账号,为 null):设置页据此列不列「邮件」格式、个人邮件渠道发到哪。""" + from app.db.models import User + principal = current_principal() stmt = select(NotifyChannel).order_by(NotifyChannel.created_at) if principal.mode != "off": # 个人渠道只给本人看 stmt = stmt.where(or_(NotifyChannel.scope != "user", NotifyChannel.owner_id == principal.user_id)) async with SessionLocal() as session: - return {"items": [channel_out(r) for r in (await session.execute(stmt)).scalars()]} + rows = list((await session.execute(stmt)).scalars()) + cfg = await mail.load_config(session) + mine = await session.get(User, principal.user_id) if principal.mode != "off" and principal.user_id else None + emails = await _owner_emails(rows) + return {"items": [channel_out(r, emails.get(r.owner_id or "")) for r in rows], + "mail": {"enabled": cfg.enabled, "account_email": (mine.email or None) if mine is not None else None}} @router.get("/events") @@ -96,19 +148,25 @@ async def list_events() -> list[dict[str, Any]]: async def create_channel(payload: ChannelIn) -> dict[str, Any]: owner = current_principal().user_id if payload.scope == "user" else payload.owner_id _can_edit(payload.scope, owner) - try: - url = core.check_url(payload.url) - except ValueError as e: - raise HTTPException(422, str(e)) from e - _validated(payload, url=url) - await _safe_personal(payload.scope, url) + if payload.format == "email": + _validated(payload, url=None) + url = await _mail_target(payload.scope, payload.url) + secret = None # 邮件没有签名密钥 + else: + try: + url = core.check_url(payload.url) + except ValueError as e: + raise HTTPException(422, str(e)) from e + _validated(payload, url=url) + await _safe_personal(payload.scope, url) + secret = encrypt(payload.secret) if payload.secret else None row = NotifyChannel(name=payload.name.strip(), scope=payload.scope, owner_id=owner, format=payload.format, - url=encrypt(url), secret=encrypt(payload.secret) if payload.secret else None, - events=list(dict.fromkeys(payload.events)), enabled=payload.enabled) + url=encrypt(url), secret=secret, events=list(dict.fromkeys(payload.events)), + enabled=payload.enabled) async with SessionLocal() as session: session.add(row) await session.commit() - return channel_out(row) + return channel_out(row, (await _owner_emails([row])).get(row.owner_id or "")) class ChannelPatch(BaseModel): @@ -144,29 +202,40 @@ async def update_channel(channel_id: str, payload: ChannelIn) -> dict[str, Any]: _can_edit(row.scope, row.owner_id) if payload.scope != row.scope: raise HTTPException(422, "通知渠道的范围建好之后不能修改,请新建一个") - url = None - if payload.url: - try: - url = core.check_url(payload.url) - except ValueError as e: - raise HTTPException(422, str(e)) from e - if url is None: - from app.core.crypto import decrypt + from app.core.crypto import decrypt - current = decrypt(row.url) or "" - _validated(payload, url=current or None, saved=list(row.events or [])) + url = None + if payload.format == "email": + _validated(payload, url=None, saved=list(row.events or [])) + # 只开关、改名、改订阅(地址不传)的不重新核对邮件服务:停用了邮件服务,已有的渠道照样能关掉、改名 + if payload.url or row.format != "email": + saved = decrypt(row.url) if row.format == "email" and row.scope != "user" else None + row.url = encrypt(await _mail_target(row.scope, payload.url, saved=saved)) + row.secret = None else: - _validated(payload, url=url, saved=list(row.events or [])) - await _safe_personal(row.scope, url) - row.url = encrypt(url) + if payload.url: + try: + url = core.check_url(payload.url) + except ValueError as e: + raise HTTPException(422, str(e)) from e + elif row.format == "email": + # 邮件渠道换成 Webhook:原来存的是收件地址,不是能发的 Webhook 地址 + raise HTTPException(422, "换成 Webhook 格式要填写 Webhook 地址") + if url is None: + current = decrypt(row.url) or "" + _validated(payload, url=current or None, saved=list(row.events or [])) + else: + _validated(payload, url=url, saved=list(row.events or [])) + await _safe_personal(row.scope, url) + row.url = encrypt(url) + if payload.secret is not None: + row.secret = encrypt(payload.secret) if payload.secret else None row.name, row.format = payload.name.strip(), payload.format row.events, row.enabled = list(dict.fromkeys(payload.events)), payload.enabled - if payload.secret is not None: - row.secret = encrypt(payload.secret) if payload.secret else None if row.scope == "app": row.owner_id = payload.owner_id await session.commit() - return channel_out(row) + return channel_out(row, (await _owner_emails([row])).get(row.owner_id or "")) @router.delete("/channels/{channel_id}", status_code=204) @@ -191,7 +260,8 @@ async def test_channel(channel_id: str) -> dict[str, Any]: raise HTTPException(404, "通知渠道不存在,可能已被删除") _can_edit(row.scope, row.owner_id) message = {"event": "test", "title": f"通知渠道「{row.name}」测试", "ok": True, "retry": False, - "lines": [("说明", "这是一条测试消息。收到即表示渠道地址配置正确" + "lines": [("说明", ("这是一封测试邮件。收到即表示邮件服务和收件地址配置正确" if row.format == "email" else + "这是一条测试消息。收到即表示渠道地址配置正确") + (";请求头带有签名,接收端可据此核对签名密钥" if row.secret and row.format == "generic" else ""))]} outcome = await send(row, message) @@ -201,6 +271,10 @@ async def test_channel(channel_id: str) -> dict[str, Any]: attempts=outcome.attempts, error=outcome.error)) await session.commit() if outcome.ok: + if row.format == "email": + # 交给了邮件服务器不等于进了收件箱:退信不追踪,照实说 + return {"ok": True, "http_status": None, + "message": f"{outcome.error or mail.HANDED_OFF},是否送达以邮件服务器为准,请到收件箱确认"} return {"ok": True, "http_status": outcome.http_status, "message": "请到接收端确认已收到"} return {"ok": False, "http_status": outcome.http_status, "message": outcome.error or "发送失败"} @@ -212,12 +286,15 @@ async def list_deliveries( task_id: str | None = None, limit: int = Query(default=100, ge=1, le=500), ) -> dict[str, Any]: - """投递记录。开登录后 user 角色只看发往自己的个人渠道的:别的渠道的投递记录里有所有应用、所有运行的待办和动作。""" - stmt = select(NotifyDelivery).order_by(NotifyDelivery.created_at.desc()).limit(limit) + """投递记录。开登录后 user 角色只看发往自己的个人渠道的:别的渠道的投递记录里有所有应用、所有运行的待办和动作。 + + format 是渠道的格式:邮件渠道成功的那条界面上写「已交给邮件服务器」,不写「已送达」(退信不追踪)。""" + stmt = (select(NotifyDelivery, NotifyChannel.format) + .join(NotifyChannel, NotifyChannel.id == NotifyDelivery.channel_id) + .order_by(NotifyDelivery.created_at.desc()).limit(limit)) principal = current_principal() if principal.mode != "off" and not principal.at_least("builder"): - stmt = stmt.join(NotifyChannel, NotifyChannel.id == NotifyDelivery.channel_id).where( - NotifyChannel.scope == "user", NotifyChannel.owner_id == principal.user_id) + stmt = stmt.where(NotifyChannel.scope == "user", NotifyChannel.owner_id == principal.user_id) if channel_id: stmt = stmt.where(NotifyDelivery.channel_id == channel_id) if run_id: @@ -225,9 +302,9 @@ async def list_deliveries( if task_id: stmt = stmt.where(NotifyDelivery.task_id == task_id) async with SessionLocal() as session: - rows = (await session.execute(stmt)).scalars() + rows = (await session.execute(stmt)).all() return {"items": [{ "id": r.id, "channel_id": r.channel_id, "subject_kind": r.subject_kind, "subject_id": r.subject_id, "event": r.event, "run_id": r.run_id, "task_id": r.task_id, "status": r.status, - "http_status": r.http_status, "attempts": r.attempts, "error": r.error, - "created_at": r.created_at.isoformat() if r.created_at else None} for r in rows]} + "http_status": r.http_status, "attempts": r.attempts, "error": r.error, "format": fmt, + "created_at": r.created_at.isoformat() if r.created_at else None} for r, fmt in rows]} diff --git a/backend/app/api/settings.py b/backend/app/api/settings.py index c45a685a..c1f0fdaa 100644 --- a/backend/app/api/settings.py +++ b/backend/app/api/settings.py @@ -613,8 +613,9 @@ def catalog_draft_values(stored: Any) -> dict[str, Any]: #: 全站只认一个对外地址(core/public_url.py):环境变量 AGENTLAB_PUBLIC_URL 设了的话这一项不生效、不能改(PUT 回 409)。 #: 键名沿用 notify 一组,界面上在「设置 → 通用」 NOTIFY_GROUP = public_url.SETTING_GROUP -NOTIFY_DEFAULTS: dict[str, Any] = {public_url.SETTING_KEY: None} -NOTIFY_SETTING_LABEL = {public_url.SETTING_KEY: "对外访问地址"} +#: digest_at:每天几点给订阅了「每天的待办汇总」的个人渠道发汇总(HH:MM,按服务端所在时区;notify/digest.py,04 细案 B3) +NOTIFY_DEFAULTS: dict[str, Any] = {public_url.SETTING_KEY: None, "digest_at": "09:00"} +NOTIFY_SETTING_LABEL = {public_url.SETTING_KEY: "对外访问地址", "digest_at": "待办汇总的发送时间"} #: GET /api/settings 另给的只读一组:{value: 生效的对外访问地址, env_locked: 是不是环境变量指定的}。设置页据此显示 #: 「由环境变量指定」;PUT 带上它也不落库(同 limits) PUBLIC_URL_GROUP = "public_url" @@ -641,15 +642,25 @@ def notify_problem(value: Any) -> str | None: if key not in NOTIFY_DEFAULTS: return (f"「通知」设置中不支持「{key}」,可设置的项:" + "、".join(f"「{NOTIFY_SETTING_LABEL[k]}」" for k in NOTIFY_DEFAULTS)) - if problem := _base_url_problem(item): + if key == "digest_at": + from app.notify.digest import time_ok + + if not time_ok(item): + return f"「{NOTIFY_SETTING_LABEL[key]}」需要写成 时:分(00:00 到 23:59,例如 09:00),当前为「{item}」" + elif problem := _base_url_problem(item): return problem return None def notify_values(stored: Any) -> dict[str, Any]: - """库里存的(或刚写进来的)notify 一组 → 补齐默认、规范化:去掉首尾空白和末尾的 /,空串当没填;存坏了的按没填。""" + """库里存的(或刚写进来的)notify 一组 → 补齐默认、规范化:去掉首尾空白和末尾的 /,空串当没填;存坏了的按没填。 + 汇总时间存坏了按缺省。""" + from app.notify.digest import time_ok + stored = stored if isinstance(stored, dict) else {} - return {public_url.SETTING_KEY: public_url.normalize(stored.get(public_url.SETTING_KEY))} + at = stored.get("digest_at") + return {public_url.SETTING_KEY: public_url.normalize(stored.get(public_url.SETTING_KEY)), + "digest_at": at.strip() if time_ok(at) else NOTIFY_DEFAULTS["digest_at"]} async def notify_settings(session: AsyncSession) -> dict[str, Any]: @@ -676,8 +687,11 @@ def public_url_values(stored_notify: Any) -> dict[str, Any]: #: user_personal_apps:开了登录时使用者能不能建个人应用、刷新、提交审核(默认关,同问数据的开关;搭建者及以上不受它管)。 #: 关登录时它照样生效:关着就没有个人应用的入口。只有管理员能改(整个设置接口的改动都要管理员) APPS_GROUP = "apps" -APPS_DEFAULTS: dict[str, Any] = {"on_demand_daily_limit": 200, "user_personal_apps": False} -APPS_SETTING_LABEL = {"on_demand_daily_limit": "按需视图每日上限", "user_personal_apps": "使用者可以建个人应用"} +#: share_links:能不能建分享链接(只读、不用登录就能看的视图页,api/shares.py,04 细案 C2、集成-I6)。缺省关;关掉时已有的 +#: 分享链接一并打不开(管理员随时收得回来),撤销照常能做 +APPS_DEFAULTS: dict[str, Any] = {"on_demand_daily_limit": 200, "user_personal_apps": False, "share_links": False} +APPS_SETTING_LABEL = {"on_demand_daily_limit": "按需视图每日上限", "user_personal_apps": "使用者可以建个人应用", + "share_links": "允许建分享链接"} #: 上限的上限:再大就等于不限,要不限的不该靠这一项 APPS_DAILY_LIMIT_MAX = 100_000 @@ -694,7 +708,7 @@ def apps_problem(value: Any) -> str | None: if key not in APPS_DEFAULTS: return (f"「应用」设置中不支持「{key}」,可设置的项:" + "、".join(f"「{APPS_SETTING_LABEL[k]}」" for k in APPS_DEFAULTS)) - if key == "user_personal_apps": + if key in ("user_personal_apps", "share_links"): if not isinstance(item, bool): return f"「{APPS_SETTING_LABEL[key]}」只能是开或关,当前为「{item}」" elif not _daily_limit_ok(item): @@ -708,8 +722,10 @@ def apps_values(stored: Any) -> dict[str, Any]: stored = stored if isinstance(stored, dict) else {} limit = stored.get("on_demand_daily_limit") personal = stored.get("user_personal_apps") + shares = stored.get("share_links") return {"on_demand_daily_limit": limit if _daily_limit_ok(limit) else APPS_DEFAULTS["on_demand_daily_limit"], - "user_personal_apps": personal if isinstance(personal, bool) else APPS_DEFAULTS["user_personal_apps"]} + "user_personal_apps": personal if isinstance(personal, bool) else APPS_DEFAULTS["user_personal_apps"], + "share_links": shares if isinstance(shares, bool) else APPS_DEFAULTS["share_links"]} async def apps_settings(session: AsyncSession) -> dict[str, Any]: @@ -718,6 +734,15 @@ async def apps_settings(session: AsyncSession) -> dict[str, Any]: return apps_values(row.value if row else None) +# -------------------------------------------------------------------------- +# 邮件服务(notify/mail.py,04 细案 B2):只有管理员能改(整个设置接口的改动都要管理员),口令加密存、读的时候只说配没配 +# -------------------------------------------------------------------------- + +MAIL_GROUP = "mail" +#: 发测试邮件没有可发的账号(关登录)、账号没有邮箱时 POST /api/settings/mail/test 回 422 的机读码 +MAIL_TEST_NO_ADDRESS = "mail_test_no_address" + + # -------------------------------------------------------------------------- # 用户设置 # -------------------------------------------------------------------------- @@ -731,6 +756,19 @@ def _hidden_groups() -> tuple[str, ...]: return (AUTH_KEY,) +def _mail_public(stored: Any) -> dict[str, Any]: + from app.notify import mail + + return mail.public_value(stored) + + +def _internal(key: str) -> bool: + """通知自己记的账(每天汇总的认领行、自动建过邮件渠道的人,notify/digest.STATE_PREFIX):不是用户设置,不列、不收。""" + from app.notify.digest import STATE_PREFIX + + return key.startswith(STATE_PREFIX) + + DEFAULT_SETTINGS: dict[str, Any] = { "ui": {"theme": "system", "language": "zh", "canvas_snap": True, "autosave": True}, "run": { @@ -761,8 +799,10 @@ DEFAULT_SETTINGS: dict[str, Any] = { NOTIFY_GROUP: notify_values(None), # 起草模型:数据目录起草、按配方导入的 AI 起草用的模型,留空沿用助手的模型 CATALOG_DRAFT_GROUP: catalog_draft_values(None), - # 应用:按需视图的每日上限、使用者能不能建个人应用(管理员在设置页改) + # 应用:按需视图的每日上限、使用者能不能建个人应用、能不能建分享链接(管理员在设置页改) APPS_GROUP: apps_values(None), + # 邮件服务(SMTP):通知渠道的邮件格式用它发信。缺省关 + MAIL_GROUP: _mail_public(None), } @@ -817,6 +857,7 @@ async def get_settings(session: AsyncSession = Depends(get_session)) -> dict[str stored.pop(VERIFY_SPEND, None) for key in _hidden_groups(): stored.pop(key, None) + stored = {k: v for k, v in stored.items() if not _internal(k)} merged = {k: {**v, **(stored.get(k) or {})} for k, v in DEFAULT_SETTINGS.items()} # 裁判、核查设置按引擎实际生效的样子给:存坏了的项显示默认,存了 null 的上限显示不限 merged[JUDGE_GROUP] = judge_values(stored.get(JUDGE_GROUP)) @@ -825,6 +866,8 @@ async def get_settings(session: AsyncSession = Depends(get_session)) -> dict[str merged[PUBLIC_URL_GROUP] = public_url_values(stored.get(NOTIFY_GROUP)) merged[CATALOG_DRAFT_GROUP] = catalog_draft_values(stored.get(CATALOG_DRAFT_GROUP)) merged[APPS_GROUP] = apps_values(stored.get(APPS_GROUP)) + # 口令不回(password 恒为 null),只说配没配(password_set) + merged[MAIL_GROUP] = _mail_public(stored.get(MAIL_GROUP)) for key, value in stored.items(): merged.setdefault(key, value) return merged @@ -914,8 +957,10 @@ async def put_settings( if problem := notify_problem(payload.values[NOTIFY_GROUP]): raise HTTPException(422, problem) # 存规范化之后的:末尾带 / 的地址拼链接会多出一个斜杠 - payload.values[NOTIFY_GROUP] = notify_values(payload.values[NOTIFY_GROUP]) - if public_url.env_locked() and payload.values[NOTIFY_GROUP] != await notify_settings(session): + # 只给了一部分的(只改汇总时间)补上存着的另几项,不把对外访问地址冲成没填 + payload.values[NOTIFY_GROUP] = notify_values({**await notify_settings(session), **payload.values[NOTIFY_GROUP]}) + current_url = (await notify_settings(session))[public_url.SETTING_KEY] + if public_url.env_locked() and payload.values[NOTIFY_GROUP][public_url.SETTING_KEY] != current_url: # 环境变量指定了对外访问地址:改这一项不会生效,照实拒绝,不悄悄存一个用不上的值。原样写回(整组回写)不算改 raise CodedHTTPException( 409, f"对外访问地址由环境变量 {public_url.ENV_NAME} 指定({public_url.env_url()}),不能在设置里修改。" @@ -924,10 +969,18 @@ async def put_settings( if problem := apps_problem(payload.values[APPS_GROUP]): raise HTTPException(422, problem) payload.values[APPS_GROUP] = apps_values(payload.values[APPS_GROUP]) + if MAIL_GROUP in payload.values: + from app.notify import mail + + saved_mail = await session.get(Setting, MAIL_GROUP) + saved_value = saved_mail.value if saved_mail is not None else None + if problem := mail.settings_problem(payload.values[MAIL_GROUP], saved_value): + raise HTTPException(422, problem) + payload.values[MAIL_GROUP] = mail.stored_value(payload.values[MAIL_GROUP], saved_value) if found := await _provider_problem(session, payload.values): raise CodedHTTPException(422, found[1], PROVIDER_INVALID, field=found[0]) for key, value in payload.values.items(): - if key in (TRUST_KEY, "limits", PUBLIC_URL_GROUP, JUDGE_SPEND, VERIFY_SPEND, *_hidden_groups()): + if key in (TRUST_KEY, "limits", PUBLIC_URL_GROUP, JUDGE_SPEND, VERIFY_SPEND, *_hidden_groups()) or _internal(key): # 信任三档只走 PUT /api/tools/trust:设置页整组回写时带着一份旧的, # 会把刚在工具页改的档位冲掉。limits 是环境变量定的、public_url 是算出来的,写进库也不生效。 # 裁判、核查的每日计数是引擎记的账,只有引擎自己写。登录设置只经 /api/auth/settings 改(_hidden_groups) @@ -944,6 +997,35 @@ async def put_settings( return await get_settings(session) +@router.post("/settings/mail/test") +async def test_mail(session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """按存着的邮件服务设置发一封测试邮件,发到管理员自己的账号邮箱(只发到认证过的账号,不收任意地址:不让这个接口成了 + 邮件中继)。没启用也能测(配好了先试一封再启用);不重试。{ok, message}:成功说「已交给邮件服务器」,是否送达以邮件服务器 + 为准(退信不追踪)。关登录时没有账号、账号没有邮箱:422(mail_test_no_address),说清怎么办。""" + from app.api.deps import current_principal + from app.db.models import User + from app.notify import mail + from app.notify.core import Message + + principal = current_principal() + if principal.mode == "off" or not principal.user_id: + raise CodedHTTPException(422, "关闭登录时没有账号邮箱,测试邮件发不到人:请建一个全局的邮件渠道、填上收件地址," + "用渠道的「发送测试消息」试", MAIL_TEST_NO_ADDRESS) + user = await session.get(User, principal.user_id) + to = (user.email or "").strip() if user is not None else "" + if not mail.address_ok(to): + raise CodedHTTPException(422, f"{mail.NO_EMAIL},再发测试邮件", MAIL_TEST_NO_ADDRESS) + row = await session.get(Setting, MAIL_GROUP) + cfg = mail.config_of(row.value if row is not None else None) + if not cfg.ready: + return {"ok": False, "message": f"请先填写并保存「{mail.LABEL['host']}」和「{mail.LABEL['from_addr']}」,再发测试邮件"} + msg = Message(title="邮件服务测试", ok=True, lines=[("说明", "这是一封测试邮件。收到即表示邮件服务配置正确")]) + outcome = await mail.send(cfg, [to], msg, label="测试邮件", retry=False) + if outcome.ok: + return {"ok": True, "message": f"{mail.HANDED_OFF}(发到 {to}),是否送达以邮件服务器为准,请到收件箱确认"} + return {"ok": False, "message": outcome.error or "发送失败"} + + @router.get("/settings/judge/spend") async def get_judge_spend(session: AsyncSession = Depends(get_session)) -> dict[str, Any]: """今天(本地日期)结论句裁判花了多少,设置页放在每日上限旁边。只读:计数只有裁判自己记。 diff --git a/backend/app/notify/__init__.py b/backend/app/notify/__init__.py index cc70c81e..13c2eb47 100644 --- a/backend/app/notify/__init__.py +++ b/backend/app/notify/__init__.py @@ -1,6 +1,7 @@ """通知的发送核心(附录 C,BE-2 提供)。从 scheduler/webhook.py 抽出:四种格式、签名、发送、脱敏(core.py); webhook.py 照原名再导出,定时任务的通知存储不迁移(F14)。新对象(待办、实例、动作)的订阅和投递记录在 -service.py:渠道(notify_channels)、投递记录(notify_deliveries)。""" +service.py:渠道(notify_channels)、投递记录(notify_deliveries)。渠道的第五种格式「邮件」走 mail.py(SMTP),订阅、 +投递记录、消息结构都和 Webhook 同一套,只是在这里按格式分到另一条发送路上。""" from __future__ import annotations from typing import Any @@ -22,6 +23,10 @@ async def send(channel: Any, message: dict[str, Any]) -> Any: lines=[(str(k), str(v)) for k, v in message.get("lines") or []], links=[(str(k), str(v)) for k, v in message.get("links") or []], ok=bool(message.get("ok"))) + if channel.format == "email": + from app.notify import mail + + return await mail.deliver(channel, message, msg) if not url: return Outcome(False, None, 0, "渠道的地址无法解密(加密密钥可能已更换),请重新填写地址") if getattr(channel, "scope", None) == "user": diff --git a/backend/app/notify/core.py b/backend/app/notify/core.py index d354f5d4..8ea196e5 100644 --- a/backend/app/notify/core.py +++ b/backend/app/notify/core.py @@ -1,6 +1,7 @@ """通知的发送核心:四种格式、签名、发送、脱敏(从 scheduler/webhook.py 抽出,定时任务和待办、实例、动作共用一份)。 -四种格式:通用 JSON、飞书(文本消息)、企业微信(markdown)、钉钉(markdown)。配了签名密钥时:通用格式在请求头 +四种格式:通用 JSON、飞书(文本消息)、企业微信(markdown)、钉钉(markdown)。通知渠道另有第五种「邮件」,发送在 +notify/mail.py(SMTP,不经这里的 HTTP 推送),消息结构(Message、text_of)共用这里的。配了签名密钥时:通用格式在请求头 里带 HMAC-SHA256 签名,飞书、钉钉按各自平台的算法签(飞书放在请求体,钉钉放在地址上);企业微信的 key 本来就在 地址里,没有另外的签名。入站钩子(app/process/hooks.py)验的也是通用格式这一套签名。 @@ -37,8 +38,11 @@ from app.db.base import utcnow logger = logging.getLogger(__name__) FORMATS = ("generic", "feishu", "wecom", "dingtalk") +#: 通知渠道能选的格式:Webhook 的四种,加上邮件(notify/mail.py,04 细案 B2,第五种格式)。定时任务的 Webhook 只有前四种 +#: (它只会发 HTTP),所以邮件不进 FORMATS:scheduler/webhook 再导出的、定时任务接口校验的都是那一份 +CHANNEL_FORMATS = (*FORMATS, "email") #: 格式在报错里的叫法,和界面上的选项一致 -FORMAT_LABEL = {"generic": "通用", "feishu": "飞书", "wecom": "企业微信", "dingtalk": "钉钉"} +FORMAT_LABEL = {"generic": "通用", "feishu": "飞书", "wecom": "企业微信", "dingtalk": "钉钉", "email": "邮件"} #: 单次请求的超时(秒) TIMEOUT_S = 10.0 #: 失败后再试 3 次,每次之前等这么久(秒)。4xx(429 除外)不重试:地址或参数错了,重试也一样 diff --git a/backend/app/notify/digest.py b/backend/app/notify/digest.py new file mode 100644 index 00000000..574bb2ca --- /dev/null +++ b/backend/app/notify/digest.py @@ -0,0 +1,185 @@ +"""每天的待办汇总、访问密钥快到期:什么时候推(docs/design/next-round/04-对外集成与触达.md B3)。 + +调度循环每一拍调一次(scheduler/loop.process_due 的步骤列表);拼消息、推送在 notify/service(notify_digest、 +notify_key_expiring),推送放在后台(service.spawn):接收端挂住时超时加重试要几十秒,不能拖着这一拍别的步骤。 + +待办汇总(task.digest): +- 每天到设置里的 notify.digest_at(缺省 09:00,按服务端所在时区)之后的第一拍,给订阅了 task.digest 的个人渠道的拥有者各发 + 一条(没有待办的人不发); +- 按日期在 settings 表里认领一行(键 STATE_PREFIX + "digest:<日期>",主键冲突就是已经认领过):同一天只发一次,重启了也不 + 重发。认领之后推送失败不补发——通知本来就是至多一次,投递记录里照实记失败。停机错过的那一天不补; +- 认领行只留最近 KEEP_DAYS 天。 + +访问密钥快到期(key.expiring): +- 到期前 7 天、1 天各推一次(THRESHOLDS):个人访问密钥推给拥有者的个人渠道,服务账号的推给订阅了的全局渠道; +- 去重靠审计:推之前先记一条 access_key.expiring(data.days 是哪一档),记过的不再推(进程里另记一份,省得每拍查审计); +- 不推的:建的时候离到期已经不到这一档(自己设了短有效期,知道它快到期);轮换下来、24 小时后到期的旧密钥(新的那把已经 + 在用);撤销了的;拥有者停用了的;个人密钥开关关着时的个人密钥(本来就不认了)。 + +这两种状态(认领行、自动建过邮件渠道的人)存在 settings 表里,键都以 STATE_PREFIX 开头:它们是通知自己记的账,不是用户设置, +GET /api/settings 不列、PUT 不收(api/settings.py)。 +""" +from __future__ import annotations + +import logging +import re +from datetime import datetime, timedelta +from typing import Any + +from sqlalchemy import delete, select +from sqlalchemy.exc import IntegrityError + +from app.db.base import SessionLocal, utcnow +from app.db.models import NotifyChannel, Setting, User + +logger = logging.getLogger(__name__) + +#: settings 表里通知自己记的账(不是用户设置)的键的开头 +STATE_PREFIX = "notify_state:" +DIGEST_CLAIM = STATE_PREFIX + "digest:" +#: 汇总的缺省发送时间(服务端所在时区) +DEFAULT_AT = "09:00" +#: 认领行留几天 +KEEP_DAYS = 7 +#: 访问密钥到期前几天各推一次 +THRESHOLDS = (7, 1) + +_TIME = re.compile(r"^([01]\d|2[0-3]):([0-5]\d)$") +#: 这个进程里已经认领(或者看到别人认领了)的日期:同一天不再去插认领行 +_claimed: set[str] = set() +#: 这个进程里已经推过(或者审计里已经有)的 (密钥 id, 档) +_noted: set[tuple[str, int]] = set() + + +def time_ok(value: Any) -> bool: + return isinstance(value, str) and bool(_TIME.match(value.strip())) + + +def at_of(stored_notify: Any) -> tuple[int, int]: + """设置 notify 一组里的 digest_at → (时, 分);没填、存坏了按缺省。""" + raw = stored_notify.get("digest_at") if isinstance(stored_notify, dict) else None + match = _TIME.match(raw.strip()) if isinstance(raw, str) else None + if match is None: + match = _TIME.match(DEFAULT_AT) + assert match is not None + return int(match.group(1)), int(match.group(2)) + + +async def _claim(day: str, now: datetime) -> bool: + """认领这一天的汇总:插一行,主键冲突就是已经有人认领过。顺带清掉 KEEP_DAYS 天以前的认领行。""" + key = DIGEST_CLAIM + day + async with SessionLocal() as session: + if await session.get(Setting, key) is not None: + return False + session.add(Setting(key=key, value={"claimed_at": now.isoformat()})) + try: + await session.commit() + except IntegrityError: + return False + floor = DIGEST_CLAIM + (now.astimezone().date() - timedelta(days=KEEP_DAYS)).isoformat() + await session.execute(delete(Setting).where(Setting.key.like(DIGEST_CLAIM + "%"), Setting.key < floor)) + await session.commit() + return True + + +async def digest_due(now: datetime | None = None) -> list[str]: + """到点了就认领今天、给订阅了汇总的人各发一条(后台推)。交回这一拍要发给谁(用户 id),没到点、已经发过是空的。""" + from app.api.settings import NOTIFY_GROUP + from app.notify import service + + now = now or utcnow() + local = now.astimezone() + day = local.date().isoformat() + if day in _claimed: + return [] + async with SessionLocal() as session: + row = await session.get(Setting, NOTIFY_GROUP) + if (local.hour, local.minute) < at_of(row.value if row is not None else None): + return [] + claimed = await _claim(day, now) + _claimed.add(day) + if not claimed: + return [] + async with SessionLocal() as session: + rows = (await session.execute(select(NotifyChannel.owner_id, NotifyChannel.events).where( + NotifyChannel.scope == "user", NotifyChannel.enabled.is_(True), + NotifyChannel.owner_id.is_not(None)))).all() + owners = list(dict.fromkeys(owner for owner, events in rows if "task.digest" in (events or []))) + for owner in owners: + service.spawn(_digest_one(owner)) + if owners: + logger.info("今天(%s)的待办汇总:发给 %d 个人", day, len(owners)) + return owners + + +async def _digest_one(user_id: str) -> None: + from app.notify import service + + try: + await service.notify_digest(user_id) + except Exception: # noqa: BLE001 - 一个人的汇总出错不影响别人,待办本身也不受影响 + logger.exception("给用户 %s 发待办汇总失败", user_id) + + +async def keys_due(now: datetime | None = None) -> list[str]: + """访问密钥快到期了的,按档推一次(见模块说明)。交回这一拍推了哪几把(密钥 id)。""" + from app.auth import personal_keys_enabled + from app.auth.audit import record + from app.auth.keys import SERVICE_KIND + from app.db.models import AuditEvent + from app.db.models_identity import AccessKey + from app.notify import service + + now = now or utcnow() + horizon = now + timedelta(days=max(THRESHOLDS)) + async with SessionLocal() as session: + rows = (await session.execute(select(AccessKey, User).join(User, User.id == AccessKey.owner_user_id).where( + AccessKey.revoked_at.is_(None), AccessKey.expires_at > now, AccessKey.expires_at <= horizon))).all() + if not rows: + return [] + ids = [key.id for key, _ in rows] + replaced = set((await session.execute(select(AccessKey.rotated_from).where( + AccessKey.rotated_from.in_(ids)))).scalars()) + out: list[str] = [] + for key, owner in rows: + if owner.disabled or key.id in replaced: + continue + if owner.kind != SERVICE_KIND and not personal_keys_enabled(): + continue + expires = service._utc(key.expires_at) + left = expires - now + days = next(d for d in sorted(THRESHOLDS) if left <= timedelta(days=d)) + created = service._utc(key.created_at) if key.created_at else None + if created is not None and created > expires - timedelta(days=days): + continue + if (key.id, days) in _noted: + continue + async with SessionLocal() as session: + seen = (await session.execute(select(AuditEvent.data).where( + AuditEvent.action == "access_key.expiring", AuditEvent.subject_id == key.id))).scalars() + if any(isinstance(d, dict) and d.get("days") == days for d in seen): + _noted.add((key.id, days)) + continue + await record(session, "access_key.expiring", "access_key", key.id, actor=None, verified=False, + data={"days": days, "expires_at": expires.isoformat(), "name": key.name, + "owner": owner.username}) + await session.commit() + _noted.add((key.id, days)) + service.spawn(_key_one(key.id, days)) + out.append(key.id) + return out + + +async def _key_one(key_id: str, days: int) -> None: + from app.notify import service + + try: + await service.notify_key_expiring(key_id, days) + except Exception: # noqa: BLE001 + logger.exception("访问密钥 %s 快到期的提醒推送失败", key_id) + + +def forget() -> None: + """测试用:清掉进程里记的(认领过的日期、推过的密钥档)。""" + _claimed.clear() + _noted.clear() diff --git a/backend/app/notify/mail.py b/backend/app/notify/mail.py new file mode 100644 index 00000000..2318bfe7 --- /dev/null +++ b/backend/app/notify/mail.py @@ -0,0 +1,424 @@ +"""邮件:通知渠道的第五种格式(docs/design/next-round/04-对外集成与触达.md B2,总方案 X12、集成-I4)。 + +为什么改写应用平台的 Q6(「待办通知只用 Webhook 的四种格式,不做邮件——SMTP 要另配服务器、还要处理退信」): +- 待办派给了人却找不到人:群机器人群里人人看得见,算不上个人;用户表里本来就有 email(单点登录时自动填,管理员在 + 「设置 → 身份」里也能改),邮件是真正能触达个人、成本最低的办法; +- Q6 担心的两件事这里都照实处理,不假装做到:SMTP 是可选配置(设置里的 mail 一组,缺省关,不配就没有邮件这一格式); + 退信不追踪——投递记录成功时写的是「已交给邮件服务器」,是否进了收件箱以邮件服务器为准,界面上也照这样写; +- IM 应用消息(企业微信、飞书、钉钉的应用消息)这次不做:要企业应用凭据、令牌刷新和用户 id 映射,和 IM 登录是同一套, + 放到一起做。 + +一种说法:邮件只是渠道的一种格式,订阅、投递记录(notify_deliveries)、测试、消息结构(core.Message:只有标题、状态、 +条数、链接,不放数字)都走同一套;不另建邮件表。 + +收件人: +- 个人邮件渠道(scope=user)不填地址,只发到拥有者在名录里的账号邮箱(users.email):可以填任意地址的话,个人渠道就成了 + 谁都能用的垃圾邮件中继,而且发到的不是认证过的身份。账号没有邮箱时记一条失败的投递并写明原因(NO_EMAIL); +- 全局、应用的邮件渠道(搭建者以上能建)填固定的收件地址,最多 MAX_RECIPIENTS 个,和全局 Webhook 同一个信任级别。 + 地址同 Webhook 一样加密落库(渠道表不改结构:个人渠道存一个占位)。 + +发送:标准库 smtplib,放在 asyncio.to_thread 里(不多一个依赖),单次超时 TIMEOUT_S 秒。4xx(临时错误)和连不上按 +1/2/4 秒重试,5xx(地址、认证、内容被拒)不重试——重试也一样。报错里只写主机名和服务器的回话,绝不出现口令(scrub)。 +测试把 _smtp_factory 换成假的(同 core._transport 的做法)。 + +邮件内容:纯文本一份、简单的 HTML 一份(全部转义);带 List-Unsubscribe(指向「设置 → 通知」,没有对外访问地址时不带: +这个头只认完整的地址),Auto-Submitted: auto-generated。 + +设置的 mail 一组只有管理员能改(整个设置接口的改动都要管理员);口令用 core/crypto 加密存,读设置时只说配没配。 +内网的 SMTP 由管理员配置,不做 SSRF 检查(同全局 Webhook)。 +""" +from __future__ import annotations + +import asyncio +import html +import logging +import re +import smtplib +import socket +import ssl +from collections.abc import Callable +from dataclasses import dataclass +from email.message import EmailMessage +from email.utils import formataddr, formatdate, make_msgid +from typing import Any + +from app.notify.core import Message, Outcome, text_of + +logger = logging.getLogger(__name__) + +#: 设置里的这一组 +GROUP = "mail" +#: 加密方式:starttls(587,明文连上再升级)、ssl(465,一上来就是加密连接)、none(内网明文中继) +SECURITY = ("starttls", "ssl", "none") +SECURITY_LABEL = {"starttls": "STARTTLS", "ssl": "SSL/TLS", "none": "不加密"} +DEFAULTS: dict[str, Any] = {"enabled": False, "host": None, "port": 587, "security": "starttls", "username": None, + "password": None, "from_addr": None, "from_name": "AgentLab", + "default_for_assignees": False} +LABEL = {"enabled": "启用邮件", "host": "SMTP 服务器", "port": "端口", "security": "加密方式", "username": "用户名", + "password": "口令", "from_addr": "发件地址", "from_name": "发件人名称", + "default_for_assignees": "默认发邮件给待办处理人"} +#: 单次连接、读写的超时(秒) +TIMEOUT_S = 10.0 +#: 临时错误、连不上时再试 3 次,每次之前等这么久(秒) +RETRY_DELAYS: tuple[float, ...] = (1.0, 2.0, 4.0) +#: 全局、应用的邮件渠道最多几个收件地址 +MAX_RECIPIENTS = 20 +#: 个人邮件渠道 url 列存的占位(加密后落库):收件人一律取拥有者的账号邮箱 +PERSONAL_PLACEHOLDER = "account-email" +#: 管理员开了「默认发邮件给待办处理人」时,自动建的个人邮件渠道默认订阅这几项(本人之后可以改、可以关) +ASSIGNEE_EVENTS = ("task.opened", "action.unknown", "review.done") +ASSIGNEE_CHANNEL_NAME = "待办邮件(自动建)" + +NO_EMAIL = "你的账号没有邮箱地址,请联系管理员在「设置 → 身份」里填写" +NOT_ENABLED = "邮件服务没有启用:请管理员在「设置 → 通知 → 邮件服务」里配置并启用" +HANDED_OFF = "已交给邮件服务器" + +#: 测试用:换成假的 SMTP 工厂,(host, port, security, timeout) → 有 starttls / login / send_message / quit / close 的对象 +_smtp_factory: Callable[[str, int, str, float], Any] | None = None + +# 地址只认最常见的写法:本地部分不含空白和尖括号,域名至少有一个点。换行一律拒收(防邮件头注入) +_ADDRESS = re.compile(r"^[^@\s<>\"(),;:\\]+@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+$") +_HOST = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$|^\[[0-9A-Fa-f:.]+\]$") + + +# -------------------------------------------------------------------------- +# 地址、设置 +# -------------------------------------------------------------------------- + + +def address_ok(text: Any) -> bool: + return isinstance(text, str) and len(text) <= 254 and bool(_ADDRESS.match(text)) + + +def parse_recipients(raw: Any) -> list[str]: + """全局、应用邮件渠道填的收件地址(逗号、分号、空白、换行分隔都行)→ 去重后的列表。不对抛 ValueError(中文说明)。""" + if isinstance(raw, list): + parts = [str(p) for p in raw] + elif isinstance(raw, str): + parts = re.split(r"[\s,;,;、]+", raw) + else: + parts = [] + out = list(dict.fromkeys(p.strip() for p in parts if p and p.strip())) + if not out: + raise ValueError("请填写至少一个收件地址,多个地址用逗号或换行分隔") + if len(out) > MAX_RECIPIENTS: + raise ValueError(f"收件地址最多 {MAX_RECIPIENTS} 个,当前填了 {len(out)} 个;人多的请改用邮件组的地址") + bad = [p for p in out if not address_ok(p)] + if bad: + raise ValueError(f"收件地址「{bad[0][:80]}」不是有效的邮件地址") + return out + + +def _text(value: Any) -> str | None: + return value.strip() if isinstance(value, str) and value.strip() else None + + +def _port_ok(value: Any) -> bool: + return isinstance(value, int) and not isinstance(value, bool) and 1 <= value <= 65535 + + +def settings_problem(value: Any, saved: Any = None) -> str | None: + """设置页写进来的 mail 一组有什么问题,没问题是 None。saved 是库里存着的那份(口令没给就沿用它)。 + + 启用时要配全:服务器、发件地址;没启用时可以只填一部分先存着。发件人名称、主机名里不许有换行(邮件头注入)。""" + if not isinstance(value, dict): + return f"「邮件服务」设置格式有误,需要是一个对象,当前为「{value}」" + for key, item in value.items(): + if key == "password_set": + continue # GET 给的只读项,整组回写时带着它不算错 + if key not in DEFAULTS: + return "「邮件服务」设置中不支持「" + key + "」,可设置的项:" + "、".join(f"「{LABEL[k]}」" for k in DEFAULTS) + label = LABEL[key] + if key in ("enabled", "default_for_assignees"): + if not isinstance(item, bool): + return f"「{label}」只能是开或关,当前为「{item}」" + elif key == "port": + if not _port_ok(item): + return f"「{label}」需要是 1 到 65535 之间的整数,当前为「{item}」" + elif key == "security": + if item not in SECURITY: + return f"「{label}」只能是 {'、'.join(SECURITY_LABEL.values())} 之一" + elif item is not None and not isinstance(item, str): + return f"「{label}」需要是文字,当前为「{item}」" + elif isinstance(item, str) and any(c in item for c in "\r\n"): + return f"「{label}」里不能有换行" + elif key == "host" and _text(item) and not _HOST.match(item.strip()): + return f"「{label}」需要是主机名或 IP 地址(例如 smtp.example.com),不带协议和端口,当前为「{item}」" + elif key == "from_addr" and _text(item) and not address_ok(item.strip()): + return f"「{label}」不是有效的邮件地址,当前为「{item}」" + elif key in ("username", "from_name") and isinstance(item, str) and len(item) > 200: + return f"「{label}」最长 200 个字" + elif key == "password" and isinstance(item, str) and len(item) > 500: + return f"「{label}」过长" + merged = {**public_value(saved), **{k: v for k, v in value.items() if k in DEFAULTS and k != "password"}} + if merged.get("enabled"): + if not _text(merged.get("host")): + return f"启用邮件之前请填写「{LABEL['host']}」" + if not _text(merged.get("from_addr")): + return f"启用邮件之前请填写「{LABEL['from_addr']}」" + return None + + +def stored_value(value: dict[str, Any], saved: Any = None) -> dict[str, Any]: + """校验过的 mail 一组 → 落库的样子:补齐默认、去掉首尾空白;口令没给(或给 null)沿用存着的,给空串表示去掉, + 给了新的就加密。""" + from app.core.crypto import encrypt + + old = saved if isinstance(saved, dict) else {} + out = {**DEFAULTS, **{k: v for k, v in old.items() if k in DEFAULTS}} + for key, item in value.items(): + if key not in DEFAULTS or key == "password": + continue + out[key] = item.strip() if isinstance(item, str) else item + for key in ("host", "username", "from_addr", "from_name"): + out[key] = _text(out.get(key)) + out["from_name"] = out["from_name"] or DEFAULTS["from_name"] + given = value.get("password") + if isinstance(given, str): + out["password"] = encrypt(given) if given else None + return out + + +def public_value(stored: Any) -> dict[str, Any]: + """读设置时给的样子(GET /api/settings 的 mail 一组):口令不回,只说配没配(password_set)。存坏了的项按默认。""" + stored = stored if isinstance(stored, dict) else {} + out: dict[str, Any] = {} + for key, default in DEFAULTS.items(): + item = stored.get(key) + if key in ("enabled", "default_for_assignees"): + out[key] = item if isinstance(item, bool) else default + elif key == "port": + out[key] = item if _port_ok(item) else default + elif key == "security": + out[key] = item if item in SECURITY else default + elif key == "password": + out[key] = None + else: + out[key] = _text(item) or default + out["password_set"] = bool(stored.get("password")) + return out + + +@dataclass(frozen=True) +class MailConfig: + """发信用的配置(口令已解密,只在发送时用)。""" + + enabled: bool + host: str | None + port: int + security: str + username: str | None + password: str | None + from_addr: str | None + from_name: str + default_for_assignees: bool + + @property + def ready(self) -> bool: + """配全了能发:服务器、发件地址都有。启不启用另看 enabled。""" + return bool(self.host and self.from_addr) + + +def config_of(stored: Any) -> MailConfig: + from app.core.crypto import decrypt + + shown = public_value(stored) + secret = stored.get("password") if isinstance(stored, dict) else None + return MailConfig(enabled=shown["enabled"], host=shown["host"], port=shown["port"], security=shown["security"], + username=shown["username"], password=decrypt(secret) if isinstance(secret, str) else None, + from_addr=shown["from_addr"], from_name=shown["from_name"], + default_for_assignees=shown["default_for_assignees"]) + + +async def load_config(session: Any = None) -> MailConfig: + from app.db.base import SessionLocal + from app.db.models import Setting + + if session is None: + async with SessionLocal() as own: + row = await own.get(Setting, GROUP) + else: + row = await session.get(Setting, GROUP) + return config_of(row.value if row is not None else None) + + +# -------------------------------------------------------------------------- +# 邮件内容 +# -------------------------------------------------------------------------- + + +_FOOTER = "这封邮件由 AgentLab 自动发出,请勿直接回复。不想再收到:在 AgentLab「设置 → 通知」里关掉或删除这个渠道" + + +def build(cfg: MailConfig, to: list[str], msg: Message, *, unsubscribe: str | None) -> EmailMessage: + """一封邮件:纯文本一份、HTML 一份(全部转义)。unsubscribe 是「设置 → 通知」的完整地址,没有就不带退订头。""" + em = EmailMessage() + em["Subject"] = f"【AgentLab】{msg.title}"[:200] + em["From"] = formataddr((cfg.from_name or DEFAULTS["from_name"], cfg.from_addr or "")) + em["To"] = ", ".join(to) + em["Date"] = formatdate(localtime=True) + em["Message-ID"] = make_msgid(domain=(cfg.from_addr or "agentlab.invalid").rpartition("@")[2] or None) + # 自动发出的通知:自动回复不该回给它(RFC 3834) + em["Auto-Submitted"] = "auto-generated" + if unsubscribe: + em["List-Unsubscribe"] = f"<{unsubscribe}>" + footer = _FOOTER + (f":{unsubscribe}" if unsubscribe else "") + em.set_content(f"{text_of(msg)}\n\n——\n{footer}\n") + em.add_alternative(_html(msg, unsubscribe), subtype="html") + return em + + +def _html(msg: Message, unsubscribe: str | None) -> str: + esc = html.escape + color = "#1a7f37" if msg.ok else "#9a6700" + rows = "".join( + f'
【AgentLab】{esc(msg.title)}
' + f'{tail}
') + + +# -------------------------------------------------------------------------- +# 发送 +# -------------------------------------------------------------------------- + + +def _default_factory(host: str, port: int, security: str, timeout: float) -> Any: + if security == "ssl": + return smtplib.SMTP_SSL(host, port, timeout=timeout, context=ssl.create_default_context()) + return smtplib.SMTP(host, port, timeout=timeout) + + +def scrub(text: str, cfg: MailConfig) -> str: + """报错里不出现口令(服务器回话里偶尔会把收到的内容原样带回来)。""" + if cfg.password and len(cfg.password) >= 3: + text = text.replace(cfg.password, "…") + return text + + +def _reply(error: Any) -> str: + raw = getattr(error, "smtp_error", b"") + text = raw.decode("utf-8", "replace") if isinstance(raw, bytes) else str(raw or "") + return " ".join(text.split())[:200] + + +def _send_once(cfg: MailConfig, to: list[str], em: EmailMessage) -> Outcome: + """连一次、发一次(同步,在线程里跑)。结果按 SMTP 的回码分:2xx 已交给邮件服务器;4xx、连不上值得再试;5xx 不再试。""" + host = f"{cfg.host}:{cfg.port}" + factory = _smtp_factory or _default_factory + client = None + try: + client = factory(cfg.host or "", cfg.port, cfg.security, TIMEOUT_S) + if cfg.security == "starttls": + client.starttls(context=ssl.create_default_context()) + if cfg.username: + client.login(cfg.username, cfg.password or "") + refused = client.send_message(em, from_addr=cfg.from_addr, to_addrs=to) or {} + except smtplib.SMTPNotSupportedError: + return Outcome(False, None, 1, f"邮件服务器 {host} 不支持 STARTTLS:请把「加密方式」改成 SSL/TLS 或不加密") + except smtplib.SMTPRecipientsRefused as e: + codes = [code for code, _ in (e.recipients or {}).values()] + temporary = any(400 <= int(c) < 500 for c in codes) + return Outcome(False, None, 1, f"邮件服务器 {host} 拒收了全部 {len(codes) or len(to)} 个收件地址" + + ("(临时错误)" if temporary else ""), retryable=temporary) + except smtplib.SMTPAuthenticationError as e: + code = int(e.smtp_code or 0) + return Outcome(False, None, 1, scrub(f"邮件服务器 {host} 不接受这组用户名和口令({code})" + + (f":{_reply(e)}" if _reply(e) else ""), cfg)[:300], + retryable=400 <= code < 500) + except smtplib.SMTPResponseException as e: + code = int(e.smtp_code or 0) + detail = _reply(e) + text = scrub(f"邮件服务器 {host} 回复 {code}" + (f":{detail}" if detail else ""), cfg)[:300] + # SMTPConnectError 也走这里(连上了但对方回了错误码);回码不是 5xx 的都当临时错误 + return Outcome(False, None, 1, text, retryable=not 500 <= code < 600) + except smtplib.SMTPServerDisconnected: + return Outcome(False, None, 1, f"邮件服务器 {host} 断开了连接", retryable=True) + except ssl.SSLError: + return Outcome(False, None, 1, f"和邮件服务器 {host} 建立加密连接失败:请核对「加密方式」和端口(SSL/TLS 常用 465," + "STARTTLS 常用 587)") + except (socket.timeout, TimeoutError): + return Outcome(False, None, 1, f"连接邮件服务器 {host} 超时({TIMEOUT_S:g} 秒)", retryable=True) + except socket.gaierror: + return Outcome(False, None, 1, f"找不到邮件服务器 {cfg.host}(域名无法解析)", retryable=True) + except OSError: + return Outcome(False, None, 1, f"无法连接邮件服务器 {host}", retryable=True) + except Exception as e: # noqa: BLE001 - 拼信、编码出错也只记一条失败,不让推送任务抛出去 + logger.exception("发邮件时出错(%s)", host) + return Outcome(False, None, 1, f"向邮件服务器 {host} 发信时出错({type(e).__name__})") + finally: + if client is not None: + try: + client.quit() + except Exception: # noqa: BLE001 - 已经断开的连接 quit 会抛,关掉就行 + try: + client.close() + except Exception: # noqa: BLE001 + pass + if refused: + # 部分地址被拒:其余的已经交给邮件服务器,算成功,照实写有几个没收 + return Outcome(True, None, 1, f"{HANDED_OFF},其中 {len(refused)} 个收件地址被拒收") + return Outcome(True, None, 1) + + +async def send(cfg: MailConfig, to: list[str], msg: Message, *, label: str, unsubscribe: str | None = None, + retry: bool = True, delays: tuple[float, ...] | None = None) -> Outcome: + """发一封邮件(含重试)。label 是日志里的「谁的推送」。没配全的照实回失败,不连服务器。""" + if not cfg.ready: + return Outcome(False, None, 0, NOT_ENABLED) + em = build(cfg, to, msg, unsubscribe=unsubscribe) + waits = (RETRY_DELAYS if delays is None else delays) if retry else () + last = Outcome(False, None, 0, "没有发出邮件") + for attempt in range(len(waits) + 1): + if attempt: + await asyncio.sleep(waits[attempt - 1]) + last = await asyncio.to_thread(_send_once, cfg, to, em) + last.attempts = attempt + 1 + if last.ok: + return last + logger.warning("%s(邮件服务器 %s)第 %d 次发信失败:%s", label, cfg.host, attempt + 1, last.error) + if not last.retryable: + break + return last + + +async def recipients_of(session: Any, channel: Any) -> tuple[list[str], str | None]: + """这个邮件渠道发给谁:(地址, 发不了的原因)。个人渠道取拥有者的账号邮箱,其余解密填的那几个。""" + from app.core.crypto import decrypt + from app.db.models import User + + if getattr(channel, "scope", None) == "user": + user = await session.get(User, channel.owner_id) if channel.owner_id else None + email = (user.email or "").strip() if user is not None else "" + if not email or not address_ok(email): + return [], NO_EMAIL + return [email], None + try: + return parse_recipients(decrypt(channel.url) or ""), None + except ValueError as e: + return [], f"收件地址无法使用:{e}" + + +async def deliver(channel: Any, message: dict[str, Any], msg: Message) -> Outcome: + """按渠道发一封邮件(notify/__init__.send 的邮件分支):配置没启用、收件人取不出来都记成失败、写明原因。""" + from app.core import public_url + from app.db.base import SessionLocal + + async with SessionLocal() as session: + cfg = await load_config(session) + to, problem = await recipients_of(session, channel) + base = await public_url.refresh(session) + if not cfg.enabled: + return Outcome(False, None, 0, NOT_ENABLED) + if problem: + return Outcome(False, None, 0, problem) + return await send(cfg, to, msg, label=f"通知渠道「{channel.name}」", + unsubscribe=f"{base}/settings/notify" if base else None, + retry=bool(message.get("retry", True))) diff --git a/backend/app/notify/service.py b/backend/app/notify/service.py index b2b1f218..cde5b874 100644 --- a/backend/app/notify/service.py +++ b/backend/app/notify/service.py @@ -35,7 +35,7 @@ from typing import Any from sqlalchemy import select from app.db.base import SessionLocal, utcnow -from app.db.models import App, AppVersion, NotifyChannel, NotifyDelivery, Run, Task, TaskAssignment, User +from app.db.models import App, AppVersion, NotifyChannel, NotifyDelivery, Run, Setting, Task, TaskAssignment, User from app.notify.core import Message, Outcome, host_of logger = logging.getLogger(__name__) @@ -74,10 +74,11 @@ EVENTS: dict[str, Event] = { # 定时评测有题从通过变成不通过 / 评测没跑完(01 第 15 项):题集名、通过数、退步题数、链接;不放期望值和答案里的数 "eval.regressed": Event("评测有退步", ()), "eval.failed": Event("评测失败", ()), - # 每天一条待办汇总(04 B3):只推个人渠道;条数、最早的时限、最多 5 条(节点在图上的名字)、去待办箱的链接 - "task.digest": Event("每天的待办汇总", ()), - # 访问密钥到期前 7 天、1 天各一次(04 B3):个人密钥推本人,服务账号的推全局渠道;密钥名、到期日、链接 - "key.expiring": Event("访问密钥快到期", ()), + # 每天一条待办汇总(04 B3,notify_digest):只推个人渠道;条数、最早的时限、最多 5 条(节点在图上的名字)、去待办箱的链接 + "task.digest": Event("每天的待办汇总", ("user",)), + # 访问密钥到期前 7 天、1 天各一次(04 B3,notify_key_expiring):个人密钥推本人的个人渠道,服务账号的推全局渠道; + # 密钥名、到期日、链接 + "key.expiring": Event("访问密钥快到期", ("global", "user")), } EVENT_LABEL = {name: event.label for name, event in EVENTS.items()} @@ -133,14 +134,23 @@ async def personal_url_problem(url: str) -> str | None: return None -def channel_out(row: NotifyChannel) -> dict[str, Any]: - """渠道的接口形状(typesApp.ts 的 NotifyChannelRow):地址只回主机名,密钥只说配没配。""" +def channel_out(row: NotifyChannel, owner_email: str | None = None) -> dict[str, Any]: + """渠道的接口形状(typesApp.ts 的 NotifyChannelRow):地址只回主机名,密钥只说配没配。 + + 邮件渠道(notify/mail.py)没有主机名:mail_to 是发给谁——个人渠道是拥有者的账号邮箱(owner_email,没有邮箱是空的), + 全局、应用的是填的那几个收件地址(搭建者以上才看得到这些渠道,改地址时要整份重填,所以照原样给)。""" from app.core.crypto import decrypt url = decrypt(row.url) or "" - return {"id": row.id, "name": row.name, "scope": row.scope, "owner_id": row.owner_id, "format": row.format, - "url_host": host_of(url) if url else "", "signed": bool(row.secret), "events": list(row.events or []), - "enabled": row.enabled} + out = {"id": row.id, "name": row.name, "scope": row.scope, "owner_id": row.owner_id, "format": row.format, + "url_host": host_of(url) if url and row.format != "email" else "", "signed": bool(row.secret), + "events": list(row.events or []), "enabled": row.enabled} + if row.format == "email": + if row.scope == "user": + out["mail_to"] = [owner_email] if owner_email else [] + else: + out["mail_to"] = [p.strip() for p in url.split(",") if p.strip()] + return out def generic_body(message: dict[str, Any], msg: Message) -> dict[str, Any]: @@ -237,8 +247,61 @@ async def _where(session: Any, run: Run | None) -> str: return f"工作流「{run.workflow_name}」" if run.workflow_name else "" +#: 管理员开了「默认发邮件给待办处理人」(设置 mail.default_for_assignees,04 细案 B2、集成-I5)之后,给哪些人自动建过个人 +#: 邮件渠道:设置表里一行 {用户 id: 建的时间}(通知自己记的账,键的开头同 notify/digest.STATE_PREFIX,设置接口不列)。只在 +#: 第一次派到待办时建一次——本人删掉了就是不要,不再替他建回来 +MAIL_AUTO_KEY = "notify_state:mail_auto" +_mail_auto_lock = asyncio.Lock() + + +async def ensure_assignee_mail(users: list[str]) -> int: + """派到待办的人还没有个人邮件渠道时自动给他建一个(默认订阅 mail.ASSIGNEE_EVENTS),本人之后可以改订阅、可以关。 + + 只在开了登录(个人渠道挂在认证过的账号上)、邮件服务启用、管理员开了这个开关时做;服务账号、停用的人不建。缺省关:刚配好 + SMTP 的部署不该突然往外发邮件(照实说、不意外)。交回这次建了几个。同一时刻只做一份:两条待办同时派给同一个人不建两个。""" + from app.auth import current_mode + from app.core.crypto import encrypt + from app.notify import mail + + if not users or current_mode() == "off": + return 0 + async with _mail_auto_lock, SessionLocal() as session: + cfg = await mail.load_config(session) + if not (cfg.enabled and cfg.default_for_assignees): + return 0 + ids = list((await session.execute(select(User.id).where( + User.username.in_(users), User.kind != "service", User.disabled.is_(False)))).scalars()) + record = await session.get(Setting, MAIL_AUTO_KEY) + done = dict(record.value or {}) if record is not None else {} + fresh = [uid for uid in ids if uid not in done] + if not fresh: + return 0 + have = set((await session.execute(select(NotifyChannel.owner_id).where( + NotifyChannel.scope == "user", NotifyChannel.format == "email", + NotifyChannel.owner_id.in_(fresh)))).scalars()) + made = 0 + for uid in fresh: + if uid not in have: + session.add(NotifyChannel(name=mail.ASSIGNEE_CHANNEL_NAME, scope="user", owner_id=uid, format="email", + url=encrypt(mail.PERSONAL_PLACEHOLDER), events=list(mail.ASSIGNEE_EVENTS))) + made += 1 + done[uid] = utcnow().isoformat() + if record is None: + session.add(Setting(key=MAIL_AUTO_KEY, value=done)) + else: + record.value = done + await session.commit() + return made + + async def notify_task(task_id: str, event: str, *, users: list[str]) -> int: - """待办的通知(task.opened / reassigned / escalated / reminded)。users 是这次要通知到的人(派给的用户名)。返回推了几个渠道。""" + """待办的通知(task.opened / reassigned / escalated / reminded)。users 是这次要通知到的人(派给的用户名)。返回推了几个渠道。 + + 管理员开了「默认发邮件给待办处理人」时,先给还没有个人邮件渠道的处理人建一个(ensure_assignee_mail),这一条就推得到。""" + try: + await ensure_assignee_mail(users) + except Exception: # noqa: BLE001 - 自动建渠道出错不挡这条待办的通知 + logger.exception("给待办 %s 的处理人自动建邮件渠道失败", task_id) async with SessionLocal() as session: task = await session.get(Task, task_id) if task is None: @@ -357,3 +420,109 @@ async def notify_action(action_id: str, event: str) -> int: "subject": {"action_id": action_id, "run_id": rec.run_id, "task_id": task_id}} return await _push(channels, message, subject_kind="action", subject_id=action_id, event=event, run_id=rec.run_id, task_id=task_id) + + +# -------------------------------------------------------------------------- +# 每天的待办汇总、访问密钥快到期(04 细案 B3):什么时候推由 notify/digest.py 在调度循环里定,这里只拼消息、推送 +# -------------------------------------------------------------------------- + +#: 汇总里最多列几条 +DIGEST_ITEMS = 5 + + +def _utc(moment: Any) -> Any: + """库里的时间一律按 UTC 认(待办的时限是不带时区的 UTC),比较前统一成带时区的。""" + from datetime import timezone + + return moment if moment.tzinfo else moment.replace(tzinfo=timezone.utc) + + +def _local(moment: Any) -> str: + return _utc(moment).astimezone().strftime("%Y-%m-%d %H:%M") + + +async def notify_digest(user_id: str) -> int: + """给一个人发今天的待办汇总(task.digest):只推他自己订阅了这件事的个人渠道。没有待办不发(不每天发一条「0 条」)。 + + 内容(P4、X6):条数、最早的时限、最多 DIGEST_ITEMS 条(节点在图上的名字,加所在应用和时限)、去待办箱的链接;不放按运行 + 数据渲染出来的待办标题。「派给我的」和待办箱同一个判断(process/tasks._mine)。返回推了几个渠道。""" + from app.auth import current_mode + from app.auth.sessions import principal_of + from app.process.tasks import _mine + + event = "task.digest" + async with SessionLocal() as session: + user = await session.get(User, user_id) + if user is None or user.disabled or user.kind == "service": + return 0 + channels = [c for c in await _channels(session, event, None, [user.username]) + if c.scope == "user" and c.owner_id == user.id] + if not channels: + return 0 + principal = await principal_of(session, user, current_mode()) + query = select(Task).where(Task.status == "pending") + if (clause := _mine(principal)) is not None: + query = query.where(clause) + tasks = list((await session.execute(query)).scalars()) + if not tasks: + return 0 + # 有时限的在前、时限早的在前;没有时限的按开出的先后 + far = _utc(utcnow().replace(year=9999)) + tasks.sort(key=lambda t: (_utc(t.due_at) if t.due_at else far, _utc(t.created_at) if t.created_at else far)) + runs = {r.id: r for r in (await session.execute(select(Run).where( + Run.id.in_({t.run_id for t in tasks[:DIGEST_ITEMS]})))).scalars()} + names = {a.id: a.name for a in (await session.execute(select(App).where( + App.id.in_({t.app_id for t in tasks[:DIGEST_ITEMS] if t.app_id})))).scalars()} + base = await _base_url(session) + lines = [("状态", "待处理"), ("条数", f"{len(tasks)} 条")] + dues = [t.due_at for t in tasks if t.due_at is not None] + if dues: + lines.append(("最早时限", _local(min(dues, key=_utc)))) + for task in tasks[:DIGEST_ITEMS]: + run = runs.get(task.run_id) + node = _label(run.graph if run else None, task.node_id) if task.node_id else task.title[:80] + where = f"应用「{names[task.app_id]}」" if task.app_id in names else ( + f"工作流「{run.workflow_name}」" if run is not None and run.workflow_name else "") + tail = [where] if where else [] + if task.due_at is not None: + tail.append(f"时限 {_local(task.due_at)}") + lines.append(("待办", f"「{node}」" + (f"({','.join(tail)})" if tail else ""))) + if len(tasks) > DIGEST_ITEMS: + lines.append(("另有", f"{len(tasks) - DIGEST_ITEMS} 条,见待办箱")) + message = {"event": event, "status": "pending", "title": f"你有 {len(tasks)} 条待办", + "lines": lines, "links": [("去待办箱", f"{base}/apps?tab=inbox")] if base else [], + "subject": {"user_id": user_id, "tasks": len(tasks)}} + return await _push(channels, message, subject_kind="digest", subject_id=user_id, event=event, run_id=None, + task_id=None) + + +async def notify_key_expiring(key_id: str, days: int) -> int: + """访问密钥快到期了(key.expiring,到期前 7 天、1 天各一次,由 notify/digest 判断时候到没到、记审计)。 + + 个人访问密钥推给拥有者自己订阅了这件事的个人渠道;服务账号的密钥推给订阅了它的全局渠道(服务账号不能登录,没有个人 + 渠道)。消息只有密钥名、开头一截、到期时间和去轮换的链接,不放密钥本身。返回推了几个渠道。""" + from app.db.models_identity import AccessKey + + event = "key.expiring" + async with SessionLocal() as session: + key = await session.get(AccessKey, key_id) + if key is None: + return 0 + owner = await session.get(User, key.owner_user_id) + if owner is None: + return 0 + service = owner.kind == "service" + found = await _channels(session, event, None, [] if service else [owner.username]) + channels = [c for c in found if (c.scope == "global" if service else c.scope == "user" and c.owner_id == owner.id)] + if not channels: + return 0 + base = await _base_url(session) + left = "1 天内" if days <= 1 else f"{days} 天后" + lines = [("状态", "快到期"), ("密钥", f"「{key.name[:80]}」({key.prefix}…)"), + ("拥有者", f"服务账号 {owner.username}" if service else (owner.display_name or owner.username)), + ("到期", _local(key.expires_at))] + message = {"event": event, "status": "expiring", "title": f"访问密钥「{key.name[:80]}」将在{left}到期", + "lines": lines, "links": [("去轮换", f"{base}/settings/keys")] if base else [], + "subject": {"key_id": key_id, "days": days}} + return await _push(channels, message, subject_kind="access_key", subject_id=key_id, event=event, run_id=None, + task_id=None) diff --git a/backend/app/scheduler/loop.py b/backend/app/scheduler/loop.py index 422bacd3..38baf29e 100644 --- a/backend/app/scheduler/loop.py +++ b/backend/app/scheduler/loop.py @@ -123,14 +123,17 @@ async def tick(now: datetime | None = None) -> None: async def process_due(now: datetime | None = None) -> None: """流程的一拍(app/process):待办的提醒、升级、超时驳回(永不自动批准);结果未知的写入按退避去查; 上传了却一直没提交的文件过了时限清掉(app/files,每小时一次);访问密钥的请求记录批量写库、过了保留期的清掉 - (auth/keys.py,每小时清一次:每个请求同步写一行会和运行抢 SQLite 的写锁,所以攒到这一拍写)。 + (auth/keys.py,每小时清一次:每个请求同步写一行会和运行抢 SQLite 的写锁,所以攒到这一拍写);每天到点发待办汇总、 + 访问密钥到期前 7 天和 1 天各提醒一次(notify/digest.py,04 细案 B3:按日期认领、按审计去重,推送放在后台,不拖这一拍)。 各自出错只记日志:这一拍出错不该让调度循环停下,下一拍照常再查。""" from app.auth import keys from app.files import store as files_store + from app.notify import digest from app.process import actions, tasks for name, step in (("待办的时限处理", tasks.tick), ("写入结果的查询", actions.tick), - ("没有提交的上传文件清理", files_store.cleanup_tick), ("访问密钥的请求记录", keys.tick)): + ("没有提交的上传文件清理", files_store.cleanup_tick), ("访问密钥的请求记录", keys.tick), + ("每天的待办汇总", digest.digest_due), ("访问密钥快到期的提醒", digest.keys_due)): try: done = await step(now) if isinstance(done, list) and done: diff --git a/backend/tests/test_notify_digest.py b/backend/tests/test_notify_digest.py new file mode 100644 index 00000000..b6465971 --- /dev/null +++ b/backend/tests/test_notify_digest.py @@ -0,0 +1,251 @@ +"""每天的待办汇总、访问密钥快到期(notify/digest.py + notify/service,docs/design/next-round/04-对外集成与触达.md B3)。 + +守的是: +- 待办汇总到设置的时间(notify.digest_at,按服务端时区)才发,只发给订阅了 task.digest 的个人渠道;内容是条数、最早时限、 + 最多 5 条节点在图上的名字(不是按运行数据渲染出来的待办标题)、去待办箱的链接,不放数; +- 同一天只发一次,重启(进程里记的清掉)也不重发:靠 settings 表里按日期认领的一行;第二天照常发; +- 没有待办的人不发; +- 访问密钥到期前 7 天、1 天各推一次,不多推;个人密钥推本人的个人渠道,服务账号的推全局渠道;每次推都记审计; +- 轮换下来的旧密钥、撤销了的、建的时候就已经在这一档里的(自己设了短有效期),不推。 + +都用 Webhook 渠道和 httpx.MockTransport 接收;人名、应用名是虚构的。 +""" +from __future__ import annotations + +import json +from datetime import datetime, timedelta, timezone + +import httpx +import pytest +from sqlalchemy import delete, select + +from app.core.crypto import encrypt +from app.db.base import SessionLocal, utcnow +from app.db.models import App, AuditEvent, NotifyChannel, NotifyDelivery, Run, Setting, Task, TaskAssignment, User +from app.notify import core, digest, service +from tests.fakes import auth_env + +URL = "https://hooks.example.com/agentlab/digest-91c2" + + +@pytest.fixture +def received(monkeypatch): + got: list[dict] = [] + + def handler(request: httpx.Request) -> httpx.Response: + got.append(json.loads(request.content)) + return httpx.Response(200, json={"ok": True}) + + monkeypatch.setattr(core, "_transport", httpx.MockTransport(handler)) + monkeypatch.setattr(core, "RETRY_DELAYS", (0, 0, 0)) + + async def public(url: str) -> None: + return None + + monkeypatch.setattr(service, "personal_url_problem", public) + return got + + +@pytest.fixture(autouse=True) +async def login_on(received): + """开着账号密码登录(个人渠道挂在认证过的账号上)。依赖 received:收尾时等推送推完,假的接收端还在。""" + await auth_env.reset() + digest.forget() + await auth_env.turn_on_local() + async with SessionLocal() as session: + session.add(Setting(key="notify", value={"public_base_url": "https://agentlab.example.com", + "digest_at": "09:00"})) + await session.commit() + yield + await service.drain() + async with SessionLocal() as session: + for model in (NotifyDelivery, NotifyChannel, TaskAssignment, Task): + await session.execute(delete(model)) + await session.execute(delete(Run).where(Run.workflow_name == "汇总测试")) + await session.execute(delete(App).where(App.name == "报销审批")) + await session.execute(delete(Setting).where(Setting.key.like(digest.STATE_PREFIX + "%"))) + await session.execute(delete(Setting).where(Setting.key == "notify")) + await session.commit() + digest.forget() + await auth_env.reset() + + +def local(hour: int, minute: int, *, day: int = 16) -> datetime: + """服务端所在时区的某个时刻(汇总按服务端时区算)→ UTC。""" + return datetime(2026, 10, day, hour, minute).astimezone().astimezone(timezone.utc) + + +async def personal(user: User, events: list[str]) -> NotifyChannel: + async with SessionLocal() as session: + row = NotifyChannel(name=f"个人-{user.username}", scope="user", owner_id=user.id, format="generic", + url=encrypt(URL), events=events) + session.add(row) + await session.commit() + return row + + +async def tasks_for(username: str, n: int, *, label: str = "主管审批") -> None: + graph = {"nodes": [{"id": "review", "type": "human", "data": {"label": label}}], "edges": []} + async with SessionLocal() as session: + app = App(name="报销审批", published_version=1) + session.add(app) + run = Run(workflow_name="汇总测试", status="interrupted", graph=graph, input={"amount": 45678}) + session.add(run) + await session.flush() + for i in range(n): + task = Task(run_id=run.id, node_id="review", app_id=app.id, kind="approve", + title=f"审批 45678 元的报销 #{i}", due_at=(utcnow() + timedelta(hours=i + 1)).replace(tzinfo=None)) + session.add(task) + await session.flush() + session.add(TaskAssignment(task_id=task.id, principal_kind="user", principal=username)) + await session.commit() + + +# -------------------------------------------------------------------------- +# 待办汇总 +# -------------------------------------------------------------------------- + + +async def test_digest_is_sent_once_a_day_at_the_set_time(received): + ana = await auth_env.make_user("ana", "user") + bo = await auth_env.make_user("bo", "user") + await personal(ana, ["task.digest"]) + await personal(bo, ["task.opened"]) # 没订阅汇总 + await tasks_for("ana", 7) + await tasks_for("bo", 2) + + assert await digest.digest_due(local(8, 59)) == [], "还没到点" + assert await digest.digest_due(local(9, 0)) == [ana.id] + await service.drain() + [body] = received + assert body["event"] == "task.digest" and body["title"] == "你有 7 条待办" + text = body["text"] + assert "条数:7 条" in text and "最早时限" in text + assert text.count("「主管审批」") == 5, "最多列 5 条,用节点在图上的名字" + assert "另有:2 条" in text and "报销审批" in text + assert "45678" not in json.dumps(body, ensure_ascii=False), "不放按运行数据渲染出来的标题、不放数" + assert body["links"] == [{"label": "去待办箱", "url": "https://agentlab.example.com/apps?tab=inbox"}] + + assert await digest.digest_due(local(9, 15)) == [], "同一天只发一次" + digest.forget() # 重启:进程里记的没了 + assert await digest.digest_due(local(10, 0)) == [], "重启了也不重发:认领在 settings 表里" + await service.drain() + assert len(received) == 1 + async with SessionLocal() as session: + rows = (await session.execute(select(NotifyDelivery).where(NotifyDelivery.event == "task.digest"))).scalars() + assert [(r.subject_kind, r.subject_id, r.status) for r in rows] == [("digest", ana.id, "ok")] + + assert await digest.digest_due(local(9, 1, day=17)) == [ana.id], "第二天照常" + + +async def test_digest_follows_the_configured_time_and_skips_people_with_nothing_pending(received): + cy = await auth_env.make_user("cy", "user") + await personal(cy, ["task.digest"]) + async with SessionLocal() as session: + row = await session.get(Setting, "notify") + row.value = {**row.value, "digest_at": "17:30"} + await session.commit() + assert await digest.digest_due(local(9, 0)) == [] + assert await digest.digest_due(local(17, 30)) == [cy.id] + await service.drain() + assert received == [], "没有待办不发「0 条」" + + +async def test_claim_rows_are_not_listed_as_settings(received): + await digest.digest_due(local(9, 0)) + async with auth_env.client() as c: + root = await auth_env.login("root") + body = (await root.get("/api/settings")).json() + assert not [k for k in body if k.startswith(digest.STATE_PREFIX)] + + +# -------------------------------------------------------------------------- +# 访问密钥快到期 +# -------------------------------------------------------------------------- + + +async def _expiring_audits(key_id: str) -> list[int]: + async with SessionLocal() as session: + rows = (await session.execute(select(AuditEvent).where(AuditEvent.action == "access_key.expiring", + AuditEvent.subject_id == key_id))).scalars() + return sorted(r.data["days"] for r in rows) + + +async def _age(key, days: float) -> None: + from app.db.models_identity import AccessKey + + async with SessionLocal() as session: + row = await session.get(AccessKey, key.id) + row.created_at = utcnow() - timedelta(days=days) + await session.commit() + + +async def test_personal_key_reminds_its_owner_at_7_and_1_days(received): + await auth_env.personal_keys(True) + dee = await auth_env.make_user("dee", "user") + mine = await personal(dee, ["key.expiring"]) + async with SessionLocal() as session: + session.add(NotifyChannel(name="全局", scope="global", format="generic", url=encrypt(URL), + events=["key.expiring"])) + await session.commit() + key, secret = await auth_env.make_key(dee, days=30, name="周报脚本") + await _age(key, 60) + now = utcnow() + assert await digest.keys_due(now) == [], "离到期还有 30 天" + assert await digest.keys_due(now + timedelta(days=23, hours=1)) == [key.id] + await service.drain() + [body] = received + assert body["event"] == "key.expiring" and "周报脚本" in body["title"] and "7 天后" in body["title"] + assert secret not in json.dumps(body) and key.prefix in body["text"] + assert body["links"] == [{"label": "去轮换", "url": "https://agentlab.example.com/settings/keys"}] + async with SessionLocal() as session: + to = (await session.execute(select(NotifyDelivery.channel_id))).scalars().all() + assert to == [mine.id], "个人密钥只推本人,不推全局渠道" + assert await digest.keys_due(now + timedelta(days=24)) == [], "这一档推过了" + digest.forget() + assert await digest.keys_due(now + timedelta(days=25)) == [], "重启后按审计认得出推过了" + assert await digest.keys_due(now + timedelta(days=29, hours=1)) == [key.id], "到期前 1 天再推一次" + assert await digest.keys_due(now + timedelta(days=29, hours=12)) == [] + assert await _expiring_audits(key.id) == [1, 7] + await service.drain() + assert len(received) == 2 and "1 天内" in received[1]["title"] + + +async def test_service_account_keys_remind_global_channels(received): + svc = await auth_env.make_service("svc-portal") + async with SessionLocal() as session: + glob = NotifyChannel(name="运维群", scope="global", format="generic", url=encrypt(URL), events=["key.expiring"]) + session.add(glob) + await session.commit() + key, _ = await auth_env.make_key(svc, days=5, name="门户拉数") + await _age(key, 30) + assert await digest.keys_due(utcnow()) == [key.id] + await service.drain() + [body] = received + assert "服务账号 svc-portal" in body["text"] + async with SessionLocal() as session: + assert (await session.execute(select(NotifyDelivery.channel_id))).scalars().all() == [glob.id] + + +async def test_keys_that_should_not_remind(received): + from app.db.models_identity import AccessKey + + svc = await auth_env.make_service("svc-bi") + async with SessionLocal() as session: + session.add(NotifyChannel(name="运维群", scope="global", format="generic", url=encrypt(URL), + events=["key.expiring"])) + await session.commit() + short, _ = await auth_env.make_key(svc, days=3, name="临时") # 建的时候就只有 3 天:不推 7 天那一档 + old, _ = await auth_env.make_key(svc, days=0.5, name="轮换下来的") + await _age(old, 90) + new, _ = await auth_env.make_key(svc, days=90, name="轮换上去的") + revoked, _ = await auth_env.make_key(svc, days=2, name="撤销了的") + await _age(revoked, 30) + async with SessionLocal() as session: + (await session.get(AccessKey, new.id)).rotated_from = old.id + (await session.get(AccessKey, revoked.id)).revoked_at = utcnow() + await session.commit() + assert await digest.keys_due(utcnow()) == [] + assert await digest.keys_due(utcnow() + timedelta(days=2, hours=1)) == [short.id], "1 天那一档照推" + await service.drain() + assert len(received) == 1 diff --git a/backend/tests/test_notify_events.py b/backend/tests/test_notify_events.py index 211d4dc1..98d166f7 100644 --- a/backend/tests/test_notify_events.py +++ b/backend/tests/test_notify_events.py @@ -30,8 +30,11 @@ from app.notify import service TERMS_TS = Path(__file__).resolve().parents[2] / "frontend" / "src" / "lib" / "terms.ts" URL = "https://hooks.example.com/agentlab/notify-events-5d1c" -#: 本轮登记的六个(总方案 X6):都还没有推送 +#: 本轮登记的六个(总方案 X6) THIS_ROUND = ("source.changed", "ledger.recall", "eval.regressed", "eval.failed", "task.digest", "key.expiring") +#: 其中已经实现了推送、打开了订阅的(推给哪几条路):每天的待办汇总只推个人渠道;访问密钥快到期,个人密钥推本人、服务账号的 +#: 推全局渠道(第 3 波 W3-d,notify/digest.py) +PUSHED_THIS_ROUND = {"task.digest": {"user"}, "key.expiring": {"global", "user"}} @pytest.fixture @@ -54,7 +57,10 @@ def test_this_rounds_events_are_registered_once_and_not_pushed_yet(): for name in THIS_ROUND: assert name in service.EVENTS, f"{name} 没有登记" assert service.EVENTS[name].label, name - assert service.EVENTS[name].scopes == (), f"{name} 还没有推送:不该有人订阅得到" + if name in PUSHED_THIS_ROUND: + assert set(service.EVENTS[name].scopes) == PUSHED_THIS_ROUND[name], name + else: + assert service.EVENTS[name].scopes == (), f"{name} 还没有推送:不该有人订阅得到" assert len({e.label for e in service.EVENTS.values()}) == len(service.EVENTS), "两个事件叫成了同一句" assert service.EVENT_LABEL == {k: v.label for k, v in service.EVENTS.items()} @@ -66,6 +72,7 @@ def test_events_that_are_pushed_today_keep_their_audience(): "task.opened": every, "run.finished": every, "run.failed": every, "action.unknown": every, # 发给提交人自己(和订阅了它的全局渠道),不归哪个应用 "review.done": {"global", "user"}, + **PUSHED_THIS_ROUND, } for event in service.EVENTS.values(): assert set(event.scopes) <= every diff --git a/backend/tests/test_notify_mail.py b/backend/tests/test_notify_mail.py new file mode 100644 index 00000000..d2146d6a --- /dev/null +++ b/backend/tests/test_notify_mail.py @@ -0,0 +1,421 @@ +"""邮件:通知渠道的第五种格式(notify/mail.py,docs/design/next-round/04-对外集成与触达.md B2)。 + +全程用假的 SMTP 工厂(mail._smtp_factory),不连任何邮件服务器。守的是: +- 个人邮件渠道只发到拥有者在名录里的账号邮箱;账号没有邮箱时记一条失败的投递、写明原因;个人渠道不收地址; +- 全局、应用的邮件渠道填固定的收件地址(最多 20 个,格式不对的拒收);邮件服务没启用时不收新的邮件渠道; +- 4xx(临时错误)和连不上按 1/2/4 秒重试,5xx 不重试;报错里绝不出现口令; +- 邮件里只有标题、状态、链接,纯文本 + 转义过的 HTML,带 List-Unsubscribe;投递记录成功写「已交给邮件服务器」(不说已送达); +- 设置的 mail 一组:口令加密存、读的时候只说配没配;启用时要配全;发件人名称不许换行;只有管理员能改; +- 发测试邮件只发到管理员自己的账号邮箱:关登录、账号没有邮箱时 422 说清怎么办; +- 管理员开了「默认发邮件给待办处理人」:第一次派到待办的人自动有一个个人邮件渠道(默认订阅三项),本人删了不再建回来; + 开关缺省关时不建。 + +人名、地址、主机都是虚构的。 +""" +from __future__ import annotations + +import json +import smtplib +from types import SimpleNamespace + +import pytest +from httpx import ASGITransport, AsyncClient +from sqlalchemy import delete, select + +from app.core.crypto import encrypt +from app.db.base import SessionLocal +from app.db.models import NotifyChannel, NotifyDelivery, Setting, User +from app.notify import mail, service +from app.notify.core import Message + +PASSWORD = "Sm7p-Pa55word-Zq" + + +class FakeSMTP: + """假的 SMTP 连接:记下登录、发出的信;box.failures 里排着的异常按顺序在 send_message 上抛。""" + + def __init__(self, box: SimpleNamespace) -> None: + self.box = box + + def starttls(self, context=None) -> None: + self.box.tls += 1 + + def login(self, username: str, password: str) -> None: + self.box.logins.append((username, password)) + if self.box.auth_error: + # 有的服务器会把收到的内容回显在错误里:报错里也不能出现口令 + raise smtplib.SMTPAuthenticationError(535, f"5.7.8 bad credentials {password}".encode()) + + def send_message(self, em, from_addr=None, to_addrs=None): + if self.box.failures: + raise self.box.failures.pop(0) + self.box.sent.append(SimpleNamespace(from_addr=from_addr, to=list(to_addrs or []), em=em)) + return {} + + def quit(self) -> None: + self.box.quits += 1 + + def close(self) -> None: + pass + + +@pytest.fixture +def smtp(monkeypatch): + box = SimpleNamespace(sent=[], logins=[], failures=[], connects=[], refuse=0, tls=0, quits=0, auth_error=False) + + def factory(host, port, security, timeout): + box.connects.append((host, port, security, timeout)) + if box.refuse: + box.refuse -= 1 + raise ConnectionRefusedError("refused") + return FakeSMTP(box) + + monkeypatch.setattr(mail, "_smtp_factory", factory) + monkeypatch.setattr(mail, "RETRY_DELAYS", (0, 0, 0)) + return box + + +@pytest.fixture(autouse=True) +async def clean(): + yield + await service.drain() + async with SessionLocal() as session: + await session.execute(delete(NotifyDelivery)) + await session.execute(delete(NotifyChannel)) + await session.execute(delete(Setting).where(Setting.key.in_([mail.GROUP, "notify", service.MAIL_AUTO_KEY]))) + await session.execute(delete(User).where(User.username.like("mail-%"))) + await session.commit() + + +async def configure(**over) -> None: + value = mail.stored_value({"enabled": True, "host": "smtp.example.com", "port": 587, "security": "starttls", + "username": "agentlab", "password": PASSWORD, "from_addr": "agentlab@example.com", + "from_name": "AgentLab", **over}) + async with SessionLocal() as session: + row = await session.get(Setting, mail.GROUP) + if row is None: + session.add(Setting(key=mail.GROUP, value=value)) + else: + row.value = value + notify = await session.get(Setting, "notify") + if notify is None: + session.add(Setting(key="notify", value={"public_base_url": "https://agentlab.example.com"})) + await session.commit() + + +async def person(name: str, email: str | None) -> User: + async with SessionLocal() as session: + user = User(username=f"mail-{name}", display_name=name, role="user", email=email) + session.add(user) + await session.commit() + await session.refresh(user) + return user + + +async def channel(scope: str, owner_id: str | None = None, to: str = mail.PERSONAL_PLACEHOLDER, + events: list[str] | None = None) -> NotifyChannel: + async with SessionLocal() as session: + row = NotifyChannel(name=f"邮件-{scope}", scope=scope, owner_id=owner_id, format="email", url=encrypt(to), + events=events or ["task.opened"]) + session.add(row) + await session.commit() + await session.refresh(row) + return row + + +MESSAGE = {"event": "task.opened", "status": "pending", "title": "新的待办:审批 付款", + "lines": [("状态", "待处理"), ("所在", "应用「报销 & 付款」")], + "links": [("去处理", "https://agentlab.example.com/apps/inbox/t1")]} + + +async def _deliveries() -> list[NotifyDelivery]: + async with SessionLocal() as session: + return list((await session.execute(select(NotifyDelivery))).scalars()) + + +# -------------------------------------------------------------------------- +# 发到谁 +# -------------------------------------------------------------------------- + + +async def test_personal_mail_goes_to_the_account_email_only(smtp): + await configure() + ana = await person("ana", "ana@example.com") + row = await channel("user", ana.id) + sent = await service._push([row], MESSAGE, subject_kind="task", subject_id="t1", event="task.opened", + run_id=None, task_id="t1") + assert sent == 1 + [mail_out] = smtp.sent + assert mail_out.to == ["ana@example.com"] and mail_out.from_addr == "agentlab@example.com" + assert smtp.logins == [("agentlab", PASSWORD)] and smtp.tls == 1 + em = mail_out.em + assert em["Subject"] == "【AgentLab】新的待办:审批 付款" + assert em["List-Unsubscribe"] == "