project-triage

Frappe 项目初步排查

快速分析 Frappe 项目，确定其类型、已安装的应用、版本和可用工具。

适用场景

• 打开新的 Frappe 项目时的第一步
• 修改代码前，了解代码库
• 调试时，确定涉及的应用和版本
• 识别开发环境（Bench 还是 Frappe Manager）

所需输入

• 项目根目录路径（apps/、sites/ 或应用代码所在位置）
• 运行 shell 命令的权限（用于检查版本）

操作流程

0) 识别项目结构

检查以下模式：

模式	项目类型
apps/ + sites/ 目录	Bench 安装
包含 frappe 的 docker-compose.yml	Frappe Manager 站点
包含 frappe 的 pyproject.toml 或 setup.py	独立应用
doctype/ 目录	位于应用模块内

1) 检测已安装的应用

# Inside Bench/FM shell
bench --site <site> list-apps

# Or check apps directory
ls apps/

2) 检查 Frappe 版本

# Inside Bench/FM shell
bench version

# Or check from Python
bench --site <site> console
>>> frappe.__version__

3) 识别工具

文件/目录	工具
Procfile	标准 Bench
docker-compose.yml	Docker/FM
cypress/	可进行 UI 测试
.github/workflows/	已配置 CI
含有 @frappe/* 的 package.json	JS 构建工具

4) 检查开发模式

# Check site config
bench --site <site> console
>>> frappe.conf.developer_mode

验证

• 已识别项目类型（bench/FM/独立应用）
• 已列出已安装的应用
• 已确认 Frappe 版本
• 已确认开发模式状态
• 已记录可用工具

故障模式 / 调试

• 未找到站点：可能位于应用目录内，请导航至 bench 根目录
• 找不到 bench 命令：当前不在 bench 环境中，请使用 fm shell 或激活 venv
• 权限错误：检查当前用户是否正确

升级处理

如果项目结构不明确：

1. 查找 hooks.py 以识别应用根目录
2. 查找 sites/common_site_config.json 以识别 bench 根目录
3. 检查 git remote，以识别应用仓库

输出格式

完成初步排查后，记录：

Project Type: [bench|frappe-manager|standalone-app]
Frappe Version: X.Y.Z
Installed Apps: [list]
Developer Mode: [yes|no]
Tooling: [list]
Site Name: <site>

使用此输出转至相应技能：

• DocType 工作 → doctype-development
• API 工作 → api-development
• 测试 → testing
• 企业模式 → enterprise-patterns

防护措施

• 完成初步排查前，绝不修改代码——先了解项目
• 检查是否存在自定义应用，这些应用可能会覆盖标准行为
• 运行站点专用命令前，确认站点存在
• 进行架构更改前，检查 developer_mode（修改 DocType 时必须开启）
• 记录 Node.js 版本——前端构建需要兼容的 Node.js 版本（v15 通常需要 18+）

常见错误

错误	失败原因	修复方法
未指定站点就运行 bench migrate	影响错误的站点或默认站点	始终使用 --site sitename
假设已安装 ERPNext	导入错误、缺少 DocType	先检查 list-apps 输出
缺少 FM shell 上下文	找不到 bench 命令	先使用 fm shell sitename
目录层级错误	命令静默失败	导航至 bench 根目录（存在 apps/ 的位置）
忽略自定义应用覆盖	行为异常	检查 hooks.py 中的覆盖项
未检查 Python 版本	语法/兼容性错误	确认 v15+ 使用 Python >= 3.10