frappe-enterprise-patterns

Frappe 企业级模式

用于构建生产级企业应用的架构模式。

适用场景

• 构建 CRM、Helpdesk、HRMS 或类似的多实体系统
• 设计 SLA 驱动的工作流
• 实现分配和队列管理
• 构建审计跟踪和活动日志
• 与外部系统集成（电子邮件、电话、CRM）

所需输入

• 系统类型（CRM/Helpdesk/自定义）
• 核心实体及其关系
• SLA 要求
• 工作流状态和转换
• 集成点

流程

0) 设计数据模型

从清晰、规范化的 DocType 开始：

Ticket (parent)
├── customer (Link: Customer)
├── assigned_to (Link: User)
├── status (Select: Open, In Progress, Resolved, Closed)
├── priority (Link: Priority)
├── sla (Link: SLA)
├── activities (Table: Ticket Activity)
└── response_by, resolution_by (Datetime)

关键模式：

• 使用 Link 字段建立关系
• 使用子表记录活动、时间线和明细项
• 当目标 DocType 不固定时，使用 Dynamic Link

1) 实现状态机

选项 A：Workflow DocType

• 创建包含状态和基于角色的转换的 Workflow
• 将其关联到你的 DocType

选项 B：用于提交流程的 docstatus

docstatus	含义
0	草稿
1	已提交
2	已取消

选项 C：使用自定义状态字段并进行验证

def validate(self):
    allowed = self.get_allowed_transitions()
    if self.status not in allowed:
        frappe.throw(f"Cannot transition to {self.status}")

2) 设置权限

行级筛选：

• 使用 User Permissions 按实体进行限制
• 与 Role Permissions 结合使用

始终在 RPC 方法中重新检查：

@frappe.whitelist()
def update_ticket(name, status):
    doc = frappe.get_doc("Ticket", name)
    if not frappe.has_permission("Ticket", "write", doc):
        frappe.throw("Not permitted", frappe.PermissionError)
    doc.status = status
    doc.save()

3) 构建活动跟踪记录

使用 Activity Log 或自定义子表跟踪变更：

def on_update(self):
    if self.has_value_changed("status"):
        self.append("activities", {
            "action": "Status Change",
            "old_value": self._doc_before_save.status,
            "new_value": self.status,
            "timestamp": frappe.utils.now()
        })

4) 实现 SLA

SLA DocType：

SLA
├── entity_type (Link: DocType)
├── response_time (Duration)
├── resolution_time (Duration)
└── escalation_rules (Table: Escalation Rule)

创建时应用 SLA：

def after_insert(self):
    sla = get_applicable_sla(self)
    if sla:
        self.response_by = add_to_date(self.creation, hours=sla.response_time)
        self.resolution_by = add_to_date(self.creation, hours=sla.resolution_time)
        self.db_update()

监控超时（计划任务）：

def check_sla_breaches():
    tickets = frappe.get_all("Ticket", 
        filters={"status": ["not in", ["Resolved", "Closed"]]},
        fields=["name", "resolution_by"]
    )
    for t in tickets:
        if frappe.utils.now_datetime() > t.resolution_by:
            mark_sla_breached(t.name)

5) 分配和队列

轮询分配：

def assign_next_agent(queue):
    agents = frappe.get_all("Queue Member",
        filters={"queue": queue, "available": 1},
        fields=["user", "current_load"],
        order_by="current_load asc"
    )
    if agents:
        return agents[0].user
    return None

用于自动分配的 Assignment Rules DocType。

6) 通知和升级

配置 Notification DocType，用于：

• SLA 即将超时
• 分配变更
• 状态转换
• 客户回复

升级链：

Level 1 (0h): Notify assigned agent
Level 2 (4h): Notify team lead
Level 3 (8h): Notify manager
Level 4 (24h): Notify department head

7) 外部集成

集中放在 integrations/ 模块中：

# my_app/integrations/email_connector.py
def sync_emails():
    # Fetch from Email Account
    # Create Communications
    # Link to Tickets

使用后台作业进行同步：

frappe.enqueue(
    "my_app.integrations.email_connector.sync_emails",
    queue="long",
    timeout=600
)

验证

• 所有角色的工作流转换均可正常运行
• 在 API 层强制执行权限
• 活动日志记录所有变更
• SLA 计算正确
• 通知按预期触发
• 集成同步运行无误

故障模式 / 调试

• 权限绕过：检查 RPC 方法是否有明确的权限检查
• SLA 未应用：确认计划任务正在运行
• 活动未记录：检查 has_value_changed 的用法
• 通知未发送：检查 Notification 规则和电子邮件队列

升级处理

• 复杂的权限模式请参阅 references/advanced-permissions.md
• 队列优化请参阅 references/queue-patterns.md
• UI/UX 模式请参阅 frappe-ui-patterns

参考资料

• references/workflow-patterns.md - 状态机设计
• references/sla-implementation.md - SLA 详情
• references/integration-patterns.md - 外部系统

守则

• 遵循 CRM/Helpdesk UI 模式：对于 CRUD 应用，请遵循 frappe-ui-patterns 技能，其中记录了来自官方 Frappe 应用的应用外壳、导航、列表视图和表单模式。这包括侧边栏布局、快速筛选器、看板视图和详情面板。
• 前端使用 Frappe UI：所有自定义企业前端都必须使用 Frappe UI（Vue 3 + TailwindCSS）——不得使用原生 JS 或 jQuery
• 谨慎设计工作流：在实现前梳理所有状态和转换；考虑回滚路径
• 处理边缘情况：为工作流中的已取消、暂停和异常状态做好规划
• 尽早测试性能：对高数据量 DocType 和复杂查询执行负载测试
• 重型操作使用后台作业：不得让长时间运行的任务阻塞 Web 请求
• 记录关键操作：使用 frappe.log_error() 和活动日志确保可审计性

常见错误

错误	失败原因	修复方法
工作流过于复杂	难以维护，令用户困惑	尽可能保持工作流线性；拆分复杂流程
集成中缺少错误处理	静默失败、数据不一致	使用 try/except 包装外部调用；记录错误；添加重试逻辑
文档更新中的竞态条件	数据损坏	使用 frappe.db.get_value(..., for_update=True) 加锁
SLA 未处理时区	面向全球用户时计算错误	以 UTC 存储和比较；使用 frappe.utils.convert_utc_to_timezone
批量操作未使用队列	超时、内存问题	对大量记录执行操作时使用 frappe.enqueue()
角色名称硬编码	角色变更时失效	使用常量或设置来指定角色名称
自定义 UI 模式	UX 不一致，令用户困惑	研究并遵循 CRM/Helpdesk 应用外壳
前端使用原生 JS/jQuery	增加维护负担，与生态系统不匹配	始终使用基于 Vue 3 的 Frappe UI