frappe-enterprise-patterns

Frappe エンタープライズパターン

本番環境に対応したエンタープライズアプリケーションを構築するためのアーキテクチャパターンです。

使用する場面

• CRM、ヘルプデスク、HRMS など、複数のエンティティを扱うシステムを構築する場合
• SLA に基づくワークフローを設計する場合
• 割り当てとキュー管理を実装する場合
• 監査証跡とアクティビティログを構築する場合
• 外部システム（メール、電話、CRM）と連携する場合

必要な入力

• システムの種類（CRM／ヘルプデスク／カスタム）
• 中核となるエンティティとその関係
• 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／ヘルプデスクの UI パターンに従う：CRUD アプリでは、公式 Frappe アプリのアプリシェル、ナビゲーション、リストビュー、フォームのパターンを説明している frappe-ui-patterns スキルに従ってください。これにはサイドバーレイアウト、クイックフィルター、カンバンビュー、詳細パネルが含まれます。
• フロントエンドには 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 を使用します