frappe-enterprise-patterns（冰沙企业模式）

Frappe Enterprise Patterns

Architectural patterns for building production-grade enterprise applications.

When to use

• Building CRM, Helpdesk, HRMS, or similar multi-entity systems
• Designing SLA-driven workflows
• Implementing assignment and queue management
• Building audit trails and activity logs
• Integrating with external systems (email, telephony, CRM)

Inputs required

• System type (CRM/Helpdesk/custom)
• Core entities and relationships
• SLA requirements
• Workflow states and transitions
• Integration points

Procedure

0) Design data model

Start with clear, normalized DocTypes:

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)

Key patterns:

• Use Link fields for relationships
• Use child tables for activities, timelines, line items
• Use Dynamic Link when target DocType varies

1) Implement state machine

Option A: Workflow DocType

• Create Workflow with states and role-based transitions
• Link to your DocType

Option B: docstatus for submission flow

Option C: Custom status field with validation

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

2) Set up permissions

Row-level filtering:

• Use User Permissions to restrict by entity
• Combine with Role Permissions

Always re-check in RPC methods:

@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) Build activity trail

Track changes using Activity Log or custom child table:

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) Implement SLA

SLA DocType:

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

Apply SLA on creation:

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()

Monitor breaches (scheduled job):

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) Assignment and queues

Round-robin assignment:

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 for automatic assignment.

6) Notifications and escalations

Configure Notification DocType for:

• SLA approaching breach
• Assignment changes
• Status transitions
• Customer replies

Escalation chain:

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

7) External integrations

Centralize in integrations/ module:

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

Use background jobs for sync:

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

Verification

• Workflow transitions work for all roles
• Permissions enforced at API level
• Activity log captures all changes
• SLA calculation correct
• Notifications fire appropriately
• Integration sync runs without errors

Failure modes / debugging

• Permission bypass: Check RPC methods have explicit permission checks
• SLA not applying: Verify scheduled job is running
• Activities not logging: Check has_value_changed usage
• Notifications not sending: Check Notification rules and email queue

Escalation

• For complex permission patterns, see references/advanced-permissions.md
• For queue optimization, see references/queue-patterns.md
• For UI/UX patterns → frappe-ui-patterns

References

• references/workflow-patterns.md - State machine design
• references/sla-implementation.md - SLA details
• references/integration-patterns.md - External systems

Guardrails

• Follow CRM/Helpdesk UI patterns: For CRUD apps, follow frappe-ui-patterns skill which documents app shell, navigation, list views, and form patterns from official Frappe apps. This includes sidebar layouts, quick filters, Kanban views, and detail panels.
• Use Frappe UI for frontends: All custom enterprise frontends must use Frappe UI (Vue 3 + TailwindCSS) — never vanilla JS or jQuery
• Design workflows carefully: Map all states and transitions before implementation; consider rollback paths
• Handle edge cases: Plan for cancelled, on-hold, and exception states in workflows
• Test performance early: Run load tests for high-volume DocTypes and complex queries
• Use background jobs for heavy operations: Never block web requests with long-running tasks
• Log critical operations: Use frappe.log_error() and activity logs for auditability

Common Mistakes