Frappe MCP Server

🚀 Frappe 框架用戶指南

本指南將幫助您瞭解如何安裝、配置和使用 Frappe 框架，同時提供一些最佳實踐，助您高效開發和維護 Web 應用程序。

🚀 快速開始

安裝與配置

安裝步驟

1. 下載安裝包：從 Frappe 官方網站 下載適用於您操作系統的最新版本的安裝包。
2. 環境準備：
   • 確保您的系統已安裝 Python 3.7 或更高版本。
   • 安裝 PostgreSQL 數據庫，確保其版本為 10 或更高。
3. 安裝腳本執行：運行下載的安裝包中的 setup.py 腳本。根據提示完成安裝過程。
4. 初始化配置：
   • 執行 frappe init 命令創建新項目。
   • 按照提示選擇所需的應用模塊並完成初始化設置。
5. 啟動服務：使用命令 python3 -m frappe serve 啟動 Frappe 服務，默認端口為 8000。

環境變量配置

• FRAPPE_SITE_URL：設置您的 Frappe 站點 URL，例如 http://localhost:8000。
• FRAPPE_SECRET_KEY：用於 API 調用的密鑰生成，默認為隨機字符串。
• DATABASE_URI：數據庫連接 URI 格式為 postgresql://用戶名:密碼@主機/數據庫名。

✨ 主要特性

Doctype 管理

創建與編輯文檔類型

1. 創建新的 Doctype：
   • 在 Frappe 的 doc 目錄下新建一個 JSON 文件，命名為 doctype_name.json。
   • 定義字段結構和驗證規則。
2. 自定義 Doctype 表單：
   • 使用 HTML 和 JavaScript 創建表單界面，保存為 doctype_name.html。
   • 在 doctype_name.js 中添加事件監聽器和自定義函數。
3. 啟用與禁用文檔類型：
   • 進入 Frappe 的系統設置，找到 Doctype 管理模塊，選擇所需操作。

文檔類型示例

# 示例文檔類型結構
{
  "doctype": "Customer",
  "fields": [
    {"label": "客戶名稱", "fieldname": "customer_name", "type": "Data"},
    {"label": "客戶類型", "fieldname": "customer_type", "type": "Select", "options": ["Individual", "Company"]}
  ],
  "validation": {
    "required_fields": ["customer_name"],
    "unique": ["customer_email"]
  }
}

數據庫交互

查詢數據

1. 基本查詢：
   • 使用 frappe.get_all 獲取記錄列表，支持過濾和排序。

   customers = frappe.get_all('Customer', filters={'customer_type': 'Individual'}, fields=['name', 'customer_name'])
   

2. 插入數據：
   • 調用 frappe.insert 方法添加新文檔。

   new_customer = {
     "doctype": "Customer",
     "customer_name": "John Doe",
     "customer_type": "Individual"
   }
   frappe.insert(new_customer)
   

3. 更新數據：
   • 使用 frappe.update 方法修改現有記錄。

   frappe.update('Customer', 'CUST-00001', {'email_id': 'john@example.com'})
   

4. 刪除數據：
   • 調用 frappe.delete 方法刪除指定文檔。

   frappe.delete('Customer', 'CUST-00001')
   

表單驗證與事件

自定義表單驗證

// 示例驗證函數
frappe.add_events("Customer", {
  "on_submit": function(doc) {
    if (!doc.customer_name) {
      throw new frappe.ValidationError("請輸入客戶名稱");
    }
  }
});

📦 安裝指南

安裝步驟

1. 下載安裝包：從 Frappe 官方網站 下載適用於您操作系統的最新版本的安裝包。
2. 環境準備：
   • 確保您的系統已安裝 Python 3.7 或更高版本。
   • 安裝 PostgreSQL 數據庫，確保其版本為 10 或更高。
3. 安裝腳本執行：運行下載的安裝包中的 setup.py 腳本。根據提示完成安裝過程。
4. 初始化配置：
   • 執行 frappe init 命令創建新項目。
   • 按照提示選擇所需的應用模塊並完成初始化設置。
5. 啟動服務：使用命令 python3 -m frappe serve 啟動 Frappe 服務，默認端口為 8000。

環境變量配置

• FRAPPE_SITE_URL：設置您的 Frappe 站點 URL，例如 http://localhost:8000。
• FRAPPE_SECRET_KEY：用於 API 調用的密鑰生成，默認為隨機字符串。
• DATABASE_URI：數據庫連接 URI 格式為 postgresql://用戶名:密碼@主機/數據庫名。

💻 使用示例

基礎用法

# 示例文檔類型結構
{
  "doctype": "Customer",
  "fields": [
    {"label": "客戶名稱", "fieldname": "customer_name", "type": "Data"},
    {"label": "客戶類型", "fieldname": "customer_type", "type": "Select", "options": ["Individual", "Company"]}
  ],
  "validation": {
    "required_fields": ["customer_name"],
    "unique": ["customer_email"]
  }
}

高級用法

# 高級查詢示例
customers = frappe.get_all('Customer', filters={'customer_type': 'Individual'}, fields=['name', 'customer_name'], order_by='customer_name')

📚 詳細文檔

開發與進階使用

插件開發指南

1. 創建插件結構：
   • 在項目根目錄下新建 plugins 文件夾。
   • 創建插件主文件 plugin_name.js 和配置文件 plugin_name.json。
2. 註冊自定義事件：

   frappe.plugins.register('my_plugin', {
     onReady: function() {
       console.log("插件已加載");
     }
   });
   

3. 擴展文檔類型：
   • 在 doctype_name.js 中添加自定義方法和事件監聽器。

API 使用說明

1. 獲取訪問令牌：

   curl --user admin:admin_pass http://localhost:8000/api/method/frappe.auth.get_token
   

2. 調用 REST API：

   curl -X GET "http://localhost:8000/api/resource/doctype/Customer"
   

3. 處理文件上傳：

   curl -F file=@/path/to/image.jpg "http://localhost:8000/api/method/frappe.core.doctype.file_manager.upload_file"
   

最佳實踐

性能優化

1. 數據庫索引優化：
   • 在常用查詢字段上創建索引，提高查詢效率。

   CREATE INDEX idx_customer_name ON Customer(customer_name);
   

2. 緩存機制應用：
   • 使用 frappe.cache 模塊緩存頻繁訪問的數據，減少數據庫負載。
3. 異步任務處理：
   • 利用 Celery 等工具實現任務隊列，提升系統響應速度。

安全注意事項

1. 權限控制：
   • 配置合適的角色和權限，確保最小化用戶權限。

   frappe.add_perm("Customer", "Sales User", "read");
   

2. 日誌記錄：
   • 啟用詳細日誌記錄，監控系統行為並及時發現異常。
3. 定期安全審計：
   • 定期檢查系統漏洞，更新組件至最新版本，確保系統安全。

通過遵循這些指南和最佳實踐，您可以高效地使用 Frappe 框架開發和維護您的 Web 應用程序。