frappe-doctype-development

Frappe DocType 开发

构建和修改 DocType——Frappe Framework 中核心的数据模型抽象。

适用场景

• 创建新的 DocType（标准、单例、子表、可提交、树形）
• 为现有 DocType 添加或修改字段
• 实现控制器逻辑（validate、before_save、on_submit 等）
• 设置命名规则和自动命名
• 配置权限和工作流
• 构建子表和父子关系

所需输入

• 目标应用和模块路径
• DocType 名称和类型（standard/single/child/submittable/tree）
• 字段定义（名称、类型、选项）
• 各角色所需的权限
• 是否需要工作流

流程

0) 验证环境

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

1) 选择 DocType 类型

类型	用例	关键设置
标准	多条记录	默认
单例	配置/设置（单条记录）	issingle: 1
子表	父表中的行	istable: 1
可提交	草稿→提交→取消工作流	is_submittable: 1
树形	分层数据	is_tree: 1
虚拟	外部数据源	is_virtual: 1

2) 创建 DocType

选项 A：通过 UI 创建（推荐用于新建 DocType）

1. 前往 DocType 列表 → 新建
2. 定义字段、权限和设置
3. 保存（开发者模式下会导出到应用中）

选项 B：通过代码创建

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

3) 定义字段

常见字段模式：

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

所有字段类型请参阅 references/field-types.md。

4) 实现控制器

在 JSON 文件旁创建 <doctype_name>.py：

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) 设置命名规则

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

选项：field:fieldname、naming_series:、hash、format:PREFIX-{####}

6) 配置权限

在 DocType → 权限选项卡中设置：

• 角色 + 读取/写入/创建/删除/提交/取消
• 用于行级筛选的用户权限

7) 添加工作流（如有需要）

创建 Workflow DocType，将其关联到你的 DocType，并设置状态和转换。

验证

• DocType 显示在列表中，且可以创建新记录
• 所有字段都能正确保存
• 控制器钩子正常触发（检查日志）
• 各角色的权限均已生效
• 命名规则能正确生成名称
• 运行：bench --site <site> migrate 成功

故障模式 / 调试

• 找不到 DocType：检查模块路径和应用安装情况
• 控制器未加载：确认类名与 DocType 名称一致（PascalCase）
• 字段未保存：检查 fieldtype 和选项是否兼容
• 权限被拒绝：检查角色权限和用户权限

升级处理

• 复杂权限逻辑请参阅 references/permissions.md
• 子表模式请参阅 references/child-tables.md
• 虚拟 DocType 请参阅 references/virtual-doctypes.md

参考资料

• references/field-types.md - 所有字段类型和选项
• references/controllers.md - 控制器生命周期钩子
• references/child-tables.md - 父子模式
• references/naming.md - 命名模式

注意事项

• 更改架构前检查 developer_mode：只有当站点配置中的 developer_mode = 1 时，DocType 修改才会导出到文件
• 确认命名规则唯一：确保命名规则前缀不会与现有 DocType 冲突
• 单独测试子表：子表有自己的生命周期；与父表集成前，应先单独测试
• 更改后始终运行 migrate：架构更改需要运行 bench --site <site> migrate 才能生效
• 验证 fieldname 命名约定：使用 snake_case，最多 140 个字符，且不得使用保留的 SQL 关键字

常见错误

错误	失败原因	修复方法
必填字段缺少 reqd	用户可以保存不完整的数据	对必须填写的字段设置 reqd: 1
数据的字段类型错误	数据被截断或出现验证错误	根据数据选择匹配的字段类型（例如，金额使用 Currency，而不是 Float）
未运行 bench migrate	数据库未应用架构更改	修改 DocType 后，务必运行 bench --site <site> migrate
Link 依赖存在循环	DocType 创建失败	使用 Dynamic Link 或重新设计关联关系
控制器类名称不匹配	控制器方法不会被调用	类名必须是 DocType 名称的 PascalCase 形式（例如，"Sales Order" 对应 SalesOrder）
关键字段缺少 in_list_view	字段不会显示在列表中	对重要字段设置 in_list_view: 1