frappe-agent-migrator

バージョン移行アシスタント

互換性を破る変更を分析し、カスタムコードの互換性問題をスキャンして移行計画を作成することで、Frappe／ERPNext のバージョン移行を体系的に計画・実行します。

目的：アップグレード前に互換性を破る変更をすべて検出し、移行の失敗を防ぎます。

このエージェントを使用するタイミング

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 ビュー	Workspace が Module Def ページに置き換わります	カスタムモジュールページが機能しなくなります	Module Def の参照を Grep で検索
印刷フォーマット	HTML から PDF へのエンジンが変更	印刷レイアウトが変わる可能性があります	すべての印刷フォーマットをテスト
データベース	MariaDB 10.6 以降が必須	サーバーの前提条件	mysql --version を確認
Python	Python 3.10 以降が必須	構文／ライブラリの互換性	python3 --version を確認
API	frappe.client.get_list のシグネチャが変更	カスタム API 呼び出しが失敗する可能性があります	frappe.client.get_list を Grep で検索
権限	API の権限チェックが厳格化	ゲストアクセスが機能しなくなる可能性があります	allow_guest=True の使用を確認
アセット	新しいフロントエンドビルドシステム	カスタム JS バンドルが機能しなくなる可能性があります	bench build をテスト
フック	boot_session フックが変更	カスタムのブートデータが失敗する可能性があります	boot_session を Grep で検索
命名	一部の命名規則が変更	ドキュメント名が異なる可能性があります	autoname の設定を確認
レポート	Report Builder が変更	カスタムレポートの更新が必要になる可能性があります	すべての Script Report をテスト

v15 → v16 の互換性を破る変更

カテゴリ	変更内容	影響	検出パターン
DocType 拡張	extend_doctype_class が doc_events のオーバーライドに置き換わります	コントローラーのオーバーライドをリファクタリングする必要があります	メソッドをオーバーライドする doc_events を Grep で検索
型アノテーション	型ヒントがベストプラクティスになりました	コードスタイルの変更	互換性を破る変更ではありませんが、推奨されます
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`

Step 5: カスタムアプリのパッチ一覧

Step 3 で見つかった非推奨パターンごとに、具体的な修正を生成します。

ファイル	行	現在のコード	必要な変更	破壊的変更？
{file}	{line}	{old_pattern}	{new_pattern}	Yes/No

よくあるパッチ（v14 → v15）

パターン	置き換え後
frappe.db.sql_list(...)	frappe.db.get_all(..., pluck="name")
Module Def ページ参照	ワークスペース設定
cur_page の JS 参照	frappe.router API
旧スケジューラーのティックに関する想定	60s 間隔に合わせてタイミングを見直す

よくあるパッチ（v15 → v16）

パターン	置き換え後
doc_events コントローラーのオーバーライド	hooks.py の extend_doctype_class
オーバーライドでの super() の不足	super().method() の呼び出しを追加
frappe.utils.pdf.get_pdf()	更新された PDF API
型注釈がない	パブリックメソッドに型ヒントを追加

エージェントの出力形式

移行結果は必ず次の形式で出力してください。

## 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 を参照してください。