frappe-agent-migrator

版本迁移助手

通过分析破坏性变更、扫描自定义代码以检查兼容性问题并生成迁移计划，系统地规划和执行 Frappe/ERPNext 版本迁移。

目的：在升级前检测每一项破坏性变更，防止迁移失败。

何时使用此 Agent

MIGRATION TRIGGER
|
+-- Planning a version upgrade
|   "We need to go from v14 to v15"
|   --> USE THIS AGENT
|
+-- Post-upgrade errors
|   "Everything broke after bench update"
|   --> USE THIS AGENT (Step 2-5 for diagnosis)
|
+-- Checking custom app compatibility
|   "Will our custom app work on v16?"
|   --> USE THIS AGENT (Step 3 for code scan)
|
+-- Already mid-migration with issues
|   "bench migrate fails with errors"
|   --> USE THIS AGENT + frappe-agent-debugger

迁移工作流

STEP 1: IDENTIFY MIGRATION PATH
  Source version → Target version (NEVER skip major versions)

STEP 2: CHECK BREAKING CHANGES
  Apply breaking changes database for each version jump

STEP 3: SCAN CUSTOM CODE
  Grep for deprecated patterns in all custom apps

STEP 4: GENERATE MIGRATION PLAN
  Backup → Staging → Test → Production sequence

STEP 5: GENERATE PATCH LIST
  Specific code changes needed per custom app

详细步骤请参阅 references/workflow.md。

步骤 1：迁移路径规则

绝不跳过主要版本。务必按顺序迁移：

来源	目标	路径
v14	v15	v14 → v15
v14	v16	v14 → v15 → v16
v15	v16	v15 → v16

版本识别

# Check current versions
bench version
# Output shows: frappe X.Y.Z, erpnext X.Y.Z

# Check available versions
cd apps/frappe && git tag | grep "^v1[456]" | tail -5

步骤 2：破坏性变更摘要

v14 → v15 破坏性变更

类别	变更	影响	检测模式
调度器	Tick 间隔从 240s 变为 60s	任务可能运行得更频繁	检查 scheduler_events
后台任务	新增 job_id 去重	现在会阻止重复任务	检查 frappe.enqueue() 调用
Web 视图	工作区取代 Module Def 页面	自定义模块页面会失效	搜索 Module Def 引用
打印格式	HTML 转 PDF 引擎变更	打印布局可能不同	测试所有打印格式
数据库	要求 MariaDB 10.6+	服务器先决条件	检查 mysql --version
Python	要求 Python 3.10+	语法／库兼容性	检查 python3 --version
API	frappe.client.get_list 签名变更	自定义 API 调用可能失败	搜索 frappe.client.get_list
权限	对 API 的权限检查更加严格	访客访问可能失效	检查 allow_guest=True 的用法
资源	新前端构建系统	自定义 JS 包可能失效	测试 bench build
钩子	boot_session 钩子变更	自定义启动数据可能失效	搜索 boot_session
命名	部分命名规则变更	文档名称可能不同	检查 autoname 设置
报表	报表生成器变更	可能需要更新自定义报表	测试所有脚本报表

v15 → v16 破坏性变更

类别	变更	影响	检测模式
DocType 扩展	extend_doctype_class 取代 doc_events 覆盖	控制器覆盖需要重构	搜索带有方法覆盖的 doc_events
类型注解	类型提示现为最佳实践	代码风格变更	不会造成破坏，但建议采用
Chrome PDF	新 PDF 引擎（基于 Chrome）	打印格式渲染变更	测试所有打印格式
数据脱敏	新隐私功能	需要配置 PII 字段	检查敏感字段
UUID 命名	新的 uuid 命名规则	命名逻辑变更	检查 autoname 设置
Python	要求 Python 3.11+	库兼容性	检查 python3 --version
Node.js	要求 Node 18+	构建系统先决条件	检查 node --version
Redis	要求 Redis 7+	缓存／队列兼容性	检查 redis-server --version
已弃用的 API	移除了多个 API	使用已移除 API 的代码会失败	参阅 breaking-changes.md
工作流	工作流引擎更新	可能需要检查自定义工作流状态	测试所有工作流
门户	门户页面渲染变更	自定义门户页面可能失效	测试所有门户页面
后台任务	RQ 版本升级	任务序列化方式变更	测试后台任务

完整详情请参阅 references/breaking-changes.md。

步骤 3：已弃用模式检测

务必扫描自定义应用代码，查找以下模式：

v14 → v15 已弃用模式

# Run these grep commands in apps/{your_app}/ directory:

# 1. Old-style module page references
grep -rn "Module Def" --include="*.py" --include="*.json"

# 2. Old scheduler API
grep -rn "frappe.utils.scheduler" --include="*.py"

# 3. Deprecated client API
grep -rn "frappe.set_route\|cur_page\|page_container" --include="*.js"

# 4. Old-style print format
grep -rn "frappe.get_print\|standard_format" --include="*.py"

# 5. Deprecated database methods
grep -rn "frappe.db.sql_list\|frappe.db.sql_ddl" --include="*.py"

