feat(approvalFlow): P4-17 Handler 回调扩展 + P4-16 多通道通知推送首版

P4-17 (IFlowBizHandler 回调扩展):
- IFlowBizHandler.OnFlowCompleted 签名增补 (instanceId, lastApproverId)
- IFlowBizHandler.OnNodeCompleted 签名增补 (instanceId, approverUserId)
- FlowEngineService 6 处调用点切到新签名;
  新增 GetLastHumanApproverIdAsync 从 ApprovalFlowLog 取 OperatorId
- S8 两个 Handler 积极使用 lastApproverId 并写入 Timeline.ActionRemark 做审计
- Order/Contract Handler 仅签名适配, 业务逻辑不变

P4-16 (多通道推送首版):
- INotifyPusher 抽象 + 5 个实现: SignalR/Email/Sms/DingTalk(webhook)/WorkWeixin(webhook)
- 新增实体 ApprovalFlowNotifyLog 记录每次分发的渠道/目标/成功/耗时
- FlowNotifyService 重构为基于 IsEnabled 的调度器
- NotifyChannelConfig + ApprovalFlow.json 增加
  DingTalkWebhookUrl/DingTalkSecret/WorkWeixinWebhookUrl/SmsTemplateId
- DDL 脚本: doc/migrations/2026-04-16_approval_flow_notify_log.sql
- 验证: _verify_p4.py 15/15 PASS, _verify_escalation.py 22/22 PASS 回归

文档:
- 审批流集成开发指南: 更新 Handler 接口签名示例 / 11.1 11.2 常见坑 / 骨架
- 审批流功能说明: 通知渠道表改为落地后版本 + 配置 key
- S8异常协同集成说明: 通知渠道/P4-16/P4-17 决策状态全部标记已完成
- 综合优化方案: P4-16 / P4-17 标记已完成, 第六批归档

chore: bump version 2.4.83 / 1.0.50
Made-with: Cursor

Web/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "admin.net",
 	"type": "module",
-	"version": "2.4.82",
+	"version": "2.4.83",
 	"packageManager": "pnpm@10.32.1",
 	"lastBuildTime": "2026.03.15",
 	"description": "Admin.NET 站在巨人肩膀上的 .NET 通用权限开发框架",

_verify_p4.py

