sbknext/forge-frappe-skill

frappe-app-development

Scaffold, architect, and build production-grade custom Frappe/ERPNext apps.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/sbknext/forge-frappe-skill --skill frappe-app-development

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Frappe App Development

Scaffold and build production-grade custom Frappe / ERPNext applications with correct separation of concerns and tested patterns.

When to use

  • Creating a new custom Frappe app from scratch (bench new-app)
  • Designing DocType structure (fields, child tables, naming series)
  • Writing hooks.py — doc_events, scheduler_events, override_whitelisted_methods
  • Implementing background jobs via frappe.enqueue
  • Building REST APIs with @frappe.whitelist()
  • Service-layer pattern: thin controllers, fat service modules
  • Adding caching, logging, error handling cross-cutting utilities
  • Permission checks with frappe.has_permission() / frappe.only_for()
  • Writing tests with frappe.tests.utils.FrappeTestCase
  • Deploying and migrating (bench migrate, bench build)

Inputs required

  • App name and purpose
  • Target Frappe version (v14, v15, v16+)
  • Module structure (which DocTypes, which APIs)
  • Site name

Core patterns

1. App scaffold

bash
bench new-app <app_name>
bench --site <site> install-app <app_name>

2. DocType conventions (Frappe way)

  • Use frappe.get_doc() / frappe.get_list() — never raw SQL unless parameterized
  • frappe.db.get_value() for single field reads
  • frappe.db.sql() ONLY with %s params, never f-strings
  • Naming: PascalCase for DocTypes, snake_case for Python, camelCase for JS

3. hooks.py — golden patterns

python
# doc_events — thin controller, delegate to service
doc_events = {
    "Sales Order": {
        "on_submit": "myapp.services.order_sync.on_submit",
        "on_cancel": "myapp.services.order_sync.on_cancel",
    }
}

# Scheduler events
scheduler_events = {
    "daily": ["myapp.tasks.daily_sync.run"],
    "cron": {
        "0 */2 * * *": ["myapp.tasks.monitor.run"],  # every 2h
    }
}

# Override whitelisted methods (use sparingly)
override_whitelisted_methods = {
    "frappe.client.get_list": "myapp.overrides.client.get_list"
}

4. Service layer pattern

myapp/
  myapp/
    services/
      order_sync.py   ← business logic (no frappe.form refs)
      external_api.py ← external API wrapper
    api/
      v1.py           ← @frappe.whitelist() endpoints (thin)
    utils/
      logger.py       ← frappe.logger() wrapper
      cache.py        ← frappe.cache() helpers
    tasks/
      daily_sync.py   ← scheduler entry points

5. Background jobs

python
# Enqueue (fire and forget)
frappe.enqueue(
    "myapp.services.order_sync.sync_order",
    order_name=doc.name,
    queue="long",       # short / default / long
    timeout=1800,
    job_id=f"sync_order_{doc.name}",  # dedup key
    is_async=True,
)

# Inside the job — always log, never raise silently
def sync_order(order_name):
    logger = frappe.logger("order_sync", allow_site=True)
    try:
        doc = frappe.get_doc("Sales Order", order_name)
        # ... work ...
        frappe.db.commit()
    except Exception:
        logger.error(frappe.get_traceback())
        raise

6. Whitelisted REST APIs

python
import frappe

@frappe.whitelist()
def get_order_status(order_name: str) -> dict:
    frappe.has_permission("Sales Order", "read", order_name, throw=True)
    doc = frappe.get_doc("Sales Order", order_name)
    return {
        "name": doc.name,
        "status": doc.status,
        "customer": doc.customer,
    }

7. Caching

python
# Per-site, TTL in seconds
cache_key = f"myapp:config:{frappe.local.site}"
config = frappe.cache().get_value(cache_key)
if not config:
    config = frappe.get_single("My App Settings").as_dict()
    frappe.cache().set_value(cache_key, config, expires_in_sec=300)

8. Permission pattern

python
# Role check
frappe.only_for(["System Manager", "My App Manager"])

# Document-level
frappe.has_permission("Sales Order", "write", order_name, throw=True)

9. Tests

python
import frappe
from frappe.tests.utils import FrappeTestCase

class TestOrderSync(FrappeTestCase):
    def test_sync_sets_status(self):
        doc = frappe.get_doc({
            "doctype": "Sales Order",
            "customer": "Test Customer",
            # ...
        }).insert()
        result = sync_order(doc.name)
        self.assertEqual(result["status"], "Synced")

10. Migrations (safe)

bash
# Run migrate after every schema change
bench --site <site> migrate
bench build --app <app_name>

11. Controller hooks and v15 type annotations

