frappe-core-notifications

Frappe 通知系统

快速参考

渠道	方法	用例
电子邮件	frappe.sendmail()	完全可控的程序化电子邮件
电子邮件	Notification DocType (Email)	文档事件触发的无代码电子邮件
系统	frappe.publish_realtime()	通过 socket.io 在应用内实时发送提醒
系统	Notification DocType (System)	无代码应用内提醒
短信	Notification DocType (SMS)	文档事件触发的无代码短信
Slack	Notification DocType (Slack)	无代码 Slack webhook 消息
指派	frappe.desk.form.assign_to.add()	将文档指派给用户（创建 ToDo）
ToDo	frappe.get_doc({"doctype": "ToDo", ...})	直接创建任务
评论	doc.add_comment("Comment", text)	在文档时间线上添加评论
标签	doc.add_tag("tag_name")	为文档添加标签以便筛选

---

决策树

What notification mechanism do you need?
│
├─ Email on document event (no code)?
│  └─ Notification DocType → Channel: Email
│
├─ Programmatic email with custom logic?
│  └─ frappe.sendmail() in server script or hook
│
├─ Real-time in-app notification?
│  ├─ No-code → Notification DocType → Channel: System Notification
│  └─ Programmatic → frappe.publish_realtime()
│
├─ SMS on document event?
│  └─ Notification DocType → Channel: SMS (requires SMS Settings)
│
├─ Assign document to user?
│  ├─ No-code → Assignment Rule DocType
│  └─ Programmatic → frappe.desk.form.assign_to.add()
│
├─ Recurring document creation?
│  └─ Auto Repeat DocType
│
└─ Add comment or tag?
   ├─ Comment → doc.add_comment("Comment", text="...")
   └─ Tag → doc.add_tag("tag_name")

---

Notification DocType

Notification DocType 可通过四种渠道实现无代码提醒。

事件触发器

事件	触发时机
New	创建文档时
Save	保存文档时
Submit	提交文档时
Cancel	取消文档时
Value Change	特定字段值发生变化时
Days Before	日期字段值对应日期的前 N 天
Days After	日期字段值对应日期的后 N 天
Method	调用自定义 Python 方法时

条件语法

Condition 字段中始终使用 Python 表达式：

# Status-based
doc.status == "Open"

# Date-based
doc.due_date == nowdate()

# Threshold-based
doc.grand_total > 40000

# Combined
doc.status == "Overdue" and doc.grand_total > 10000

可用上下文：doc、nowdate()、frappe.utils.*。

收件人配置

来源	说明
Document Field	文档上的电子邮件/电话字段
Role	指定角色的所有用户
Custom	硬编码的电子邮件地址
All Assignees	指派给该文档的所有用户
Condition	用于筛选收件人的 Jinja 表达式

Jinja 消息模板

<h3>Order Overdue</h3>
<p>Transaction {{ doc.name }} has exceeded its due date.</p>

{% if comments %}
Last comment: {{ comments[-1].comment }} by {{ comments[-1].by }}
{% endif %}

<ul>
  <li>Customer: {{ doc.customer }}</li>
  <li>Amount: {{ doc.grand_total }}</li>
</ul>

模板变量：{{ doc }}、{{ doc.fieldname }}、{{ comments }}、{{ nowdate() }}。

附加打印件

将 Attach Print 设为启用，以附加文档的 PDF。选择 Print Format 以使用自定义布局。

---

frappe.sendmail()：程序化电子邮件

frappe.sendmail(
    recipients=["[email protected]"],       # list of email addresses
    subject="Invoice Due",                  # email subject
    message="<p>Your invoice is due.</p>",  # HTML body
    template="invoice_reminder",            # Jinja template name (optional)
    args={"customer": "ACME"},              # template context variables
    attachments=[{"fname": "inv.pdf", "fcontent": pdf_bytes}],
    reference_doctype="Sales Invoice",      # links email to document
    reference_name="SINV-00001",
    delayed=True,                           # queue via Email Queue (default)
    now=False,                              # True = send immediately, skip queue
    sender="[email protected]",           # override sender
    cc=["[email protected]"],
    bcc=["[email protected]"],
    reply_to="[email protected]",
    expose_recipients="header",             # show recipients in email header
)

