DocType 变更后字段不显示问题总结与解决方案

问题现象

• 在本地开发环境中，DocType 新增或修改字段（如 mark 字段）后，前端 desk 可以正常显示。
• 将代码（json 文件）推送到 Github 并在新环境部署后，虽然 json 文件中有新字段，但 desk 前端却无法看到。
• 即使执行了 bench migrate，问题依旧。

---

原因分析

1. Frappe 的 DocType 定义有两份：

   • 数据库中的 DocType 配置（tabDocType、tabDocField 等表）
   • apps 目录下的 json 文件（如 rg_production_orders.json）

2. frappe 以数据库为准：

   • 你在开发环境用 UI 改 DocType，frappe 会同步到数据库，并导出 json 文件。
   • 你直接改 json 文件，数据库不会自动同步，frappe 只会用数据库里的定义。

3. bench migrate 不会自动用 json 覆盖数据库 DocType 配置：

   • 这样做是为了防止误删线上字段或数据。
   • 所以 migrate 只做数据库 schema 迁移和 patch，不 reload DocType。

---

解决方案

1. 手动同步 DocType

每次部署后，必须执行 reload-doc，用 json 文件内容覆盖数据库 DocType 配置：

bench --site [site_name] reload-doc [app_name] doctype [DocType名称]

如：

bench --site site1.local reload-doc rongguan_erp doctype rg_production_orders

2. 批量 reload

如果有多个 DocType，可以批量 reload：

for dt in $(ls apps/erpnextcn/erpnextcn/erpnextcn/doctype/); do
    bench --site site1.local reload-doc erpnextcn doctype $dt || true
done

for dt in $(ls apps/rongguan_erp/rongguan_erp/rongguan_erp/doctype/); do
    bench --site site1.local reload-doc rongguan_erp doctype $dt || true
done

3. 自动化建议

在自动化部署脚本中，建议在所有 app 安装完毕后、关闭开发者模式前，统一 reload-doc。

示例插入位置：

bench --site ${siteName} install-app erpnextcn
bench --site ${siteName} install-app rongguan_erp

# reload erpnextcn 所有 DocType
for dt in $(ls /home/${userName}/${installDir}/apps/erpnextcn/erpnextcn/erpnextcn/doctype/); do
    bench --site ${siteName} reload-doc erpnextcn doctype $dt || true
done

# reload rongguan_erp 所有 DocType
for dt in $(ls /home/${userName}/${installDir}/apps/rongguan_erp/rongguan_erp/rongguan_erp/doctype/); do
    bench --site ${siteName} reload-doc rongguan_erp doctype $dt || true
done

bench --site ${siteName} set-config developer_mode 0

---

最佳实践

• 开发时：用 UI 改 DocType，改完后导出 json（bench export-fixtures 或 bench export-doc）。
• 生产/部署时：只用 json 文件做版本管理，部署后自动 reload-doc。
• 不要直接手动改 json 文件然后指望 migrate 自动同步。

---

总结

• frappe 的 DocType 以数据库为准，json 只是导入导出用。
• 只要你直接改 json，就要 reload-doc。
• 建议开发用 UI 改，生产用 reload-doc 自动同步。