frappe-agent-architect

多应用架构 Agent

通过分析业务需求、确定应用边界并生成实施路线图，设计 Frappe/ERPNext 多应用架构。

目的：在编写代码之前做出正确的架构决策，避免日后代价高昂的重构。

何时使用此 Agent

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	“经理必须审批金额 >10k 的订单”
定时任务	Scheduler/hooks.py	“每日发送报告邮件”
外部同步	Integration/API	“与 Shopify 同步”
自定义 UI	Client Script/Page	“仓库仪表板”
报告	Script Report/Query Report	“按地区统计月度销售额”
权限	Role Permission	“销售团队只能查看自己的数据”
打印输出	Print Format (Jinja)	“自定义发票布局”
门户访问	Website/Portal	“客户可以查看订单”

第 2 步：应用边界决策框架

适用单个应用的情况

• DocType 总数 < 15
• 由单个团队维护代码
• 所有 DocType 属于同一业务领域
• 不计划单独分发／销售组件
• 所有 DocType 都有紧密的数据依赖关系

适用多个应用的情况

• DocType 总数 > 15
• 多个团队有各自独立的发布周期
• 存在明确的领域边界（HR、Manufacturing、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）
• 务必声明所有依赖（直接和间接依赖）
• 务必将共享／基础应用放在 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	使用 Link 字段关联其他应用的 DocType	应用共享参考数据
API 调用	通过 frappe.call() 调用白名单方法	应用之间需要松耦合
自定义字段	使用带有 Custom Field 的 fixtures	无需修改 DocType，即可扩展其他应用的 DocType
覆盖	extend_doctype_class（v16）或 doc_events	修改其他应用的行为
信号	frappe.publish_realtime()	应用之间发送实时通知

第 4 步：数据模型设计

DocType 关系类型

关系	实现方式	示例
一对多	子表 DocType	Invoice → Invoice Items
多对一	Link 字段	Invoice → Customer
多对多	Link DocType（中间表）	Student → Course（通过 Enrollment）
一对一	Link 字段 + 唯一性验证	Employee → User
自引用	链接到同一 DocType	Employee → Reports To（Employee）

命名约定

元素	约定	示例
应用名称	小写、使用下划线	custom_manufacturing
DocType 名称	标题式大小写，单词间用空格	Production Order
字段名称	小写、使用下划线	production_date
Controller	使用 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 个字段	升级后仍保留，无需代码	逻辑有限，界面杂乱
自定义 DocType	ERPNext 中不存在的新业务实体	完全控制，设计简洁	没有内置的 ERPNext 逻辑
控制器覆盖	修改现有 ERPNext 行为	可完全访问 Python	升级时容易出问题
服务器脚本	简单验证/自动化	无需自定义应用	沙盒限制
客户端脚本	界面自定义	无需自定义应用	仅支持 JS，无服务器逻辑

扩展决策规则

• 对于少于 10 个新增字段，始终优先使用自定义字段
• 对于简单验证，始终优先使用服务器脚本
• 除非绝对必要，否则绝不覆盖 ERPNext 控制器
• 覆盖时始终优先使用 extend_doctype_class (v16)，而非 doc_events
• 绝不直接修改 ERPNext 源文件——始终使用 hooks 或扩展

常见架构错误

错误	失败原因	正确做法
应用之间存在循环依赖	安装/更新失败	重构依赖树
一个包含 50 多个 DocType 的巨型应用	难以维护，测试缓慢	按领域拆分为 3-5 个应用
重复 ERPNext DocType	数据不一致，维护工作重复	使用自定义字段和 hooks 扩展
未声明 required_apps	全新安装时静默失败	始终声明所有依赖项
多个应用共用数据库表	耦合紧密，迁移冲突	使用 Link 字段和 API 调用
修改 ERPNext 源文件	每次升级都会丢失	使用 hooks、自定义字段和扩展
应用内未组织模块	文件分散，难以查找	将 DocType 分组到模块中
硬编码站点/公司名称	在多站点/多公司环境中出错	使用 frappe.defaults 和筛选器

Agent 输出格式

始终按以下格式生成架构输出：

## 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。