frappe-doctype-development（冰沙文档类型开发）

Frappe DocType Development

Build and modify DocTypes—the core data model abstraction in Frappe Framework.

When to use

• Creating new DocTypes (standard, single, child table, submittable, tree)
• Adding or modifying fields on existing DocTypes
• Implementing controller logic (validate, before_save, on_submit, etc.)
• Setting up naming series and auto-naming
• Configuring permissions and workflows
• Building child tables and parent-child relationships

Inputs required

• Target app and module path
• DocType name and type (standard/single/child/submittable/tree)
• Field definitions (name, type, options)
• Permission requirements by role
• Whether workflow is needed

Procedure

0) Verify environment

# Ensure developer mode is enabled
bench --site <site> console
>>> frappe.conf.developer_mode  # Must be True

1) Choose DocType type

2) Create DocType

Option A: Via UI (recommended for new DocTypes)

1. Navigate to DocType List → New
2. Define fields, permissions, settings
3. Save (exports to app in developer mode)

Option B: Via code

# Create DocType JSON in:
# <app>/<module>/doctype/<doctype_name>/<doctype_name>.json

3) Define fields

Common field patterns:

{
  "fieldname": "customer",
  "fieldtype": "Link",
  "label": "Customer",
  "options": "Customer",
  "reqd": 1
}

See references/field-types.md for all field types.

4) Implement controller

Create <doctype_name>.py alongside the JSON:

import frappe
from frappe.model.document import Document

class MyDocType(Document):
    def validate(self):
        # Lightweight validation
        if not self.customer:
            frappe.throw("Customer is required")

    def before_save(self):
        # Pre-save normalization
        self.full_name = f"{self.first_name} {self.last_name}"

    def after_insert(self):
        # Post-create side effects
        frappe.publish_realtime("new_doc", {"name": self.name})

5) Set up naming

{
  "autoname": "naming_series:",
  "fields": [
    {
      "fieldname": "naming_series",
      "fieldtype": "Select",
      "options": "PRJ-.YYYY.-\nPRJ-.YYYY.-.###"
    }
  ]
}

Options: field:fieldname, naming_series:, hash, format:PREFIX-{####}

6) Configure permissions

Set in DocType → Permissions tab:

• Role + Read/Write/Create/Delete/Submit/Cancel
• User permissions for row-level filtering

7) Add workflow (if needed)

Create Workflow DocType linking to your DocType with states and transitions.

Verification

• DocType appears in list and can create new records
• All fields save correctly
• Controller hooks fire (check logs)
• Permissions enforced for each role
• Naming series generates correctly
• Run: bench --site <site> migrate succeeds

Failure modes / debugging

• DocType not found: Check module path and app installation
• Controller not loading: Verify class name matches DocType name (PascalCase)
• Fields not saving: Check fieldtype and options compatibility
• Permission denied: Verify role permissions and User Permissions

Escalation

• For complex permission logic, see references/permissions.md
• For child table patterns, see references/child-tables.md
• For Virtual DocTypes, see references/virtual-doctypes.md

References

• references/field-types.md - All field types and options
• references/controllers.md - Controller lifecycle hooks
• references/child-tables.md - Parent-child patterns
• references/naming.md - Naming patterns

Guardrails

• Check developer_mode before schema changes: DocType modifications only export to files when developer_mode = 1 in site config
• Verify naming series uniqueness: Ensure naming series prefixes don't conflict with existing DocTypes
• Test child tables separately: Child tables have their own lifecycle; test them in isolation before parent integration
• Always run migrate after changes: Schema changes require bench --site <site> migrate to apply
• Validate fieldname conventions: Use snake_case, max 140 chars, no reserved SQL keywords

Common Mistakes