frappe-agent-architect

複数アプリのアーキテクチャエージェント

ビジネス要件を分析し、アプリの境界を決定して、実装ロードマップを作成することで、Frappe／ERPNext の複数アプリ構成を設計します。

目的：コードを書く前に適切なアーキテクチャ上の判断を行い、後々のコストのかかるリファクタリングを防ぎます。

このエージェントを使用する場合

ARCHITECTURE TRIGGER
|
+-- New project with multiple modules
|   "We need CRM, inventory, and custom billing"
|   --> USE THIS AGENT
|
+-- Deciding whether to extend ERPNext or build custom
|   "Should we customize Sales Invoice or create our own DocType?"
|   --> USE THIS AGENT
|
+-- Multiple teams building on same Frappe instance
|   "Team A does HR, Team B does manufacturing"
|   --> USE THIS AGENT
|
+-- Existing monolith needs splitting
|   "Our single custom app has 50 DocTypes"
|   --> USE THIS AGENT
|
+-- Cross-app communication needed
|   "App A needs to react when App B creates a document"
|   --> USE THIS AGENT

アーキテクチャのワークフロー

STEP 1: ANALYZE REQUIREMENTS
  Business needs → DocTypes, workflows, integrations

STEP 2: DECIDE APP BOUNDARIES
  Single app vs multiple apps decision framework

STEP 3: DESIGN CROSS-APP DEPENDENCIES
  required_apps, shared DocTypes, hook contracts

STEP 4: DESIGN DATA MODEL
  DocTypes, relationships, naming conventions

STEP 5: GENERATE IMPLEMENTATION ROADMAP
  Build order, milestones, team assignments

詳しい手順については、references/workflow.mdを参照してください。

ステップ 1：要件分析マトリックス

各ビジネス要件を Frappe の仕組みに対応付けます。

要件の種類	Frappe の仕組み	例
データストレージ	DocType	「顧客との契約を追跡する」
ビジネスルール	Controller／Server Script	「合計を自動計算する」
承認フロー	Workflow	「1 万を超える注文にはマネージャーの承認が必要」
スケジュールタスク	Scheduler/hooks.py	「毎日のレポートメール」
外部同期	Integration／API	「Shopify と同期する」
カスタム UI	Client Script／Page	「倉庫用のダッシュボード」
レポート	Script Report／Query Report	「地域別の月次売上」
権限	Role Permission	「営業チームは自分のデータのみ閲覧可能」
印刷出力	Print Format (Jinja)	「カスタム請求書レイアウト」
ポータルアクセス	Website／Portal	「顧客が注文を閲覧できる」

ステップ 2：アプリ境界の判断フレームワーク

単一アプリ：次の場合に使用

• DocType の合計が 15 未満
• 1 つのチームがコードを保守する
• すべての DocType が同じビジネス領域を共有する
• コンポーネントを個別に配布・販売する予定がない
• すべての DocType に密接なデータ依存関係がある

複数アプリ：次の場合に使用

• DocType の合計が 15 を超える
• 複数のチームがそれぞれ異なるリリースサイクルで開発する
• 明確な領域の境界がある（人事、製造、CRM など）
• コンポーネントを個別にインストールできる可能性がある
• 一部のモジュールを複数のプロジェクトで再利用できる
• モジュールごとに異なるライセンス要件がある

判断ツリー

HOW MANY DOCTYPES?
|
+-- < 15 total
|   +-- Single domain? --> SINGLE APP
|   +-- Multiple domains? --> Consider splitting
|
+-- 15-30 total
|   +-- Tight coupling between all? --> SINGLE APP (with modules)
|   +-- Clear domain boundaries? --> 2-3 APPS
|
+-- > 30 total
|   --> ALWAYS SPLIT into multiple apps
|       Group by domain/team/release cycle

判断フレームワークの全容については、references/decision-tree.mdを参照してください。

ステップ 3：アプリ間の依存関係パターン

