这是用于指导如何在 Frappe/ERPNext 中实现 hooks.py 配置的技能。它不负责精确语法(那由 erpnext-syntax-hooks 处理),而是帮助开发者在多个钩子之间做选型决策,版本兼容 v14/v15/v16,其中 V16 专属特性会单独标注。
主要用途是回答“该用哪种钩子”:需要响应其他应用 DocType 的文档事件时用 doc_events;需要周期性执行任务时用 scheduler_events;需要修改已有 DocType 控制器行为时,V16+ 推荐 extend_doctype_class(多应用可共存),V14/V15 只能用 override_doctype_class(后安装的应用生效);需要改已有 API 端点时用 override_whitelisted_methods;需要自定义权限逻辑时,列表过滤用 permission_query_conditions,文档级用 has_permission;需要在页面加载时向客户端传数据用 extend_bootinfo;在站点间导入导出配置用 fixtures;需要注入 JS/CSS 时按 Desk、Portal 或具体表单分别使用 app_include_js/css、web_include_js/css、doctype_js。
技能内提供决策树,例如区分自有 DocType 与其他应用 DocType、如何选择具体 doc_event(validate、before_insert、after_insert、on_update、on_change、before/on_submit、before/on_cancel、on_trash、before/after_rename)、根据任务时长(5 分钟内与 5 至 25 分钟的 _long 变体,超过 25 分钟需拆分或改用后台任务)选择调度器事件类型(all、hourly、daily、weekly、monthly、cron)。还给出各钩子的处理函数签名与实现流程,例如 doc_events 需在 hooks.py 注册后编写处理模块,再执行 bench --site sitename migrate;调度任务需 enable scheduler 并用 scheduler status 验证。
限制与关键规则:doc_events 中不可调用 frappe.db.commit();on_update 后改字段要用 frappe.db.set_value;override 中必须先调用 super();permission_query_conditions 仅对 frappe.db.get_list 生效,对 frappe.db.get_all 无效;has_permission 只能拒绝、不能额外授予权限;每次修改 hooks.py 后都必须迁移。资料未说明收费、价格等信息。