规则：

• 如果电子邮件与文档相关，始终设置 reference_doctype 和 reference_name，这样电子邮件就会显示在文档时间线上。
• 生产环境中切勿设置 now=True，否则会阻塞请求。使用 delayed=True（默认值），通过 Email Queue 将邮件加入队列。
• 调用 frappe.sendmail 前，始终确保已配置启用“Enable Outgoing”的 Email Account。

Email Queue

电子邮件会加入 Email Queue DocType 的队列，并由调度程序发送。检查队列状态：

# Check pending emails
pending = frappe.get_all("Email Queue", filters={"status": "Not Sent"}, limit=10)

---

frappe.publish_realtime()：系统通知

frappe.publish_realtime(
    event="msgprint",                      # event name
    message={"msg": "Task completed!"},    # dict payload
    user="[email protected]",               # target specific user
    doctype="Sales Invoice",               # broadcast to doctype room
    docname="SINV-00001",                  # broadcast to document room
    after_commit=True,                     # emit after transaction commits
)

房间类型

房间	受众
user:{email}	单个用户（设置 user=）
doctype:{dt}	正在查看该列表的所有用户
doc:{dt}/{dn}	正在查看该文档的所有用户
all	站点范围内的所有 Desk 用户
task_progress:{id}	后台任务进度

如果在数据库事务中发布事件，始终设置 after_commit=True；否则事件会在数据提交前触发，客户端可能会读取到过期数据。

---

指派规则

根据条件自动将文档指派给用户（无需编写代码）。

配置字段

字段	用途
Document Type	触发规则的 DocType
Assign Condition	Python 表达式（与 Notification 相同）
Assignment Days	限定为特定星期几
Users	要指派给的用户列表
Assignment Rule	轮询、负载均衡或基于字段

程序化分配

from frappe.desk.form.assign_to import add, remove, close, clear

# Assign
add({
    "assign_to": ["[email protected]"],
    "doctype": "Task",
    "name": "TASK-00001",
    "description": "Please review this task",
    "priority": "High",
    "date": "2025-12-31",
})

# Remove assignment (cancels ToDo)
remove("Task", "TASK-00001", "[email protected]")

# Close assignment (only assignee can close)
close("Task", "TASK-00001", "[email protected]")

# Clear all assignments
clear("Task", "TASK-00001")

切勿以被分配人以外的用户身份调用 close()，否则会引发权限错误。

---

自动重复

按计划定期创建文档副本。

字段	用途
参考 DocType	要重复的 DocType
参考文档	要复制的源文档
频率	每日、每周、每月、每季度、每半年、每年
开始日期 / 结束日期	计划时间范围
通过电子邮件通知	创建时发送通知

务必为自动重复设置结束日期——没有结束日期的计划会无限期创建文档，且难以调试。

---

ToDo API

# Create ToDo directly
todo = frappe.get_doc({
    "doctype": "ToDo",
    "allocated_to": "[email protected]",
    "assigned_by": frappe.session.user,
    "description": "Review the quarterly report",
    "priority": "Medium",
    "date": "2025-12-31",
    "status": "Open",
    "reference_type": "Task",
    "reference_name": "TASK-00001",
}).insert(ignore_permissions=True)

ToDo 状态：Open、Closed、Cancelled。

---

评论和标签

# Add comment (appears in document timeline)
doc.add_comment("Comment", text="Reviewed and approved")
doc.add_comment("Edit", "Values changed")

# Add/get tags
doc.add_tag("urgent")
tags = doc.get_tags()  # returns list of tag strings

---

版本差异

功能	v14	v15	v16
Notification DocType	全部 4 个渠道	全部 4 个渠道	全部 4 个渠道
分钟前/后	不可用	可用	可用
frappe.publish_realtime	可用	可用	可用
分配规则	可用	可用	可用

---

另请参阅

• references/email-system.md — Email Account、Email Queue、Communication 关联、Newsletter、Notification Log
• references/examples.md — 完整的通知工作流示例
• references/anti-patterns.md — 常见错误及修复方法
• references/api-reference.md — 完整的 API 签名
• frappe-core-database — 通知中引用的数据库操作
• frappe-core-permissions — 通知访问的权限模型