Frappe auto-generates Python type stubs in controllers (v15+). Enable with:

python
# hooks.py
export_python_type_annotations = True

The generated block between # begin: auto-generated types / # end: auto-generated types is overwritten on DocType update — put custom logic outside it.

Key lifecycle hooks: before_validate (set defaults), validate (throw to block save), before_save, on_update, on_submit, on_cancel, on_change (also fires on db_set — keep idempotent).

doc.insert() / doc.save() escape hatches (use sparingly, never in user-facing paths without audit):

python
doc.insert(ignore_permissions=True, ignore_links=True, ignore_mandatory=True)
doc.save(ignore_permissions=True, ignore_version=True)
doc.db_set("status", "Closed")  # skips validate/hooks — prefer doc.save()

Controller hooks & v15 type annotations

Put lifecycle logic in the DocType controller (before_save, validate, on_submit, etc.) — see the full hook matrix in the Controllers docs. Prefer controller methods over inline hooks.py doc_events when logic belongs to one DocType.

v15+ can auto-export Python type annotations in controllers:

python
# hooks.py
export_python_type_annotations = True

Annotations regenerate on DocType update — do not hand-edit the auto-generated block.

Security guardrails (HARD RULES)

  • NEVER frappe.db.sql("... WHERE name = '%s'" % name) — use %s params
  • NEVER disable CSRF (frappe.flags.ignore_csrf = True) in production
  • NEVER store secrets in DocType fields — use site_config.json + frappe.conf.get()
  • ALWAYS validate file uploads (type, size, extension) before save
  • ALWAYS use frappe.only_for() or frappe.has_permission() on sensitive APIs
  • ALWAYS run bench --site <site> migrate after schema changes — never touch the DB directly

Production patterns

  • Use frappe.enqueue with job_id for dedup on high-frequency events
  • Keep app hooks thin — delegate to a service layer that has no frappe.form references
  • Specify --site <site> explicitly in every bench command on multi-site benches
  • Prefer Frappe-native workflow + notification primitives over custom cron hacks

From Frappe docs

  • Controller hooks table (insert/save/submit/cancel columns): https://docs.frappe.io/framework/user/en/basics/doctypes/controllers
  • Document API (insert, save, db_set, queue_action): https://docs.frappe.io/framework/user/en/api/document
  • Tutorial — developer mode + DocType boilerplate: https://docs.frappe.io/framework/user/en/tutorial/create-a-doctype
  • Controller methods tutorial (before_save example): https://docs.frappe.io/framework/user/en/tutorial/controller-methods
같은 저장소의 Skills

더 많은 Skills

모든 Skills
sbknext
커뮤니티

frappe-client-scripting

Customize Frappe desk forms and lists with client scripts — frappe.ui.form.on handlers, field events, setquery link filters, setdfproperty, custom buttons, frappe.call, and list view settings. Use when adding form interactivity, dynamic filters, validation, or buttons in the desk UI. Trigger on: "client script", "frappe.ui.form.on", "form event", "setquery", "custom button", "frappe.call", "list view settings", "curfrm".

1시간 설치 수
1
GitHub Stars
18
업데이트
6월 7일
sbknext
커뮤니티

frappe-database-orm

Query and mutate data in Frappe safely — getdoc/getall/getlist, frappe.db.getvalue/setvalue, parameterized frappe.db.sql, Query Builder (frappe.qb), transactions, bulk ops, and performance. Use when reading or writing data, optimizing slow queries, or avoiding SQL injection. Trigger on: "frappe.db.sql", "frappe.getall", "query builder", "frappe.qb", "bulk update", "N+1", "db transaction", "getvalue setvalue".

1시간 설치 수
1
GitHub Stars
18
업데이트
6월 7일
sbknext
커뮤니티

frappe-report-development

Build Frappe reports — Query Reports (SQL), Script Reports (Python), filters, columns, charts, formatters, and report permissions. Use when creating analytics/listing reports, dashboards, or exportable views in Frappe/ERPNext. Trigger on: "query report", "script report", "Frappe report", "report filters", "report chart", "columns formatter", "report builder".

1시간 설치 수
1
GitHub Stars
18
업데이트
6월 7일
sbknext
커뮤니티

frappe-testing

Write and run tests for Frappe/ERPNext apps — FrappeTestCase, test records, fixtures, mocking, permission tests, running with bench run-tests, and CI. Use when adding test coverage, doing TDD on a DocType or API, or setting up a test pipeline. Trigger on: "Frappe test", "FrappeTestCase", "bench run-tests", "unit test DocType", "test fixtures", "TDD frappe".

1시간 설치 수
1
GitHub Stars
18
업데이트
6월 7일