v15 → v16 已弃用模式

# Run these grep commands in apps/{your_app}/ directory:

# 1. doc_events that should use extend_doctype_class
grep -rn "doc_events" hooks.py

# 2. Old-style controller override
grep -rn "override_doctype_class" --include="*.py"

# 3. Deprecated frappe.utils methods
grep -rn "frappe.utils.now_datetime\b" --include="*.py"

# 4. Old print format API
grep -rn "frappe.utils.pdf\|get_pdf" --include="*.py"

# 5. Removed API calls
grep -rn "frappe.get_hooks\b.*boot_session" --include="*.py"

# 6. Missing type annotations (warning, not error)
grep -rn "def .*whitelist" --include="*.py"

步骤 4：迁移计划模板

务必按以下格式生成迁移计划：

## Migration Plan: v{source} → v{target}

### Prerequisites
- [ ] Python version: {required}
- [ ] Node.js version: {required}
- [ ] MariaDB version: {required}
- [ ] Redis version: {required}
- [ ] Disk space: minimum 2x current DB size

### Phase 1: Preparation (Day 1)
1. Full backup: `bench --site {site} backup --with-files`
2. Document current state: `bench version > pre-migration-versions.txt`
3. List all custom apps: `bench --site {site} list-apps`
4. Run deprecated pattern scan (Step 3)
5. Fix all detected issues in custom apps

### Phase 2: Staging (Day 2-3)
1. Clone production to staging environment
2. Restore backup on staging: `bench --site staging restore {backup}`
3. Switch branch: `bench switch-to-branch version-{target} frappe erpnext`
4. Run migration: `bench --site staging migrate`
5. Run full test suite on staging

### Phase 3: Testing (Day 4-5)
- [ ] All DocTypes load correctly
- [ ] All print formats render correctly
- [ ] All workflows transition correctly
- [ ] All scheduled jobs execute correctly
- [ ] All custom reports generate correctly
- [ ] All API endpoints respond correctly
- [ ] All user permissions work correctly
- [ ] Performance is acceptable (page load < 3s)

### Phase 4: Production (Day 6)
1. Schedule maintenance window
2. Enable maintenance mode: `bench --site {site} set-maintenance-mode on`
3. Final backup: `bench --site {site} backup --with-files`
4. Switch branch: `bench switch-to-branch version-{target} frappe erpnext`
5. Run migration: `bench --site {site} migrate`
6. Run `bench build --production`
7. Restart: `bench restart` (or `sudo supervisorctl restart all`)
8. Disable maintenance mode: `bench --site {site} set-maintenance-mode off`
9. Verify (Phase 3 checklist again)

### Rollback Plan
1. Stop all services: `sudo supervisorctl stop all`
2. Restore backup: `bench --site {site} restore {backup_path}`
3. Switch back: `bench switch-to-branch version-{source} frappe erpnext`
4. Run migration: `bench --site {site} migrate`
5. Rebuild: `bench build --production`
6. Restart: `sudo supervisorctl restart all`

步骤 5：自定义应用补丁列表

对于步骤 3 中发现的每种已弃用模式，都生成具体的修复方案：

文件	行	当前代码	所需更改	是否有破坏性影响？
{file}	{line}	{old_pattern}	{new_pattern}	是/否

常见补丁（v14 → v15）

模式	替换为
frappe.db.sql_list(...)	frappe.db.get_all(..., pluck="name")
Module Def 页面引用	工作区配置
cur_page JS 引用	frappe.router API
旧的调度器 tick 假设	检查 60s 间隔的时间安排

常见补丁（v15 → v16）

模式	替换为
doc_events 控制器覆盖	hooks.py 中的 extend_doctype_class
覆盖方法中缺少 super()	添加 super().method() 调用
frappe.utils.pdf.get_pdf()	更新后的 PDF API
没有类型注解	为公共方法添加类型提示

Agent 输出格式

始终按以下格式生成迁移输出：

## Migration Assessment

### Version Path
{source} → {target} (via {intermediate versions if any})

### Prerequisites Status
| Requirement | Current | Required | Status |
|-------------|---------|----------|--------|
| Python | {ver} | {ver} | OK/FAIL |
| Node.js | {ver} | {ver} | OK/FAIL |
| MariaDB | {ver} | {ver} | OK/FAIL |

### Breaking Changes Found: {count}
[List from Step 2]

### Custom Code Issues Found: {count}
[Table from Step 3 scan]

### Migration Plan
[From Step 4]

### Patch List
[From Step 5]

### Risk Assessment
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|

### Estimated Timeline
Preparation: {days} | Staging: {days} | Testing: {days} | Production: {hours}

### Referenced Skills
- `frappe-ops-upgrades`: Version upgrade procedures
- `frappe-ops-backup`: Backup and restore
- `frappe-agent-debugger`: For post-migration error diagnosis

请参阅 references/checklists.md 获取完整的迁移检查清单。 请参阅 references/breaking-changes.md 获取完整的破坏性变更数据库。