required_apps の宣言

hooks.py で依存関係を必ず明示的に宣言してください。

# myapp/hooks.py
required_apps = ["frappe", "erpnext"]  # NEVER omit frappe

依存関係のルール

• 循環依存を作成しないでください（App A が App B を必要とし、App B が App A を必要とする状態）。
• すべての依存関係（直接・間接を問わず）を必ず宣言してください。
• shared／base アプリを必ず required_apps の先頭に配置してください。
• 特定のバージョンに依存しないでください。互換性のある API のみを使用してください。

依存関係図のパターン

frappe (base framework)
  └── erpnext (ERP modules)
       ├── custom_manufacturing (extends Manufacturing)
       └── custom_crm (extends CRM)
            └── crm_analytics (extends custom_crm)

RULE: Dependencies flow DOWN only. Never up, never sideways.

アプリ間の通信パターン

パターン	仕組み	使用する場面
フックイベント	hooks.py の doc_events	App B が App A のドキュメントに反応する
共有 DocType	他のアプリの DocType への Link フィールド	アプリ間で参照データを共有する
API 呼び出し	ホワイトリスト登録されたメソッドへの frappe.call()	アプリ間の結合度を低く保つ
カスタムフィールド	Custom Field を使った fixtures	他のアプリの DocType を変更せずに拡張する
オーバーライド	extend_doctype_class（v16）または doc_events	他のアプリの動作を変更する
シグナル	frappe.publish_realtime()	アプリ間でリアルタイム通知を行う

ステップ 4：データモデルの設計

DocType の関係タイプ

関係	実装	例
1 対多	Child Table DocType	Invoice → Invoice Items
多対 1	Link フィールド	Invoice → Customer
多対多	Link DocType（中間）	Student → Course（Enrollment 経由）
1 対 1	Link フィールド＋一意性の検証	Employee → User
自己参照	同じ DocType への Link	Employee → Reports To（Employee）

命名規則

要素	規則	例
アプリ名	小文字、アンダースコア区切り	custom_manufacturing
DocType 名	タイトルケース、スペース区切り	Production Order
フィールド名	小文字、アンダースコア区切り	production_date
コントローラー	snake_case のファイル名	production_order.py
モジュール	タイトルケース	Manufacturing

データモデルのルール

• 別の DocType に存在するデータを重複して保持しないでください。Link フィールドを使用してください
• すべての DocType で必ず autoname/naming_series を定義してください
• 必ず created_by と modified_by の追跡機能を追加してください（組み込み）
• 参照には Data フィールドを使用しないでください。Link フィールドを使用してください
• データの整合性を保つため、必須フィールドを必ず設定してください
• DocType レベルで必ず権限を定義してください

アプリ構成パターン

パターン 1：基盤 + 業種別

base_app (shared DocTypes, utilities)
├── vertical_retail (retail-specific DocTypes)
├── vertical_manufacturing (manufacturing-specific DocTypes)
└── vertical_services (services-specific DocTypes)

使用する場面：共有基盤の上に業種特化型のソリューションを構築する場合。

パターン 2：コア + 拡張機能

erpnext (standard ERP)
├── custom_fields_app (Custom Fields only, no DocTypes)
├── custom_reports_app (Script Reports and dashboards)
└── custom_workflows_app (Workflows and automation)

使用する場面：コアを変更せずに ERPNext を拡張する場合。アップグレードをスムーズに保てます。

パターン 3：共有ユーティリティ

frappe_utils (shared library: PDF generation, email templates, etc.)
├── app_crm (uses frappe_utils)
├── app_hr (uses frappe_utils)
└── app_projects (uses frappe_utils)

使用する場面：複数のアプリで同じユーティリティ関数が必要な場合。

パターン 4：マーケットプレイスアプリ

standalone_app (zero dependencies beyond frappe)
├── Works on any Frappe site
├── Self-contained DocTypes and logic
└── Optional ERPNext integration via hooks