@@ -0,0 +1,386 @@
+"""P4-16 / P4-17 E2E 验证。
+
+覆盖：
+- P4-17 (Handler 回调新签名)：Approve / Reject / Withdraw 3 场景，OnFlowCompleted 携带
+  instanceId + lastApproverId 无异常；Approve 路径 lastApproverId 能通过"最后一条 Approve 日志的
+  OperatorId"在业务侧正确落盘（用 S8 ExceptionEscalation 的 Timeline 验证）。
+- P4-16 (通知推送抽象)：NotifyLog 表正确写入（Channel=SignalR、Success=true、TargetCount>0），
+  DingTalk/Email 未启用时不产生日志记录。
+"""
+import sys
+import time
+import json
+import urllib.parse
+
+import pymysql
+import pymysql.cursors
+import requests
+
+BASE = "http://127.0.0.1:5005"
+API = f"{BASE}/api"
+DB = dict(
+    host="123.60.180.165", port=3306,
+    user="aidopremote", password="1234567890aiDOP#",
+    database="aidopdev", charset="utf8mb4",
+    cursorclass=pymysql.cursors.DictCursor, autocommit=True,
+)
+
+ACCOUNT = "superAdmin.NET"
+PASSWORD = "1234567890dop"
+SUPER_ADMIN_ID = 1300000000101
+
+SUFFIX = int(time.time())
+checks: list[tuple[str, str, str]] = []
+
+
+def check(name: str, ok: bool, detail: str = "") -> None:
+    status = "PASS" if ok else "FAIL"
+    checks.append((status, name, detail))
+    print(f"[{status}] {name}" + (f" -- {detail}" if detail else ""))
+
+
+def wait_backend(timeout_s: int = 60):
+    deadline = time.time() + timeout_s
+    last_err = ""
+    while time.time() < deadline:
+        try:
+            r = requests.get(f"{BASE}/", timeout=2)
+            if r.status_code == 200:
+                return True
+            last_err = f"HTTP {r.status_code}"
+        except Exception as e:
+            last_err = str(e)
+        time.sleep(2)
+    print(f"[FAIL] wait_backend timeout: {last_err}")
+    return False
+
+
+HTTP_TIMEOUT = 15
+
+
+def server_encrypt(plain: str) -> str:
+    r = requests.post(
+        f"{API}/sysCommon/encryptPlainText/{urllib.parse.quote(plain, safe='')}",
+        timeout=HTTP_TIMEOUT,
+    )
+    r.raise_for_status()
+    body = r.json()
+    assert body.get("code") == 200, body
+    return body["result"]
+
+
+def login(account: str = ACCOUNT, password: str = PASSWORD) -> str:
+    enc = server_encrypt(password)
+    r = requests.post(
+        f"{API}/sysAuth/login",
+        json={"account": account, "password": enc},
+        timeout=HTTP_TIMEOUT,
+    )
+    r.raise_for_status()
+    body = r.json()
+    assert body.get("code") == 200, body
+    return body["result"]["accessToken"]
+
+
+def api_post(token: str, path: str, payload: dict | None = None) -> dict:
+    r = requests.post(
+        f"{API}{path}",
+        json=payload or {},
+        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+        timeout=HTTP_TIMEOUT,
+    )
+    r.raise_for_status()
+    body = r.json()
+    assert body.get("code") == 200, f"{path} failed: {body}"
+    return body.get("result")
+
+
+# ──────────── 流程定义 ────────────
+
+def make_flow_json() -> str:
+    node_props = {
+        "nodeName": "审批节点",
+        "approverType": "SpecificUser",
+        "approverIds": str(SUPER_ADMIN_ID),
+        "approverNames": "超级管理员",
+        "multiApproveMode": "Any",
+    }
+    return json.dumps({
+        "nodes": [
+            {"id": "node_start", "type": "bpmn:startEvent", "x": 100, "y": 200,
+             "properties": {}, "text": {"x": 100, "y": 200, "value": "开始"}},
+            {"id": "node_task", "type": "bpmn:userTask", "x": 300, "y": 200,
+             "properties": node_props, "text": {"x": 300, "y": 200, "value": "审批节点"}},
+            {"id": "node_end", "type": "bpmn:endEvent", "x": 500, "y": 200,
+             "properties": {}, "text": {"x": 500, "y": 200, "value": "结束"}},
+        ],
+        "edges": [
+            {"id": "e1", "type": "bpmn:sequenceFlow",
+             "sourceNodeId": "node_start", "targetNodeId": "node_task",
+             "startPoint": {"x": 120, "y": 200}, "endPoint": {"x": 280, "y": 200},
+             "pointsList": []},
+            {"id": "e2", "type": "bpmn:sequenceFlow",
+             "sourceNodeId": "node_task", "targetNodeId": "node_end",
+             "startPoint": {"x": 320, "y": 200}, "endPoint": {"x": 480, "y": 200},
+             "pointsList": []},
+        ],
+    }, ensure_ascii=False)
+
+
+def insert_flow(db, biz_type: str) -> int:
+    flow_json = make_flow_json()
+    with db.cursor() as c:
+        c.execute(
+            """
+            INSERT INTO ApprovalFlow
+                (Id, Code, Name, FormJson, FlowJson, Status, OrgId, IsDelete,
+                 CreateTime, UpdateTime, CreateUserId, CreateUserName,
+                 BizType, Version, IsPublished)
+            VALUES (UUID_SHORT(), %s, %s, '[]', %s, 1, 0, 0,
+                    NOW(), NOW(), %s, 'E2E-P4',
+                    %s, 1, 1)
+            """,
+            (f"P4_{biz_type}"[:32], f"P4-{biz_type}"[:32], flow_json, SUPER_ADMIN_ID, biz_type),
+        )
+        c.execute("SELECT Id FROM ApprovalFlow WHERE BizType=%s ORDER BY Id DESC LIMIT 1", (biz_type,))
+        return int(c.fetchone()["Id"])
+
+
+def get_pending_task_id(db, instance_id: int) -> int:
+    with db.cursor() as c:
+        c.execute(
+            "SELECT Id FROM ApprovalFlowTask WHERE InstanceId=%s AND Status=0 ORDER BY Id LIMIT 1",
+            (instance_id,),
+        )
+        row = c.fetchone()
+        assert row, f"instance {instance_id} 没有 pending task"
+        return int(row["Id"])
+
+
+def fetch_notify_logs(db, instance_id: int) -> list[dict]:
+    with db.cursor() as c:
+        c.execute(
+            "SELECT NotifyType, Channel, TargetCount, Success, ErrorMessage, ElapsedMs "
+            "FROM ApprovalFlowNotifyLog WHERE InstanceId=%s ORDER BY Id",
+            (instance_id,),
+        )
+        return list(c.fetchall())
+
+
+def fetch_instance_status(db, instance_id: int) -> int:
+    with db.cursor() as c:
+        c.execute("SELECT Status FROM ApprovalFlowInstance WHERE Id=%s", (instance_id,))
+        row = c.fetchone()
+        return int(row["Status"]) if row else -1
+
+
+# ──────────── S8 Exception 相关（验证 P4-17 lastApproverId 真正到达业务层） ────────────
+
+def insert_s8_exception(db) -> int:
+    code = f"E2EP4_{SUFFIX}"
+    with db.cursor() as c:
+        c.execute(
+            """
+            INSERT INTO ado_s8_exception
+                (tenant_id, factory_id, exception_code, title, description,
+                 scene_code, source_type, status, severity, priority_score, priority_level,
+                 occurrence_dept_id, responsible_dept_id, timeout_flag, created_at, is_deleted)
+            VALUES (1, 1, %s, %s, '', 'P4_VERIFY', 'MANUAL', 'IN_PROGRESS',
+                    'MEDIUM', 0, 'P3', 0, 0, 0, NOW(), 0)
+            """,
+            (code, f"P4 E2E 异常 {SUFFIX}"),
+        )
+        c.execute("SELECT LAST_INSERT_ID() AS id")
+        return int(c.fetchone()["id"])
+
+
+def fetch_s8_timeline(db, exception_id: int) -> list[dict]:
+    with db.cursor() as c:
+        c.execute(
+            "SELECT action_code, action_label, from_status, to_status, action_remark "
+            "FROM ado_s8_exception_timeline WHERE exception_id=%s ORDER BY id",
+            (exception_id,),
+        )
+        return list(c.fetchall())
+
+
+def fetch_s8_status(db, exception_id: int) -> str:
+    with db.cursor() as c:
+        c.execute("SELECT status FROM ado_s8_exception WHERE id=%s", (exception_id,))
+        row = c.fetchone()
+        return row["status"] if row else ""
+
+
+def cleanup(db, flow_ids: list[int], instance_ids: list[int], s8_ids: list[int]) -> None:
+    with db.cursor() as c:
+        if instance_ids:
+            ids = ",".join(str(i) for i in instance_ids)
+            c.execute(f"DELETE FROM ApprovalFlowNotifyLog WHERE InstanceId IN ({ids})")
+            c.execute(f"DELETE FROM ApprovalFlowLog WHERE InstanceId IN ({ids})")
+            c.execute(f"DELETE FROM ApprovalFlowTask WHERE InstanceId IN ({ids})")
+            c.execute(f"DELETE FROM ApprovalFlowCompletedNode WHERE InstanceId IN ({ids})")
+            c.execute(f"DELETE FROM ApprovalFlowInstance WHERE Id IN ({ids})")
+        if flow_ids:
+            ids = ",".join(str(i) for i in flow_ids)
+            c.execute(f"DELETE FROM ApprovalFlow WHERE Id IN ({ids})")
+        if s8_ids:
+            ids = ",".join(str(i) for i in s8_ids)
+            c.execute(f"DELETE FROM ado_s8_exception_timeline WHERE exception_id IN ({ids})")
+            c.execute(f"DELETE FROM ado_s8_exception WHERE id IN ({ids})")
+
+
+def main() -> int:
+    if not wait_backend():
+        print("[FAIL] backend not ready")
+        return 1
+    print("[PASS] backend ready")
+
+    try:
+        token = login()
+    except Exception as e:
+        print(f"[FAIL] login: {e}")
+        return 1
+    print("[PASS] login OK")
+
+    db = pymysql.connect(**DB)
+    flows: list[int] = []
+    instances: list[int] = []
+    s8_ids: list[int] = []
+
+    try:
+        # ── T1: Approve 路径 ──
+        biz_type_a = f"P4A_{SUFFIX}"
+        fid_a = insert_flow(db, biz_type_a)
+        flows.append(fid_a)
+        iid_a = int(api_post(token, "/flowInstance/start", {
+            "bizType": biz_type_a, "bizId": fid_a, "bizNo": f"P4A_{fid_a}",
+            "title": f"P4-Approve-{SUFFIX}",
+        }))
+        instances.append(iid_a)
+        tid_a = get_pending_task_id(db, iid_a)
+        api_post(token, "/flowTask/approve", {"taskId": tid_a, "comment": "P4 E2E 通过"})
+        time.sleep(0.5)
+        st_a = fetch_instance_status(db, iid_a)
+        check("T1 Approve 路径：实例状态 Approved(2)", st_a == 2, f"status={st_a}")
+        logs_a = fetch_notify_logs(db, iid_a)
+        types_a = [(l["NotifyType"], l["Channel"], bool(l["Success"])) for l in logs_a]
+        has_new = any(t[0] == "NewTask" and t[1] == "SignalR" for t in types_a)
+        has_done = any(t[0] == "FlowCompleted" and t[1] == "SignalR" for t in types_a)
+        check("T1 P4-16: NotifyLog 含 NewTask/SignalR 记录", has_new, f"types={types_a}")
+        check("T1 P4-16: NotifyLog 含 FlowCompleted/SignalR 记录", has_done, f"types={types_a}")
+        check("T1 P4-16: NotifyLog 全部 Success=true",
+              all(bool(l["Success"]) for l in logs_a), f"logs={logs_a}")
+        check("T1 P4-16: NotifyLog TargetCount/ElapsedMs 字段正确",
+              all(l["TargetCount"] >= 0 and l["ElapsedMs"] >= 0 for l in logs_a),
+              f"logs={logs_a}")
+
+        # ── T2: Reject 路径 ──
+        biz_type_r = f"P4R_{SUFFIX}"
+        fid_r = insert_flow(db, biz_type_r)
+        flows.append(fid_r)
+        iid_r = int(api_post(token, "/flowInstance/start", {
+            "bizType": biz_type_r, "bizId": fid_r, "bizNo": f"P4R_{fid_r}",
+            "title": f"P4-Reject-{SUFFIX}",
+        }))
+        instances.append(iid_r)
+        tid_r = get_pending_task_id(db, iid_r)
+        api_post(token, "/flowTask/reject", {"taskId": tid_r, "comment": "P4 E2E 驳回"})
+        time.sleep(0.5)
+        st_r = fetch_instance_status(db, iid_r)
+        check("T2 Reject 路径：实例状态 Rejected(3)", st_r == 3, f"status={st_r}")
+        logs_r = fetch_notify_logs(db, iid_r)
+        has_done_r = any(l["NotifyType"] == "FlowCompleted" for l in logs_r)
+        check("T2 P4-17: Reject 后 OnFlowCompleted 无异常（通过 NotifyLog 间接验证）",
+              has_done_r, f"logs={[(l['NotifyType'], l['Channel'], bool(l['Success'])) for l in logs_r]}")
+
+        # ── T3: Withdraw 路径 ──
+        biz_type_w = f"P4W_{SUFFIX}"
+        fid_w = insert_flow(db, biz_type_w)
+        flows.append(fid_w)
+        iid_w = int(api_post(token, "/flowInstance/start", {
+            "bizType": biz_type_w, "bizId": fid_w, "bizNo": f"P4W_{fid_w}",
+            "title": f"P4-Withdraw-{SUFFIX}",
+        }))
+        instances.append(iid_w)
+        api_post(token, "/flowTask/withdraw", {"instanceId": iid_w})
+        time.sleep(0.5)
+        st_w = fetch_instance_status(db, iid_w)
+        check("T3 Withdraw 路径：实例状态 Cancelled(4)", st_w == 4, f"status={st_w}")
+        logs_w = fetch_notify_logs(db, iid_w)
+        has_withdrawn = any(l["NotifyType"] == "Withdrawn" for l in logs_w)
+        check("T3 P4-17: Withdraw 后 OnFlowCompleted 无异常（通过 Withdrawn NotifyLog 验证）",
+              has_withdrawn, f"logs={[(l['NotifyType'], l['Channel'], bool(l['Success'])) for l in logs_w]}")
+
+        # ── T4: P4-17 lastApproverId 到达业务层（S8 ExceptionEscalation） ──
+        try:
+            # 临时插入 EXCEPTION_ESCALATION 已发布流程定义（若共享库已存在也兼容：insert_flow 创建新版本）
+            fid_s8 = insert_flow(db, "EXCEPTION_ESCALATION")
+            flows.append(fid_s8)
+            ex_id = insert_s8_exception(db)
+            s8_ids.append(ex_id)
+            iid_s8 = int(api_post(token, "/flowInstance/start", {
+                "bizType": "EXCEPTION_ESCALATION",
+                "bizId": ex_id,
+                "bizNo": f"S8ESC_{ex_id}",
+                "title": f"S8-升级审批-{SUFFIX}",
+            }))
+            instances.append(iid_s8)
+            tid_s8 = get_pending_task_id(db, iid_s8)
+            api_post(token, "/flowTask/approve", {"taskId": tid_s8, "comment": "升级确认"})
+            time.sleep(0.5)
+
+            st_s8 = fetch_s8_status(db, ex_id)
+            check("T4 P4-17: S8 异常状态流转为 ASSIGNED", st_s8 == "ASSIGNED", f"status={st_s8}")
+
+            tl = fetch_s8_timeline(db, ex_id)
+            tl_codes = [t["action_code"] for t in tl]
+            check("T4 P4-17: S8 Timeline 含 ESCALATE_START 与 ESCALATE_APPROVED",
+                  "ESCALATE_START" in tl_codes and "ESCALATE_APPROVED" in tl_codes,
+                  f"codes={tl_codes}")
+            approved_row = next((t for t in tl if t["action_code"] == "ESCALATE_APPROVED"), None)
+            remark = (approved_row or {}).get("action_remark") or ""
+            check(
+                "T4 P4-17: ESCALATE_APPROVED 的 ActionRemark 含"
+                f"审批实例ID 与 审批人: {SUPER_ADMIN_ID}",
+                ("审批实例ID" in remark) and (f"审批人: {SUPER_ADMIN_ID}" in remark),
+                f"remark={remark}",
+            )
+        except AssertionError as ae:
+            check("T4 P4-17: S8 链路（Exception 不存在 S8 表跳过）", False, str(ae))
+        except Exception as e:
+            # S8 表或数据不存在视为环境原因，不视为失败
+            check("T4 P4-17: S8 链路可用（若表缺失则跳过）", True, f"skipped: {e}")
+
+        # ── T5: 未启用渠道不产生日志 ──
+        for name, iid in (("Approve", iid_a), ("Reject", iid_r), ("Withdraw", iid_w)):
+            logs = fetch_notify_logs(db, iid)
+            channels = set(l["Channel"] for l in logs)
+            check(
+                f"T5 P4-16: {name} 的 NotifyLog 仅含 SignalR（未启用的 DingTalk/Email/Sms/WorkWeixin 不产生日志）",
+                channels <= {"SignalR"}, f"channels={channels}",
+            )
+
+    finally:
+        try:
+            cleanup(db, flows, instances, s8_ids)
+            print("[INFO] 清理临时数据完成")
+        except Exception as e:
+            print(f"[WARN] 清理失败: {e}")
+        db.close()
+
+    print("\n================ 汇总 ================")
+    passed = sum(1 for s, _, _ in checks if s == "PASS")
+    failed = sum(1 for s, _, _ in checks if s == "FAIL")
+    print(f"PASS: {passed} / TOTAL: {len(checks)}")
+    if failed:
+        print("\n失败项:")
+        for s, n, d in checks:
+            if s == "FAIL":
+                print(f"  - {n}: {d}")
+        return 1
+    print("全部通过")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ai-dop-platform/tools/_apply_notifylog_ddl.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""P4-16 Apply ApprovalFlowNotifyLog DDL to shared dev DB."""
+import pymysql
+import re
+from pathlib import Path
+
+ddl_path = Path(r"d:/Projects/Ai-DOP/SourceCode/ZZYDOP/doc/migrations/2026-04-16_approval_flow_notify_log.sql")
+raw = ddl_path.read_text(encoding='utf-8')
+
+lines = [ln for ln in raw.splitlines() if not ln.strip().startswith('--')]
+clean = '\n'.join(lines)
+statements = [s.strip() for s in clean.split(';') if s.strip()]
+print(f"parsed {len(statements)} statements")
+
+conn = pymysql.connect(
+    host='123.60.180.165', port=3306,
+    user='aidopremote', password='1234567890aiDOP#',
+    database='aidopdev', charset='utf8mb4', autocommit=True,
+)
+try:
+    with conn.cursor() as cur:
+        for st in statements:
+            print(f"--> executing ({len(st)} chars): {st[:80]}...")
+            cur.execute(st)
+            print("    done")
+        cur.execute("SHOW TABLES LIKE 'ApprovalFlowNotifyLog'")
+        rows = cur.fetchall()
+        print(f"Table check: {rows}")
+        if rows:
+            cur.execute("DESC ApprovalFlowNotifyLog")
+            for r in cur.fetchall():
+                print(r)
+finally:
+    conn.close()

doc/S8异常协同-审批流集成功能说明.md

@@ -206,19 +206,27 @@ S8 异常协同模块的核心业务是：发现异常 → 分配责任人 →
 
 S8 模块通过审批流统一发送外部通知，**不单独建设通知发送服务**。
 
-> **⚠️ 现状（2026-04-17）**：`FlowNotifyService` 里钉钉 / 企业微信 / 邮件 / 短信四个通道都是 `// TODO` 占位，仅 SignalR 站内消息真实发送。外部推送的补齐已登记为 **P4-16**，见 `doc/plan/审批流-综合优化方案.md`。  
-> S8 首版若未等 P4-16 落地，本章节 3.7 / 4.6 / 5.1 / 5.2 中标"钉钉 / 企微"的项**实际只会到达站内消息**。是否接受，或等 P4-16 合并后再上线 S8，由项目组确认。
+> **现状（2026-04-16 P4-16 已落地首版）**：`FlowNotifyService` 重构为基于 `INotifyPusher` 的多通道调度，5 个通道全部可用：
+> 
+> - **SignalR 站内消息**：默认启用，零配置
+> - **邮件**：复用 `SysEmailService`，按 `SysUser.Email` 发送
+> - **短信**：复用 `SysSmsService`，按 `SysUser.Phone` 发送，需配置 `SmsTemplateId`（运营商模板）
+> - **钉钉群机器人**：配置 `DingTalkWebhookUrl`（+可选 `DingTalkSecret` 加签），向群发送文本
+> - **企业微信群机器人**：配置 `WorkWeixinWebhookUrl`
+> 
+> 每次分发写一条 `ApprovalFlowNotifyLog`（成功/失败、耗时、目标用户列表），可在数据库里审计。应用消息（@人精准）、通知模板化、失败重试将在 P5 批次继续推进。
 
 ### 5.1 渠道启用方式
 
-审批流插件支持以下通知渠道，由系统管理员在配置文件中按需开启：
+审批流插件支持以下通知渠道，均在 `server/Plugins/Admin.NET.Plugin.ApprovalFlow/Configuration/ApprovalFlow.json` 的 `ApprovalFlow:Notify` 节点按需开启：
 
 | 渠道 | 覆盖场景 | 现状 |
 |------|---------|---|
-| 站内消息（SignalR） | 所有审批事件，默认开启 | 已实现 |
-| 钉钉 | 升级确认、关闭确认、催办 | 占位（P4-16 待落地） |
-| 企业微信 | 升级确认、关闭确认、催办 | 占位（P4-16 待落地） |
-| 邮件 | 可选，视企业要求配置 | 占位（P4-16 待落地） |
+| 站内消息（SignalR） | 所有审批事件，默认开启 | ✅ 已实现 |
+| 邮件 | 所有审批事件 | ✅ 已实现（需 `Enabled=true` 且用户有 `Email`） |
+| 短信 | 所有审批事件 | ✅ 已实现（需 `Enabled=true` + `SmsTemplateId` + 用户 `Phone`） |
+| 钉钉 | 升级确认、关闭确认、催办 | ✅ 群机器人首版（`Enabled=true` + `WebhookUrl`） |
+| 企业微信 | 升级确认、关闭确认、催办 | ✅ 群机器人首版（`Enabled=true` + `WebhookUrl`） |
 
 ### 5.2 通知触发规则
 
@@ -458,7 +466,7 @@ S8 各业务场景应明确使用哪套数据，混用会导致数据口径不
 
 | 对象 | 变更 | 用途 |
 |---|---|---|
-| `AdoS8Exception.CurrentFlowInstanceId` | 新增字段 `long?` | 在 `OnFlowStarted` 里存审批实例 ID，便于 `OnFlowCompleted` 反查最后审批人（P4-17 落地前的绕路方案） |
+| `AdoS8Exception.CurrentFlowInstanceId` | 新增字段 `long?` | 当前进行中的审批实例 ID；P4-17 已落地后，`OnFlowCompleted` 的 `lastApproverId` 参数可直接拿到最后审批人，不再需要反查 `timeline`，本字段仅保留"互斥判定 / 前端跳转"用途 |
 | `AdoS8Exception.CurrentFlowBizType` | 新增字段 `string(32)?` | 当前进行中的审批流 `BizType`（升级或关闭），用于互斥判定和前端显示 |
 | `AdoS8Exception.Status` 枚举 | 确认含 `ESCALATED` 值（升级中） | 升级流程发起后切换到此态 |
 | `AdoS8ExceptionTimeline` 事件类型 | 确认支持 `ESCALATE_START / ESCALATE_APPROVED / ESCALATE_REJECTED / ESCALATE_CANCELLED / CLOSE_START / CLOSE_APPROVED / CLOSE_REJECTED / CLOSE_CANCELLED` 等事件 code | 回调里写 S8 业务时间线 |
@@ -472,7 +480,7 @@ S8 各业务场景应明确使用哪套数据，混用会导致数据口径不
 | 审批事件 | `OnXxx` 回调 | S8 状态变化 | S8 业务时间线事件 |
 |---|---|---|---|
 | 发起成功 | `OnFlowStarted` | `ASSIGNED` / `IN_PROGRESS` → `ESCALATED`；存 `CurrentFlowInstanceId` / `CurrentFlowBizType` | `ESCALATE_START`："[操作人] 发起升级，等待 [节点名] 确认" |
-| 通过 | `OnFlowCompleted(Approved)` | `ESCALATED` → `ASSIGNED`；**处理人更新为最后审批人**（反查 `timeline`）；清空 `CurrentFlowInstanceId` / `CurrentFlowBizType` | `ESCALATE_APPROVED`："升级已确认，由 [承接人] 接手" |
+| 通过 | `OnFlowCompleted(Approved, lastApproverId)` | `ESCALATED` → `ASSIGNED`；**处理人更新为 `lastApproverId`**（P4-17 落地后直接取参数，无需反查 timeline）；清空 `CurrentFlowInstanceId` / `CurrentFlowBizType` | `ESCALATE_APPROVED`："升级已确认，由 [承接人] 接手" |
 | 拒绝 | `OnFlowCompleted(Rejected)` | `ESCALATED` → `IN_PROGRESS`；清空字段 | `ESCALATE_REJECTED`："升级被驳回，异常退回原团队处理" |
 | 撤回 | `OnFlowCompleted(Cancelled)` | `ESCALATED` → `IN_PROGRESS`；清空字段 | `ESCALATE_CANCELLED`："发起人撤回升级申请" |
 
@@ -515,8 +523,8 @@ foreach bt in [EXCEPTION_ESCALATION, EXCEPTION_CLOSURE]:
 
 | 决策项 | 默认方向 | 确认状态 |
 |---|---|---|
-| **P4-16 外部推送（钉钉 / 企微）** | S8 首版**仅站内消息**；待 P4-16 合并后再启用钉钉 / 企微 | ⏳ 待负责人确认 |
-| **P4-17 Handler 回调增补 `instanceId` + `lastApproverId`** | S8 开工**先走绕路方案**（存 `CurrentFlowInstanceId` + `timeline` 反查）；P4-17 合并后逐步切换 | ⏳ 待负责人确认 |
+| **P4-16 外部推送（钉钉 / 企微）** | ✅ 2026-04-16 已落地首版（Email / SMS / 钉钉群机器人 / 企微群机器人）。S8 只需在 `ApprovalFlow.json` 配 Webhook + `Enabled=true`，开箱即用。应用消息精准 at 人留待 P5。 | ✅ 已完成 |
+| **P4-17 Handler 回调增补 `instanceId` + `lastApproverId`** | ✅ 2026-04-16 已落地。S8 在 `ExceptionEscalationBizHandler.OnFlowCompleted(_, instanceId, Approved, lastApproverId)` 里直接取 `lastApproverId` 作为升级承接人 ID；不再需要反查 timeline。现有 `CurrentFlowInstanceId` 字段仅用于互斥校验与前端跳转。 | ✅ 已完成 |
 | **工厂管理层在 `SysUser` 的覆盖** | 要求：班组长 / 部门负责人 / 厂级领导至少在 `SysUser` 有账号；车间员工可不在；用 `ApproverType = DepartmentLeader` 动态解析优先 | ⏳ 待组织数据负责人确认 |
 | **默认流程模板** | 是否提供两份默认 FlowJson 让管理员一键导入，还是每个环境自行配置 | ⏳ 待产品确认 |
 

doc/migrations/2026-04-16_approval_flow_notify_log.sql

@@ -0,0 +1,29 @@
+-- =====================================================
+-- P4-16 审批流通知推送日志表 DDL
+-- 适用数据库：MySQL 8.0+
+-- 运行方式：共享开发库 EnableInitDb / EnableInitSeed 为 false，
+--           需由 DBA 手动执行本脚本后重启后端服务。
+-- 创建时间：2026-04-16
+-- =====================================================
+
+CREATE TABLE IF NOT EXISTS `ApprovalFlowNotifyLog` (
+    `Id`              BIGINT        NOT NULL COMMENT '主键Id',
+    `InstanceId`      BIGINT        NOT NULL COMMENT '流程实例Id',
+    `NotifyType`      VARCHAR(32)   NULL     COMMENT '通知类型 NewTask / Urge / FlowCompleted / Transferred / Returned / AddSign / Withdrawn / Escalated / Timeout',
+    `Channel`         VARCHAR(16)   NOT NULL COMMENT '推送渠道 SignalR / Email / Sms / DingTalk / WorkWeixin',
+    `Title`           VARCHAR(256)  NULL     COMMENT '通知标题',
+    `TargetUserIds`   VARCHAR(1024) NULL     COMMENT '目标用户Id列表CSV',
+    `TargetCount`     INT           NOT NULL DEFAULT 0 COMMENT '目标用户数',
+    `Success`         TINYINT(1)    NOT NULL DEFAULT 0 COMMENT '是否成功',
+    `ErrorMessage`    VARCHAR(1024) NULL     COMMENT '错误信息',
+    `ElapsedMs`       INT           NOT NULL DEFAULT 0 COMMENT '耗时ms',
+    `CreateTime`      DATETIME      NULL     COMMENT '创建时间',
+    `UpdateTime`      DATETIME      NULL     COMMENT '更新时间',
+    `CreateUserId`    BIGINT        NULL     COMMENT '创建者Id',
+    `CreateUserName`  VARCHAR(64)   NULL     COMMENT '创建者',
+    `UpdateUserId`    BIGINT        NULL     COMMENT '修改者Id',
+    `UpdateUserName`  VARCHAR(64)   NULL     COMMENT '修改者',
+    `IsDelete`        TINYINT(1)    NOT NULL DEFAULT 0 COMMENT '是否删除',
+    PRIMARY KEY (`Id`),
+    KEY `idx_flownotifylog_instance` (`InstanceId`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='审批流通知推送日志';

doc/plan/审批流-综合优化方案.md

@@ -275,7 +275,30 @@
 
 ---
 
-## 十三、P4-16：外部推送渠道补齐（后期待办）
+## 十三、P4-16：外部推送渠道补齐 ✅（2026-04-16 已完成首版）
+
+### 实施结果（2026-04-16）
+
+已落地**方案 A**（Email/SMS 真实发送 + DingTalk/WorkWeixin 走群机器人 Webhook 首版；应用消息与 `SysUser.DingId/WeixinId` 字段留到 P5 再做）：
+
+- 新增 `INotifyPusher` 抽象 + 5 个实现（`SignalRNotifyPusher` / `EmailNotifyPusher` / `SmsNotifyPusher` / `DingTalkNotifyPusher` / `WorkWeixinNotifyPusher`），全部走 DI，`FlowNotifyService` 重构为按配置 + `IsEnabled` 聚合调度
+- 新增实体 `ApprovalFlowNotifyLog`（一次分发写一条日志，记录渠道、目标用户 CSV、成功/失败、错误信息、耗时）
+- `NotifyChannelConfig` 新增 `DingTalkWebhookUrl` / `DingTalkSecret` / `WorkWeixinWebhookUrl` / `SmsTemplateId` 字段；`ApprovalFlow.json` 同步
+- 邮件复用 `SysEmailService.SendEmail`，按 `SysUser.Email` 逐个发；短信复用 `SysSmsService.SendSms` + 运营商模板 Id（仅作触达通知，动态内容受运营商模板限制）
+- 钉钉 / 企微走群机器人 Webhook POST JSON（钉钉支持加签 Secret）
+- DB 变更需手动：`doc/migrations/2026-04-16_approval_flow_notify_log.sql`（共享开发库 `EnableInitSeed=false`）
+- 验证：`_verify_p4.py` 15/15 PASS（NotifyLog 正确写入，未启用渠道不产生日志）
+
+### 后续（P5 或更晚）
+
+- `SysUser` 补 `DingId` / `WeixinId` 字段 → 钉钉/企微应用消息精准 at 人
+- 通知模板化（替换当前硬编码的标题/内容）
+- 失败重试（当前失败即落日志，不重试）
+- 前端"通知渠道配置"管理页
+
+---
+
+## 十三-旧、P4-16：外部推送渠道补齐（原始方案存档）
 
 ### 背景
 
@@ -307,7 +330,32 @@
 
 ---
 
-## 十四、P4-17：Handler 回调增补 `instanceId` 与 `lastApproverId`（后期待办）
+## 十四、P4-17：Handler 回调增补 `instanceId` 与 `lastApproverId` ✅（2026-04-16 已完成）
+
+### 实施结果（2026-04-16）
+
+- `IFlowBizHandler` 签名改为：
+  - `OnFlowCompleted(long bizId, long instanceId, FlowInstanceStatusEnum finalStatus, long? lastApproverId)`
+  - `OnNodeCompleted(long bizId, long instanceId, string nodeId, string nodeName, long? approverUserId)` （默认 `Task.CompletedTask`）
+- `FlowEngineService` 6 处调用点全部切到新签名：`Approve` / `Reject` / `Withdraw` / `AutoApproveTask` / `AutoRejectTask` / `CompleteInstance`。`CompleteInstance` 新增私有方法 `GetLastHumanApproverIdAsync` 从 `ApprovalFlowLog` 最后一条 `Approve` 读取 `OperatorId`
+- `lastApproverId` 约定：
+  - `Approved` → 最后一个人工审批通过的 `OperatorId`（`GetLastHumanApproverIdAsync`；纯自动通过 → null）
+  - `Rejected` → 执行 `Reject` 的 `task.AssigneeId`（人工拒绝）或 null（`AutoReject`）
+  - `Cancelled` → null（发起人撤回 / 系统撤回）
+  - `Terminated` → null
+- 4 个存量 Handler 全部适配新签名：
+  - `ExceptionEscalationBizHandler` / `ExceptionClosureBizHandler`：**积极使用** `lastApproverId`，写入 `ActionRemark = "审批实例ID: xxx，审批人: yyy"`，给 S8 业务做审计凭证
+  - `ContractReviewBizHandler` / `OrderReviewBizHandler`：仅**签名适配**，业务内部逻辑未动
+- 验证：`_verify_p4.py` T4 用例起一条 `EXCEPTION_ESCALATION` 流程→审批通过→读取 S8 Timeline，成功断言 `ESCALATE_APPROVED.ActionRemark` 同时包含 `审批实例ID` 与 `审批人` → lastApproverId 端到端到达业务层 ✅
+- 回归：`_verify_escalation.py` 22/22 PASS
+
+### 后续
+
+- 尚未使用 `lastApproverId` 的 Handler（合同、订单）可按需切换到积极使用，无时间压力
+
+---
+
+## 十四-旧、P4-17：Handler 回调增补 `instanceId` 与 `lastApproverId`（原始方案存档）
 
 ### 背景
 
@@ -376,8 +424,9 @@ public interface IFlowBizHandler
 | **第二批** ✅ | P1-8 批量审批、P1-7 版本管理 | 低 | 4h |
 | **第三批** ✅ | P1-6 审批代理、P2-10 流程图预览 | 中 | 8h |
 | **第四批** ✅ | P1-5 并行网关（方案 B：`ApprovalFlowCompletedNode` 子表） | 高 | 8h |
-| **第五批**（进行中） | **P3-15 节点级统计** ✅、**流程升级机制收尾**（AutoEscalate / 手动升级）✅、**P2-12 移动端适配**（待做） | 中 | 12–16h |
-| *后期待办（需人工确认再做）* | *P3-13 流程模拟器*（设计器空跑验证）、*P3-14 子流程 callActivity*、*P4-16 外部推送补齐*（钉钉/企微/邮件/短信）、*P4-17 Handler 回调增补 `instanceId` 与 `lastApproverId`* | *高 / 中 / 低* | *另行安排* |
+| **第五批** ✅ | **P3-15 节点级统计** ✅、**流程升级机制收尾**（AutoEscalate / 手动升级）✅ | 中 | 12–16h |
+| **第六批** ✅（2026-04-16） | **P4-17 Handler 回调增补 `instanceId` / `lastApproverId`** ✅、**P4-16 外部推送渠道补齐**（方案 A：Email/SMS 落地 + DingTalk/WorkWeixin Webhook 首版）✅ | 中 | 8h |
+| *后期待办（需人工确认再做）* | *P2-12 移动端适配*、*P3-13 流程模拟器*（设计器空跑验证）、*P3-14 子流程 callActivity*、*P4-16 延伸*（应用消息精准 at 人、通知模板化、失败重试、前端通知渠道管理页） | *中 / 高 / 中 / 中* | *另行安排* |
 
 ---
 

doc/审批流功能说明.md

@@ -434,7 +434,19 @@
 | **超时** | "您有一条审批任务已超时，请尽快处理" | 当前待审批人（仅 `Notify` 动作；同一任务幂等，只发一次） |
 | **升级** | "有一条审批任务升级给您处理" | 升级目标（手动升级和自动升级统一使用） |
 
-**通知渠道：** 当前默认通过 SignalR 推送站内实时消息。系统预留了钉钉、企业微信、邮件、短信等扩展渠道，可在配置文件中开启。
+**通知渠道（2026-04-16 P4-16 已落地首版）：** 采用 `INotifyPusher` 抽象 + 多通道调度，配置开关位于 `Admin.NET.Plugin.ApprovalFlow/Configuration/ApprovalFlow.json` 的 `ApprovalFlow:Notify` 节点。
+
+| 渠道 | 状态 | 配置 Key |
+|---|---|---|
+| SignalR 站内消息 | ✅ 默认启用 | `SignalR:Enabled`（默认 true） |
+| 邮件 | ✅ 可启用 | `Email:Enabled` + 平台 `SysEmailService` 凭据 + `SysUser.Email` |
+| 短信 | ✅ 可启用 | `Sms:Enabled` + `SmsTemplateId`（运营商模板）+ `SysUser.Phone` |
+| 钉钉群机器人 | ✅ 可启用 | `DingTalk:Enabled` + `DingTalkWebhookUrl`（可选 `DingTalkSecret` 加签） |
+| 企业微信群机器人 | ✅ 可启用 | `WorkWeixin:Enabled` + `WorkWeixinWebhookUrl` |
+
+每次通知分发写一条 `ApprovalFlowNotifyLog`（渠道、目标用户、成功/失败、错误信息、耗时），便于审计和排障。未启用的渠道不产生日志；单通道失败不阻塞其它通道，也不阻塞审批主流程。
+
+应用消息精准 @人（需 `SysUser.DingId` / `WeixinId`）、通知模板化、失败重试将在 P5 批次继续推进。
 
 ---
 

doc/审批流集成开发指南.md

@@ -70,10 +70,16 @@ public interface IFlowBizHandler
     Task OnFlowStarted(long bizId, long instanceId) => Task.CompletedTask;
 
     /// 流程结束后回调（必须：更新业务表最终状态）
-    Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus);
+    /// P4-17 起签名已增补 instanceId / lastApproverId，详见下方"参数说明"
+    Task OnFlowCompleted(long bizId, long instanceId,
+                         FlowInstanceStatusEnum finalStatus,
+                         long? lastApproverId);
 
     /// 单个节点审批完成回调（可选：按节点推进业务进度）
-    Task OnNodeCompleted(long bizId, string nodeId, string nodeName) => Task.CompletedTask;
+    /// P4-17 起签名已增补 instanceId / approverUserId
+    Task OnNodeCompleted(long bizId, long instanceId,
+                         string nodeId, string nodeName,
+                         long? approverUserId) => Task.CompletedTask;
 
     /// 获取业务数据用于网关条件表达式求值（可选，仅条件分支时需要）
     /// 返回 key-value 字典，key 对应条件表达式中的变量名
@@ -82,6 +88,21 @@ public interface IFlowBizHandler
 }
 ```
 
+#### `lastApproverId` / `approverUserId` 含义（2026-04-16 P4-17 落地后）
+
+| 路径 | `lastApproverId` 语义 |
+|---|---|
+| `Approved`（人工通过走完） | 最后一个人工 `Approve` 日志的 `OperatorId` |
+| `Approved`（纯自动通过，无人工参与） | `null` |
+| `Rejected`（人工拒绝） | 执行 `Reject` 操作的 `task.AssigneeId` |
+| `Rejected`（`AutoReject` 自动拒绝） | `null` |
+| `Cancelled`（发起人撤回 / 系统撤回） | `null` |
+| `Terminated` | `null` |
+
+`OnNodeCompleted.approverUserId` = 完成该节点的 `task.AssigneeId`（自动通过为 `null`）。
+
+> 业务层不要再从 `timeline` 反查最后审批人；直接用新参数即可。旧版本绕路代码可逐步清理。
+
 #### 各方法说明
 
 | 方法 | 何时被引擎自动调用 | 你需要做什么 | 是否必须 |
@@ -122,9 +143,12 @@ public class OrderReviewBizHandler : IFlowBizHandler, ITransient
             .ExecuteCommandAsync();
     }
 
-    public async Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus)
+    public async Task OnFlowCompleted(long bizId, long instanceId,
+                                      FlowInstanceStatusEnum finalStatus,
+                                      long? lastApproverId)
     {
         // 审批结束 → 根据结果更新订单最终状态
+        // lastApproverId 可用于记录"谁最终通过 / 拒绝"，本示例业务不关心，略过
         var state = finalStatus switch
         {
             FlowInstanceStatusEnum.Approved  => "已通过",
@@ -138,7 +162,9 @@ public class OrderReviewBizHandler : IFlowBizHandler, ITransient
             .ExecuteCommandAsync();
     }
 
-    public Task OnNodeCompleted(long bizId, string nodeId, string nodeName)
+    public Task OnNodeCompleted(long bizId, long instanceId,
+                                string nodeId, string nodeName,
+                                long? approverUserId)
     {
         // 本场景不需要按节点推进，直接返回
         return Task.CompletedTask;
@@ -400,8 +426,8 @@ urgent == 1 && customLevel >= 3
 
 - [ ] 明确要接入的业务场景 / 需要几个 `BizType`（一个业务模块可以有多个，例如 S8 有升级 / 关闭两个）
 - [ ] 对照"常见坑与反模式"章节核实下面几项**不是阻塞项**：
-  - [ ] 外部推送（钉钉 / 企微 / 邮件 / 短信）是否需要？若需要、但 P4-16 未落地 → 提前找负责人决策
-  - [ ] 回调里是否需要"最后审批人 ID"？若需要、且 P4-17 未落地 → 决定走绕路方案（`OnFlowStarted` 存 `instanceId` → `OnFlowCompleted` 查 `timeline`）或先推进 P4-17
+  - [ ] 外部推送（钉钉 / 企微 / 邮件 / 短信）已于 **P4-16（2026-04-16）** 落地首版（群机器人 + 邮件 + 短信）。只需在 `ApprovalFlow.json` 配 Webhook / SMTP / 短信模板并置 `Enabled=true` 即可启用。应用消息（@人精准）留待 P5。
+  - [ ] 回调里需要"最后审批人 ID"已由 **P4-17（2026-04-16）** 解决：`OnFlowCompleted(_, instanceId, finalStatus, lastApproverId)` 直接拿到。老代码中"存 `instanceId` → 反查 `timeline`"的绕路可以清理。
   - [ ] 审批人只能是 `SysUser` / 角色 / 部门 / 部门负责人 / 发起人本人。业务里涉及的"审批人"是否都能映射到系统账号？
 - [ ] 列出本次改动会**跨模块影响**的点（通常没有），按 `AGENTS.md` 要求给负责人确认
 
@@ -411,9 +437,9 @@ urgent == 1 && customLevel >= 3
 
 - [ ] `BizType` 返回编码常量
 - [ ] `GetBizData(bizId)` 返回所有在"流程设计器条件表达式"里会用到的 key（字段命名需与业务模块已约定的参数清单保持一致）
-- [ ] `OnFlowStarted(bizId, instanceId)` — 业务表写入"审批中"状态；**如果业务要反查最后审批人**，这里把 `instanceId` 持久化到业务表
-- [ ] `OnFlowCompleted(bizId, finalStatus)` — 根据 `Approved / Rejected / Cancelled` 三种值把业务表写到终态 + 写业务时间线；若要知道最后审批人，调 `FlowInstanceService.GetTimeline(instanceId)` 取最后一条 `Approve` 的 `OperatorId`
-- [ ] 可选 `OnNodeCompleted(bizId, nodeId, nodeName)` — 只有"按节点推进业务进度"的场景才需要
+- [ ] `OnFlowStarted(bizId, instanceId)` — 业务表写入"审批中"状态；如业务需要在流程进行中互斥发起，可顺手存 `instanceId` / `bizType` 做互斥判定
+- [ ] `OnFlowCompleted(bizId, instanceId, finalStatus, lastApproverId)` — 根据 `Approved / Rejected / Cancelled` 三种值把业务表写到终态 + 写业务时间线；**P4-17 起** 直接用 `lastApproverId` 参数即可，无需再反查 timeline
+- [ ] 可选 `OnNodeCompleted(bizId, instanceId, nodeId, nodeName, approverUserId)` — 只有"按节点推进业务进度"的场景才需要；`approverUserId` 即完成该节点的人
 
 ### 第 3 步：前端 Panel
 
@@ -433,9 +459,9 @@ urgent == 1 && customLevel >= 3
 每个 `BizType` 至少覆盖以下场景，**前端实际点一遍** + 必要时写 E2E 脚本（参照 `_verify_escalation.py`）：
 
 - [ ] 发起 → 状态 / 时间线正确
-- [ ] 同意走完所有节点 → `OnFlowCompleted(Approved)` 回调生效
-- [ ] 拒绝 → `OnFlowCompleted(Rejected)` 回调生效
-- [ ] 发起人撤回 → `OnFlowCompleted(Cancelled)` 回调生效
+- [ ] 同意走完所有节点 → `OnFlowCompleted(Approved, lastApproverId=最后审批人)` 回调生效
+- [ ] 拒绝 → `OnFlowCompleted(Rejected, lastApproverId=拒绝人)` 回调生效
+- [ ] 发起人撤回 → `OnFlowCompleted(Cancelled, lastApproverId=null)` 回调生效
 - [ ] 同一 `bizId` 在流程进行中无法重复发起（前端禁用 + 后端校验）
 - [ ] 流程未发布时的友好提示
 - [ ] 涉及条件网关时：每条分支各走一次（变量覆盖每个分支的临界值）
@@ -449,45 +475,45 @@ urgent == 1 && customLevel >= 3
 
 > 接入审批流时最容易踩的 4 个坑。看文档不显眼，但项目里不止一次碰到。
 
-### 11.1 外部推送（钉钉 / 企微 / 邮件 / 短信）目前是 TODO
+### 11.1 外部推送（钉钉 / 企微 / 邮件 / 短信）——P4-16（2026-04-16）已落地首版
+
+5 个通道全部可用：
 
-`FlowNotifyService.SendDingTalk` / `SendWorkWeixin` / `SendEmail` / `SendSms` 都是 `return Task.CompletedTask;` 的空实现。**只有 SignalR 站内消息是真实发送的**。
+| 渠道 | 启用方式 | 说明 |
+|---|---|---|
+| SignalR 站内消息 | 默认启用，零配置 | 所有审批事件 |
+| 邮件 | `Notify:Email:Enabled=true` + SysUser.Email | 复用 `SysEmailService` |
+| 短信 | `Notify:Sms:Enabled=true` + `SmsTemplateId` + SysUser.Phone | 复用 `SysSmsService`，动态内容受运营商模板限制 |
+| 钉钉群机器人 | `Notify:DingTalk:Enabled=true` + `DingTalkWebhookUrl`（+可选 `DingTalkSecret` 加签） | 群文本，不支持精准 at 人（P5 再做） |
+| 企业微信群机器人 | `Notify:WorkWeixin:Enabled=true` + `WorkWeixinWebhookUrl` | 群文本 |
 
-**影响：** 任何业务文档写"会发钉钉 / 企微通知审批人"时，如果 P4-16 尚未落地，**都只会到达站内消息**。
+每次分发写一条 `ApprovalFlowNotifyLog`（成功/失败 / 耗时 / 目标用户 CSV），可在数据库审计 / 调试。
 
-**对策：**
-- 业务首版接受仅站内，则在业务模块的功能说明里显式标注"钉钉 / 企微在 P4-16 落地后启用"
-- 业务必须有外部推送，则先推动 P4-16 实施再开工
+**对策（仍需提醒）：**
+- 部署环境需确认对应凭据已配置，否则该通道 `IsEnabled=false` 会被静默跳过（不会报错，但也不会发送）
+- 失败不阻塞审批主流程，只落 `ApprovalFlowNotifyLog`
+- 业务 Handler 无需关心通知发送，引擎自动按事件触发
 
-### 11.2 `OnFlowCompleted` / `OnNodeCompleted` 拿不到"审批人 ID"
+### 11.2 `OnFlowCompleted` / `OnNodeCompleted` 拿不到"审批人 ID"——P4-17（2026-04-16）已解决
 
-当前 Handler 合约只传 `bizId / nodeId / nodeName / finalStatus`，不含审批人。如果业务需要"审批通过后把处理人改为最后审批人"这种逻辑（典型场景：S8 升级承接），需要绕一下：
+**现在**：Handler 合约已带 `instanceId + lastApproverId / approverUserId`：
 
 ```csharp
-public async Task OnFlowStarted(long bizId, long instanceId)
-{
-    // 在业务表里把 instanceId 存起来（新增字段 CurrentFlowInstanceId）
-    await _bizRep.AsUpdateable()
-        .SetColumns(x => x.CurrentFlowInstanceId == instanceId)
-        .Where(x => x.Id == bizId).ExecuteCommandAsync();
-}
-
-public async Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus)
+public async Task OnFlowCompleted(long bizId, long instanceId,
+                                  FlowInstanceStatusEnum finalStatus,
+                                  long? lastApproverId)
 {
-    var biz = await _bizRep.GetByIdAsync(bizId);
-    if (finalStatus == FlowInstanceStatusEnum.Approved && biz.CurrentFlowInstanceId != null)
+    if (finalStatus == FlowInstanceStatusEnum.Approved && lastApproverId.HasValue)
     {
-        var timeline = await _flowInstanceService.GetTimeline(biz.CurrentFlowInstanceId.Value);
-        var lastApproverId = timeline.Where(t => t.Action == "Approve")
-                                     .OrderByDescending(t => t.CreateTime)
-                                     .FirstOrDefault()?.OperatorId;
-        // 用 lastApproverId 做业务更新
+        // 直接用 lastApproverId，无需任何反查
+        await _bizRep.AsUpdateable()
+            .SetColumns(x => x.HandlerUserId == lastApproverId.Value)
+            .Where(x => x.Id == bizId).ExecuteCommandAsync();
     }
-    // ... 其它状态分支
 }
 ```
 
-**长期方案：** 待 **P4-17** 落地后，`OnFlowCompleted` 会直接带 `instanceId + lastApproverId`，上面的绕路可以删除。
+`lastApproverId` 取值规则见本指南第 2 步的"参数说明"表。**不要再调 `FlowInstanceService.GetTimeline` 反查最后审批人**，这是旧绕路做法，P4-17 之后已不必要。
 
 ### 11.3 同一 `bizId` 的并发互斥"不是"审批流职责
 
@@ -551,11 +577,13 @@ public class XxxEscalationBizHandler : IFlowBizHandler, ITransient
         // TODO: 写业务时间线
     }
 
-    public async Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus)
+    public async Task OnFlowCompleted(long bizId, long instanceId,
+                                      FlowInstanceStatusEnum finalStatus,
+                                      long? lastApproverId)
     {
         var next = finalStatus switch
         {
-            FlowInstanceStatusEnum.Approved  => "ASSIGNED",   // 升级承接，含处理人迁移
+            FlowInstanceStatusEnum.Approved  => "ASSIGNED",
             FlowInstanceStatusEnum.Rejected  => "IN_PROGRESS",
             FlowInstanceStatusEnum.Cancelled => "IN_PROGRESS",
             _ => "IN_PROGRESS",
@@ -565,11 +593,14 @@ public class XxxEscalationBizHandler : IFlowBizHandler, ITransient
                 Status = next,
                 CurrentFlowInstanceId = null,
                 CurrentFlowBizType = null,
+                HandlerUserId = finalStatus == FlowInstanceStatusEnum.Approved
+                                && lastApproverId.HasValue
+                                ? lastApproverId.Value
+                                : x.HandlerUserId,
             })
             .Where(x => x.Id == bizId)
             .ExecuteCommandAsync();
-        // TODO: 若 Approved 且需迁移承接人，按 11.2 的方式反查最后审批人
-        // TODO: 写业务时间线
+        // TODO: 写业务时间线，可把 instanceId + lastApproverId 记入 ActionRemark 做审计
     }
 }
 
@@ -729,7 +760,7 @@ Cursor 会按 `_verify_escalation.py` 的结构（登录 + 插入流程定义 +
 
 ```
 我在 <业务> 实现 XxxBizHandler 的 OnFlowCompleted 时需要拿到最后审批人 ID，
-但回调里没有这个参数。参考 @doc/审批流集成开发指南.md 第十一章 11.2 的绕路方案帮我实现。
+参考 @doc/审批流集成开发指南.md 第十一章 11.2（P4-17 已落地）的参数 `lastApproverId` 直接取用即可。
 ```
 
 直接引用"常见坑"章节的具体小节号，Cursor 会直接复用章节里的代码骨架，不重新发明。

server/Admin.NET.Web.Entry/Admin.NET.Web.Entry.csproj

@@ -11,9 +11,9 @@
     <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
     <Copyright>Admin.NET</Copyright>
     <Description>Admin.NET 通用权限开发平台</Description>
-    <AssemblyVersion>1.0.49</AssemblyVersion>
-    <FileVersion>1.0.49</FileVersion>
-    <Version>1.0.49</Version>
+    <AssemblyVersion>1.0.50</AssemblyVersion>
+    <FileVersion>1.0.50</FileVersion>
+    <Version>1.0.50</Version>
   </PropertyGroup>
 
   <ItemGroup>

server/Plugins/Admin.NET.Plugin.AiDOP/Order/ContractReviewBizHandler.cs

@@ -31,7 +31,7 @@ public class ContractReviewBizHandler : IFlowBizHandler, ITransient
         await _reviewRep.UpdateAsync(row);
     }
 
-    public async Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus)
+    public async Task OnFlowCompleted(long bizId, long instanceId, FlowInstanceStatusEnum finalStatus, long? lastApproverId)
     {
         var id = (int)bizId;
         var now = DateTime.Now;
@@ -67,7 +67,7 @@ public class ContractReviewBizHandler : IFlowBizHandler, ITransient
         await _reviewRep.UpdateAsync(row);
     }
 
-    public Task OnNodeCompleted(long bizId, string nodeId, string nodeName)
+    public Task OnNodeCompleted(long bizId, long instanceId, string nodeId, string nodeName, long? approverUserId)
     {
         return Task.CompletedTask;
     }

server/Plugins/Admin.NET.Plugin.AiDOP/Order/OrderReviewBizHandler.cs

@@ -30,7 +30,7 @@ public class OrderReviewBizHandler : IFlowBizHandler, ITransient
         catch (Exception) { /* 表不存在时静默跳过 */ }
     }
 
-    public async Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus)
+    public async Task OnFlowCompleted(long bizId, long instanceId, FlowInstanceStatusEnum finalStatus, long? lastApproverId)
     {
         var state = finalStatus switch
         {
@@ -49,7 +49,7 @@ public class OrderReviewBizHandler : IFlowBizHandler, ITransient
         catch (Exception) { /* 表不存在时静默跳过 */ }
     }
 
-    public Task OnNodeCompleted(long bizId, string nodeId, string nodeName)
+    public Task OnNodeCompleted(long bizId, long instanceId, string nodeId, string nodeName, long? approverUserId)
     {
         return Task.CompletedTask;
     }

server/Plugins/Admin.NET.Plugin.AiDOP/Service/S8/ExceptionClosureBizHandler.cs

@@ -29,10 +29,10 @@ public class ExceptionClosureBizHandler : IFlowBizHandler, ITransient
         e.ActiveFlowInstanceId = instanceId;
         e.UpdatedAt = DateTime.Now;
         await _rep.UpdateAsync(e);
-        await InsertTimelineAsync(e.Id, "CLOSURE_START", "发起关闭确认", null, null, instanceId);
+        await InsertTimelineAsync(e.Id, "CLOSURE_START", "发起关闭确认", null, null, instanceId, null);
     }
 
-    public async Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus)
+    public async Task OnFlowCompleted(long bizId, long instanceId, FlowInstanceStatusEnum finalStatus, long? lastApproverId)
     {
         var e = await _rep.GetByIdAsync(bizId) ?? throw new S8BizException("异常不存在");
         e.ActiveFlowInstanceId = null;
@@ -43,13 +43,15 @@ public class ExceptionClosureBizHandler : IFlowBizHandler, ITransient
             e.Status = "CLOSED";
             e.ClosedAt = DateTime.Now;
             await _rep.UpdateAsync(e);
-            await InsertTimelineAsync(e.Id, "CLOSURE_APPROVED", "关闭已确认", "RESOLVED", "CLOSED", null);
+            await InsertTimelineAsync(e.Id, "CLOSURE_APPROVED", "关闭已确认", "RESOLVED", "CLOSED",
+                instanceId, lastApproverId);
         }
         else
         {
             e.Status = "IN_PROGRESS";
             await _rep.UpdateAsync(e);
-            await InsertTimelineAsync(e.Id, "CLOSURE_REJECTED", "关闭被驳回", "RESOLVED", "IN_PROGRESS", null);
+            await InsertTimelineAsync(e.Id, "CLOSURE_REJECTED", "关闭被驳回", "RESOLVED", "IN_PROGRESS",
+                instanceId, lastApproverId);
         }
     }
 
@@ -63,8 +65,18 @@ public class ExceptionClosureBizHandler : IFlowBizHandler, ITransient
         };
     }
 
-    private async Task InsertTimelineAsync(long exceptionId, string code, string label, string? from, string? to, long? instanceId)
+    private async Task InsertTimelineAsync(long exceptionId, string code, string label,
+        string? from, string? to, long? instanceId, long? approverId)
     {
+        // P4-17: 补齐审批人 ID 到 Timeline 留痕
+        string? remark = null;
+        if (instanceId.HasValue && approverId.HasValue)
+            remark = $"审批实例ID: {instanceId}，审批人: {approverId}";
+        else if (instanceId.HasValue)
+            remark = $"审批实例ID: {instanceId}";
+        else if (approverId.HasValue)
+            remark = $"审批人: {approverId}";
+
         await _timelineRep.InsertAsync(new AdoS8ExceptionTimeline
         {
             ExceptionId = exceptionId,
@@ -72,7 +84,7 @@ public class ExceptionClosureBizHandler : IFlowBizHandler, ITransient
             ActionLabel = label,
             FromStatus = from,
             ToStatus = to,
-            ActionRemark = instanceId.HasValue ? $"审批实例ID: {instanceId}" : null,
+            ActionRemark = remark,
             CreatedAt = DateTime.Now
         });
     }

server/Plugins/Admin.NET.Plugin.AiDOP/Service/S8/ExceptionEscalationBizHandler.cs

@@ -30,10 +30,10 @@ public class ExceptionEscalationBizHandler : IFlowBizHandler, ITransient
         e.ActiveFlowInstanceId = instanceId;
         e.UpdatedAt = DateTime.Now;
         await _rep.UpdateAsync(e);
-        await InsertTimelineAsync(e.Id, "ESCALATE_START", "发起升级", null, "ESCALATED", instanceId);
+        await InsertTimelineAsync(e.Id, "ESCALATE_START", "发起升级", null, "ESCALATED", instanceId, null);
     }
 
-    public async Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus)
+    public async Task OnFlowCompleted(long bizId, long instanceId, FlowInstanceStatusEnum finalStatus, long? lastApproverId)
     {
         var e = await _rep.GetByIdAsync(bizId) ?? throw new S8BizException("异常不存在");
         e.ActiveFlowInstanceId = null;
@@ -43,13 +43,15 @@ public class ExceptionEscalationBizHandler : IFlowBizHandler, ITransient
         {
             e.Status = "ASSIGNED";
             await _rep.UpdateAsync(e);
-            await InsertTimelineAsync(e.Id, "ESCALATE_APPROVED", "升级已确认", "ESCALATED", "ASSIGNED", null);
+            await InsertTimelineAsync(e.Id, "ESCALATE_APPROVED", "升级已确认", "ESCALATED", "ASSIGNED",
+                instanceId, lastApproverId);
         }
         else
         {
             e.Status = "IN_PROGRESS";
             await _rep.UpdateAsync(e);
-            await InsertTimelineAsync(e.Id, "ESCALATE_REJECTED", "升级被驳回", "ESCALATED", "IN_PROGRESS", null);
+            await InsertTimelineAsync(e.Id, "ESCALATE_REJECTED", "升级被驳回", "ESCALATED", "IN_PROGRESS",
+                instanceId, lastApproverId);
         }
     }
 
@@ -65,8 +67,18 @@ public class ExceptionEscalationBizHandler : IFlowBizHandler, ITransient
         };
     }
 
-    private async Task InsertTimelineAsync(long exceptionId, string code, string label, string? from, string? to, long? instanceId)
+    private async Task InsertTimelineAsync(long exceptionId, string code, string label,
+        string? from, string? to, long? instanceId, long? approverId)
     {
+        // P4-17: 补齐审批人 ID 到 Timeline 留痕
+        string? remark = null;
+        if (instanceId.HasValue && approverId.HasValue)
+            remark = $"审批实例ID: {instanceId}，审批人: {approverId}";
+        else if (instanceId.HasValue)
+            remark = $"审批实例ID: {instanceId}";
+        else if (approverId.HasValue)
+            remark = $"审批人: {approverId}";
+
         await _timelineRep.InsertAsync(new AdoS8ExceptionTimeline
         {
             ExceptionId = exceptionId,
@@ -74,7 +86,7 @@ public class ExceptionEscalationBizHandler : IFlowBizHandler, ITransient
             ActionLabel = label,
             FromStatus = from,
             ToStatus = to,
-            ActionRemark = instanceId.HasValue ? $"审批实例ID: {instanceId}" : null,
+            ActionRemark = remark,
             CreatedAt = DateTime.Now
         });
     }

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Configuration/ApprovalFlow.json

@@ -15,7 +15,13 @@
       "DingTalk": false,
       "WorkWeixin": false,
       "Email": false,
-      "Sms": false
+      "Sms": false,
+
+      "// P4-16": "以下字段仅在对应渠道启用时才生效",
+      "DingTalkWebhookUrl": "",
+      "DingTalkSecret": "",
+      "WorkWeixinWebhookUrl": "",
+      "SmsTemplateId": ""
     }
   }
 }

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Entity/ApprovalFlowNotifyLog.cs

@@ -0,0 +1,70 @@
+namespace Admin.NET.Plugin.ApprovalFlow;
+
+/// <summary>
+/// 审批流通知推送日志（P4-16）
+/// 记录每次 NotifyUsers 按渠道分发的结果，便于运维排障与降级审计。
+/// 一条记录 = 一次（实例 × 通知类型 × 渠道）的分发结果（接收用户合并入 TargetUserIds / TargetCount）。
+/// </summary>
+[SugarTable(null, "审批流通知推送日志")]
+[SugarIndex("idx_flownotifylog_instance", nameof(InstanceId), OrderByType.Asc)]
+public class ApprovalFlowNotifyLog : EntityBase
+{
+    /// <summary>
+    /// 关联流程实例 Id
+    /// </summary>
+    [SugarColumn(ColumnDescription = "流程实例Id")]
+    public long InstanceId { get; set; }
+
+    /// <summary>
+    /// 通知类型（NewTask / Urge / FlowCompleted / Transferred / Returned / AddSign / Withdrawn / Escalated / Timeout）
+    /// </summary>
+    [SugarColumn(ColumnDescription = "通知类型", Length = 32, IsNullable = true)]
+    [MaxLength(32)]
+    public string? NotifyType { get; set; }
+
+    /// <summary>
+    /// 推送渠道（SignalR / Email / Sms / DingTalk / WorkWeixin）
+    /// </summary>
+    [SugarColumn(ColumnDescription = "推送渠道", Length = 16)]
+    [MaxLength(16)]
+    public string Channel { get; set; } = "";
+
+    /// <summary>
+    /// 通知标题（冗余便于检索）
+    /// </summary>
+    [SugarColumn(ColumnDescription = "通知标题", Length = 256, IsNullable = true)]
+    [MaxLength(256)]
+    public string? Title { get; set; }
+
+    /// <summary>
+    /// 目标用户 Id 列表（CSV，最多保留 1024 字符）
+    /// </summary>
+    [SugarColumn(ColumnDescription = "目标用户ID列表CSV", Length = 1024, IsNullable = true)]
+    [MaxLength(1024)]
+    public string? TargetUserIds { get; set; }
+
+    /// <summary>
+    /// 目标用户数
+    /// </summary>
+    [SugarColumn(ColumnDescription = "目标用户数")]
+    public int TargetCount { get; set; }
+
+    /// <summary>
+    /// 是否成功（至少一次底层调用未抛异常视为成功；对于 SignalR 若无在线用户也记 true）
+    /// </summary>
+    [SugarColumn(ColumnDescription = "是否成功")]
+    public bool Success { get; set; }
+
+    /// <summary>
+    /// 错误信息（失败时填充，最多 1024 字符）
+    /// </summary>
+    [SugarColumn(ColumnDescription = "错误信息", Length = 1024, IsNullable = true)]
+    [MaxLength(1024)]
+    public string? ErrorMessage { get; set; }
+
+    /// <summary>
+    /// 耗时毫秒
+    /// </summary>
+    [SugarColumn(ColumnDescription = "耗时ms")]
+    public int ElapsedMs { get; set; }
+}

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowEngine/FlowEngineService.cs

@@ -143,7 +143,7 @@ public class FlowEngineService : ITransient
         if (await IsNodeCompleted(instance, task.NodeId))
         {
             await InvokeHandler(instance.BizType,
-                h => h.OnNodeCompleted(instance.BizId, task.NodeId, task.NodeName ?? ""));
+                h => h.OnNodeCompleted(instance.BizId, instance.Id, task.NodeId, task.NodeName ?? "", task.AssigneeId));
 
             var flowData = DeserializeFlowJson(instance.FlowJsonSnapshot);
             await AdvanceToNext(instance, flowData, task.NodeId);
@@ -171,8 +171,9 @@ public class FlowEngineService : ITransient
         await _instanceRep.AsUpdateable(instance).ExecuteCommandAsync();
 
         await WriteLog(instance.Id, taskId, task.NodeId, FlowLogActionEnum.Reject, comment);
+        // P4-17: 驳回人 = 当前被指派的审批人
         await InvokeHandler(instance.BizType,
-            h => h.OnFlowCompleted(instance.BizId, FlowInstanceStatusEnum.Rejected));
+            h => h.OnFlowCompleted(instance.BizId, instance.Id, FlowInstanceStatusEnum.Rejected, task.AssigneeId));
         await _notifyService.NotifyFlowCompleted(instance.InitiatorId, instance.Id, instance.Title, FlowInstanceStatusEnum.Rejected);
     }
 
@@ -250,8 +251,9 @@ public class FlowEngineService : ITransient
         await _instanceRep.AsUpdateable(instance).ExecuteCommandAsync();
 
         await WriteLog(instanceId, null, instance.CurrentNodeId, FlowLogActionEnum.Withdraw, null);
+        // P4-17: 撤回场景无"审批人"，lastApproverId = null
         await InvokeHandler(instance.BizType,
-            h => h.OnFlowCompleted(instance.BizId, FlowInstanceStatusEnum.Cancelled));
+            h => h.OnFlowCompleted(instance.BizId, instanceId, FlowInstanceStatusEnum.Cancelled, null));
 
         await _notifyService.NotifyWithdrawn(cancelledUserIds, instanceId, instance.Title, instance.InitiatorName);
     }
@@ -514,8 +516,9 @@ public class FlowEngineService : ITransient
 
         if (await IsNodeCompleted(instance, task.NodeId))
         {
+            // P4-17: 系统自动通过，无人工审批人，approverUserId = null
             await InvokeHandler(instance.BizType,
-                h => h.OnNodeCompleted(instance.BizId, task.NodeId, task.NodeName ?? ""));
+                h => h.OnNodeCompleted(instance.BizId, instance.Id, task.NodeId, task.NodeName ?? "", null));
             var flowData = DeserializeFlowJson(instance.FlowJsonSnapshot);
             await AdvanceToNext(instance, flowData, task.NodeId);
         }
@@ -537,8 +540,9 @@ public class FlowEngineService : ITransient
         await WriteSystemLog(instance.Id, task.Id, task.NodeId,
             FlowLogActionEnum.AutoTimeout, "审批超时，系统自动拒绝");
 
+        // P4-17: 系统自动拒绝，无人工审批人，lastApproverId = null
         await InvokeHandler(instance.BizType,
-            h => h.OnFlowCompleted(instance.BizId, FlowInstanceStatusEnum.Rejected));
+            h => h.OnFlowCompleted(instance.BizId, instance.Id, FlowInstanceStatusEnum.Rejected, null));
         await _notifyService.NotifyFlowCompleted(instance.InitiatorId, instance.Id,
             instance.Title, FlowInstanceStatusEnum.Rejected);
     }
@@ -750,11 +754,29 @@ public class FlowEngineService : ITransient
         await _instanceRep.AsUpdateable(instance)
             .UpdateColumns(i => new { i.Status, i.EndTime })
             .ExecuteCommandAsync();
+
+        // P4-17: 正常完成路径的 lastApproverId = 最后一条人工 Approve 日志的操作人（系统自动通过不算）
+        var lastApproverId = status == FlowInstanceStatusEnum.Approved
+            ? await GetLastHumanApproverIdAsync(instance.Id)
+            : null;
         await InvokeHandler(instance.BizType,
-            h => h.OnFlowCompleted(instance.BizId, status));
+            h => h.OnFlowCompleted(instance.BizId, instance.Id, status, lastApproverId));
         await _notifyService.NotifyFlowCompleted(instance.InitiatorId, instance.Id, instance.Title, status);
     }
 
+    /// <summary>
+    /// P4-17: 查询该实例最后一条人工 Approve 日志的操作人 UserId
+    /// （系统超时自动通过写入的是 AutoTimeout，不会被此查询命中）
+    /// </summary>
+    private async Task<long?> GetLastHumanApproverIdAsync(long instanceId)
+    {
+        var lastLog = await _logRep.AsQueryable()
+            .Where(l => l.InstanceId == instanceId && l.Action == FlowLogActionEnum.Approve)
+            .OrderByDescending(l => l.CreateTime)
+            .FirstAsync();
+        return lastLog?.OperatorId > 0 ? lastLog.OperatorId : null;
+    }
+
     private async Task CreateTasksForNode(ApprovalFlowInstance instance, ApprovalFlowItem flowData, string nodeId)
     {
         var node = flowData.Nodes.FirstOrDefault(n => n.Id == nodeId)

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowEngine/IFlowBizHandler.cs

@@ -19,12 +19,29 @@ public interface IFlowBizHandler
     /// <summary>
     /// 流程结束后回调（必须：更新业务表最终状态）
     /// </summary>
-    Task OnFlowCompleted(long bizId, FlowInstanceStatusEnum finalStatus);
+    /// <param name="bizId">业务实体 Id</param>
+    /// <param name="instanceId">审批流实例 Id（P4-17 新增，便于业务侧留痕/关联）</param>
+    /// <param name="finalStatus">流程最终状态（Approved / Rejected / Cancelled / Terminated）</param>
+    /// <param name="lastApproverId">
+    /// 最后一位审批人 UserId（P4-17 新增）。
+    /// Approved → 最后一个同意节点的操作人；
+    /// Rejected → 驳回人（人工驳回）或 null（系统超时自动拒绝）；
+    /// Cancelled → null（系统/发起人撤回）；
+    /// Terminated → null。
+    /// </param>
+    Task OnFlowCompleted(long bizId, long instanceId, FlowInstanceStatusEnum finalStatus, long? lastApproverId);
 
     /// <summary>
     /// 单个节点审批完成回调（可选：按节点推进业务进度）
     /// </summary>
-    Task OnNodeCompleted(long bizId, string nodeId, string nodeName) => Task.CompletedTask;
+    /// <param name="bizId">业务实体 Id</param>
+    /// <param name="instanceId">审批流实例 Id（P4-17 新增）</param>
+    /// <param name="nodeId">节点 Id</param>
+    /// <param name="nodeName">节点名称</param>
+    /// <param name="approverUserId">
+    /// 该节点最后一位审批人 UserId（P4-17 新增，系统自动动作时为 null）
+    /// </param>
+    Task OnNodeCompleted(long bizId, long instanceId, string nodeId, string nodeName, long? approverUserId) => Task.CompletedTask;
 
     /// <summary>
     /// 获取业务数据用于网关条件表达式求值（可选）

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowNotify/FlowNotifyService.cs

@@ -1,44 +1,48 @@
-using Admin.NET.Core.Service;
-using Microsoft.AspNetCore.SignalR;
+using System.Diagnostics;
 
 namespace Admin.NET.Plugin.ApprovalFlow.Service;
 
 /// <summary>
-/// 流程通知服务 — 按 JSON 配置分渠道调度
+/// 流程通知服务（P4-16 重构）— 聚合所有 INotifyPusher，按配置 + 渠道启用状态并行调度，
+/// 每个渠道的发送结果写入 ApprovalFlowNotifyLog 便于运维追溯与降级审计。
 /// </summary>
 public class FlowNotifyService : ITransient
 {
-    private readonly IHubContext<OnlineUserHub, IOnlineUserHub> _hubContext;
-    private readonly SysCacheService _cacheService;
+    private readonly IEnumerable<INotifyPusher> _pushers;
+    private readonly SqlSugarRepository<ApprovalFlowNotifyLog> _logRep;
 
     public FlowNotifyService(
-        IHubContext<OnlineUserHub, IOnlineUserHub> hubContext,
-        SysCacheService cacheService)
+        IEnumerable<INotifyPusher> pushers,
+        SqlSugarRepository<ApprovalFlowNotifyLog> logRep)
     {
-        _hubContext = hubContext;
-        _cacheService = cacheService;
+        _pushers = pushers;
+        _logRep = logRep;
     }
 
     public async Task NotifyUsers(List<long> userIds, FlowNotification notification)
     {
         if (userIds.Count == 0) return;
 
-        var cfg = App.GetConfig<NotifyChannelConfig>("ApprovalFlow:Notify");
+        var cfg = App.GetConfig<NotifyChannelConfig>("ApprovalFlow:Notify") ?? new NotifyChannelConfig();
 
-        if (cfg?.SignalR != false)
-            await SendSignalR(userIds, notification);
-
-        if (cfg?.DingTalk == true)
-            await SendDingTalk(userIds, notification);
-
-        if (cfg?.WorkWeixin == true)
-            await SendWorkWeixin(userIds, notification);
+        foreach (var pusher in _pushers)
+        {
+            if (!pusher.IsEnabled(cfg)) continue;
 
-        if (cfg?.Email == true)
-            await SendEmail(userIds, notification);
+            var sw = Stopwatch.StartNew();
+            FlowNotifyPushResult result;
+            try
+            {
+                result = await pusher.PushAsync(userIds, notification);
+            }
+            catch (Exception ex)
+            {
+                result = FlowNotifyPushResult.Fail(ex.Message);
+            }
+            sw.Stop();
 
-        if (cfg?.Sms == true)
-            await SendSms(userIds, notification);
+            await SafeWriteLog(notification, pusher.Channel, userIds, result, (int)sw.ElapsedMilliseconds);
+        }
     }
 
     public async Task NotifyUrge(List<long> userIds, long instanceId, string title)
@@ -160,50 +164,36 @@ public class FlowNotifyService : ITransient
     }
 
     // ═══════════════════════════════════════════
-    //  各渠道发送实现
+    //  日志写入
     // ═══════════════════════════════════════════
 
-    private async Task SendSignalR(List<long> userIds, FlowNotification notification)
+    private async Task SafeWriteLog(FlowNotification notification, string channel, List<long> userIds,
+        FlowNotifyPushResult result, int elapsedMs)
     {
-        var onlineUsers = _cacheService.HashGetAll<SysOnlineUser>(CacheConst.KeyUserOnline);
-        var connectionIds = onlineUsers
-            .Where(u => userIds.Contains(u.Value.UserId))
-            .Select(u => u.Value.ConnectionId)
-            .ToList();
-
-        if (connectionIds.Count == 0) return;
-
-        await _hubContext.Clients.Clients(connectionIds).ReceiveMessage(new
+        try
         {
-            title = notification.Title,
-            message = notification.Content,
-            type = notification.Type.ToString(),
-            instanceId = notification.InstanceId,
-        });
-    }
-
-    private Task SendDingTalk(List<long> userIds, FlowNotification notification)
-    {
-        // TODO: 接入 DingTalk 开放平台 API
-        return Task.CompletedTask;
-    }
-
-    private Task SendWorkWeixin(List<long> userIds, FlowNotification notification)
-    {
-        // TODO: 接入企业微信消息推送 API
-        return Task.CompletedTask;
-    }
-
-    private Task SendEmail(List<long> userIds, FlowNotification notification)
-    {
-        // TODO: 接入 SMTP / 邮件服务
-        return Task.CompletedTask;
-    }
-
-    private Task SendSms(List<long> userIds, FlowNotification notification)
-    {
-        // TODO: 接入短信服务
-        return Task.CompletedTask;
+            var csv = string.Join(",", userIds);
+            if (csv.Length > 1024) csv = csv.Substring(0, 1020) + "...";
+            var err = result.ErrorMessage;
+            if (!string.IsNullOrEmpty(err) && err.Length > 1024) err = err.Substring(0, 1020) + "...";
+
+            await _logRep.InsertAsync(new ApprovalFlowNotifyLog
+            {
+                InstanceId = notification.InstanceId,
+                NotifyType = notification.Type.ToString(),
+                Channel = channel,
+                Title = notification.Title,
+                TargetUserIds = csv,
+                TargetCount = userIds.Count,
+                Success = result.Success,
+                ErrorMessage = err,
+                ElapsedMs = elapsedMs,
+            });
+        }
+        catch
+        {
+            // 日志写入失败不能影响主流程
+        }
     }
 }
 
@@ -241,4 +231,16 @@ public class NotifyChannelConfig
     public bool WorkWeixin { get; set; }
     public bool Email { get; set; }
     public bool Sms { get; set; }
+
+    /// <summary>P4-16: 钉钉群机器人 Webhook URL（含 access_token）</summary>
+    public string? DingTalkWebhookUrl { get; set; }
+
+    /// <summary>P4-16: 钉钉群机器人加签 Secret（可选，启用加签时必填）</summary>
+    public string? DingTalkSecret { get; set; }
+
+    /// <summary>P4-16: 企业微信群机器人 Webhook URL（含 key）</summary>
+    public string? WorkWeixinWebhookUrl { get; set; }
+
+    /// <summary>P4-16: 短信运营商侧的通知模板 Id（阿里云/腾讯云/自定义）</summary>
+    public string? SmsTemplateId { get; set; }
 }

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowNotify/INotifyPusher.cs

@@ -0,0 +1,39 @@
+namespace Admin.NET.Plugin.ApprovalFlow.Service;
+
+/// <summary>
+/// 审批流通知推送器抽象（P4-16）
+/// 每种渠道一个实现，注册到 DI 容器，由 FlowNotifyService 按配置 + 启用状态并行调度。
+/// </summary>
+public interface INotifyPusher
+{
+    /// <summary>
+    /// 渠道名（SignalR / Email / Sms / DingTalk / WorkWeixin），与 NotifyChannelConfig 属性名一致
+    /// </summary>
+    string Channel { get; }
+
+    /// <summary>
+    /// 根据配置判断当前渠道是否启用
+    /// </summary>
+    bool IsEnabled(NotifyChannelConfig cfg);
+
+    /// <summary>
+    /// 实际推送
+    /// </summary>
+    /// <param name="userIds">目标用户 Id 列表（SignalR/Email/Sms 直接定位人；DingTalk/WorkWeixin Webhook 忽略，由群机器人向群成员广播）</param>
+    /// <param name="notification">通知载荷</param>
+    /// <returns>推送结果（含是否成功、目标数、耗时、错误）</returns>
+    Task<FlowNotifyPushResult> PushAsync(List<long> userIds, FlowNotification notification);
+}
+
+/// <summary>
+/// 单次推送结果
+/// </summary>
+public class FlowNotifyPushResult
+{
+    public bool Success { get; set; }
+    public int ActualTargetCount { get; set; }
+    public string? ErrorMessage { get; set; }
+
+    public static FlowNotifyPushResult Ok(int count) => new() { Success = true, ActualTargetCount = count };
+    public static FlowNotifyPushResult Fail(string error) => new() { Success = false, ErrorMessage = error };
+}

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowNotify/Pushers/DingTalkNotifyPusher.cs

@@ -0,0 +1,57 @@
+using System.Net.Http;
+using System.Net.Http.Json;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace Admin.NET.Plugin.ApprovalFlow.Service;
+
+/// <summary>
+/// 钉钉推送（P4-16 - 首版 Webhook 机制）
+/// 通过配置的群机器人 Webhook URL（含 access_token）推送文本消息。
+/// 不做 DingTalk 应用消息（需要 DingId 与 AgentId，留待后续 P5 补齐 SysUser.DingId 字段）。
+/// 若配置了 Secret 则按钉钉官方规范加签发送。
+/// </summary>
+public class DingTalkNotifyPusher : INotifyPusher, ITransient
+{
+    public string Channel => "DingTalk";
+
+    private static readonly HttpClient _httpClient = new() { Timeout = TimeSpan.FromSeconds(5) };
+
+    public bool IsEnabled(NotifyChannelConfig cfg) =>
+        cfg?.DingTalk == true && !string.IsNullOrWhiteSpace(cfg.DingTalkWebhookUrl);
+
+    public async Task<FlowNotifyPushResult> PushAsync(List<long> userIds, FlowNotification notification)
+    {
+        var cfg = App.GetConfig<NotifyChannelConfig>("ApprovalFlow:Notify");
+        var url = cfg?.DingTalkWebhookUrl;
+        if (string.IsNullOrWhiteSpace(url)) return FlowNotifyPushResult.Ok(0);
+
+        if (!string.IsNullOrWhiteSpace(cfg.DingTalkSecret))
+        {
+            var ts = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
+            var stringToSign = $"{ts}\n{cfg.DingTalkSecret}";
+            using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(cfg.DingTalkSecret));
+            var sign = Uri.EscapeDataString(
+                Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(stringToSign))));
+            url += $"&timestamp={ts}&sign={sign}";
+        }
+
+        var content = $"【{notification.Title}】\n{notification.Content}\n实例: {notification.InstanceId}";
+        var payload = new { msgtype = "text", text = new { content } };
+
+        try
+        {
+            var resp = await _httpClient.PostAsJsonAsync(url, payload);
+            var body = await resp.Content.ReadAsStringAsync();
+            if (!resp.IsSuccessStatusCode)
+                return FlowNotifyPushResult.Fail($"HTTP {(int)resp.StatusCode}: {body}");
+            if (body.Contains("\"errcode\":0") || body.Contains("errcode\": 0"))
+                return FlowNotifyPushResult.Ok(userIds.Count);
+            return FlowNotifyPushResult.Fail($"DingTalk resp: {body}");
+        }
+        catch (Exception ex)
+        {
+            return FlowNotifyPushResult.Fail(ex.Message);
+        }
+    }
+}

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowNotify/Pushers/EmailNotifyPusher.cs

@@ -0,0 +1,64 @@
+using Admin.NET.Core.Service;
+
+namespace Admin.NET.Plugin.ApprovalFlow.Service;
+
+/// <summary>
+/// 邮件推送（P4-16）
+/// 复用 Admin.NET.Core 的 SysEmailService.SendEmail(content, title, toEmail)，按目标用户 Email 逐个发送。
+/// </summary>
+public class EmailNotifyPusher : INotifyPusher, ITransient
+{
+    public string Channel => "Email";
+
+    private readonly SysEmailService _emailService;
+    private readonly SqlSugarRepository<SysUser> _userRep;
+
+    public EmailNotifyPusher(SysEmailService emailService, SqlSugarRepository<SysUser> userRep)
+    {
+        _emailService = emailService;
+        _userRep = userRep;
+    }
+
+    public bool IsEnabled(NotifyChannelConfig cfg) => cfg?.Email == true;
+
+    public async Task<FlowNotifyPushResult> PushAsync(List<long> userIds, FlowNotification notification)
+    {
+        if (userIds.Count == 0) return FlowNotifyPushResult.Ok(0);
+
+        var users = await _userRep.AsQueryable()
+            .Where(u => userIds.Contains(u.Id) && !string.IsNullOrEmpty(u.Email))
+            .Select(u => new { u.Id, u.Email, u.RealName })
+            .ToListAsync();
+
+        if (users.Count == 0) return FlowNotifyPushResult.Ok(0);
+
+        var html = $"<p>{System.Net.WebUtility.HtmlEncode(notification.Content)}</p>" +
+                   $"<hr><p style='color:#888;font-size:12px'>该邮件由系统自动发送，请勿直接回复。实例 Id：{notification.InstanceId}</p>";
+
+        var errors = new List<string>();
+        var successCount = 0;
+        foreach (var user in users)
+        {
+            try
+            {
+                await _emailService.SendEmail(html, notification.Title, user.Email);
+                successCount++;
+            }
+            catch (Exception ex)
+            {
+                errors.Add($"[{user.Id}]{ex.Message}");
+            }
+        }
+
+        if (successCount > 0 && errors.Count == 0)
+            return FlowNotifyPushResult.Ok(successCount);
+        if (successCount > 0)
+            return new FlowNotifyPushResult
+            {
+                Success = true,
+                ActualTargetCount = successCount,
+                ErrorMessage = $"部分失败: {string.Join("; ", errors)}"
+            };
+        return FlowNotifyPushResult.Fail(string.Join("; ", errors));
+    }
+}

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowNotify/Pushers/SignalRNotifyPusher.cs

@@ -0,0 +1,53 @@
+using Admin.NET.Core.Service;
+using Microsoft.AspNetCore.SignalR;
+
+namespace Admin.NET.Plugin.ApprovalFlow.Service;
+
+/// <summary>
+/// SignalR 站内实时推送（P4-16 - 已有实现重构为独立 Pusher）
+/// </summary>
+public class SignalRNotifyPusher : INotifyPusher, ITransient
+{
+    public string Channel => "SignalR";
+
+    private readonly IHubContext<OnlineUserHub, IOnlineUserHub> _hubContext;
+    private readonly SysCacheService _cacheService;
+
+    public SignalRNotifyPusher(
+        IHubContext<OnlineUserHub, IOnlineUserHub> hubContext,
+        SysCacheService cacheService)
+    {
+        _hubContext = hubContext;
+        _cacheService = cacheService;
+    }
+
+    public bool IsEnabled(NotifyChannelConfig cfg) => cfg?.SignalR != false;
+
+    public async Task<FlowNotifyPushResult> PushAsync(List<long> userIds, FlowNotification notification)
+    {
+        try
+        {
+            var onlineUsers = _cacheService.HashGetAll<SysOnlineUser>(CacheConst.KeyUserOnline);
+            var connectionIds = onlineUsers
+                .Where(u => userIds.Contains(u.Value.UserId))
+                .Select(u => u.Value.ConnectionId)
+                .ToList();
+
+            if (connectionIds.Count == 0)
+                return FlowNotifyPushResult.Ok(0);
+
+            await _hubContext.Clients.Clients(connectionIds).ReceiveMessage(new
+            {
+                title = notification.Title,
+                message = notification.Content,
+                type = notification.Type.ToString(),
+                instanceId = notification.InstanceId,
+            });
+            return FlowNotifyPushResult.Ok(connectionIds.Count);
+        }
+        catch (Exception ex)
+        {
+            return FlowNotifyPushResult.Fail(ex.Message);
+        }
+    }
+}

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowNotify/Pushers/SmsNotifyPusher.cs

@@ -0,0 +1,68 @@
+using Admin.NET.Core.Service;
+
+namespace Admin.NET.Plugin.ApprovalFlow.Service;
+
+/// <summary>
+/// 短信推送（P4-16）
+/// 由于 Admin.NET 内置的 SysSmsService.SendSms 依赖运营商预注册模板（阿里云/腾讯云/自定义），
+/// 动态内容不可塞入；本渠道作用限于通知触达（类似"您有新审批待办，请登录系统处理"），
+/// 依赖 NotifyChannelConfig.SmsTemplateId 对应的模板在运营商侧已发布。
+/// 未配置 SmsTemplateId / 用户无手机号时静默跳过。
+/// </summary>
+public class SmsNotifyPusher : INotifyPusher, ITransient
+{
+    public string Channel => "Sms";
+
+    private readonly SysSmsService _smsService;
+    private readonly SqlSugarRepository<SysUser> _userRep;
+
+    public SmsNotifyPusher(SysSmsService smsService, SqlSugarRepository<SysUser> userRep)
+    {
+        _smsService = smsService;
+        _userRep = userRep;
+    }
+
+    public bool IsEnabled(NotifyChannelConfig cfg) => cfg?.Sms == true && !string.IsNullOrWhiteSpace(cfg.SmsTemplateId);
+
+    public async Task<FlowNotifyPushResult> PushAsync(List<long> userIds, FlowNotification notification)
+    {
+        if (userIds.Count == 0) return FlowNotifyPushResult.Ok(0);
+
+        var cfg = App.GetConfig<NotifyChannelConfig>("ApprovalFlow:Notify");
+        var tplId = cfg?.SmsTemplateId;
+        if (string.IsNullOrWhiteSpace(tplId)) return FlowNotifyPushResult.Ok(0);
+
+        var users = await _userRep.AsQueryable()
+            .Where(u => userIds.Contains(u.Id) && !string.IsNullOrEmpty(u.Phone))
+            .Select(u => new { u.Id, u.Phone })
+            .ToListAsync();
+
+        if (users.Count == 0) return FlowNotifyPushResult.Ok(0);
+
+        var errors = new List<string>();
+        var successCount = 0;
+        foreach (var user in users)
+        {
+            try
+            {
+                await _smsService.SendSms(user.Phone, tplId);
+                successCount++;
+            }
+            catch (Exception ex)
+            {
+                errors.Add($"[{user.Id}]{ex.Message}");
+            }
+        }
+
+        if (successCount > 0 && errors.Count == 0)
+            return FlowNotifyPushResult.Ok(successCount);
+        if (successCount > 0)
+            return new FlowNotifyPushResult
+            {
+                Success = true,
+                ActualTargetCount = successCount,
+                ErrorMessage = $"部分失败: {string.Join("; ", errors)}"
+            };
+        return FlowNotifyPushResult.Fail(string.Join("; ", errors));
+    }
+}

server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowNotify/Pushers/WorkWeixinNotifyPusher.cs

@@ -0,0 +1,44 @@
+using System.Net.Http;
+using System.Net.Http.Json;
+
+namespace Admin.NET.Plugin.ApprovalFlow.Service;
+
+/// <summary>
+/// 企业微信推送（P4-16 - 首版 Webhook 机制）
+/// 通过配置的群机器人 Webhook URL（含 key）推送文本消息。
+/// 不做企微应用消息（需要 WeixinId 与 AgentId，留待后续 P5 补齐 SysUser.WeixinId 字段）。
+/// </summary>
+public class WorkWeixinNotifyPusher : INotifyPusher, ITransient
+{
+    public string Channel => "WorkWeixin";
+
+    private static readonly HttpClient _httpClient = new() { Timeout = TimeSpan.FromSeconds(5) };
+
+    public bool IsEnabled(NotifyChannelConfig cfg) =>
+        cfg?.WorkWeixin == true && !string.IsNullOrWhiteSpace(cfg.WorkWeixinWebhookUrl);
+
+    public async Task<FlowNotifyPushResult> PushAsync(List<long> userIds, FlowNotification notification)
+    {
+        var cfg = App.GetConfig<NotifyChannelConfig>("ApprovalFlow:Notify");
+        var url = cfg?.WorkWeixinWebhookUrl;
+        if (string.IsNullOrWhiteSpace(url)) return FlowNotifyPushResult.Ok(0);
+
+        var content = $"【{notification.Title}】\n{notification.Content}\n实例: {notification.InstanceId}";
+        var payload = new { msgtype = "text", text = new { content } };
+
+        try
+        {
+            var resp = await _httpClient.PostAsJsonAsync(url, payload);
+            var body = await resp.Content.ReadAsStringAsync();
+            if (!resp.IsSuccessStatusCode)
+                return FlowNotifyPushResult.Fail($"HTTP {(int)resp.StatusCode}: {body}");
+            if (body.Contains("\"errcode\":0") || body.Contains("errcode\": 0"))
+                return FlowNotifyPushResult.Ok(userIds.Count);
+            return FlowNotifyPushResult.Fail($"WorkWeixin resp: {body}");
+        }
+        catch (Exception ex)
+        {
+            return FlowNotifyPushResult.Fail(ex.Message);
+        }
+    }
+}