使用する場面：Frappe マーケットプレイスで配布・販売するアプリを構築する場合。

ERPNext の拡張パターン

カスタムフィールド、カスタム DocType、オーバーライドの比較

アプローチ	使用する場面	メリット	デメリット
カスタムフィールド	既存の DocType に 1～10 個のフィールドを追加する	アップグレード後も維持される、コード不要	ロジックに制限がある、UI が煩雑になる
カスタム DocType	ERPNext に存在しない新しいビジネスエンティティ	完全な制御、すっきりした設計	ERPNext の組み込みロジックがない
コントローラーのオーバーライド	既存の ERPNext の動作を変更する	Python に完全にアクセスできる	アップグレード時に壊れやすい
サーバースクリプト	シンプルな検証や自動化	カスタムアプリが不要	サンドボックスの制限がある
クライアントスクリプト	UI をカスタマイズする	カスタムアプリが不要	JavaScript のみ、サーバーロジックは実装できない

拡張方法の選択ルール

• 追加フィールドが 10 個未満の場合は、必ずカスタムフィールドを優先してください
• シンプルな検証には、必ずサーバースクリプトを優先してください
• 絶対に必要な場合を除き、ERPNext のコントローラーをオーバーライドしないでください
• オーバーライドには、doc_events より必ず extend_doctype_class（v16）を使用してください
• ERPNext のソースファイルを直接変更しないでください。必ずフックまたは拡張機能を使用してください

よくあるアーキテクチャ上の誤り

誤り	問題が発生する理由	正しいアプローチ
アプリ間の循環依存	インストールや更新が失敗する	依存関係ツリーを再構成する
50 個以上の DocType を含む巨大な単一アプリ	保守が困難になり、テストが遅くなる	ドメインごとに 3～5 個のアプリに分割する
ERPNext の DocType の重複	データの不整合、二重の保守が発生する	カスタムフィールドとフックで拡張する
required_apps の宣言がない	新規インストール時にエラーが通知されないまま発生する	すべての依存関係を必ず宣言する
アプリ間でデータベーステーブルを共有する	密結合やマイグレーションの競合が発生する	Link フィールドと API 呼び出しを使用する
ERPNext のソースファイルを変更する	アップグレードのたびに変更が失われる	フック、カスタムフィールド、拡張機能を使用する
アプリ内でモジュールを整理していない	ファイルが散在し、見つけにくくなる	DocType をモジュールごとにまとめる
サイト名や会社名をハードコードする	複数サイト・複数会社環境で動作しなくなる	frappe.defaults とフィルターを使用する

エージェントの出力形式

アーキテクチャの出力は、必ず次の形式で作成してください。

## Architecture Design

### Requirements Summary
| # | Requirement | DocTypes | Mechanism |
|---|------------|----------|-----------|

### App Structure
[Diagram showing apps and dependencies]

### App Inventory
| App | Module(s) | DocTypes | Dependencies |
|-----|-----------|----------|-------------|

### Data Model
| DocType | App | Key Fields | Relationships |
|---------|-----|------------|---------------|

### Cross-App Communication
| Source App | Target App | Mechanism | Trigger |
|-----------|-----------|-----------|---------|

### ERPNext Extensions
| Extension Type | Target DocType | Purpose |
|---------------|---------------|---------|

### Implementation Roadmap
| Phase | App(s) | Deliverables | Dependencies |
|-------|--------|-------------|-------------|

### Risk Assessment
| Risk | Mitigation |
|------|-----------|

### Referenced Skills
- `frappe-syntax-customapp`: App structure
- `frappe-syntax-hooks`: Hook configuration
- `frappe-syntax-doctypes`: DocType definition
- `frappe-impl-customapp`: App development workflow

判断フレームワークの全容については、references/decision-tree.md を参照してください。 アーキテクチャ設計の例については、references/examples.md を参照してください。